番茄小说搜索阅读MCP服务

番茄小说：MCP、独立 Skill 与本地 API

搜索番茄作品、查看小说目录和网站可见正文、读取书评；本人扫码登录后，还可以读取自己的书架、阅读进度和收藏划线原文。

当前版本：0.2.0-dev.6，GitHub开发预览版。 默认使用本机运行的数据核心，直接请求番茄官方站点，已取消对旧第三方开放API的默认依赖。独立Skill包含全部必需运行代码，只需要Node.js 22+和网络；MCP需要安装项目依赖。

下载本版 · 详细安装与使用 · 全部方法清单 · HTTP接口文档

本版发布到GitHub，未发布npm registry。不要用旧说明中的 npx -y @fysh925/mcp-server-fanqie 安装方式判断本版能力：registry里的旧包仍是旧架构。请使用本仓库源码或本版Release附件。

为什么重做：从第三方服务迁移到本地实现

旧版0.1.x的主要职责是把第三方服务封装成14个MCP工具，默认请求 http://101.35.133.34:5000。搜索、目录、正文和设备管理等能力由该第三方服务器提供。第三方地址不可用后，MCP工具虽然仍能列出，实际查询也会随之失效。

本次把数据获取实现放进项目本身：

• 本地实现公开查询：搜索、书籍详情、目录、网站可见章节、书评正文，直接访问官方入口。
• 同时提供MCP和独立Skill：两种入口共用核心，Skill不需要另外启动HTTP服务，也不依赖仓库外的运行代码。
• 新增本人账号能力：扫码登录、当前书架、云端阅读位置、收藏划线原文及翻页。
• 补齐使用与错误处理：目录分页、分类搜索游标、完整书评文本、故障重试、限流提示及本地索引后备。
• 明确能力边界：保留旧路径方便迁移，未实现的功能返回501；不把工具名称还存在当作功能已经完成。

本版解决的是旧第三方API这一中间依赖，仍需要联网访问番茄官方站点。官方接口、网页结构、字体或匿名设备规则变化后，仍可能需要维护。

对比旧第三方服务：本次实现了什么

“旧版范围”以仓库0.1.x的README和API封装为依据，只说明当时声明或转发了什么，不代表现在还可验证旧服务，也不保证新旧返回字段逐项相同。

结论：本版覆盖了公开搜索、书评、小说网站阅读和个人阅读数据的当前需求，并未完整复刻旧服务的音视频、漫画内容、设备池、iOS或整本下载能力。

当前MCP与Skill能调用哪些方法

以下Skill命令均由技能目录内的 scripts/fanqie.mjs 执行。源码用户可使用 node "server/cli.mjs" <命令>。

公开查询，无需账号登录

本人账号，需要扫码授权

辅助与兼容方法

MCP共注册22个工具，其中16个公开查询/本人账号工具、2个状态兼容工具、4个未实现工具。Skill/CLI有19个命令，含help和capabilities。参数、HTTP路径及边界见 完整清单。

我们如何实现

旧版调用链是“AI客户端 → MCP封装 → 第三方开放API → 数据”。本版默认调用链如下：

flowchart TD
    A[支持MCP的AI客户端] --> B[MCP工具层]
    B --> C[自动启动的本机HTTP API]
    D[Skill或终端CLI] --> E[共享数据核心]
    F[其他本机程序] --> C
    C --> E
    E --> G[公开查询客户端]
    E --> H[本人账号客户端]
    G --> I[番茄官网网页与目录接口]
    G --> J[官方小说搜索接口]
    G --> K[官方App搜索与书评接口]
    G --> L[本地元数据索引后备]
    H --> M[官方扫码登录与账号接口]
    H --> N[本机用户目录中的账号凭据]

数据来源与处理方式

小说公开搜索不需要签名或本人登录。书评与App分类搜索使用匿名设备参数和本地签名，内置公共示例设备可能失效，可配置配套的 FANQIE_DEVICE_ID、FANQIE_INSTALL_ID；不会自动注册设备或激活会员。个人书架和划线使用本人扫码的会话，与匿名设备配置是两条独立链路。

