@super-repo/mcp

super-mcp — Model Context Protocol server that exposes the Super CLI cross-repo workflow as MCP tools. Drop-in for any MCP-aware client (Claude Desktop, Cursor, etc.); under the hood it shells out to @super-repo/cli so behavior stays identical to the human CLI.

Install

pnpm add -D @super-repo/mcp
# Or globally if you want a system-wide stdio server:
pnpm add -g @super-repo/mcp

Tools

The server registers eleven tools — six core cross-repo + five for the autonomous factory:

| Tool | Purpose | | -------------------------- | ----------------------------------------------------------------------------- | | super_context | Return the resolved config, repo list, and output dir. | | super_status | Per-repo status (branch, dirty/clean, ahead/behind, last commit). | | super_diff | Aggregated git diff across stack repos, optionally filtered by name. | | super_feature_start | Create feat/<slug> branches in every stack repo and write a plan file. | | super_feature_sync | Pull-rebase the active feature branch in every stack repo. | | super_commit | Validate one Conventional Commits message and ship it across stack repos. | | super_factory_status | Read autonomous-loop state: current iteration, phase, consecutive failures. | | super_factory_history | Read iteration history (JSONL) — outcome, halt reason, duration, repo count. | | super_factory_backlog | Merged ranked backlog (curated tasks/backlog.md + GitHub issues + heuristics).| | super_factory_propose | Generate heuristic backlog candidates without enqueueing them. | | super_factory_feature | Read a per-feature PRD (tasks/<slug>.md): frontmatter, decisions, status log.|

Each tool's input schema is declared via zod and surfaced through MCP's introspection — clients see typed parameters and descriptions automatically.

Common parameters

Every tool accepts these optional inputs:

| Parameter | Purpose | | -------------- | ----------------------------------------------------------------------------- | | cwd | Working directory (defaults to process.cwd()). | | config_path | Path to super.config.ts if not at the project root or referenced via package.json#super. Threaded into the cli's loadConfig so MCP behaves identically to super -c <path> .... |

Run

The bin (super-mcp) is a stdio MCP server. It expects to find a super.config.ts at the working directory it's launched from (override via -c / --config).

# stdio server (typical use — wired into a client config)
super-mcp

# Pin a specific config path
super-mcp --config ./super.staging.ts

# Override the .super output dir
super-mcp --dir /tmp/super

Wire into Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or the equivalent path on your OS):

{
  "mcpServers": {
    "super": {
      "command": "npx",
      "args": ["-y", "@super-repo/mcp"],
      "env": { "ANTHROPIC_API_KEY": "..." }
    }
  }
}

When Claude Desktop restarts, the six super_* tools become available in the tool palette.

Wire into Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "super": {
      "command": "npx",
      "args": ["-y", "@super-repo/mcp"]
    }
  }
}

How it works

1. Server boots over stdio (@modelcontextprotocol/sdk).
2. On every tool call, it resolves super.config.ts from cwd (or -c), instantiates the cli's primitives (scanRepos, runCommit, etc.), and returns the structured result.
3. No long-running git processes are kept around between calls — each tool invocation is independent and idempotent.

Because the server delegates to @super-repo/cli, you can debug any tool by reproducing the equivalent CLI command. For example:

| Tool | Equivalent CLI | | --------------------- | ------------------------------------------------------- | | super_status | super status | | super_diff | super diff | | super_commit | super commit -m "<message>" |

Programmatic API

import { startServer } from '@super-repo/mcp'

await startServer({ configPath: './super.config.ts' })

startServer returns once the stdio transport closes. See src/server.ts for the complete signature.