# dsh-novel-forge

dsh-novel-forge is a Claude Code MCP server that structures long-form fiction writing across 24 tools. It validates scene contracts and blocks plot contradictions before text hits the disk.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 50 repo stars
- Author: huangziyuan-general
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/huangziyuan-general/dsh-novel-forge
- Updated: 2026-11-17
- Security check: automated, 2026-11-17 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/mcp/dsh-novel-forge

## What it does

The server provides 24 tools under the `novel_*` prefix to manage long-form novel projects. A deterministic nine-stage state machine guides work from premise, world setting, and character sheets to scene outlines and chapter drafts. It enforces consistency through `novel_ledger`, rejecting contradictory status changes within the same chapter instead of silently overwriting them.

All consistency checks run locally with zero token consumption. The `novel_audit` tool scans for timeline gaps, character contradictions, and unresolved foreshadowing. If a single chapter gets rejected three times consecutively by validation gates, a circuit breaker halts drafting until the scene outline is revised.

Execution requires Node 20 or higher, with Node 22 recommended for search indexing. The project directory must be specified via the `NOVEL_FORGE_ROOT` environment variable.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NOVEL_FORGE_ROOT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add dsh-novel-forge -e NOVEL_FORGE_ROOT=<NOVEL_FORGE_ROOT> -- npx -y dsh-novel-forge
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add dsh-novel-forge --env NOVEL_FORGE_ROOT=<NOVEL_FORGE_ROOT> -- npx -y dsh-novel-forge
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "dsh-novel-forge": {
            "command": "npx",
            "args": [
                "-y",
                "dsh-novel-forge"
            ],
            "env": {
                "NOVEL_FORGE_ROOT": "<NOVEL_FORGE_ROOT>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "dsh-novel-forge": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "dsh-novel-forge"
            ],
            "env": {
                "NOVEL_FORGE_ROOT": "<NOVEL_FORGE_ROOT>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NOVEL_FORGE_ROOT=<NOVEL_FORGE_ROOT> dsh-novel-forge npx -y dsh-novel-forge
```
Replace <…> with your own values

## When to use it
- enforce worldbuilding consistency across long serialized chapters
- audit novel drafts for plot discrepancies without token costs
- guide manuscript development through a structured nine-stage pipeline
- prevent silent character and inventory overwrites in story progression

## Example prompts
- Initialize a new fantasy book project using `novel_project init`.
- Run `novel_audit` to scan the entire manuscript for character contradictions.
- Generate the context package for the upcoming chapter using `novel_briefing`.

## Similar
- [dsh-novel-writer — 网文写作体检](https://affpapa.org/en/nevibecode/mcp/dsh-novel-writer.md) — MCP server · ★ 32 repo stars
- [novel-revision](https://affpapa.org/en/nevibecode/skills/novel-revision.md) — skill · 702 installs
- [dsh-baton](https://affpapa.org/en/nevibecode/mcp/dsh-baton.md) — MCP server · ★ 249 repo stars
- [markdown-novel-viewer](https://affpapa.org/en/nevibecode/skills/markdown-novel-viewer.md) — skill · 1 install
- [inkos-multi-agent-novel-writing](https://affpapa.org/en/nevibecode/skills/inkos-multi-agent-novel-writing.md) — skill · 2800 installs
- [novel-writer](https://affpapa.org/en/nevibecode/skills/novel-writer.md) — skill · 614 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
