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; SOURCECRAFT_GIT_BASE overrides https://git.sourcecraft.dev (used by the Git LFS tools).

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?". |

Issues

Issues are addressed by their slug (the number shown in the UI); comments and issue links by id.

| Name | Method + Path | Purpose | | --- | --- | --- | | sc_issue_list | GET /repos/{org}/{repo}/issues (or GET /me/issues without repo) | List issues. filter is SourceCraft QL, e.g. status=open and priority=critical, label_slug=bug, assignee_slug="alice". sort_by like -created_at. | | sc_issue_get | GET /repos/{org}/{repo}/issues/{slug} | One issue. | | sc_issue_create | POST /repos/{org}/{repo}/issues | Create: title, description, priority, status_slug, assignee_id, milestone / labels / linked PRs by id or slug, deadline (RFC3339). | | sc_issue_update | PATCH /repos/{org}/{repo}/issues/{slug} | Partial update. Close with status_slug: "closed", reopen with "open". | | sc_issue_delete | DELETE /repos/{org}/{repo}/issues/{slug} | Permanently delete. | | sc_issue_statuses | GET /issue_statuses | Available status_slug values (open, inProgress, paused, closed, declined, duplicate). | | sc_issue_comments / sc_issue_comment_create | …/issues/{slug}/comments | List / add comments (parent_id for replies). | | sc_issue_comment_update / sc_issue_comment_delete | /issue_comments/id:{id} | Edit / delete a comment. | | sc_issue_labels | …/issues/{slug}/labels | action: list / add / remove / replace, by ids or slugs. | | sc_issue_linked_prs | …/issues/{slug}/linked_prs | action: list / add / remove PRs (slugs = PR numbers). | | sc_issue_links / sc_issue_link_delete | …/issues/{slug}/issue_links, /issue_links/id:{id} | Issue-to-issue links (blocks, subissue_of, duplicates, …). | | sc_label_list / sc_label_create | /repos/{org}/{repo}/labels | Repository labels. | | sc_milestone_list / sc_milestone_create | /repos/{org}/{repo}/milestones | Repository milestones. |

Git LFS

SourceCraft exposes LFS through the standard Git LFS HTTP API on the git host, https://git.sourcecraft.dev/{org}/{repo}.git/info/lfs (override with SOURCECRAFT_GIT_BASE). The same personal token is used. Object bytes travel to/from pre-signed Object Storage URLs returned by the batch call.

| Name | Method + Path | Purpose | | --- | --- | --- | | sc_lfs_batch | POST …/info/lfs/objects/batch | Raw batch call: which objects exist, pre-signed hrefs. | | sc_lfs_download | batch + GET href | Download one object by oid+size or by pointer text. Verifies sha256. Returns inline (utf8/base64, ≤ max_bytes) or writes to save_to. | | sc_lfs_upload | batch + PUT href (+ verify) | Upload a local file; returns oid, size and the pointer text. Commit that pointer via git to attach the object to the repo — SourceCraft serves an object for download only after a commit referencing it has been pushed. | | sc_lfs_locks_list | GET …/info/lfs/locks | List file locks (filters path, id, refspec; cursor/limit). | | sc_lfs_lock | POST …/info/lfs/locks | Lock a path. | | sc_lfs_unlock | POST …/info/lfs/locks/{id}/unlock | Release a lock (force for someone else's). | | sc_lfs_locks_verify | POST …/info/lfs/locks/verify | Locks split into ours / theirs. |

ref arguments accept a short branch name (main) or a full ref (refs/heads/main).

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