Metadata-Version: 2.4
Name: gh-backlog-mcp
Version: 0.2.0
Summary: GitHub Issues-backed backlog MCP server for Claude Code
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0

# backlog

An MCP server that wraps GitHub Issues as a lightweight backlog for Claude Code. Lets Claude create, track, and resolve work items using your GitHub repo as the backend — no extra database or token management required.

## How it works

The server exposes 12 tools to Claude via the [Model Context Protocol](https://modelcontextprotocol.io/):

| Tool | Description |
|------|-------------|
| `create_backlog_item` | Open a new issue with type and priority labels |
| `list_backlog_items` | List issues filtered by status, type, or priority |
| `get_backlog_item` | Fetch full issue details including comments |
| `search_backlog` | Full-text search across open issues |
| `start_working_on` | Mark an item in-progress |
| `add_progress_note` | Add a comment to track progress or log a decision |
| `complete_backlog_item` | Close an issue with a resolution summary |
| `reopen_backlog_item` | Reopen a closed issue with rationale |
| `migrate_branch_issues` | Transfer issues from one branch scope to another |
| `create_spike` | Open a formal research spike |
| `check_research` | Surface prior research before starting an investigation |
| `save_research_output` | Persist spike findings to `research/` in the working repo |

All GitHub operations go through the `gh` CLI — no personal access tokens to manage.

## Prerequisites

- Python 3.10+
- [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
- [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)

## Installation

```bash
uvx gh-backlog-mcp --setup
```

That's it. `uvx` fetches the package from PyPI on demand — no cloning, no `pip install`. The setup command:

1. Verifies `gh` is installed and authenticated
2. Registers the MCP server in `~/.claude.json`
3. Prints a CLAUDE.md snippet to add to your project

Labels are created automatically on first use in each repo. Restart Claude Code after setup to pick up the server.

## Configuration

Setup registers the server in `~/.claude.json` using `uvx`:

```json
{
  "mcpServers": {
    "backlog": {
      "type": "stdio",
      "command": "uvx",
      "args": ["gh-backlog-mcp"]
    }
  }
}
```

The repo is auto-detected from the current working directory via `gh repo view`. The server targets whichever GitHub repo you have open — no configuration needed.

## Labels

The server auto-creates these label groups on first use in each repo:

| Group | Values |
|-------|--------|
| **Status** | `backlog`, `in-progress`, `blocked` |
| **Type** | `feature`, `bug`, `design`, `research`, `question` |
| **Modifier** | `spike` — stacks with `research` to mark formal investigations |
| **Priority** | `priority:high`, `priority:medium`, `priority:low` |

## Branch Scoping

Issues are automatically scoped to the current git branch via `branch:X` labels. When you create or list backlog items, the server detects your current branch and applies the corresponding label.

- **Auto-detect** — `create_backlog_item`, `list_backlog_items`, `search_backlog`, and `create_spike` all default to the current git branch
- **Cross-branch view** — pass `branch="all"` to any of these tools to see/create items across all branches
- **Explicit branch** — pass `branch="feature/foo"` to target a specific branch regardless of what you have checked out
- **Graceful degradation** — if branch detection fails (not in a git repo, detached HEAD), scoping is silently skipped

### After merging a branch

Use `migrate_branch_issues` to transfer open issues from a merged feature branch to the target branch:

```
migrate_branch_issues(from_branch="feature/auth-rewrite")
```

The `to_branch` defaults to the current git branch, so after merging `feature/auth-rewrite` into `main`, just call this from `main` and the issues will be relabeled automatically.

## Research Spikes

A research spike is a formal investigation item that signals to the agent picking it up: enter plan mode, do web research, and produce a written output before any implementation begins.

### Creating a spike

```
create_spike(
  title="Evaluate vector DB options for embedding search",
  goal="Determine which vector database best fits our latency and cost requirements",
  research_questions="- What are the top open-source options?\n- How do they compare on query latency at 1M vectors?\n- What are the operational costs?",
  success_criteria="Output doc must include a comparison table and a recommendation with rationale",
  priority="high"
)
```

The issue is created with both `research` and `spike` labels. The body includes a structured template (Goal, Background, Research Questions, Success Criteria, Output path).

### Agent workflow for spikes

When an agent calls `start_working_on` on a spike, it receives explicit instructions to:

1. Enter plan mode
2. Call `check_research` to find any prior work on the topic
3. Use `WebSearch`/`WebFetch` to answer the research questions
4. Call `save_research_output` with the synthesized findings
5. Call `complete_backlog_item` to close the issue

### Research output files

`save_research_output` writes findings to `research/<issue-number>-<slug>.md` in the current working repository (determined via `git rev-parse --show-toplevel`). It also:

- Creates the `research/` directory if it doesn't exist
- Adds `research/` to `.gitignore` automatically so outputs are never accidentally committed
- Posts a comment on the GitHub issue linking to the file

### Checking prior research

```
check_research(topic="vector database")
```

Searches two sources:
1. Local `research/*.md` files — keyword match against filename and first 500 chars
2. GitHub spike issues (open and closed) matching the topic

Use this before creating a new spike or before implementing something that may have been researched previously.
