story-architect-mcp

A Model Context Protocol (MCP) Server for AI-Assisted Long-Form Fiction Writing, Worldbuilding, Continuity Auditing, and Novel Architecture.

Key Features • Novel-as-Code • Quick Start • Client Setup • API Reference

📖 Overview & Core Philosophy

Writing long-form fiction (epics, thrillers, fantasy sagas, or multi-volume series) with AI assistance introduces severe context degradation, narrative drift, and structural inconsistencies. As manuscripts expand to tens or hundreds of thousands of words, LLMs easily forget minor lore points, character arcs, timeline logic, and voice guidelines.

story-architect-mcp solves this problem by pioneering the "Novels as Codebases" (NaC) paradigm. It bridges your AI writing assistant directly to a structured fiction repository via the Model Context Protocol (MCP).

flowchart TD
    subgraph Client["MCP Clients (Claude Desktop / Cursor / Antigravity / Windsurf)"]
        AI["AI LLM Agent"]
    end

    subgraph MCP["story-architect-mcp Server"]
        Tools["20 MCP Tools"]
        Res["6 Resources & 3 Templates"]
        Prompts["5 Workflow Prompts"]
    end

    subgraph Storage["Novel Workspace (File System)"]
        StoryMeta[".story/ (Config, Timelines, State)"]
        Bible["bible/ (Characters, World, Factions)"]
        Manuscript["manuscript/ (Arcs & Chapters)"]
        Outline["outline/ (Scene Beats & Plot Arcs)"]
    end

    AI <-->|JSON-RPC via Stdio| MCP
    MCP <-->|Read / Write / Snapshot| Storage

Related MCP server: FastMCP Novel Processing Tool

💡 The "Novels as Codebases" Paradigm

✨ Key Features

🧹 1. Messy Project Rescue & Auto-Refactoring

• Smart File Classifier (story_scan_messy_project): Scans unorganized manuscript folders, auto-detects character encodings (UTF-8, Windows-1252, ISO-8859-1), computes content similarity matrices, and tags files (Manuscript, Lore, Notes, Outline) with confidence scores.

• Automated Refactoring (story_auto_refactor_structure): Reorganizes scattered files into a clean project structure with safe dry-run previews (confirm: false).

• Snapshot & Rollback Protection (story_snapshot / story_rollback): Creates automatic point-in-time state backups prior to file operations.

🔍 2. Continuity Auditing & Plot Hole Tracking

• Plot Hole Manager (story_log_plot_hole / story_resolve_plot_hole): Tracks unresolved plot holes, severity levels, and proposed fixes directly in .story/unresolved_holes.json.

• Chekhov’s Gun Tracker (story_log_setup / story_log_payoff): Ensures planted clues or foreshadowed events are resolved before the story concludes.

• Timeline Conflict Detector (story_detect_timeline_conflicts): Audits character ages, event order, and absolute dates, generating interactive Mermaid Gantt Charts.

🧠 3. Knowledge Graph & Story Bible Integration

• Automatic Entity Extraction (story_extract_entities_to_bible): Parses chapter drafts to automatically create structured Markdown profiles in bible/characters/ and bible/world/.

• Dynamic Relationship Graph (story_map_relationships): Tracks changing relationships between characters across chapters into .story/relationships.json.

• Token-Budget Context Querying (story_query_context): Generates optimized context packages for LLMs by combining graph memory traversal with token budget constraints.

📈 4. Pacing, Voice Drift & Analytics

• Pacing Inspector (story_analyze_pacing): Measures Action / Dialogue / Description distribution and scene tension curves across chapters.

• Voice Drift Monitor (story_analyze_voice): Evaluates sentence complexity, vocabulary richness, and POV/tense compliance against your .story/style_guide.json.

• Writing Statistics (story_stats): Real-time word counts, writing velocity, and estimated project completion dates.

✍️ 5. AI Prompt Generator & Manuscript Export

• Context-Rich Prompt Builder (story_generate_writing_prompt): Automatically compiles lore, recent chapter endings, outline beats, and active Chekhov's guns into an optimized writing prompt.

