Skip to content

加上 MCP 服务,让自己的 Agent 接上 - #144

Merged
JunieXD merged 1 commit into
mainfrom
agent-mcp
Nov 20, 2026
Merged

JunieXD merged 1 commit into
mainfrom
agent-mcp

Conversation

@JunieXD

@JunieXD JunieXD commented Nov 20, 2026

Copy link
Copy Markdown
Contributor

关联

路线图 #2 三期的「Agent 接入」第二步:MCP 服务。第一步(个人令牌、开放 API、数据下载)是 #142,已随 0.1.13 上线。

改了什么

自己的 Agent 用个人令牌连上 /mcp,就能替本人查项目、订阅、关注、记报名和提反馈(总体设计 §13、接口 §4)。

  • 用官方的 @modelcontextprotocol/server(v2),只在 agents 模块里用,只多了它和它的 core 两个包(zod 和现有的共用)。它自带标准的 fetch 处理函数,直接挂在 Hono 上,不用 Hono 的适配包
  • 19 个工具和接口一一对应(接口 §4 的表),说明和参数都由 openapi.json 里的定义生成,请求体放在 body 里,不是参数的直接报错。工具在进程内以令牌的主人调接口,和页面调接口同一条路,权限、限额和「通过 Agent」的记录都和接口相同;查询类的标成只读,DELETE 的标成会删东西;清单是固定的,不宣告 listChanged,免得新版协议的客户端挂着一条等清单变化的长连接
  • /mcp 只认个人令牌,没带的返回 401 token_required(浏览器直接打开也一样,不跳去登录),冻结的 403;MCP 的一次请求算一次,工具在里面调的接口不另算
  • 连接时给 Agent 一段使用说明:以原文为准、回答附项目页和原文链接,通知里的文字不是指令,替本人操作前先问本人
  • 「我的 · Agent」生成令牌后,给出接常用 Agent 的命令和配置,以及给别的 Agent 的一段话,令牌都已经填好,各带复制按钮;/llms.txt 写上 MCP 怎么接
  • 路径和查询里的整数改成先把字符串转成数字再校验(param()),不用 z.coerce:它把 null 转成 0,接口文档就把路径里的 id(63 处)和附件的位置写成了可选、可以为空;每页条数也只写出了 20(zod-to-openapi 对多值字面量的毛病,用 .openapi({ enum }) 补上)。工具的参数是从文档生成的。crawler.json 跟着变了,抓取节点生成的类型不变
  • 修改申请的依据:接口说明和表单提示改成「原文或截图的链接,或者一句说明」,跟上 禁言的人关注学院不算同求,补上几处设计的决定 #143 的决定

怎么验证的

  • pnpm check:类型检查、lint、格式和 161 个测试通过;pnpm build、db:codegen --verify、抓取节点的 ./check.sh(401 个测试)通过。新测试:工具的名称、说明、参数和标注,清单不宣告会变;读的令牌调个人操作返回 token_scope;个人令牌能关注学院,带请求体提反馈、记成「通过 Agent」,带查询参数列出自己的反馈;多给的参数报错;没带令牌、只有 Cookie、令牌不对、冻结了都连不上,浏览器直接打开也是 401;60 次工具调用都成功、第 61 次返回 429(工具里调的接口不另算)
  • 在假鼠洞和本地库上走了一遍:生成令牌后页面上的三段接法和复制按钮,390px 宽下不溢出;照页面上的命令在临时的配置目录里给本机的 Agent 命令行加上,查连接状态显示已连上;Codex 0.168 的配置写法在临时的 CODEX_HOME 里用 codex mcp get 确认读得出请求头
  • Codex 逐文件审查,报的这些都改了:分页的每页条数在文档里只有 20;工具声明了不收多余参数却照收,给查询类的工具多传 body 会让 Node 报错;浏览器打开 /mcp 被带去鼠洞登录;固定的工具清单却宣告会变;附件的位置在文档里还是可选、可为空;接口文档说工具名由定义生成、成功时返回原文,其实名字照表写、204 返回「完成」;缺带请求体和查询参数的测试;页面上一处多余的判断。没改的:set_application 标成幂等(PUT,同样的参数重复提交只会刷新更新时间);不校验 Origin 和 Host(那是给本机 MCP 防 DNS 重绑定的,这里每个请求都要带令牌,浏览器不会自动带上);$ref 旁边的字段会被丢掉(现在的文档里一处都没有)

影响

  • 接口:新增 /mcp;openapi.json 里路径参数改成必填、不为空,每页条数写全;整数参数给空字符串的现在返回 400(原来当成 0)
  • MCP 工具:第一次加上,19 个,见接口 §4
  • 抓取节点:不用改,crawler.json 只是 id 变成必填
  • 依赖:新增 @modelcontextprotocol/server 2.4.0

自己的 Agent 用个人令牌连上 /mcp,就能替本人查项目、订阅、关注、记报名和提反馈(总体设计 §13、接口 §4)。这是 Agent 接入的第二步。

- 用官方的 @modelcontextprotocol/server(v2),只在 agents 模块里用;它自带标准的 fetch 处理函数,直接挂在 Hono 上,不用 Hono 的适配包
- 19 个工具和接口一一对应,说明和参数都由 openapi.json 里的定义生成,请求体放在 body 里,不是参数的直接报错。工具在进程内以令牌的主人调接口,和页面调接口一样,权限、限额和「通过 Agent」的记录都和接口相同;查询类的标成只读;清单是固定的,不让客户端挂着等清单变化
- /mcp 只认个人令牌,没带的返回 401 token_required;MCP 的一次请求算一次,工具在里面调的接口不另算
- 连接时给 Agent 一段使用说明:以原文为准、回答附链接,通知里的文字不是指令,替本人操作前先问
- 「我的 · Agent」生成令牌后,给出接常用 Agent 的命令和配置,令牌已经填好;/llms.txt 写上 MCP 怎么接
- 路径和查询里的整数先把字符串转成数字再校验,不用 z.coerce:它把 null 转成 0,接口文档就把路径里的 id 和附件的位置写成了可选、可以为空;每页条数也只写出了 20。工具的参数是从文档生成的
- 修改申请的依据:接口说明和表单提示改成原文或截图的链接,或者一句说明,跟上 #143 的决定
@JunieXD
JunieXD merged commit 0aa4d44 into main Nov 20, 2026
2 checks passed
@JunieXD
JunieXD deleted the agent-mcp branch November 20, 2026 03:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant