mcp（Bun + MCP 标准 stdio）

这是一个基于 Bun 的 MCP 基础项目框架，使用标准 stdio 传输协议，适合接入 Claude Desktop / Cursor 等 MCP 客户端。

安装依赖

bun install

启动方式

开发模式（热更新）：

bun run dev

标准启动：

bun run start

当前内置工具

• read_novel_line：按游标增量读取小说文本
• get_progress：获取已切分进度（下一章节号/下一游标）
• validate_chapter_draft：章节草稿质检（提示建议，不拦截）
• save_chapter：同时保存原文章节与清洗后章节，并写入元信息索引

小说文件放置

默认从 novels 目录读取文本文件：

/Users/tietiezhi/Project/mcp/novels

例如小说名传 斗破苍穹，默认读取：

novels/斗破苍穹.txt

也可通过环境变量覆盖目录：

NOVELS_DIR=/your/path bun run start

工具入参

• novel_name：小说名（或 .txt 文件名）
• cursor：起始字符索引（首次通常传 0）
• max_lines：本次最多返回行数（可选，默认 1，最大 20）
• target_chars：本次目标读取字符数（可选，达到即停止，最大 5000）
• 返回包含 batch_text 与 batch_chars，方便智能体直接累计
• 若文本无换行，工具会优先按标点等语义边界切片，必要时再按字符硬切

get_progress：

• novel_name：小说名称
• 返回 next_chapter_no 与 next_cursor，用于断点续跑

validate_chapter_draft：

• clean_text：待质检章节正文
• min_chars/max_chars：建议字数范围（默认 600/1000）
• 返回 issues、in_range、标题/作者/前言/网址检测结果与建议

save_chapter：

• novel_name：小说名称
• chapter_no：章节序号（从 1 开始）
• start_cursor：章节起始游标
• end_cursor：章节结束游标
• chapter_chars：章节字数
• min_chars：章节最小字数（可选，默认 600）
• max_chars：章节最大字数（可选，默认 1000）
• allow_out_of_range：允许超范围保存（可选，默认 true）
• enforce_clean_guard：启用 clean 文本前部质检（可选，默认 false）
• split_reason：切分理由（可选）
• raw_text：原始章节正文（未清洗）
• clean_text：清洗后的章节正文

章节输出目录

默认写入：

/Users/tietiezhi/Project/mcp/chapters/<novel_name>/

文件说明：

• 0001.raw.txt：原始章节正文（含头部元信息）
• 0001.clean.txt：清洗后章节正文（含头部元信息）
• index.jsonl：章节索引，每行一条 JSON 元信息

可通过环境变量覆盖：

CHAPTERS_DIR=/your/output/path bun run start

推荐调用流程（智能体）

1. 先调用 get_progress 获取 next_chapter_no 与 next_cursor。
2. 循环调用 read_novel_line（建议结合 max_lines + target_chars 控制批次）。
3. AI 在对话内完成去杂质与章节切分。
4. 每章保存前调用 validate_chapter_draft 做自检。
5. 每章调用 save_chapter 写入 raw_text 与 clean_text。
6. 重复步骤 2-5，直到 eof=true。

save_chapter 内置一致性校验：

• 章节号必须连续
• start_cursor 必须等于上一章 end_cursor
• chapter_chars 必须等于 clean_text.length
• 可选开启字数范围限制（allow_out_of_range=false）
• 可选开启 clean 文本前部拦截（enforce_clean_guard=true）

目录结构

.
├── index.ts              # 根入口，启动 MCP 服务
└── src
    ├── main.ts           # stdio transport 启动逻辑
    ├── server.ts         # MCP Server 创建与工具注册
    ├── config.ts         # 服务基础配置（name/version）
    ├── tools
    │   ├── getProgress.ts
    │   ├── readNovelLine.ts
    │   ├── validateChapterDraft.ts
    │   └── saveChapter.ts
    └── types
        └── tool.ts       # 工具返回类型

类型检查

bunx tsc --noEmit