# FastMCP 小说处理工具
基于 FastMCP 的智能小说处理工具，支持小说分割、批量改写任务管理，提供 Web 界面和 MCP 服务双模式。
> 说明：当前未发布到 PyPI/uvx，请从源码本地运行。
## ✨ 核心功能
- 📄 **智能分割** - 按 Token 数精确分割小说，支持多种编码格式
- 🔄 **批量改写** - 创建和管理批量改写任务，支持自动检测和重试
- 📝 **提示词管理** - 灵活的提示词配置和管理系统
- 🌐 **Web 界面** - 美观友好的可视化操作界面
- 🔌 **MCP 集成** - 与 Cursor 编辑器无缝集成
## 🚀 快速开始（从源码运行）
**1. 安装依赖**
```bash
cd fastmcp
uv sync
```
> 如未安装 `uv`，参考 `https://github.com/astral-sh/uv`。也可直接用系统 Python 运行（建议仍用 `uv` 管理依赖）。
**2. 启动 Web 界面**
```bash
# 使用 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 运行（推荐）**
```json
{
"mcpServers": {
"novel-processor-local": {
"command": "uv",
"args": [
"--directory",
"<FASTMCP_DIR>",
"run",
"main.py",
"--work-dir",
"<WORK_DIR>"
]
}
}
}
```
**方案 B：使用 Python 运行**
```json
{
"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/项目名/改写/` 获取改写后的最终文本
### 命令行参数
```bash
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
