mcp-server-fanqie (deepseek-harness)
fysh1010/mcp-server-fanqie/plugins/deepseek-harness
Lecteur Fanqie pour la barre latérale de DeepSeek Harness : recherche de métadonnées de livres et médias, exploration des couvertures et listes de chapitres, lecture des chapitres visibles sur le site, et affichage de la bibliothèque et des passages enregistrés après connexion par QR.
Installer
dsh plugin --profile web add github:fysh1010/mcp-server-fanqieCe plugin se trouve dans le sous-répertoire plugins/deepseek-harness du dépôt.
README
番茄小说：MCP、独立 Skill 与 DeepSeek Harness 阅读插件
搜索番茄作品、查看小说目录和网站可见正文、读取书评；本人扫码登录后，还可以读取自己的书架、阅读进度和收藏划线原文。
项目提供三种入口：MCP 服务、独立 Skill、DeepSeek Harness 图形插件，另有命令行和本地 HTTP API。各入口复用本机数据核心，直接访问番茄官方站点。
**版本说明：**MCP / Skill 历史 Release 为 0.2.0-dev.6；DeepSeek Harness 插件为源码中的 0.4.0。旧 Release 不含该插件，应从当前仓库获取插件。
安装与使用 · Harness 插件 · 功能清单 · HTTP API · 历史 Release
当前插件尚未发布到 npm；旧 npm 包
@fysh925/mcp-server-fanqie也不包含此开发预览版。请使用仓库源码或对应的历史 Release，不要使用旧 npm 包判断当前功能。
三种使用方式
- MCP：为支持 MCP 的 AI 客户端提供番茄搜索、阅读和本人账号数据查询。当前开发预览版请按使用指南从源码或 Release 安装。
- 独立 Skill：在支持 Skill 和 Node.js 22+ 的客户端中使用，技能目录包含独立运行文件。安装方法见使用指南。
- DeepSeek Harness 插件：在右侧栏搜索、查看封面和目录、阅读网站可见章节；本人扫码后查看书架和收藏划线，并提供对话工具。详见插件文档。
DeepSeek Harness 插件是独立包 dsh-fanqie-reader；它与上文提到的 MCP 包 @fysh925/mcp-server-fanqie 是不同的 npm 包。插件当前支持的媒体范围和账号使用方式见插件文档。
为什么重做：从第三方服务迁移到本地实现
旧版0.1.x的主要职责是把第三方服务封装成14个MCP工具，默认请求 http://101.35.133.34:5000。搜索、目录、正文和设备管理等能力由该第三方服务器提供。第三方地址不可用后，MCP工具虽然仍能列出，实际查询也会随之失效。
本次把数据获取实现放进项目本身：
- 本地实现公开查询：搜索、书籍详情、目录、网站可见章节、书评正文，直接访问官方入口。
- 提供 MCP、独立 Skill 和 Harness 插件：三种入口复用核心；Skill 可以独立运行，Harness 插件提供图形界面和对话工具。
- 新增本人账号能力：扫码登录、当前书架、云端阅读位置、收藏划线原文及翻页。
- 补齐使用与错误处理：目录分页、分类搜索游标、完整书评文本、故障重试、限流提示及本地索引后备。
- 明确能力边界：保留旧路径方便迁移，未实现的功能返回501；不把工具名称还存在当作功能已经完成。
本版解决的是旧第三方API这一中间依赖，仍需要联网访问番茄官方站点。官方接口、网页结构、字体或匿名设备规则变化后，仍可能需要维护。
对比旧第三方服务：本次实现了什么
“旧版范围”以仓库0.1.x的README和API封装为依据，只说明当时声明或转发了什么，不代表现在还可验证旧服务，也不保证新旧返回字段逐项相同。
| 能力 | 旧版第三方依赖范围 | 当前MCP | 当前Skill | 本版实际行为与边界 |
|---|---|---|---|---|
| 小说关键词搜索 | 转发第三方搜索 | 支持 | 支持 | 官方免签名搜索，支持offset翻页 |
| 听书搜索 | 转发第三方分类搜索 | 支持 | 支持 | 官方App只读搜索，本地生成签名 |
| 漫画搜索 | 转发第三方分类搜索 | 支持 | 支持 | 仅搜索与基本元数据；可能混入推荐 |
| 短剧搜索 | 转发第三方分类搜索 | 支持 | 支持 | 仅搜索与基本元数据；支持cursor翻页 |
| 小说详情 | 转发第三方详情 | 支持 | 支持 | 从官网页面数据提取规范化字段 |
| 分卷目录 | 转发第三方完整目录 | 支持 | 支持 | 默认每页50章，上限200章 |
| 简化目录 | 转发第三方简化目录 | 支持 | 使用directory | MCP/API可只返回标题与ID |
| 单章小说正文 | 转发第三方内容 | 部分支持 | 部分支持 | 网站可见正文；不保证与App全文一致 |
| 批量小说正文 | 转发第三方批量接口 | 支持 | 支持 | 每批最多20章，逐章校验书籍归属 |
| 原始章节数据 | 转发第三方原始内容 | 支持 | 支持 | 官网章节字段及解析正文 |
| 书评正文与翻页 | 旧文档声明评论列表 | 支持 | 支持 | 保留正文、评分、点赞、回复数及cursor；这里只读取整本书的书评 |
| 章评、段评、楼中楼正文 | 旧文档对评论范围有宽泛描述 | 未实现 | 未实现 | 不把书评当作其他评论类型 |
| 听书音频播放 | 旧统一内容接口声明支持 | 未实现 | 未实现 | 搜索可用，音频内容未接入 |
| 短剧视频播放 | 旧统一内容接口声明支持 | 未实现 | 未实现 | 搜索可用，视频内容未接入 |
| 漫画图片、下载任务与进度 | 旧统一内容与任务接口声明支持 | 未实现 | 未实现 | 任务进度兼容入口返回501 |
| 整本下载 | 旧统一内容接口声明支持 | 未实现 | 未实现 | 可按目录批量查询，未提供整本任务或导出 |
| Android设备注册、设备池 | 旧版依赖服务端设备管理 | 未实现真实管理 | 无命令 | 两个状态工具只返回网页模式说明；注册返回501 |
| iOS注册及专用正文 | 旧版依赖iOS服务 | 未实现 | 无命令 | 保留接口，返回501 |
| 本人扫码登录与本地退出 | 原14个工具未提供 | 新增 | 新增 | 手机本人确认，凭据只保存在本机 |
| 本人书架及阅读位置 | 原14个工具未提供 | 新增 | 新增 | 当前书架、云端可用阅读记录及当前章节 |
| 有收藏的书及数量 | 原14个工具未提供 | 新增 | 新增 | 划线数、书签数、笔记数 |
| 本人收藏划线原文 | 原14个工具未提供 | 新增 | 新增 | 原文、章节、位置、修改时间与cursor翻页 |
| 独立撰写的笔记/想法正文 | 原14个工具未提供 | 未实现 | 未实现 | 可读笔记数量，尚不读取笔记正文 |
| 本地元数据索引 | 原14个工具未提供 | 无专用工具 | 新增 | 通过CLI/API导入和刷新，小说搜索故障时明确标记降级 |
结论：本版覆盖了公开搜索、书评、小说网站阅读和个人阅读数据的当前需求，并未完整复刻旧服务的音视频、漫画内容、设备池、iOS或整本下载能力。
当前MCP与Skill能调用哪些方法
以下Skill命令均由技能目录内的 scripts/fanqie.mjs 执行。源码用户可使用 node "server/cli.mjs" <命令>。
公开查询，无需账号登录
| MCP工具 | Skill/CLI命令 | 用户可以做什么 |
|---|---|---|
search_books | search | 搜索小说、听书、漫画、短剧；关键词与分类保持不变继续翻页 |
get_book_detail | detail | 查看书名、作者、简介、字数及最新章节等 |
get_book_directory | directory | 分页查看含分卷信息的章节目录 |
get_simple_directory | 无独立命令，可使用directory | 获取简化的章节标题、ID列表 |
get_chapter_content | chapter | 读取一个网站可见章节 |
get_content | chapter / batch | 统一单章与批量正文入口，每批最多20章 |
get_raw_content | raw | 查看原始章节数据及解析后的正文 |
get_comments | comments | 获取整本书的书评正文、评分、点赞数和回复数 |
本人账号，需要扫码授权
| MCP工具 | Skill/CLI命令 | 用户可以做什么 |
|---|---|---|
start_account_login | login-start | 获取本人登录二维码 |
poll_account_login | login-poll | 检查扫码、确认和登录完成状态 |
get_account_status | account-status | 检查本地账号登录是否有效 |
get_my_bookshelf | bookshelf | 查看当前官方书架及已同步的阅读位置 |
get_my_reading_progress | reading-progress | 查看云端阅读记录、书名、当前章节，可筛选一本书 |
get_my_highlight_books | highlight-books | 查找有收藏记录的书及划线、书签、笔记数量 |
get_my_highlights | highlights | 分页读取自己收藏的划线原文及位置 |
logout_account | logout | 清除本机该配置的凭据，不更改官方书架、进度或收藏 |
辅助与兼容方法
| MCP工具 | Skill/CLI命令 | 实际作用 |
|---|---|---|
| 无 | index-import | 从官网录入指定书籍的元数据 |
| 无 | index-refresh | 刷新官网首页可发现的书籍索引 |
| 无 | capabilities | 查看当前能力清单 |
| 无 | help | 显示命令和参数帮助 |
get_device_pool_status | 无 | 返回网页模式说明，不管理真实设备池 |
get_device_status | 无 | 返回网页模式说明，不验证真实App设备 |
register_device | 无 | 尚未实现，返回501 |
get_ios_content | 无 | 尚未实现，返回501 |
register_ios_device | 无 | 尚未实现，返回501 |
get_manga_progress | 无 | 尚未实现，返回501 |
MCP共注册22个工具，其中16个公开查询/本人账号工具、2个状态兼容工具、4个未实现工具。Skill/CLI有19个命令，含help和capabilities。Harness 插件另注册7个 fanqie_* 对话工具，并提供图形界面；它们与 MCP 的22个工具不是一一对应。参数、HTTP路径及边界见 完整清单。
我们如何实现
旧版调用链是“AI客户端 → MCP封装 → 第三方开放API → 数据”。本版默认调用链如下：
flowchart TD
A[支持MCP的AI客户端] --> B[MCP工具层]
B --> C[自动启动的本机HTTP API]
D[Skill或终端CLI] --> E[共享数据核心]
P[Harness右侧栏与对话工具] --> Q[插件Host]
Q --> E
F[其他本机程序] --> C
C --> E
E --> G[公开查询客户端]
E --> H[本人账号客户端]
G --> I[番茄官网网页与目录接口]
G --> J[官方小说搜索接口]
G --> K[官方App搜索与书评接口]
G --> L[本地元数据索引后备]
H --> M[官方扫码登录与账号接口]
H --> N[本机用户目录中的账号凭据]
数据来源与处理方式
| 模块 | 实现方式 | 主要代码 |
|---|---|---|
| 小说搜索 | 请求官方 novel.snssdk.com 轻量搜索；失败时尝试官网后备和有限本地索引；降级结果明确标记范围 | server/core.mjs、server/local-index.mjs |
| 听书/漫画/短剧搜索 | 请求 reading.snssdk.com/reading/bookapi/search/tab/v，按book_data/video_data解析类别；保留官方推荐标记与翻页游标 | server/app.mjs、server/core.mjs |
| 书评正文 | 请求官方commentapi只读列表，保留完整文本和分页会话；不在客户端截断正文 | server/core.mjs、server/app.mjs |
| 本地请求签名 | 使用Node原生加密实现签名，无需公共签名服务；MIT来源及许可随包附带 | server/sign.mjs、第三方说明 |
| 小说详情 | 读取官网页面的JSON初始数据，直接解析，不执行页面脚本 | server/core.mjs |
| 目录和网站正文 | 目录走官网接口；章节提取可见数据，使用已知字体映射转换字符；锁定、未知字体或残余乱码明确报错 | server/core.mjs、src/fontDecrypt.ts |
| 扫码与会话 | 官方二维码、本人手机确认、手动保留跳转中的Cookie；成功后验证阅读进度接口，凭据持久化到本机 | server/accounts.mjs |
| 书架与进度 | 读取官方书架和进度，再按book_id关联书籍详情、章节标题；保留上游进度值，不猜测百分比 | server/accounts.mjs |
| 收藏划线 | 先列出有收藏的书，再读取官方bookmark列表；初次带next_id=0，后续cursor同时携带两项上游分页标记；区分划线和普通书签 | server/accounts.mjs |
| 三种入口复用 | MCP通过本地API调用核心；Skill和Harness插件分别使用同步的核心运行文件，可独立安装 | src/、scripts/build-skill.mjs、plugins/deepseek-harness/ |
小说公开搜索不需要签名或本人登录。书评与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；账号接口不面向公开部署或多租户服务。
安装：选择适合的入口
| 入口 | 前置要求 | 是否手动启动API |
|---|---|---|
| MCP | Node.js 22+、项目npm依赖、支持MCP的客户端 | 不需要，自动启动随机本地端口API |
| 独立Skill | Node.js 22+、支持Skills且能执行本地脚本的客户端 | 不需要，直接运行核心代码 |
| DeepSeek Harness 插件 | 支持插件的 Harness 桌面端；已记录 0.2.1-rc.5 的桌面验证 | 不需要，插件 Host 调用内置核心 |
| CLI | Node.js 22+和完整代码 | 不需要 |
| HTTP API | Node.js 22+和项目依赖 | 单独启动，默认127.0.0.1:5000 |
DeepSeek Harness：图形界面与对话工具
- 克隆或下载当前仓库，保留完整的
plugins/deepseek-harness/目录，包括vendor/。 - 在 Harness 的插件管理页选择该目录安装，或在会话中让智能体通过
plugin_manager install_bundle安装该目录的绝对路径。 - 按需刷新或重启 Harness，打开右侧栏的「+」开始页，选择「番茄阅读」。
- 在界面搜索、浏览目录和阅读；查看本人书架与划线时，在「我的」页面按官方提示扫码。
插件还提供7个 fanqie_* 对话工具。它与 MCP/Skill 可分别使用，账号凭据默认沿用核心的本机存储方式；具体路径可能因打包环境而不同。安装与卸载详见 插件文档。插件目前未发布到 npm，历史 0.2.0-dev.6 Release 也不含它。
独立Skill：无需npm依赖
- 下载 fanqie-novel-skill-0.2.0-dev.6.zip。
- 将整个
fanqie-novel文件夹放入客户端的技能父目录。Codex示例为Windows的$HOME/.agents/skills/，macOS/Linux的~/.agents/skills/；其他客户端使用其支持的目录。 - 确认
fanqie-novel/SKILL.md和fanqie-novel/scripts/runtime/都存在，不能只复制说明文件，也不要多套一层同名目录。 - 重新加载技能或重启客户端，输入：
$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
本人书架、阅读进度与收藏划线
- 告诉AI：“连接我的番茄账号，让我扫码。”AI调用
start_account_login或Skill的login-start并展示二维码。 - 按二维码返回的官方提示，用本人已登录的手机App扫码并确认；当前官方可能提示使用抖音App，以实际说明为准。
- AI每隔至少3秒检查登录结果，
status=connected才算完成。二维码约5分钟有效，过期重新生成。 - 先说“查看我的书架”，核对是否对应自己的番茄账号。
- 再说“列出我有划线的书，读取其中一本的全部收藏划线，按章节整理”。AI会使用cursor翻页。
- 要清除本机登录时，说“断开我的番茄账号”。
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 生成。
Plugins associés
dsh-web (dsh-task-board)
zhu1090093659/dsh-web
dsh-web (dsh-web-all)
zhu1090093659/dsh-web
dsh-TUI
ccch1mneyyy/dsh-tui
dsh-web-ui (dsh-task-board)
zhu1090093659/dsh-web-ui