Skip to main content
Glama
Sign In
novel-mcp

novel-mcp

by YinFY90
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

通用小说写作引擎

这是一套本地优先的逐章小说写作流程。章节计划、人物、世界观、风格和状态保存在小说项目目录中；初稿与审稿保存在运行目录中；正文经过人工确认后才进入正式稿并更新故事状态。

当前版本提供离线 Mock Provider，也支持 OpenAI-compatible 与 Anthropic API。Codex、Claude Code 和 WorkBuddy 可以通过同一个 MCP 服务参与写作。

环境要求

  • Python 3.11 或更高版本

  • macOS、Windows 或 Linux

Related MCP server: Novel Workspace MCP

安装

从 GitHub 直接安装

python -m pip install "git+https://github.com/YinFY90/novel-engine.git"

也可以从 Releases 下载 .whl 文件：

python -m pip install novel_engine-0.1.0-py3-none-any.whl

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[test]"

创建小说项目

novel init "我的小说" --id my-novel --title "我的小说"
novel validate "我的小说"

初始化后，在 plans/ch-0001.yaml 编写章节计划，在 canon/ 中维护人物、世界观和风格。

完成一章

所有命令均可增加 --json，便于 Codex、Claude Code、WorkBuddy 或其他工具读取结果。

# 1. 组装上下文，输出中会返回 run_id
novel --json context "我的小说" ch-0001

# 2. 使用离线 Mock Provider 生成初稿
novel --json draft "我的小说" --run-id <run_id> --provider mock

# 3. 执行基础审稿
novel --json review "我的小说" --run-id <run_id>

# 4. 查看本次运行及正典差异
novel --json run-inspect "我的小说" <run_id>

# 5. 人工确认后提交正文、状态并创建快照
novel --json approve "我的小说" --run-id <run_id>

确认前，manuscript/ 和 state/ 保持不变。确认后，本次初稿写入 manuscript/<chapter-id>.md，状态提案一次写入 state/，同时在 snapshots/ 保存恢复点。同一运行重复确认会返回已有结果。

API 模式

API 模式由引擎调用已配置的模型生成初稿。密钥放在环境变量中，项目文件和运行记录不会保存密钥。

OpenAI-compatible：

export NOVEL_PROVIDER=openai-compatible
export NOVEL_API_KEY="<API key>"
export NOVEL_MODEL="<模型名称>"
export NOVEL_BASE_URL="<API 地址>"

Anthropic：

export NOVEL_PROVIDER=anthropic
export ANTHROPIC_API_KEY="<API key>"
export NOVEL_MODEL="<模型名称>"

Windows PowerShell 使用 $env:NOVEL_PROVIDER、$env:NOVEL_API_KEY、$env:NOVEL_MODEL 和 $env:NOVEL_BASE_URL 设置相同变量。

完整章节流程仍使用统一命令：

novel --json validate "我的小说"
novel --json context "我的小说" ch-0001
novel --json draft "我的小说" --run-id <run_id>
novel --json review "我的小说" --run-id <run_id>
novel --json run-inspect "我的小说" <run_id>
novel --json approve "我的小说" --run-id <run_id>

writer、reviewer、settler 的模型配置可以分别保存；当前版本的 API 自动调用用于正文写作，审稿和状态整理继续使用可检查的本地规则与章节计划。人工确认是写入正式正文和故事状态的唯一入口。

命令参数可以覆盖项目与环境配置：

novel --json draft "我的小说" --run-id <run_id> \
  --provider openai-compatible \
  --model "<模型名称>" \
  --base-url "<API 地址>"

AI 工具模式

Codex、Claude Code、WorkBuddy 使用 novel-mcp 连接同一小说项目：

  1. validate_project 检查项目。

  2. build_context 创建章节运行并取得 run_id。

  3. AI 工具自己写正文时调用 submit_draft；使用已配置 API 时调用 generate_draft。

  4. review_run 生成审稿结果和状态提案。

  5. inspect_run 检查本次运行，project_status 查看当前阶段。

  6. 用户明确接受正文后调用 approve_run。

三种工具的配置与项目调用规则位于：

所有入口共用 runs/、manuscript/、state/ 和 snapshots/。适配层只提供调用规则，不保存独立状态。

