FastMCP 小说处理工具

基于 FastMCP 的智能小说处理工具，支持小说分割、批量改写任务管理，提供 Web 界面和 MCP 服务双模式。

说明：当前未发布到 PyPI/uvx，请从源码本地运行。

✨ 核心功能

• 📄 智能分割 - 按 Token 数精确分割小说，支持多种编码格式

• 🔄 批量改写 - 创建和管理批量改写任务，支持自动检测和重试

• 📝 提示词管理 - 灵活的提示词配置和管理系统

• 🌐 Web 界面 - 美观友好的可视化操作界面

• 🔌 MCP 集成 - 与 Cursor 编辑器无缝集成

🚀 快速开始（从源码运行）

1. 安装依赖

cd fastmcp
uv sync

如未安装 uv，参考 https://github.com/astral-sh/uv。也可直接用系统 Python 运行（建议仍用 uv 管理依赖）。

2. 启动 Web 界面

# 使用 Python 运行
python app.py --work-dir "<WORK_DIR>"

# 或使用 uv 运行
uv run app.py --work-dir "<WORK_DIR>"

启动后访问：http://127.0.0.1:8298/ （示例：<WORK_DIR> 可设置为 /path/project，<FASTMCP_DIR> 为 项目所在位置）

界面预览（UI）

🔌 MCP 部署（Cursor）

在 Cursor 设置中配置 mcp.json，使用本地源码运行。提供两种方案：

方案 A：使用 uv 运行（推荐）

{
  "mcpServers": {
    "novel-processor-local": {
      "command": "uv",
      "args": [
        "--directory",
        "<FASTMCP_DIR>",
        "run",
        "main.py",
        "--work-dir",
        "<WORK_DIR>"
      ]
    }
  }
}

方案 B：使用 Python 运行

{
  "mcpServers": {
    "novel-processor-local": {
      "command": "python",
      "args": ["<FASTMCP_DIR>\\main.py", "--work-dir", "<WORK_DIR>"]
    }
  }
}

配置完成后，即可在 Cursor 中调用 MCP 工具进行任务领取、改写与回写。

📖 使用说明

工作目录结构

工作目录会自动创建以下结构：

工作目录/
├── .batch_task/          # 任务管理目录（自动创建）
│   ├── tasks.json        # 任务列表
│   ├── logs/            # 日志文件
│   └── prompts/         # 提示词文件
└── output/              # 输出目录
    └── 项目名/
        ├── 原文/        # 分割后的原文
        └── 改写/        # 改写后的文件

端到端工作流程

1. 分割小说（Web）

• 访问首页，上传或选择小说文件

• 设置分割参数（Token 数、项目名等）

• 点击“分割”，生成分段文件并保存到 output/项目名/原文/

2. 创建批量改写任务（Web）

• 打开“任务管理”页面

• 选择项目与提示词，批量创建任务（写入 .batch_task/tasks.json）

3. 执行任务（Cursor MCP）

• 在 Cursor 中调用 run_task 获取待处理任务

• 按提示词改写内容并写入输出文件

• 调用 complete_task 标记完成（失败可重试）

4. 检查与导出

• 在 Web“任务管理/日志”查看状态与日志

• 在 output/项目名/改写/ 获取改写后的最终文本

命令行参数

python app.py [选项]

选项：
  --work-dir DIR          工作目录路径（默认：../）
  --host HOST            服务器地址（默认：127.0.0.1）
  --port PORT            服务器端口（默认：8298）
  --batch-task-dir DIR   批处理目录名（默认：.batch_task）
  --log-level LEVEL      日志级别（debug/info/warning/error）

🔧 技术栈

• 后端框架：FastMCP + Starlette + Uvicorn

• 前端：Vue.js 3 + TailwindCSS

• 依赖管理：uv

• Token 计算：tiktoken (cl100k_base)

📦 项目结构

fastmcp/
├── main.py              # MCP 服务入口
├── app.py               # Web 服务入口
├── config.py            # 配置文件
├── run-server.bat       # Windows 启动脚本（可选，不再作为推荐方式）
├── src/                 # 核心代码
│   ├── server.py        # MCP 服务器
│   ├── routes.py        # Web 路由
│   ├── task_manager.py  # 任务管理
│   ├── novel_processor.py # 小说处理
│   ├── workspace_manager.py # 工作区管理
│   └── ...
└── static/              # Web 界面
    ├── index.html       # 小说分割界面
    ├── tasks.html       # 任务管理界面
    └── prompt.html      # 提示词管理界面

📝 注意事项

1. 工作目录：建议为每个小说项目单独创建工作目录

2. 编码支持：自动检测 UTF-8、GBK、GB2312、Big5 等编码

3. Token 计算：使用 OpenAI 的 cl100k_base 编码器，适配 GPT-3.5/GPT-4

4. 任务状态：任务会自动检测超时和错误，支持重试

5. 日志记录：所有操作都有详细日志，位于 .batch_task/logs/ 目录

🛠️ 常见问题

Q: 如何更改默认端口？
A: 使用 --port 参数，如：python app.py --port 8080

Q: 提示词文件应该放在哪里？
A: 放在工作目录的 .batch_task/prompts/ 目录中，支持 .md 和 .txt 格式

Q: 如何查看任务执行日志？
A: 查看工作目录的 .batch_task/logs/ 目录中的日志文件

Q: MCP 服务和 Web 服务可以同时运行吗？
A: 可以，它们使用相同的工作目录和任务文件，数据会自动同步

❓ 为什么选择本项目

直接调用模型 API 处理长文本时，常出现“压缩式回答”（过度缩减、遗漏细节）。本项目通过：

• 分段+批处理流水线：将长篇文本按 Token 精准切分，逐段稳定处理

• 提示词可控：在 .batch_task/prompts/ 集中管理提示词，保证一致性

• 与 Cursor 深度集成：利用 Cursor 的上下文与智能编辑能力，获得可控且高质量的输出

• 自动化任务编排：状态跟踪、错误重试、日志留存，提升长流程的可靠性

📄 许可证

MIT License