MCP integration¶

Jetsam includes a built-in Model Context Protocol server, making it usable as a tool provider for AI agents like Claude Code.

Setup¶

Automatic (recommended)¶

jetsam init --mcp

This adds the jetsam server entry to .mcp.json in your repo root. If the file already has other MCP servers configured, jetsam merges its entry without overwriting them.

Manual¶

Add to your .mcp.json:

{
  "mcpServers": {
    "jetsam": {
      "command": "jetsam",
      "args": ["serve"],
      "type": "stdio"
    }
  }
}

Or start the server directly:

# stdio transport (default, for Claude Code)
jetsam serve

# SSE transport (for HTTP-based clients)
jetsam serve --transport sse

Tool reference¶

Workflow tools (plan-based)¶

These tools return a plan that must be confirmed before execution. The workflow is: call tool → inspect/modify plan → confirm or cancel.

Tool	Description
`save`	Stage and commit changes
`sync`	Fetch, rebase/merge, push
`ship`	Stage, commit, push, open PR (skips commit if nothing to commit)
`switch`	Switch branches (stash-aware)
`start`	Begin work on issue/feature
`finish`	Merge PR and clean up
`tidy`	Prune merged branches
`release`	Tag, push tag, create release

Plan management tools¶

Tool	Description
`show_plan`	Inspect a plan before confirming
`modify_plan`	Change commit message or exclude files
`confirm`	Execute a plan
`cancel`	Discard a plan

Inspection tools (immediate)¶

These tools return results directly without creating plans.

Tool	Description
`status`	Repository state snapshot
`log`	Commit history
`diff`	Diff (stat or full)
`pr_view`	PR details for a branch
`pr_list`	List pull requests
`pr_comment`	Post a comment on a PR
`pr_review`	Submit a PR review (approve/request-changes/comment)
`pr_comments`	Read comments and reviews on a PR
`checks`	CI check status
`issues`	List issues
`issue_close`	Close an issue with optional comment
`git`	Pass-through any git command

Agent workflow example¶

A typical agent interaction using jetsam MCP tools:

Agent                              Jetsam
  │                                   │
  ├─ status() ───────────────────────>│
  │<──── {branch, dirty, staged, ...} │
  │                                   │
  ├─ save(message="fix bug") ────────>│
  │<──── {plan_id: "p_abc123",        │
  │       steps: [stage, commit],     │
  │       warnings: [...]}            │
  │                                   │
  ├─ confirm(id="p_abc123") ─────────>│
  │<──── {status: "ok",               │
  │       results: [{step: "stage",   │
  │                  ok: true}, ...]}  │

Plan lifecycle¶

Plans have a 5-minute TTL. If not confirmed within 5 minutes, they expire and must be regenerated. This prevents stale plans from executing against a changed repository state.

Before execution, jetsam validates that the repository state hash matches the hash recorded when the plan was created. If the repo has changed (new commits, staged files, etc.), execution fails with a stale_plan error and a suggestion to re-run the command.

Modifying plans¶

Plans can be adjusted before confirmation:

// Change the commit message
{"tool": "modify_plan", "params": {"id": "p_abc123", "message": "better message"}}

// Remove files from staging
{"tool": "modify_plan", "params": {"id": "p_abc123", "exclude": "*.log"}}

The response includes a diff showing what changed.

Error handling¶

All errors are returned as structured objects:

{
  "error": "plan_not_found",
  "message": "Plan p_abc123 not found or expired.",
  "suggested_action": "Re-run the original command.",
  "recoverable": true
}

Step failures include recovery suggestions:

Failure	Suggestion
Push rejected	`sync` (pull/rebase first)
Rebase conflict	Resolve conflicts, then `git rebase --continue`
Checkout blocked by dirty state	`save` or stash changes first
Tag already exists	Delete existing tag first

Pass-through¶

The git tool provides a raw escape hatch for any git operation not covered by workflow tools:

{"tool": "git", "params": {"args": ["rebase", "--abort"]}}

Returns {ok, stdout, stderr, returncode}.