查看进度

novel status "我的小说"
novel status "我的小说" --run-id <run_id>
novel run-inspect "我的小说" <run_id>

示例

examples/example-story 是一个完全虚构的最小示例，包含第一章章节计划、人物资料、世界规则、行文风格和初始状态。

可以复制整个目录，在副本中运行完整流程：

cp -R examples/example-story "示例故事"
novel validate "示例故事"
novel --json context "示例故事" ch-0001

Windows PowerShell：

Copy-Item -Recurse examples\example-story "示例故事"
novel validate "示例故事"
novel --json context "示例故事" ch-0001

项目结构

novel-project/
├── novel.yaml              # 项目信息
├── canon/                  # 已确认的大纲、人物、世界观和风格
├── plans/                  # 章节计划
├── manuscript/             # 已确认正文
├── state/                  # 已确认故事状态
├── packs/                  # 作品或类型规则包
├── runs/                   # 每次运行的上下文、初稿、审稿和提案
└── snapshots/              # 确认时生成的恢复点

项目目录可以整体复制到另一台电脑。项目内文件引用统一使用相对路径。

设计参考

本项目参考了多个开源小说写作项目的工作流设计，包括可检查上下文、文件化记忆、连续性检查、审稿与回退机制。具体项目和借鉴内容见 ACKNOWLEDGMENTS.md。本仓库的代码、示例和文档独立维护，不包含这些项目的源码或作品内容。

测试

测试只使用本地临时目录和 Mock Provider，不访问网络，也不读取密钥。

pytest

跨平台 GitHub Actions 模板位于 ci/github-actions-tests.yml。仓库管理员获得 GitHub CLI 的 workflow 权限后，可将它放入 .github/workflows/tests.yml 启用。

Available Tools

8 tools
approve_runA

Human approval gate: commit draft and proposed state exactly once and create a snapshot.

Inputs: path (required), run_id (required).

build_contextC

Create a run and record an inspectable context packet for one chapter.

Inputs: path (required), chapter_id (required), run_id.

generate_draftC

Generate and record a draft with a configured provider; mock works offline.

Inputs: path (required), run_id (required), provider.

inspect_runB

Inspect run state, artifacts, and proposed state differences.

Inputs: path (required), run_id (required).

project_statusC

Return project status or one run's status.

Inputs: path (required), run_id.

review_runB

Review the recorded draft and create a state proposal for human approval.

Inputs: path (required), run_id (required).

submit_draftA

Record draft text produced by an external AI tool in an existing run.

Inputs: path (required), text (required), run_id (required).

validate_projectB

Validate a novel project without changing it.

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.5/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct action in the novel project workflow: validation, context building, draft generation, external submission, review, inspection, approval, and status. No overlapping purposes.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern in snake_case (e.g., validate_project, generate_draft, approve_run), providing clear and predictable naming.

    Tool Count5/5

    With 8 tools, the set is well-scoped for a novel writing assistant, covering the essential workflow stages without excess or deficiency.

    Completeness4/5

    Core CRUD-like operations are present: create (build_context), update (submit_draft, approve_run), read (project_status, inspect_run), delete is absent but not critical. Minor gap: no tool to list all runs or chapters, but the workflow is coherent.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Novel Workspace MCP

      LiZh132707
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI-driven long-form novel creation and management, including chapter generation, character and timeline tracking, semantic memory retrieval, version savepoints, and deep consistency checking across multiple projects through MCP tools, with support for local LM Studio or any OpenAI-compatible API.
      16
      MIT

    • canonkeeper-mcp

      zhangzhend0ng
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables long-form web novel writing workflows by ingesting chapters into a state database, running deterministic consistency checks, querying entity histories, replaying extraction results, and retrieving conflict reports via MCP tools.
      MIT

    • Goink MCP Server

      skeltandsz
      A
      license
      Not graded
      quality
      C
      maintenance
      Exposes 30+ novel-writing tools over stdio or HTTP so external agents such as Claude Code or WorkBuddy can use their own models and API keys to read chapters, write prose, manage characters, foreshadowing, story arcs and worldbuilding, run local semantic search, and launch review sub-agents. Supports one-click enabling with configurable port, token, and approval mode.
      AGPL 3.0