# proofhub-mcp

**ProofHub for Claude Code** — a zero-dependency **MCP server** (and a CLI) over the
[ProofHub](https://www.proofhub.com) v3 API, with a **BMAD** ticket-to-story sharder. Bring
your own key; nothing about your account ships in the package.

- **MCP server (primary):** 16 native tools to list / create / comment / complete tasks,
  advance tasks through board stages, and shard tickets into self-contained BMAD stories.
- **Context:** set a project + todolist once — skip the IDs for every subsequent call.
- **CLI (bundled):** the same operations from your terminal, CI, or cron.
- **Slash commands (bundled):** `/proofhub:setup` (guided config + verify) and `/proofhub:help`
  (tools + context workflow).

## Install as a Claude Code plugin

```
/plugin marketplace add yashmody/proofhub-mcp
/plugin install proofhub@proofhub-mcp
```

Then provide your key (bring-your-own-key). The fastest path is the guided command — run
**`/proofhub:setup`** and it will configure and verify for you. To do it by hand:

**Recommended — `.claude/settings.local.json` (launch-independent).** Add an `env` block to the
project's gitignored `.claude/settings.local.json`, then **fully restart Claude Code**:

```json
{
  "env": {
    "PROOFHUB_ACCOUNT": "yourteam",
    "PROOFHUB_API_KEY": "your-api-key"
  }
}
```

> ⚠️ A shell `export` in `~/.zshrc` works **only** when you launch Claude Code from a terminal.
> Started from the macOS Dock/Finder, Claude Code doesn't source your shell, so the `.mcp.json`
> placeholder `${PROOFHUB_API_KEY}` resolves empty and ProofHub returns *WRONG ACCESS TOKEN
> (code 1001)*. The `settings.local.json` env block avoids that. `.claude/settings.json` is
> committed — never put the key there.

Alternatives:

```sh
# Config file — any terminal, persists at ~/.config/proofhub/config.json (chmod 600)
proofhub login --account yourteam --key your-api-key

# Shell env — only if you always launch Claude Code from a terminal
export PROOFHUB_ACCOUNT="yourteam" PROOFHUB_API_KEY="your-api-key" && claude
```

Run `/mcp` to confirm the `proofhub` server is connected (or `proofhub doctor` from a terminal).
Tools then appear as `mcp__proofhub__list_tasks`, `mcp__proofhub__create_task`,
`mcp__proofhub__shard_to_story`, etc. Stuck? `/proofhub:setup` diagnoses and fixes it.

## Context + stages

Set a current project and list once so you don't have to repeat IDs:

```
/proofhub use 9654620832
/proofhub use-list 271191425865
/proofhub status          # confirm saved context
/proofhub add "QA smoke"  # no IDs needed
/proofhub find "QA"       # search across lists
/proofhub next 293931     # advance one stage automatically
/proofhub stage 293931 Review  # move to a named stage
/proofhub move 293931 --to-list 99887766
```

Stages are **discovered automatically** by scanning tasks — no API endpoint lists them. The
order defaults to stage-id ascending (best-effort board order). Override with:

```
/proofhub stages --set "Backlog,In Progress,Review,Done"
```

Or via the MCP tool: `set_context` with `stageOrder: "Backlog,In Progress,Review,Done"`.

## MCP tools (16)

| Tool | Does |
|---|---|
| `set_context` | save project / todolist / stageOrder as context |
| `get_context` | show current context |
| `list_projects` | list projects |
| `list_todolists` | list task lists (defaults to context) |
| `list_tasks` | list tasks in a todolist (defaults to context) |
| `get_task` | full JSON for one task (defaults to context) |
| `create_task` | create a task (defaults to context) |
| `comment` | comment on a task (defaults to context) |
| `complete` | mark a task complete (defaults to context) |
| `reopen` | reopen (un-complete) a task (defaults to context) |
| `find_task` | search tasks by title across all lists (defaults to context) |
| `list_stages` | discover board stages in id-ascending order (defaults to context) |
| `set_stage` | move task to a specific stage by name or id (defaults to context) |
| `next_stage` | advance task one stage forward automatically (defaults to context) |
| `move_task` | move task to another list / project (defaults to context) |
| `shard_to_story` | **BMAD:** shard a ticket into a self-contained story file |

All task-scoped tools accept `project` and `todolist` as optional overrides; they default to
saved context. `required` is `[]` on those tools.

## Environment overrides

| Variable | Purpose |
|---|---|
| `PROOFHUB_ACCOUNT` | ProofHub subdomain or full hostname |
| `PROOFHUB_API_KEY` | API key |
| `PROOFHUB_PROJECT` | Override saved context project (highest priority) |
| `PROOFHUB_TODOLIST` | Override saved context todolist (highest priority) |
| `PROOFHUB_STATE_PATH` | Override context state file path (default `~/.config/proofhub/state.json`) |

## BMAD sharding

`shard_to_story` turns a ProofHub ticket into a story with *Context / Acceptance
Criteria / Dev Notes / Tasks-Subtasks* and a suggested owner role + model tier — BMAD's core
move of embedding full context so the dev agent isn't guessing. See `templates/story.md`.

## CLI (bundled)

```sh
export PROOFHUB_ACCOUNT=... PROOFHUB_API_KEY=...
npx -p proofhub-mcp proofhub projects          # or, installed: proofhub projects
proofhub use <projectId>
proofhub use-list <todolistId>
proofhub add "My task"
proofhub find "keyword"
proofhub next <ticket>
proofhub stage <ticket> "Review"
proofhub move <ticket> --to-list <id>
proofhub done <ticket>
proofhub comment <projectId> <todolistId> <ticket> --body "..."
```

## Notes

- Auth header is `X-API-KEY` (not Bearer); a `User-Agent` is set automatically. The client
  throttles to ~25 req/10s and honours `Retry-After`.
- ProofHub returns some errors as HTTP 200 with a `{code,message}` envelope — the client
  surfaces those as errors. Mutations resolve the internal task id from the ticket number
  automatically.
- In-list stage changes use a plain `{ stage }` PUT. A cross-list move uses `move_task: true` and
  **must include `project`** — ProofHub returns a `{code:1301}` "Invalid request" without it.

```sh
npm test      # no-network self-test
```

MIT © Yash Mody