mcp-drone-ci

MCP server scaffold for Drone CI.

Status

This repository currently provides:

• a TypeScript project scaffold,

• a working Drone HTTP client (read + action endpoints),

• a real MCP server entrypoint on stdio (SDK-based),

• MCP tool/resource definitions for Drone CI monitoring,

• webhook parsing and HMAC signature verification,

• optional Drone webhook HTTP receiver with in-memory build-state cache,

• basic policy/state modules,

• initial unit tests.

Still pending before production use:

• webhook event processing to store richer build metadata from payloads,

• persistence backend (DB/Redis) for state beyond process memory,

• broader integration tests against mock Drone API/webhook payloads.

Implementation Plan

See docs/implementation-plan.md.

Requirements

• Node.js 20+

• npm 10+

Quick Start

1. Install dependencies:

npm install

2. Review the required environment variables:

cp .env.example .env

Then export the values in your shell or pass them explicitly in your MCP client configuration. This project does not load .env automatically. 3. Build:

npm run build

4. Run tests:

npm test

5. Start:

npm start

Run As MCP (stdio)

npm start launches the MCP server on stdio. Configure your MCP client to spawn:

• command: node

• args: dist/index.js

• env: DRONE_BASE_URL, optional tuning vars (and DRONE_WEBHOOK_SECRET only if webhook is enabled)

Example MCP config:

{
  "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 note:

• do not rely on custom parent environment variables such as DRONE_BASE_URL or DRONE_TOKEN being inherited automatically by a local stdio MCP process,

• many MCP stdio launchers only forward a safe subset of environment variables, so DRONE_* values must usually be set explicitly in the server env block,

• do not set DRONE_TOKEN to a placeholder like "${DRONE_TOKEN}" in MCP env if your client does not expand placeholders; otherwise the literal string is sent and Drone authentication fails (401).

Client compatibility note:

• MCP tool inputSchema values are intentionally kept permissive to improve compatibility with clients such as JetBrains and Codex.

• Strict business validation still happens in the tool handlers, so invalid empty strings or non-positive integers are rejected at execution time rather than at MCP discovery/schema time.

• drone_ping is available as a minimal no-input diagnostic tool to verify that a client can discover and invoke tools correctly.

Real-time CI Tracking

To enable webhook-driven state cache:

1. Set MCP_WEBHOOK_PORT to a non-zero port (for example 8080).

2. Set DRONE_WEBHOOK_SECRET to the shared secret configured in Drone.

3. Configure Drone webhook target to:

   • http://<host>:<MCP_WEBHOOK_PORT><MCP_WEBHOOK_PATH>

   • default path is /webhook/drone

Optional fallback polling:

• set MCP_RECONCILE_INTERVAL_MS (for example 5000) to periodically refresh active builds from Drone API.

MCP Tools

Read tools:

• drone_ping: minimal diagnostic tool returning { ok: true, server: "mcp-drone-ci" }

• drone_list_repos: list repositories visible to the Drone token

• drone_list_builds: list build summaries for a repository

• drone_get_build: fetch full details for one build

• drone_get_build_logs: fetch one stage/step log stream, with optional truncation

• drone_get_cached_build_state: inspect webhook-cached build state

Action tools (only when MCP_ENABLE_WRITE_ACTIONS=true):

• drone_restart_build

• drone_stop_build

• drone_approve_build

• drone_decline_build

Build filters supported by drone_list_builds:

• owner and repo are always required

• optional prNumber

• optional sourceBranch

• optional targetBranch

• optional page and limit

Numeric inputs:

• build identifiers and pagination values are exposed as generic MCP numbers for broad client compatibility

• integer, positivity, and max-value checks are enforced by the server when the tool is executed

• filtered drone_list_builds searches report when the repository scan limit is hit, instead of silently returning a false negative

Example:

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

Token Efficiency

This MCP is designed so agents can stay efficient if they use the tools in the intended order:

1. Use drone_list_builds to search.

2. Use drone_get_build only for the specific build you want to inspect in detail.

3. Use drone_get_build_logs with limitChars when you need failure evidence.

Important behavior:

• drone_list_builds returns compact build summaries, not full build payloads

• the full build message and other verbose fields are reserved for drone_get_build

• MCP JSON responses are serialized compactly to reduce token overhead

Recommended agent patterns:

• prefer owner/repo + prNumber for PR-centric queries

• otherwise use owner/repo + sourceBranch + targetBranch

• keep limit small whenever possible

• avoid drone_list_repos unless cross-repository discovery is explicitly needed

• avoid broad drone_list_builds calls without filters on large repositories

Recommended order of precision:

1. owner/repo + buildNumber

2. owner/repo + prNumber

3. owner/repo + sourceBranch + targetBranch

4. owner/repo + targetBranch

Environment Variables

Required:

• DRONE_BASE_URL: Drone base URL (for example https://drone.example.com)

• DRONE_TOKEN: Drone API token

Optional:

• DRONE_ALLOW_INSECURE_HTTP (default false, only set true for trusted internal Drone deployments without TLS)

• DRONE_TIMEOUT_MS (default 10000)

• DRONE_MAX_RETRIES (default 2)

• MCP_ENABLE_WRITE_ACTIONS (default false)

• MCP_RECONCILE_INTERVAL_MS (default 0, disabled)

• MCP_WEBHOOK_PORT (default 0, disabled)

• MCP_WEBHOOK_PATH (default /webhook/drone)

• DRONE_WEBHOOK_SECRET (required when MCP_WEBHOOK_PORT > 0)

Security Notes

• Do not commit real tokens or webhook secrets.

• Keep .env local and use .env.example as template only.

• Use a read-only Drone token by default.

• Keep write actions disabled (MCP_ENABLE_WRITE_ACTIONS=false) until authorization guardrails are in place.

Repository Protection

This repository is configured to enforce:

• branch protection on main (PR required, stale review dismissal),

• required status check (test),

• linear history and no force-push,

• signed commits on protected branch,

• secret scanning and push protection,

• Dependabot security updates.