稳定性和数据边界

• 公开上游请求串行处理，最小间隔500毫秒，同一请求合并；缓存最多100项、有效期5分钟。网络中断或502/503/504最多重试一次，限流时返回等待时间。
• 个人响应不进入公开查询缓存，按本地账号配置分别存储；同一账号跨进程使用文件锁。账号请求不自动重试。
• 账号凭据默认在系统用户数据目录，可用 FANQIE_ACCOUNT_DIR 指定；不写入技能目录、源码仓库或发布包。不同系统不保证文件加密，请使用自己的受保护用户目录。
• 书架是当前书架，阅读进度是官方当前返回的云端记录；缺少进度不能推断从未读过。read_progress不直接当作百分比。
• 只有 has_more=false 才结束划线翻页。上游分页同时计算书签等记录，某页没有划线也可能还有下一页。
• HTTP API仅监听本机，拒绝浏览器Origin及非本机Host，可选Bearer Token；账号接口不面向公开部署或多租户服务。

安装：选择MCP或Skill

独立Skill：无需npm依赖

1. 下载 fanqie-novel-skill-0.2.0-dev.6.zip。
2. 将整个 fanqie-novel 文件夹放入客户端的技能父目录。Codex示例为Windows的 $HOME/.agents/skills/，macOS/Linux的 ~/.agents/skills/；其他客户端使用其支持的目录。
3. 确认 fanqie-novel/SKILL.md 和 fanqie-novel/scripts/runtime/ 都存在，不能只复制说明文件，也不要多套一层同名目录。
4. 重新加载技能或重启客户端，输入：$fanqie-novel 搜索《三体》，核对作者并查看前20章目录。

Skill ZIP包含全部必需运行代码；不需要另外安装Python、浏览器、npm包或启动MCP服务。仍需联网访问官方站点。

从克隆仓库安装Skill也可以，无需先安装npm依赖：

node "scripts/install-skill.mjs" --target "$HOME/.agents/skills"

支持GitHub路径的技能安装器可安装 fysh1010/mcp-server-fanqie 仓库的 skills/fanqie-novel 目录。更新时先备份或重命名原技能文件夹，安装脚本不会覆盖已有目录。

MCP：从源码或源码ZIP安装

git clone https://github.com/fysh1010/mcp-server-fanqie.git
cd mcp-server-fanqie
npm ci
npm run build

也可从Release下载源码ZIP，解压后在仓库根目录执行 npm ci 和 npm run build。

支持mcpServers格式的客户端可使用以下JSON配置；其他客户端按其MCP配置格式填写相同command和args：

{
  "mcpServers": {
    "fanqie": {
      "command": "node",
      "args": ["D:/你的路径/mcp-server-fanqie/server/mcp-local.mjs"]
    }
  }
}

将args改为本机真实绝对路径。macOS/Linux填写对应的 /Users/... 或 /home/... 路径。若客户端找不到node，将command改为Node可执行文件的绝对路径。重新加载MCP连接后即可搜书，无需先运行 start:api。

Release也提供本地npm安装用的 .tgz；安装步骤见 使用指南。不要把旧npm包名的npx配置当作本版安装方法，也不要将本机路径填写到无法访问本机文件的云端托管环境。

使用：可以直接告诉AI什么

无需登录

• “搜索《三体》，核对作者，查看前20章目录。”
• “读取这本书第三章，概括情节。”
• “获取这本书20条书评，整理读者评价。”
• “搜索带‘重生’的短剧，再看下一页。”

CLI也可以直接运行：

node "server/cli.mjs" search "三体"
node "server/cli.mjs" search "绝世武神" --type manga
node "server/cli.mjs" search "重生" --type drama
node "server/cli.mjs" comments "7143038691944959011" --count 20
node "server/cli.mjs" directory "7143038691944959011" --offset 0 --limit 20

本人书架、阅读进度与收藏划线

