@workforge/gitq-mcp

@gitq/mcp

MCP server that exposes GitQ's stacked branch engine as tools for AI agents (Claude Code, Cursor, etc.).

Quick Start

Claude Code

Add to .claude/mcp.json:

{
  "mcpServers": {
    "gitq": {
      "command": "bun",
      "args": ["run", "/path/to/gitq/packages/mcp/bin/gitq-mcp.ts"]
    }
  }
}

Cursor

Add to .cursor/mcp.json with the same format.

Standalone

bun run packages/mcp/bin/gitq-mcp.ts          # resolve repo from cwd
bun run packages/mcp/bin/gitq-mcp.ts /repo     # explicit repo path

The server communicates over stdio using the Model Context Protocol.

Resources

URI	Description
stack://active	Full stack topology — nodes, parents, statuses, MR data
stack://diagnostics	Classified state per branch — situations, actions, badges
stack://preflight	Conflict predictions and drift warnings before rebase

Tools

Awareness (read-only)

Tool	Description
diagnose	Classified state of every branch — read this first
preflight	Predict conflicts before rebasing
get-diff	Diff between two refs
get-log	Commit history for a branch
get-cherry	Unique vs. duplicate commits (patch-ID)
list-conflicts	Conflicted files during a paused rebase
discover-stacks	Scan repo for branch stacks
preview-absorb	Preview how uncommitted changes distribute across branches

Rebase Workflow

Tool	Description
sync-stack	Fetch + rebase all branches onto latest trunk
cascade-merged	Rebase children of merged parents onto trunk
restack-from	Rebase a branch and descendants after mid-stack edits
continue-rebase	Continue after resolving conflicts (auto-loads pause state)
abort-rebase	Abort a paused rebase

Conflict Resolution

Tool	Description
propose-resolution	Analyze conflicts and propose strategies
resolve-conflicts	AI-resolve conflicts, write to disk, and stage
stage-files	Stage files after manual resolution

Stack Management

Tool	Description
add-branch	Add a branch to the stack (captures fork point)
remove-branch	Remove a branch (enforces removal policy)
rename-branch	Rename in git + update stack refs
reparent-branch	Move to a new parent (rebases + cascades)
fold-branch	Merge commits into parent and remove
split-branch	Split at a commit point
split-by-file	Split by file glob patterns
absorb	Distribute uncommitted changes to correct branches
reset-to-remote	Reset local branch to remote
toggle-unmanaged	Skip/unskip a branch during rebases

Forge Integration

Tool	Description
publish-stack	Push branches + create draft MRs/PRs
retarget-mr	Fix MR target branch to match stack parent
sync-forge	Refresh MR statuses from GitHub/GitLab
import-from-forge	Reconstruct a stack from existing MRs

Forge tools require a GitHub/GitLab token configured in GitQ Settings or via GITHUB_TOKEN / GITLAB_TOKEN env vars.

How It Works

The server resolves the repository from cwd at startup and caches it for the session. Tools follow the same load store → call core → save store pattern as the Electron shell's IPC handlers.

Rebase operations that pause on conflict persist state to .git/gitq-pause.json. The continue-rebase tool auto-loads this — agents don't need to track pause state themselves.

Development

bun install                    # install deps
bun run --filter @gitq/mcp check   # type-check