banyan-mcp-setup

把榕树 banyan 的 MCP server 接进编码 Agent（Claude Code / Hermes / Codex 等）：token 从哪生成、stdio 启动方式（node 拉起客户端的 banyan-mcp.mjs）、通用 mcpServers 配置片段，以及三个具体落点。当 Agent 里找不到 banyan 工具、或出现 401 / 未授权时也用它排查。

授權 MIT 內容摘要 sha256:53eda8a55…89b53b62

技能正文目前為簡體中文。

榕树 banyan — 把 MCP server 接进 Agent

榕树客户端内置一个 stdio MCP server（banyan-mcp.mjs）。它只做一件事：把 MCP 工具调用翻译成对榕树本地 API 的 HTTP 请求——业务逻辑不复制一份，认证靠环境变量。接上之后，Agent 就能用 create_article / publish_article / claim_topic 这类工具操作榕树。

什么时候用

用户说「把榕树接进 Claude Code / Hermes / Codex」「让 Agent 能用榕树的工具」；
Agent 里找不到 banyan 工具、调用报 401 / 未授权 / fetch failed；
换了 token、换了客户端安装目录、或多位作家要各自独立接入时。

第一步：拿 token

在榕树客户端 「设置 → API 与 MCP」 生成 / 查看 API token。注意：

token 与账号或作家身份绑定——每个接入方用各自的 token，多个 Agent / 多位作家不要共用一个；
页面同时给出本机的接口地址与端口（默认 http://127.0.0.1:5832）；
token 是凭据：只写进 Agent 的配置文件（见下），不要写进 SKILL.md 正文、不要提交到 git 仓库、不要贴进聊天记录或公开 issue。本文档里一律用 <token> 占位。

第二步：确认 MCP server 脚本路径

server 是打包进客户端的 banyan-mcp.mjs，用 node 直接拉起：

场景	脚本路径
装好的客户端（macOS）	`/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs`
装好的客户端（Windows）	`<安装目录>\榕树\resources\banyan-mcp.mjs`
开发态源码	`<榕树项目目录>/resources/banyan-mcp.mjs`

路径不确定时，在客户端「设置 → API 与 MCP」里有对应的 stdio 启动命令可直接复制。

环境变量（由 Agent 在拉起进程时注入）：

变量	必填	说明
`BANYAN_TOKEN`	是	API 认证 token，从「设置 → API 与 MCP」取
`BANYAN_BASE_URL`	否	API 地址，默认 `http://127.0.0.1:5832`；改过端口 / 地址时用

启动命令就是：

BANYAN_TOKEN=<token> node "/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"

通用配置片段

大多数 Agent 的 MCP 配置都是「一个 JSON 对象 + 一条 server 定义」，形状如下（占位符原样替换）：

{
  "mcpServers": {
    "banyan": {
      "command": "node",
      "args": ["/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"],
      "env": { "BANYAN_TOKEN": "<token>" }
    }
  }
}

外层键名按各家约定（mcpServers / mcp.servers 等），内层 command / args / env 三件套一致。

三个具体落点

Claude Code

用官方 CLI 注册，-s user 表示用户级（任何目录启动的会话都能用，local 只在本项目生效）：

claude mcp add banyan -s user --env BANYAN_TOKEN=<token> -- node "/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"

同名 server 已存在时 CLI 不会用新的 --env 覆盖旧 token——先 claude mcp remove banyan -s user，再 add。

Hermes Agent

写 config.yaml（默认 ~/.hermes/config.yaml；多 profile 时写 ~/.hermes/profiles/<name>/config.yaml，各 profile 独立）的 mcp_servers: 段：

mcp_servers:
  banyan:
    command: node
    args:
      - /Applications/榕树.app/Contents/Resources/banyan-mcp.mjs
    env:
      BANYAN_TOKEN: <token>

改完重启 Hermes 会话，工具才会出现在工具目录里。

Codex

写 ~/.codex/config.toml 的两个表（server 定义 + env 子表）：

[mcp_servers.banyan]
command = "node"
args = ["/Applications/榕树.app/Contents/Resources/banyan-mcp.mjs"]

[mcp_servers.banyan.env]
BANYAN_TOKEN = "<token>"

第三步：验证

客户端在运行：MCP server 只是本地 API 的代理，榕树客户端没起着就一定失败。
重启 Agent（或新开一个会话）后，先做一个只读调用，如 list_platforms / list_accounts——能返回平台列表就算接通。
直连探活（可选）：curl -s -m 8 http://127.0.0.1:5832/health
- connection refused → 客户端没在运行；
- 返回 未授权：缺少 Bearer token → 服务已在监听（缺 token 才会 401），说明地址端口是对的。
报 login_required /「生成草稿需要先登录榕树账号」→ 这是客户端账号未登录，与 MCP 配置无关，只能由用户在客户端登录，不要反复重试。

常见问题

Q：报 401 未授权，但接口地址明明是对的？ A：token 失效或写错了。去「设置 → API 与 MCP」重新生成，然后更新 Agent 配置里的 env——旧 token 不会自动同步。

Q：工具列表里没有 banyan？ A：三种常见原因：配置写进了错误的 profile / 作用域（如 Claude Code 用了 local 却在别的目录启动）、配置格式没被解析（JSON 有注释或语法错误）、或改完没重启会话。

Q：fetch failed 是什么意思？ A：MCP 代理连不上榕树本地 API——客户端没启动或正在启动。等它就绪后重试即可，不是配置错。

Q：多位作家 / 多个 Agent 怎么办？ A：每位用各自的 token、各自的 server 名（如 banyan-<名字>），互不干扰；共用 token 会让写操作落到同一个身份上。

Q：可以把 token 直接写进 SKILL.md 吗？ A：不可以。SKILL.md 会被安装、复制、可能被提交到仓库或分享给别人；token 只进 Agent 的 MCP 配置（--env / env 字段）。泄露后立即在客户端重新生成。