1. 告诉AI：“连接我的番茄账号，让我扫码。”AI调用 start_account_login 或Skill的login-start并展示二维码。
2. 按二维码返回的官方提示，用本人已登录的手机App扫码并确认；当前官方可能提示使用抖音App，以实际说明为准。
3. AI每隔至少3秒检查登录结果，status=connected 才算完成。二维码约5分钟有效，过期重新生成。
4. 先说“查看我的书架”，核对是否对应自己的番茄账号。
5. 再说“列出我有划线的书，读取其中一本的全部收藏划线，按章节整理”。AI会使用cursor翻页。
6. 要清除本机登录时，说“断开我的番茄账号”。

MCP和Skill在相同系统用户、相同账号目录配置下可共用登录状态。多账号使用不同account本地配置名，并分别扫码。账号名不是平台用户ID，不能凭别人的ID读取私人数据。不要把密码或Cookie发送到聊天里。

终端用户使用 login-start → login-poll → bookshelf / reading-progress / highlight-books / highlights；可运行示例、分页字段和退出说明见 详细使用指南。

独立HTTP API

npm run start:api

默认地址为 http://127.0.0.1:5000。示例：

Invoke-RestMethod "http://127.0.0.1:5000/health"
Invoke-RestMethod "http://127.0.0.1:5000/api/search?key=三体"
Invoke-RestMethod "http://127.0.0.1:5000/api/account/status?account=default"

成功返回 { "code": 200, "message": "success", "data": ... }，失败同时使用真实HTTP状态码及业务码。接口清单、参数、Token和端口配置见 HTTP文档。

更新、排错与验证

• 更新源码MCP：确认自己已保存本地修改，再执行 git pull --ff-only、npm ci、npm run build，重新加载MCP连接。
• 更新Skill：先备份或重命名旧技能目录，再解压新ZIP或运行安装脚本；重新发现技能。不要只更新SKILL.md。
• 401或账号过期：重新扫码，不把失败结果当成空书架。
• 403章节权限错误：官网未提供可读权限，当前实现无法读取。
• 429限流：按响应的retry_after提示等待；账号接口未返回等待秒数时稍后重试，勿循环请求。
• 409 ACCOUNT_BUSY：同一账号正在处理另一请求，完成后再试。
• 503 LOCAL_BUSY：公开请求队列繁忙，减少并发后重试。
• 评论/分类搜索匿名设备失效：配置配套的FANQIE_DEVICE_ID、FANQIE_INSTALL_ID；本人扫码登录与该匿名设备配置无关。
• 搜索结果source=local_index：只表示有限本地索引，不能推断全站没有该书。

构建与离线测试：

npm run build
npm test

当前34项离线测试覆盖解析、权限、字体、分页、签名、限流、账号隔离、登录跳转、划线游标、MCP调用与独立Skill安装。node "server/smoke.mjs" 额外执行少量公开样本在线验证；个人账号功能另经本人扫码实测，公开测试和仓库示例不包含真实账号凭据或私人划线。

历史协议实验单独记录在 EXPERIMENTS.md，实验成功不代表对应能力已经集成本版。依赖审计与发布验证信息见本版Release说明。

项目结构与许可

src/                         MCP工具定义、客户端封装、字体映射
build/                       已编译MCP代码
server/                      公开数据核心、账号核心、HTTP与CLI、测试
skills/fanqie-novel/          可独立安装的完整Skill
scripts/build-skill.mjs       从共享核心生成Skill运行文件
scripts/install-skill.mjs     安装完整技能目录，不覆盖已有安装
docs/USAGE.md                详细安装、登录、分页和排错
docs/FUNCTIONS.md            全部能力、MCP/Skill/HTTP方法对照

修改核心后执行 npm run build 同步Skill运行文件；无需维护第二套爬虫。运行使用Node.js 22+，Python仅用于开发者打包ZIP，不是用户运行依赖。

MIT。本项目为非官方工具，内容版权归原平台及权利人所有。本地签名代码的MIT参考来源与许可见 第三方说明，相关许可证随独立Skill分发。

Star History

下图展示本仓库GitHub Star数量随时间的变化，点击可打开交互页面。图表由 Star History 生成。