sourcecraft-mcp-light

Lightweight Model Context Protocol (stdio) server that exposes the SourceCraft REST API to AI assistants.

Why

AI assistants integrated into your editor cannot reach SourceCraft directly — so they end up asking you to paste CI logs, PR status, and merge results by hand. This MCP server fixes that by wrapping api.sourcecraft.tech with Bearer-token auth and exposing a small set of tools (plus a generic escape hatch) over stdio. The composite tool sc_run_failure_logs in particular answers "what broke in CI?" in a single round-trip — finds the latest failed run, walks workflows → tasks → cubes to the failure, paginates the log, and returns the tail.

Install

npx -y sourcecraft-mcp-light

Or install globally:

npm install -g sourcecraft-mcp-light

Configure your assistant

You need a SourceCraft personal access token. Set it as SOURCECRAFT_TOKEN.

Claude Desktop / Claude Code

~/.config/claude/claude_desktop_config.json (or the Claude Code MCP settings):

{
  "mcpServers": {
    "sourcecraft": {
      "command": "npx",
      "args": ["-y", "sourcecraft-mcp-light"],
      "env": {
        "SOURCECRAFT_TOKEN": "scp_xxx_your_token_here"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "sourcecraft": {
      "command": "npx",
      "args": ["-y", "sourcecraft-mcp-light"],
      "env": {
        "SOURCECRAFT_TOKEN": "scp_xxx_your_token_here"
      }
    }
  }
}

Optional: SOURCECRAFT_API_BASE overrides the default https://api.sourcecraft.tech base URL.

Tools

repo arguments take the form org_slug/repo_slug (e.g. elfenmail/ui). PR ids are slugs (or numeric ids) from the SourceCraft UI.

PR / branches

| Name | Method + Path | Purpose | | --- | --- | --- | | sc_pr_list | GET /repos/{org}/{repo}/pulls | List PRs with optional state / source / target / limit filters. | | sc_pr_get | GET /pulls/id:{slug} | Fetch one PR by slug or numeric id. | | sc_pr_create | POST /repos/{org}/{repo}/pulls | Open a PR. Body: title, description, source_branch, target_branch, reviewer_ids, publish (default true). | | sc_pr_merge | POST /pulls/id:{slug}/merge | Merge a PR with boolean flags squash, rebase, delete_branch, force. | | sc_branch_list | GET /repos/{org}/{repo}/branches | List branches with optional filter, sort_by, pagination. |

CI / CD

| Name | Method + Path | Purpose | | --- | --- | --- | | sc_run_list | GET /repos/{org}/{repo}/cicd/runs | List recent runs (each with full workflows → tasks → cubes tree). | | sc_run_get | GET /repos/{org}/{repo}/cicd/runs/{run_slug} | One run, full tree. | | sc_run_logs | GET /repos/{org}/{repo}/cicd/logs/{run}/{wf}/{task}/{cube} | Cube logs for one page. Iterate ?page for long logs. | | sc_run_failure_logs | composite | Killer feature. Finds the most recent failed run (or uses your run_slug), walks to the failed cube, paginates logs to completion, returns the failure chain + tail of the log (capped at max_log_chars, default 8000). One call answers "what broke?". |

Generic + composites

| Name | Purpose | | --- | --- | | sc_request | Generic escape hatch: call any SourceCraft REST endpoint by method + path. Returns { status, body }. | | sc_swagger | Fetch the public or cicd swagger document. Cached in memory. Use to discover endpoints not yet wrapped here. | | sc_release_status | One round-trip overview for a repo: recent PRs (summarized) + available CI/CD paths. Combine with sc_run_failure_logs for full release triage. |

When the swagger changes

The cube logs path and run-tree shape were extracted from the swagger at the time of writing (POST /repos/{org}/{repo}/pulls, GET /repos/{org}/{repo}/cicd/runs, GET /repos/{org}/{repo}/cicd/logs/{run}/{workflow}/{task}/{cube}). If SourceCraft restructures the API, sc_swagger("cicd") will return the new shape (cache flushes on server restart), and sc_request lets the assistant adapt without code changes here.

License

MIT