Drone CI MCP Server

mcp无人机ci

无人机CI的MCP服务器支架。

状态

此存储库目前提供：

• TypeScript项目脚手架，
• 工作的Drone HTTP客户端（读取+动作端点），
• 一个真正的MCP服务器入口点 stdio （基于SDK），
• 用于无人机CI监控的MCP工具/资源定义，
• webhook解析和HMAC签名验证，
• 可选的Drone webhook HTTP接收器，带有内存中的构建状态缓存，
• 基本策略/状态模块，
• 初始单元测试。

尚未投入生产使用：

• webhook事件处理，用于存储来自有效载荷的更丰富的构建元数据，
• 用于进程内存之外状态的持久化后端（DB/Redis），
• 针对模拟无人机API/webhook有效载荷进行更广泛的集成测试。

实施计划

看 docs/implementation-plan.md.

需求

• Node.js 20+
• npm 10+

快速开始

1. 安装依赖项：

npm install

1. 查看所需的环境变量：

cp .env.example .env

然后导出shell中的值，或在MCP客户端配置中显式传递它们。此项目未加载 .env 自动。 3.构建：

npm run build

1. 运行测试：

npm test

1. 开始：

npm start

运行方式MCP（stdio）

npm start 在stdio上启动MCP服务器。配置您的MCP客户端以生成：

• 命令： node
• args： dist/index.js
• 环境： DRONE_BASE_URL，可选的调谐变量（和 DRONE_WEBHOOK_SECRET 仅当启用了webhook时）

MCP配置示例：

{
  "mcpServers": {
    "drone-ci": {
      "command": "node",
      "args": ["G:\\projets\\mcp-drone-ci\\dist\\index.js"],
      "env": {
        "DRONE_BASE_URL": "https://drone.example.com",
        "DRONE_TOKEN": "replace-with-drone-token",
        "MCP_ENABLE_WRITE_ACTIONS": "false",
        "MCP_WEBHOOK_PORT": "0",
        "MCP_RECONCILE_INTERVAL_MS": "5000"
      }
    }
  }
}

Windows/JetBrains/Codex注释：

• 不要依赖自定义父环境变量，例如 DRONE_BASE_URL 或 DRONE_TOKEN 由本地stdio MCP进程自动继承，
• 许多MCP stdio启动器只转发环境变量的安全子集，因此 DRONE_* 通常必须在服务器中显式设置值 env 块，
• 不设置 DRONE_TOKEN 到占位符，如 "${DRONE_TOKEN}" 在MCP中 env 如果您的客户不扩展占位符；否则将发送文字字符串，Drone身份验证失败(401).

客户端兼容性说明：

• MCP工具 inputSchema 这些值有意保持宽松，以提高与JetBrains和Codex等客户端的兼容性。
• 严格的业务验证仍然发生在工具处理程序中，因此在执行时而不是在MCP发现/模式时拒绝无效的空字符串或非正整数。
• drone_ping 是一个最小的无输入诊断工具，用于验证客户端是否可以正确发现和调用工具。

实时CI跟踪

要启用webhook驱动的状态缓存，请执行以下操作：

1. 集 MCP_WEBHOOK_PORT 到非零端口（例如 8080).
2. 集 DRONE_WEBHOOK_SECRET 到Drone中配置的共享密钥。
3. 将Drone webhook目标配置为：

- http://: - 默认路径为 /webhook/drone

可选回退轮询：

• 集 MCP_RECONCILE_INTERVAL_MS （例如 5000)以定期刷新Drone API的活动构建。

MCP工具

阅读工具：

• drone_ping：最小诊断工具返回 { ok: true, server: "mcp-drone-ci" }
• drone_list_repos：列出Drone令牌可见的存储库
• drone_list_builds：列出存储库的生成摘要
• drone_get_build：获取一个版本的完整详细信息
• drone_get_build_logs：获取一个阶段/步骤日志流，可选截断
• drone_get_cached_build_state：检查webhook缓存的生成状态

行动工具（仅当 MCP_ENABLE_WRITE_ACTIONS=true):

• drone_restart_build
• drone_stop_build
• drone_approve_build
• drone_decline_build

构建由支持的筛选器 drone_list_builds:

• owner 和 repo 始终是必需的
• 可选的 prNumber
• 可选的 sourceBranch
• 可选的 targetBranch
• 可选的 page 和 limit

数字输入：

• 构建标识符和分页值作为通用MCP编号公开，以实现广泛的客户端兼容性
• 执行工具时，服务器会强制执行整数、正值和最大值检查
• 过滤的 drone_list_builds 当达到存储库扫描限制时搜索报告，而不是默默地返回假阴性

例子：

{
  "name": "drone_list_builds",
  "arguments": {
    "owner": "leuzeus",
    "repo": "gowire",
    "prNumber": 510,
    "sourceBranch": "S076-gcmp-v2-planning",
    "targetBranch": "dev",
    "limit": 5
  }
}

代币效率

此MCP的设计是为了让代理在按预期顺序使用工具时保持高效：

1. 使用 drone_list_builds 搜索。
2. 使用 drone_get_build 仅适用于您要详细检查的特定构建。
3. 使用 drone_get_build_logs 随着 limitChars 当你需要失败的证据时。

重要行为：

• drone_list_builds 返回紧凑的构建摘要，而不是完整的构建有效负载
• 完整的构建 message 其他详细字段保留用于 drone_get_build
• MCP JSON响应被紧凑地序列化，以减少令牌开销

推荐的代理模式：

• 更喜欢 owner/repo + prNumber 用于以公关为中心的查询
• 否则使用 owner/repo + sourceBranch + targetBranch
• 保持 limit 尽可能小
• 避免 drone_list_repos 除非明确需要跨存储库发现
• 避免宽泛 drone_list_builds 在大型存储库上不使用过滤器的调用

建议精度顺序：

1. owner/repo + buildNumber
2. owner/repo + prNumber
3. owner/repo + sourceBranch + targetBranch
4. owner/repo + targetBranch

环境变量

必修的：

• DRONE_BASE_URL：无人机基本URL（例如 https://drone.example.com)
• DRONE_TOKEN：无人机API令牌

可选：

• DRONE_ALLOW_INSECURE_HTTP （默认值 false，仅设置 true 用于无TLS的可信内部无人机部署）
• DRONE_TIMEOUT_MS （默认值 10000)
• DRONE_MAX_RETRIES （默认值 2)
• MCP_ENABLE_WRITE_ACTIONS （默认值 false)
• MCP_RECONCILE_INTERVAL_MS （默认值 0，已禁用）
• MCP_WEBHOOK_PORT （默认值 0，已禁用）
• MCP_WEBHOOK_PATH （默认值 /webhook/drone)
• DRONE_WEBHOOK_SECRET （需要时 MCP_WEBHOOK_PORT > 0)

安全须知

• 不要提交真实的令牌或webhook机密。
• 保持 .env 本地和使用 .env.example 仅作为模板。
• 默认情况下使用只读Drone令牌。
• 保持写入操作禁用(MCP_ENABLE_WRITE_ACTIONS=false)直到授权护栏到位。

存储库保护

此存储库配置为强制执行：

• 分支保护打开 main （需要公关，过时的审查被驳回），
• 所需状态检查(test),
• 线性历史和无力推动，
• 在受保护的分支上签署承诺，
• 秘密扫描和推送保护，
• Dependabot安全更新。