LLMSkillHub
mirroredCopied from ayuayue/PiDeck under MIT. ayuayue has not claimed this page, and is not affiliated with LLM SkillHub.

ayuayue / mcp-setup

帮用户接入/配置 MCP（Model Context Protocol）服务。当用户说「帮我接 MCP」「连上某个服务的 MCP」「配置 Model Context Protocol」「加个工具服务器」「为什么 MCP 连不上」等时使用。按服务官方文档把配置写进 pi 的 mcp.json，并用 pi mcp list 验证连接，全程不破坏用户已有配置。

0
SKILL.md
4.7 KB

MCP 配置助手（mcp-setup）

帮用户把 MCP 服务接进 pi。核心原则：每一步以服务官方文档为准，只改 mcp.json 里属于该服务的条目，改完必须验证。

工作流总览

  1. 弄清用户想接什么服务、拿来做什么；
  2. 查该服务官方的 MCP 接入文档（官网 docs / 官方 GitHub README；优先官方源，不用第三方目录的转述）；
  3. 按下方 schema 生成配置，写入 ~/.pi/agent/mcp.json（全局）或项目 .pi/mcp.json（仅当前项目）；
  4. 运行 pi mcp list 验证；需要 OAuth 的引导用户去 PiDeck 界面点「登录」；
  5. 向用户汇报：加了什么、写到哪、怎么验证、如何撤销。

pi 的 mcp.json 结构（唯一权威 schema）

文件是一个 JSON 对象，键 mcpServers，值是「服务名 → 定义」映射：

{
  "mcpServers": {
    "linear": { "url": "https://mcp.linear.app/mcp" },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": { "BRAVE_API_KEY": "..." }
    }
  }
}

每个服务定义二选一传输：

  • 远程 HTTP：url（必填，http/https）、headers（可选，如 {"Authorization": "Bearer <key>"}）；
  • 本地 stdio：command（必填）、args、env、cwd（可选）。

通用可选：enabled（布尔，false 则不连接）、description、timeout（秒）、exposure/toolExposure（工具暴露方式，默认不用写）。

不要手写的字段：oauth（clientId/clientSecret 等七字段）只在服务商明确要求预注册客户端时才写；pi 的 MCP OAuth 默认零配置，动态客户端注册自动完成。auth.provider 是复用 pi 模型供应商凭据的高级能力，仅全局配置可用，除非用户明确要求否则不要写。

认证形态判定（按官方文档，不猜）

服务方文档说写法
OAuth / 浏览器登录 / 无需 token只写 url；连接后 pi mcp list 显示 needs-auth，引导用户在 PiDeck「配置 → MCP」对应服务行点「登录」
API Key / PAT，放请求头headers: {"Authorization": "Bearer <key>"}（或文档指定的自定义头名）
API Key 放环境变量stdio：env: {"<文档规定的变量名>": "<key>"}
无认证只写传输字段
需要 Dockercommand: "docker"，args 按文档；先确认用户有 Docker

写文件规则（防止破坏用户配置）

  1. 先读后写：读整个 mcp.json，解析 JSON；解析失败立即停手，让用户先在 PiDeck「源文件」页修复，绝不猜着覆盖；
  2. 合并而非覆盖：只新增/替换本次服务的键，其余条目原样保留；
  3. 保格式：写回时 2 空格缩进、键序尽量维持原样；
  4. 密钥安全：密钥值直接写入文件（mcp.json 是明文，这是 pi 的存储方式）；但不要把密钥回显到对话或日志里；
  5. 项目级 .pi/mcp.json 只放该项目需要的覆盖，同名条目会遮蔽全局定义。

验证与收尾

pi mcp list          # 人读形态：每个服务的连接状态/工具数
pi mcp list --json   # 程序化形态
  • connected（带工具数）→ 成功；告诉用户工具经 tool_search 可发现，正常对话即可用；
  • needs-auth → 指导用户打开 PiDeck「配置 → MCP」，该服务行会出现「登录」按钮（或用 pi mcp login <服务名>）；
  • error → 读错误信息定位：URL 打错 / 密钥无效 / npx 包名错 / Node 缺失。stdio 服务首次连接会 npx 拉包，稍慢是正常的；
  • 修改的是正在运行会话读不到的：新配置从下一个会话/下一轮对话生效。

最后汇报三件事：写入了什么（服务名 + 字段清单，密钥打码）、验证结果、撤销方法（删掉 mcpServers 里对应键）。

常见坑

  • npx 包名带 @latest 的按文档原样保留，不要自作聪明去掉；
  • Windows 下 stdio 服务若失败，优先怀疑路径空格与杀毒软件拦截 npx；
  • 远程 URL 末尾斜杠按官方文档原样写（如 https://api.githubcopilot.com/mcp/）；
  • 服务方同时提供「远程托管」和「本地 stdio」两种时，默认选远程托管（免维护、随官方更新）；用户明确要本地/自托管时才选 stdio。