# 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）

![首页 - 文本分割](images/01.png)

![任务管理](images/02.png)

![提示词管理](images/03.png)

## 🔌 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