• Multi-Format Export (story_export): Compiles manuscript files into Markdown, EPUB, PDF, or DOCX formats with custom metadata and Table of Contents.

📁 Standard Project Architecture

story-architect-mcp organizes novel projects into a standardized layout:

my-epic-novel/
├── .story/                      # Project metadata & state tracking
│   ├── config.json              # Title, Author, Genre, POV, Tense
│   ├── status.json              # Word counts & progress tracking
│   ├── timeline.json            # Event chronology & dates
│   ├── unresolved_holes.json    # Active plot hole registry
│   ├── relationships.json       # Character relationship matrix
│   ├── foreshadowing.json       # Chekhov's gun tracker (Setups & Payoffs)
│   ├── style_guide.json         # Voice, tone, sentence rules & reference excerpts
│   └── snapshots/               # Version snapshots for rollback protection
├── bible/                       # Story Bible & Worldbuilding Lore
│   ├── characters/              # Character profiles with YAML frontmatter
│   ├── world/                   # Locations, factions, magic/tech systems
│   └── subplots/                # Subplot tracking & arc objectives
├── manuscript/                  # Official Manuscript Drafts
│   └── arc_01/
│       ├── ch_001.md
│       └── ch_002.md
├── outline/                     # Master Outline & Chapter Beats
│   ├── synopsis.md              # High-level story synopsis
│   ├── themes.md                # Themes & key motifs
│   └── arc_01/
│       ├── overview.md          # Arc overview
│       └── ch_001_outline.md    # Scene beats per chapter
└── drafts_raw/                  # Loose, unorganized writing snippets

🚀 Quick Start

1. Installation

Install globally via npm:

npm install -g story-architect-mcp

Or build from source:

git clone https://github.com/PTCuong-1102/story-architect-mcp.git
cd story-architect-mcp
npm install
npm run build

⚙️ MCP Client Configuration

Add story-architect-mcp to your favorite MCP client configuration.

💡 Zero-Config Project Switching: You do not need to hardcode your novel path in configuration args. Once the server starts, the AI agent can set or switch projects at runtime using story_set_project.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "story-architect": {
      "command": "npx",
      "args": ["-y", "story-architect-mcp"]
    }
  }
}

Antigravity / Cursor / Windsurf / VS Code (mcp.json)

{
  "mcpServers": {
    "story-architect": {
      "command": "node",
      "args": ["/absolute/path/to/story-architect-mcp/dist/index.js"]
    }
  }
}

Initializing Default Path via CLI Argument (Optional)

If you prefer to load a specific project on server startup, pass the directory as a CLI argument:

{
  "mcpServers": {
    "story-architect": {
      "command": "npx",
      "args": ["-y", "story-architect-mcp", "/path/to/your/novel-project"]
    }
  }
}

🛠️ MCP API Reference

1. MCP Tools (20 Tools)

🔹 Project & Structure Management

🔹 Rescue & Refactoring Suite

🔹 Continuity & Management Suite

🔹 Graph Memory & Context Suite

🔹 Analysis & Prompt Generator Suite

2. MCP Resources (6 Static & 3 Templates)

Static Resources

Resource Templates

3. MCP Workflow Prompts (5 Prompts)

🛡️ Data Integrity & Safety Protocol

Writing a novel takes months or years; story-architect-mcp is designed with strict data preservation measures:

1. Dry-Run Mode First (confirm: false): All destructive or structural refactoring tools run in Preview mode by default. You can inspect exact proposed file moves and edits before confirming execution (confirm: true).

2. Automated Pre-Refactor Snapshots: Executing structural changes automatically triggers story_snapshot to create a rollback checkpoint prior to file operations.

3. Transparent File Formats: All metadata is stored as standard JSON in .story/, and all story content is stored in plain Markdown with YAML frontmatter—ensuring zero vendor lock-in.

🤝 Contributing

Contributions, bug reports, and feature requests are welcome!

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.