Keypup Engineering Analytics

Keypup MCP 服务

用通俗语言询问 Keypup 工程数据，跟踪交付、质量和团队工作量。

Keypup MCP（模型上下文协议）服务可将 Keypup 工程分析数据直接接入任何兼容 MCP 的 AI 助手，包括 Claude、Cursor、Kiro、ChatGPT Desktop、Gemini CLI、VS Code 等。

连接后，你可以用通俗语言询问工程活动相关问题，AI 会为你构建并运行底层报表查询。无需学习查询语言，也无需编写代码。

与面向编写应用程序代码的开发者设计的 GraphQL API 不同，MCP 服务专为由 AI 代表你通过对话来驱动而设计。

Beta：Keypup MCP 服务目前处于 Beta 阶段。在此期间，服务提供的功能会持续扩展。欢迎通过应用内聊天提供反馈和分享使用场景。

能做什么

该服务提供了一组精简的只读工具，让 AI 能够探索和查询你的 Keypup 数据：

• 发现你的公司 — 列出你所属的公司（团队）。
• 探索数据集 — 浏览可用数据集及其提供的字段。
• 发现公式运算符 — 列出构建指标、维度和筛选条件时可用的函数和运算符。
• 运行报表查询 — 对任意数据集执行聚合查询，支持指标、维度（分组）、筛选、排序和分页。
• 根据自然语言生成查询 — 将通俗语言请求转换为可直接运行的结构化查询，随后 AI 可执行该查询。

AI 会自动协调这些工具。典型流程如下：

1. 列出你的公司
2. 选择相关数据集
3. 查询所需字段
4. 构建查询
5. 运行查询
6. 总结结果

你只需提出问题。

工具

工具	描述
list_companies	列出经过身份验证的用户所属的公司（团队）。返回每家公司的 id、name、created_at 和 updated_at。大多数其他工具都需要 id。
list_datasets	列出可用于查询的数据集（事实），每个数据集都包含 id、label 和 description。
list_dataset_fields	列出某个公司指定数据集中的可用字段。支持按 source（NATIVE/CUSTOM）和与字段 ID 匹配的正则表达式 pattern 进行筛选，并支持分页。
list_formula_operators	列出自定义公式中可用的运算符和函数。支持按 scope（DIMENSION/METRIC）和正则表达式 pattern 进行筛选，并支持分页。设置 verbose: true 可查看每个运算符的完整文档。
query_dataset	对数据集运行聚合报告。指标、维度和筛选条件均以文本公式表示，并可选择排序、设置 limit 和 offset。
generate_dataset_query	将自然语言 prompt 转换为与 query_dataset 兼容的结构化查询。

数据集

报告引擎基于以下数据集（事实）运行：

• ISSUES_PULL_REQUESTS — 问题和拉取请求。
• ACTIVITY_EVENTS — 问题/PR 上的状态变更、分配、工时记录、打开/关闭/重新打开等活动。
• COMMENTS — 问题、PR 和评审中的评论。
• COMMITS — 关联到拉取请求的提交。
• REVIEWS — 拉取请求评审。

示例问题

交付与吞吐量

• “过去 6 个月中，我们每月合并了多少个拉取请求？”
• “本季度每周的问题关闭率是多少？”
• “上个月每位作者提交了多少次？”

周期时间与绩效

• “过去 12 周中，PR 创建到合并的平均耗时是多少？”
• “显示过去 3 个月的评审周转时间趋势。”
• “哪些代码库的周期时间最长？”

质量与流程

• “本季度每周提出和关闭了多少个缺陷？”
• “我们的拉取请求中，有多少比例至少解决了一个问题？”
• “有多少 PR 在未经评审的情况下合并？”

工作量与协作

• “本月最活跃的评审者有哪些？”
• “目前团队的工作是如何分配的？”
• “我们的拉取请求平均收到多少条评论？”

开放式探索

• “总结我们上个月的工程活动。”
• “比较一段时间内已打开和已关闭的问题。”
• “我们的问题中最常见的标签有哪些？”

你可以逐步细化：“现在按代码库细分”“将范围限定为后端团队”，等等。

设置

端点

https://hq.keypup.io/mcp

服务使用可流式 HTTP 传输，并支持两种身份验证方式：

1. OAuth 2.1（推荐） — 客户端动态注册自身，并由你通过浏览器授权访问。无需复制或存储令牌。
2. API token — 将 Keypup API token 放在 Authorization 标头中传递。当你的客户端不支持 OAuth 动态客户端注册时，请使用此方式。

选项 1 — OAuth（推荐）

如果你的客户端支持带动态客户端注册的 OAuth 2.1（例如通过 Client ID Metadata Document），请在不提供凭据的情况下将其指向该端点：

{
  "mcpServers": {
    "keypup": {
      "type": "http",
      "url": "https://hq.keypup.io/mcp"
    }
  }
}

首次连接时，客户端会打开浏览器窗口，以便登录 Keypup 并授权访问。无需生成、复制或轮换令牌 — 本仓库的 .mcp.json 中提供了此配置。

如果你的客户端没有打开授权提示（或注册失败），它可能尚不支持动态客户端注册。请改用下方的 API token 方式。

选项 2 — API 令牌

对于不支持 OAuth 动态客户端注册的客户端，请添加一个指向该端点的 keypup 服务条目，并在 Authorization 标头中加入 API 令牌：

{
  "mcpServers": {
    "keypup": {
      "url": "https://hq.keypup.io/mcp",
      "headers": {
        "Authorization": "Bearer my_keypup_api_token"
      }
    }
  }
}

注意：

• 将 my_keypup_api_token 替换为你生成的令牌（见下文）。保留 Bearer 前缀。
• 服务名称（keypup）可以任意设置，按你的喜好命名即可。

保存后，在客户端中重启或重新连接 MCP 服务。Keypup 工具应会显示在客户端的工具列表中，此时即可开始提问。

生成 API 令牌

仅适用于 选项 2（API 令牌）。如果你通过 OAuth 进行身份验证，请跳过本节。

MCP 服务使用与 GraphQL API 相同的 API 令牌进行身份验证。

1. 前往 Settings → Account，然后打开 API Token 标签页。
2. 点击 Create token。
3. 设置一个描述性名称（例如，“MCP - Claude Desktop”）和有效期。强烈建议设置有效期。
4. 选择令牌权限范围。MCP 服务建议的最小权限范围为：
   • Reports read（viz:reports:read）——探索数据集／字段并运行报告查询所必需。
   • Companies read（hq:companies:read）——列出你所属的公司，并解析查询中使用的公司 ID 所必需。
5. 点击 Create。令牌仅显示一次，可复制的时间为一分钟——请立即将其复制到 MCP 客户端配置中。

遵循最小权限原则，仅授予你需要的权限范围。上述两个权限范围足以使用 MCP 服务的全部分析功能。

该令牌授予的数据访问权限与你在 Keypup 用户界面中已有的权限相同——查询会自动限制在你所属的公司范围内。

安全

• 所有 Keypup MCP 工具均为只读——绝不会修改你的数据。
• 查询会自动限制在你所属的公司范围内（数据隔离）。
• 请像对待密码一样保护 API 令牌。任何持有该令牌的人都能在授予的权限范围内查询你的 Keypup 数据。
• 优先使用有效期较短的令牌，并定期轮换。
• 请勿将令牌放入共享文件或受版本控制的文件中。仅将其存储在 MCP 客户端的本地配置中。

资源

• 使用 MCP 服务（文档）
• MCP 服务产品页面
• 使用 API
• 安全常见问题