paotong-mcp —「跑通」社区的 MCP server

让任意 MCP 客户端（Claude Desktop / Cursor / Cline 等）一键接入 vibe coding 时代的中文开发者社区**「跑通」**，浏览、搜索式地按标签/最新/热门发现，并读取文章、评论与用户资料。

这是一个 stdio MCP server，基于官方 @modelcontextprotocol/sdk。本期只读——所有工具都只是站点已有的公开只读 API 的薄包装。

不想装任何东西？ 站点还提供一个远程 MCP 端点（MCP over HTTP）：https://vibe.web3noah.com/api/mcp。支持 remote / HTTP MCP 的客户端填这个 URL 即可接入，无需构建本包。人读接入说明见 https://vibe.web3noah.com/mcp。本 README 讲的是本地 stdio 接入。两种传输复用同一份工具定义（src/tools.ts）。

工具（本期都是只读）

| 工具 | 入参 | 说明 | | --- | --- | --- | | list_articles | feed?: "latest" \| "hot"、tag?: string、page?: number | 文章列表（不含正文）。含每篇的 id、slug、标题、摘要、作者、标签、时间、点赞/评论数 | | get_article | slug: string | 单篇完整正文（Markdown contentMd）+ 元信息 | | get_article_comments | articleId: string | 某篇文章的评论（一级评论 + 回复）。注意 articleId 是文章的 id，不是 slug | | get_user | username: string | 用户公开资料（昵称、简介、粉丝/关注数、已发布文章数） | | list_user_articles | username: string、page?: number | 某用户已发布的文章（不含正文） |

约定与边界：

• 没有全文搜索。 站点目前没有搜索端点，本 server 也不会假装有——发现内容请用 list_articles 的 feed=latest／feed=hot／tag 浏览。
• 不含来源。 站点公开响应本就不返回文章的 sourceLinks，本 server 也读不到。
• 不会崩。 上游报错/超时/不可达时，工具会返回一条清晰的错误文本给 agent，而不是抛异常打死 server。

环境变量

| 变量 | 缺省 | 用途 | | --- | --- | --- | | PAOTONG_API_BASE | https://vibe.web3noah.com/api | 站点公开 API 的 base（同源代理，无需鉴权） | | PAOTONG_TOKEN | 无 | 预留：PAT（vc_pat_...）。本期只读工具用不到；存在时会给请求带 Authorization: Bearer <token>，为将来的写操作（发文/评论）预接好鉴权位 |

构建

paotong-mcp 是本仓库的 workspace 包，尚未发布到 npm。先在仓库根构建出可执行产物：

pnpm --filter paotong-mcp build
# 产物：packages/mcp/dist/index.js（带 shebang，可直接 node 执行）

接入配置

Claude Desktop

编辑 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/claude_desktop_config.json），加入：

{
  "mcpServers": {
    "paotong": {
      "command": "node",
      "args": ["/绝对路径/到/vibe-coding-commnuity/packages/mcp/dist/index.js"],
      "env": {
        "PAOTONG_API_BASE": "https://vibe.web3noah.com/api"
      }
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json（全局）或项目内 .cursor/mcp.json，配置同样的 mcpServers 结构：

{
  "mcpServers": {
    "paotong": {
      "command": "node",
      "args": ["/绝对路径/到/vibe-coding-commnuity/packages/mcp/dist/index.js"]
    }
  }
}

把 /绝对路径/到/... 换成你机器上的真实路径。Cline 等其它客户端的配置格式与上面一致（command + args + 可选 env）。

发布后（npx 形态，可选）

将来若把 paotong-mcp 发布到 npm，就能免构建直接用 npx：

{
  "mcpServers": {
    "paotong": {
      "command": "npx",
      "args": ["-y", "paotong-mcp"]
    }
  }
}

扩展位：将来的写操作

本期只做只读。写操作（发文 POST /articles、评论 POST /articles/:id/comments）需要 PAT 鉴权——PAOTONG_TOKEN 已在 HTTP 层作为 Bearer 头预接好。落地位置见 src/index.ts 里的 TODO(write-ops)。