fusion-pm-mcp

Fusion PM MCP 设置指南

何时使用

在用户询问以下内容时使用：

• Fusion PM MCP 是什么
• 如何安装或配置
• 如何验证其是否正常工作
• 如何排查设置失败或结果过时／受到速率限制的问题

典型触发语句：

• “Fusion PM MCP 是什么”
• “帮我设置 Fusion PM MCP”
• “如何将 GitHub issues/PR 导入 Copilot，同时避免触发速率限制”

何时不使用

• 实现或修改 fusion-pm-mcp 服务源代码——这应在该仓库中处理
• 检索通用 Fusion Framework 文档、EDS 或后端代码——使用 fusion-mcp
• 编写、分类或审查 GitHub issues/PR——MCP 工具可用后，使用 fusion-issue-authoring 或特定仓库的审查技能
• 未经用户确认就对环境进行破坏性更改

必需输入

提出设置步骤前，请收集：

• 是否有 GitHub token（gh auth token，或具有 repo scope 的 PAT）——按请求提供，不存储在配置中
• 目标客户端（主要是 VS Code）

如果缺少信息，请先提出简洁的后续问题。

说明

1. 说明此 MCP 服务提供的功能：
   • 作为 GitHub REST API 的缓存代理，并以 MCP 工具的形式提供接口，让 Agent 无需每次调用都访问 GitHub，从而避免触及速率限制。
   • 以托管服务的形式提供，大多数用户无需本地基础设施。
   • 工具（请通过 tools/list 确认；服务器的实际源代码才是权威依据，优先于任何过时文档）：api_get_issue、api_get_parent_issue、api_get_child_issues、api_get_issue_comments、api_list_milestones、api_get_milestone、api_upsert_issue、api_close、api_get_metadata_schema、api_get_pull_request、api_get_pr_comments、api_get_pr_reviews、api_get_pr_review、api_get_review_comments、api_resolve_review_comment
   • 响应会缓存（默认 TTL 为 300 秒）；没有缓存失效工具，过期结果会在 TTL 到期后自行清除。
2. 引导用户设置托管生产服务器——这是唯一推荐的方式：
   • 无需 Docker、无需本地克隆，也无需管理环境变量。
   • VS Code 通过 Microsoft Entra（Equinor 账户）对 MCP 连接进行身份验证。
   • 调用方还需在每个请求中通过 X-GitHub-Token 标头提供自己的 GitHub 令牌（每位用户使用自己的身份并受自己的速率限制；不要建议使用共享令牌或服务令牌）。
   • 使用 references/vscode-mcp-config.md 中的手动配置（此服务器没有发布一键安装链接）。
   • 不要建议使用本地 stdio 或完整 Docker 开发堆栈——这些仅供开发 fusion-pm-mcp 服务本身的贡献者使用；请引导他们查看该仓库的 CONTRIBUTING.md，不要在此处嵌入设置步骤。
3. 说明身份验证流程：
   • 首次调用工具时，VS Code 会提示用户使用 Equinor Entra 账户登录（该账户控制对 MCP 服务本身的访问）。
   • 此外，X-GitHub-Token 标头会在每个请求中携带调用方自己的 GitHub PAT，并将其传递给 API。
   • 两种身份验证都必须有效；401 错误可能来自其中任一层。
4. 提供验证清单：
   • 运行 initialize 并确认响应成功。
   • 运行 tools/list，并将实际返回的工具名称与预期进行比较——不要假定工具列表固定不变，它曾经发生过变化。
   • 运行一个无破坏性的 tools/call（例如 api_list_milestones 或 api_get_issue），并确认返回结果非空。
5. 按照以下顺序排查问题：
   • 未通过身份验证／很快触及速率限制 → 未配置 X-GitHub-Token 标头；未通过身份验证的调用上限为每小时 60 次。
   • 出现 401 或反复提示登录 → 通过 VS Code 重新进行身份验证（退出并重新登录，或重新加载 MCP 服务）；如果仍未解决，应视为设置问题，而非已知的暂时性问题。
   • 结果看起来过时 → 没有缓存失效工具；结果会在缓存 TTL 到期后自行清除（几分钟）。
6. 设置失败或用户要求提交 Bug 时，根据 assets/bug-report-template.md 起草 Bug 报告。
   • 默认目标仓库：equinor/fusion-pm-mcp
   • 包含具体的复现步骤、预期行为与实际行为，以及已经尝试过的故障排查措施。
   • 仅包含非敏感的环境详情（操作系统、VS Code 版本）。
   • 切勿包含 GitHub 令牌、PAT 或 Entra 凭据。
7. 对于不确定之处或仓库私有限制，明确说明假设，并链接到权威文档，不要猜测。

预期输出

返回：

• 简短说明 Fusion PM MCP 的用途及适用场景
• 根据用户环境量身定制的托管服务设置步骤
• 验证清单：initialize、tools/list（与实际返回的名称进行比较）、一次 tools/call（预期结果非空）
• 根据观察到的症状提供相应的故障排查步骤
• 在设置失败、运行异常或用户提出要求时，根据 assets/bug-report-template.md 起草 Bug 报告，默认目标为 equinor/fusion-pm-mcp
• 明确指出假设及缺失信息

参考资料

• references/vscode-mcp-config.md
• assets/bug-report-template.md

安全与约束

切勿：

• 请求或泄露 GitHub 令牌、PAT 或 Entra 凭据
• 编造项目文档未支持的设置命令
• 在没有验证输出的情况下声称设置已成功
• 建议在托管的多用户设置中使用同一个共享 GitHub 令牌
• 未经用户明确确认就运行有破坏性的命令

始终：

• 优先以官方仓库文档为准
• 引导用户使用托管的生产服务器；除非用户正在为服务本身做贡献，否则不要建议使用本地 stdio 或 Docker 设置；如果用户正在为服务本身做贡献，则链接到该仓库的 CONTRIBUTING.md，而不要直接嵌入设置步骤
• 推荐使用逐请求的 X-GitHub-Token 身份验证，而非共享令牌
• 将已确认的事实与假设分开