gh-backlog-mcp 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. gh_backlog_mcp-0.2.0/.github/workflows/publish.yml +18 -0
  2. gh_backlog_mcp-0.2.0/.gitignore +7 -0
  3. gh_backlog_mcp-0.2.0/PKG-INFO +148 -0
  4. gh_backlog_mcp-0.2.0/README.md +140 -0
  5. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/PKG-INFO +148 -0
  6. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/SOURCES.txt +11 -0
  7. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/dependency_links.txt +1 -0
  8. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/entry_points.txt +2 -0
  9. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/requires.txt +1 -0
  10. gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/top_level.txt +1 -0
  11. gh_backlog_mcp-0.2.0/pyproject.toml +21 -0
  12. gh_backlog_mcp-0.2.0/server.py +903 -0
  13. gh_backlog_mcp-0.2.0/setup.cfg +4 -0
gh_backlog_mcp-0.2.0/.github/workflows/publish.yml ADDED
@@ -0,0 +1,18 @@
1
+ name: Publish to PyPI
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+
8
+ jobs:
9
+ publish:
10
+ runs-on: ubuntu-latest
11
+ environment: pypi
12
+ permissions:
13
+ id-token: write
14
+ steps:
15
+ - uses: actions/checkout@v4
16
+ - uses: astral-sh/setup-uv@v4
17
+ - run: uv build
18
+ - uses: pypa/gh-action-pypi-publish@release/v1
gh_backlog_mcp-0.2.0/.gitignore ADDED
@@ -0,0 +1,7 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ *.egg-info/
4
+ dist/
5
+ build/
6
+ .env
7
+ CLAUDE.md
gh_backlog_mcp-0.2.0/PKG-INFO ADDED
@@ -0,0 +1,148 @@
1
+ Metadata-Version: 2.4
2
+ Name: gh-backlog-mcp
3
+ Version: 0.2.0
4
+ Summary: GitHub Issues-backed backlog MCP server for Claude Code
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: mcp>=1.0.0
8
+
9
+ # backlog
10
+
11
+ 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.
12
+
13
+ ## How it works
14
+
15
+ The server exposes 12 tools to Claude via the [Model Context Protocol](https://modelcontextprotocol.io/):
16
+
17
+ | Tool | Description |
18
+ |------|-------------|
19
+ | `create_backlog_item` | Open a new issue with type and priority labels |
20
+ | `list_backlog_items` | List issues filtered by status, type, or priority |
21
+ | `get_backlog_item` | Fetch full issue details including comments |
22
+ | `search_backlog` | Full-text search across open issues |
23
+ | `start_working_on` | Mark an item in-progress |
24
+ | `add_progress_note` | Add a comment to track progress or log a decision |
25
+ | `complete_backlog_item` | Close an issue with a resolution summary |
26
+ | `reopen_backlog_item` | Reopen a closed issue with rationale |
27
+ | `migrate_branch_issues` | Transfer issues from one branch scope to another |
28
+ | `create_spike` | Open a formal research spike |
29
+ | `check_research` | Surface prior research before starting an investigation |
30
+ | `save_research_output` | Persist spike findings to `research/` in the working repo |
31
+
32
+ All GitHub operations go through the `gh` CLI — no personal access tokens to manage.
33
+
34
+ ## Prerequisites
35
+
36
+ - Python 3.10+
37
+ - [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
38
+ - [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ uvx gh-backlog-mcp --setup
44
+ ```
45
+
46
+ That's it. `uvx` fetches the package from PyPI on demand — no cloning, no `pip install`. The setup command:
47
+
48
+ 1. Verifies `gh` is installed and authenticated
49
+ 2. Registers the MCP server in `~/.claude.json`
50
+ 3. Prints a CLAUDE.md snippet to add to your project
51
+
52
+ Labels are created automatically on first use in each repo. Restart Claude Code after setup to pick up the server.
53
+
54
+ ## Configuration
55
+
56
+ Setup registers the server in `~/.claude.json` using `uvx`:
57
+
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "backlog": {
62
+ "type": "stdio",
63
+ "command": "uvx",
64
+ "args": ["gh-backlog-mcp"]
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ 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.
71
+
72
+ ## Labels
73
+
74
+ The server auto-creates these label groups on first use in each repo:
75
+
76
+ | Group | Values |
77
+ |-------|--------|
78
+ | **Status** | `backlog`, `in-progress`, `blocked` |
79
+ | **Type** | `feature`, `bug`, `design`, `research`, `question` |
80
+ | **Modifier** | `spike` — stacks with `research` to mark formal investigations |
81
+ | **Priority** | `priority:high`, `priority:medium`, `priority:low` |
82
+
83
+ ## Branch Scoping
84
+
85
+ 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.
86
+
87
+ - **Auto-detect** — `create_backlog_item`, `list_backlog_items`, `search_backlog`, and `create_spike` all default to the current git branch
88
+ - **Cross-branch view** — pass `branch="all"` to any of these tools to see/create items across all branches
89
+ - **Explicit branch** — pass `branch="feature/foo"` to target a specific branch regardless of what you have checked out
90
+ - **Graceful degradation** — if branch detection fails (not in a git repo, detached HEAD), scoping is silently skipped
91
+
92
+ ### After merging a branch
93
+
94
+ Use `migrate_branch_issues` to transfer open issues from a merged feature branch to the target branch:
95
+
96
+ ```
97
+ migrate_branch_issues(from_branch="feature/auth-rewrite")
98
+ ```
99
+
100
+ 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.
101
+
102
+ ## Research Spikes
103
+
104
+ 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.
105
+
106
+ ### Creating a spike
107
+
108
+ ```
109
+ create_spike(
110
+ title="Evaluate vector DB options for embedding search",
111
+ goal="Determine which vector database best fits our latency and cost requirements",
112
+ 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?",
113
+ success_criteria="Output doc must include a comparison table and a recommendation with rationale",
114
+ priority="high"
115
+ )
116
+ ```
117
+
118
+ The issue is created with both `research` and `spike` labels. The body includes a structured template (Goal, Background, Research Questions, Success Criteria, Output path).
119
+
120
+ ### Agent workflow for spikes
121
+
122
+ When an agent calls `start_working_on` on a spike, it receives explicit instructions to:
123
+
124
+ 1. Enter plan mode
125
+ 2. Call `check_research` to find any prior work on the topic
126
+ 3. Use `WebSearch`/`WebFetch` to answer the research questions
127
+ 4. Call `save_research_output` with the synthesized findings
128
+ 5. Call `complete_backlog_item` to close the issue
129
+
130
+ ### Research output files
131
+
132
+ `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:
133
+
134
+ - Creates the `research/` directory if it doesn't exist
135
+ - Adds `research/` to `.gitignore` automatically so outputs are never accidentally committed
136
+ - Posts a comment on the GitHub issue linking to the file
137
+
138
+ ### Checking prior research
139
+
140
+ ```
141
+ check_research(topic="vector database")
142
+ ```
143
+
144
+ Searches two sources:
145
+ 1. Local `research/*.md` files — keyword match against filename and first 500 chars
146
+ 2. GitHub spike issues (open and closed) matching the topic
147
+
148
+ Use this before creating a new spike or before implementing something that may have been researched previously.
gh_backlog_mcp-0.2.0/README.md ADDED
@@ -0,0 +1,140 @@
1
+ # backlog
2
+
3
+ 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.
4
+
5
+ ## How it works
6
+
7
+ The server exposes 12 tools to Claude via the [Model Context Protocol](https://modelcontextprotocol.io/):
8
+
9
+ | Tool | Description |
10
+ |------|-------------|
11
+ | `create_backlog_item` | Open a new issue with type and priority labels |
12
+ | `list_backlog_items` | List issues filtered by status, type, or priority |
13
+ | `get_backlog_item` | Fetch full issue details including comments |
14
+ | `search_backlog` | Full-text search across open issues |
15
+ | `start_working_on` | Mark an item in-progress |
16
+ | `add_progress_note` | Add a comment to track progress or log a decision |
17
+ | `complete_backlog_item` | Close an issue with a resolution summary |
18
+ | `reopen_backlog_item` | Reopen a closed issue with rationale |
19
+ | `migrate_branch_issues` | Transfer issues from one branch scope to another |
20
+ | `create_spike` | Open a formal research spike |
21
+ | `check_research` | Surface prior research before starting an investigation |
22
+ | `save_research_output` | Persist spike findings to `research/` in the working repo |
23
+
24
+ All GitHub operations go through the `gh` CLI — no personal access tokens to manage.
25
+
26
+ ## Prerequisites
27
+
28
+ - Python 3.10+
29
+ - [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
30
+ - [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)
31
+
32
+ ## Installation
33
+
34
+ ```bash
35
+ uvx gh-backlog-mcp --setup
36
+ ```
37
+
38
+ That's it. `uvx` fetches the package from PyPI on demand — no cloning, no `pip install`. The setup command:
39
+
40
+ 1. Verifies `gh` is installed and authenticated
41
+ 2. Registers the MCP server in `~/.claude.json`
42
+ 3. Prints a CLAUDE.md snippet to add to your project
43
+
44
+ Labels are created automatically on first use in each repo. Restart Claude Code after setup to pick up the server.
45
+
46
+ ## Configuration
47
+
48
+ Setup registers the server in `~/.claude.json` using `uvx`:
49
+
50
+ ```json
51
+ {
52
+ "mcpServers": {
53
+ "backlog": {
54
+ "type": "stdio",
55
+ "command": "uvx",
56
+ "args": ["gh-backlog-mcp"]
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ 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.
63
+
64
+ ## Labels
65
+
66
+ The server auto-creates these label groups on first use in each repo:
67
+
68
+ | Group | Values |
69
+ |-------|--------|
70
+ | **Status** | `backlog`, `in-progress`, `blocked` |
71
+ | **Type** | `feature`, `bug`, `design`, `research`, `question` |
72
+ | **Modifier** | `spike` — stacks with `research` to mark formal investigations |
73
+ | **Priority** | `priority:high`, `priority:medium`, `priority:low` |
74
+
75
+ ## Branch Scoping
76
+
77
+ 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.
78
+
79
+ - **Auto-detect** — `create_backlog_item`, `list_backlog_items`, `search_backlog`, and `create_spike` all default to the current git branch
80
+ - **Cross-branch view** — pass `branch="all"` to any of these tools to see/create items across all branches
81
+ - **Explicit branch** — pass `branch="feature/foo"` to target a specific branch regardless of what you have checked out
82
+ - **Graceful degradation** — if branch detection fails (not in a git repo, detached HEAD), scoping is silently skipped
83
+
84
+ ### After merging a branch
85
+
86
+ Use `migrate_branch_issues` to transfer open issues from a merged feature branch to the target branch:
87
+
88
+ ```
89
+ migrate_branch_issues(from_branch="feature/auth-rewrite")
90
+ ```
91
+
92
+ 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.
93
+
94
+ ## Research Spikes
95
+
96
+ 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.
97
+
98
+ ### Creating a spike
99
+
100
+ ```
101
+ create_spike(
102
+ title="Evaluate vector DB options for embedding search",
103
+ goal="Determine which vector database best fits our latency and cost requirements",
104
+ 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?",
105
+ success_criteria="Output doc must include a comparison table and a recommendation with rationale",
106
+ priority="high"
107
+ )
108
+ ```
109
+
110
+ The issue is created with both `research` and `spike` labels. The body includes a structured template (Goal, Background, Research Questions, Success Criteria, Output path).
111
+
112
+ ### Agent workflow for spikes
113
+
114
+ When an agent calls `start_working_on` on a spike, it receives explicit instructions to:
115
+
116
+ 1. Enter plan mode
117
+ 2. Call `check_research` to find any prior work on the topic
118
+ 3. Use `WebSearch`/`WebFetch` to answer the research questions
119
+ 4. Call `save_research_output` with the synthesized findings
120
+ 5. Call `complete_backlog_item` to close the issue
121
+
122
+ ### Research output files
123
+
124
+ `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:
125
+
126
+ - Creates the `research/` directory if it doesn't exist
127
+ - Adds `research/` to `.gitignore` automatically so outputs are never accidentally committed
128
+ - Posts a comment on the GitHub issue linking to the file
129
+
130
+ ### Checking prior research
131
+
132
+ ```
133
+ check_research(topic="vector database")
134
+ ```
135
+
136
+ Searches two sources:
137
+ 1. Local `research/*.md` files — keyword match against filename and first 500 chars
138
+ 2. GitHub spike issues (open and closed) matching the topic
139
+
140
+ Use this before creating a new spike or before implementing something that may have been researched previously.
gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/PKG-INFO ADDED
@@ -0,0 +1,148 @@
1
+ Metadata-Version: 2.4
2
+ Name: gh-backlog-mcp
3
+ Version: 0.2.0
4
+ Summary: GitHub Issues-backed backlog MCP server for Claude Code
5
+ Requires-Python: >=3.10
6
+ Description-Content-Type: text/markdown
7
+ Requires-Dist: mcp>=1.0.0
8
+
9
+ # backlog
10
+
11
+ 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.
12
+
13
+ ## How it works
14
+
15
+ The server exposes 12 tools to Claude via the [Model Context Protocol](https://modelcontextprotocol.io/):
16
+
17
+ | Tool | Description |
18
+ |------|-------------|
19
+ | `create_backlog_item` | Open a new issue with type and priority labels |
20
+ | `list_backlog_items` | List issues filtered by status, type, or priority |
21
+ | `get_backlog_item` | Fetch full issue details including comments |
22
+ | `search_backlog` | Full-text search across open issues |
23
+ | `start_working_on` | Mark an item in-progress |
24
+ | `add_progress_note` | Add a comment to track progress or log a decision |
25
+ | `complete_backlog_item` | Close an issue with a resolution summary |
26
+ | `reopen_backlog_item` | Reopen a closed issue with rationale |
27
+ | `migrate_branch_issues` | Transfer issues from one branch scope to another |
28
+ | `create_spike` | Open a formal research spike |
29
+ | `check_research` | Surface prior research before starting an investigation |
30
+ | `save_research_output` | Persist spike findings to `research/` in the working repo |
31
+
32
+ All GitHub operations go through the `gh` CLI — no personal access tokens to manage.
33
+
34
+ ## Prerequisites
35
+
36
+ - Python 3.10+
37
+ - [uv](https://docs.astral.sh/uv/) installed (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
38
+ - [GitHub CLI](https://cli.github.com/) installed and authenticated (`gh auth login`)
39
+
40
+ ## Installation
41
+
42
+ ```bash
43
+ uvx gh-backlog-mcp --setup
44
+ ```
45
+
46
+ That's it. `uvx` fetches the package from PyPI on demand — no cloning, no `pip install`. The setup command:
47
+
48
+ 1. Verifies `gh` is installed and authenticated
49
+ 2. Registers the MCP server in `~/.claude.json`
50
+ 3. Prints a CLAUDE.md snippet to add to your project
51
+
52
+ Labels are created automatically on first use in each repo. Restart Claude Code after setup to pick up the server.
53
+
54
+ ## Configuration
55
+
56
+ Setup registers the server in `~/.claude.json` using `uvx`:
57
+
58
+ ```json
59
+ {
60
+ "mcpServers": {
61
+ "backlog": {
62
+ "type": "stdio",
63
+ "command": "uvx",
64
+ "args": ["gh-backlog-mcp"]
65
+ }
66
+ }
67
+ }
68
+ ```
69
+
70
+ 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.
71
+
72
+ ## Labels
73
+
74
+ The server auto-creates these label groups on first use in each repo:
75
+
76
+ | Group | Values |
77
+ |-------|--------|
78
+ | **Status** | `backlog`, `in-progress`, `blocked` |
79
+ | **Type** | `feature`, `bug`, `design`, `research`, `question` |
80
+ | **Modifier** | `spike` — stacks with `research` to mark formal investigations |
81
+ | **Priority** | `priority:high`, `priority:medium`, `priority:low` |
82
+
83
+ ## Branch Scoping
84
+
85
+ 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.
86
+
87
+ - **Auto-detect** — `create_backlog_item`, `list_backlog_items`, `search_backlog`, and `create_spike` all default to the current git branch
88
+ - **Cross-branch view** — pass `branch="all"` to any of these tools to see/create items across all branches
89
+ - **Explicit branch** — pass `branch="feature/foo"` to target a specific branch regardless of what you have checked out
90
+ - **Graceful degradation** — if branch detection fails (not in a git repo, detached HEAD), scoping is silently skipped
91
+
92
+ ### After merging a branch
93
+
94
+ Use `migrate_branch_issues` to transfer open issues from a merged feature branch to the target branch:
95
+
96
+ ```
97
+ migrate_branch_issues(from_branch="feature/auth-rewrite")
98
+ ```
99
+
100
+ 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.
101
+
102
+ ## Research Spikes
103
+
104
+ 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.
105
+
106
+ ### Creating a spike
107
+
108
+ ```
109
+ create_spike(
110
+ title="Evaluate vector DB options for embedding search",
111
+ goal="Determine which vector database best fits our latency and cost requirements",
112
+ 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?",
113
+ success_criteria="Output doc must include a comparison table and a recommendation with rationale",
114
+ priority="high"
115
+ )
116
+ ```
117
+
118
+ The issue is created with both `research` and `spike` labels. The body includes a structured template (Goal, Background, Research Questions, Success Criteria, Output path).
119
+
120
+ ### Agent workflow for spikes
121
+
122
+ When an agent calls `start_working_on` on a spike, it receives explicit instructions to:
123
+
124
+ 1. Enter plan mode
125
+ 2. Call `check_research` to find any prior work on the topic
126
+ 3. Use `WebSearch`/`WebFetch` to answer the research questions
127
+ 4. Call `save_research_output` with the synthesized findings
128
+ 5. Call `complete_backlog_item` to close the issue
129
+
130
+ ### Research output files
131
+
132
+ `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:
133
+
134
+ - Creates the `research/` directory if it doesn't exist
135
+ - Adds `research/` to `.gitignore` automatically so outputs are never accidentally committed
136
+ - Posts a comment on the GitHub issue linking to the file
137
+
138
+ ### Checking prior research
139
+
140
+ ```
141
+ check_research(topic="vector database")
142
+ ```
143
+
144
+ Searches two sources:
145
+ 1. Local `research/*.md` files — keyword match against filename and first 500 chars
146
+ 2. GitHub spike issues (open and closed) matching the topic
147
+
148
+ Use this before creating a new spike or before implementing something that may have been researched previously.
gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/SOURCES.txt ADDED
@@ -0,0 +1,11 @@
1
+ .gitignore
2
+ README.md
3
+ pyproject.toml
4
+ server.py
5
+ .github/workflows/publish.yml
6
+ gh_backlog_mcp.egg-info/PKG-INFO
7
+ gh_backlog_mcp.egg-info/SOURCES.txt
8
+ gh_backlog_mcp.egg-info/dependency_links.txt
9
+ gh_backlog_mcp.egg-info/entry_points.txt
10
+ gh_backlog_mcp.egg-info/requires.txt
11
+ gh_backlog_mcp.egg-info/top_level.txt
gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/entry_points.txt ADDED
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ gh-backlog-mcp = server:main
gh_backlog_mcp-0.2.0/gh_backlog_mcp.egg-info/requires.txt ADDED
@@ -0,0 +1 @@
1
+ mcp>=1.0.0
gh_backlog_mcp-0.2.0/pyproject.toml ADDED
@@ -0,0 +1,21 @@
1
+ [build-system]
2
+ requires = ["setuptools>=61", "setuptools-scm>=8"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "gh-backlog-mcp"
7
+ dynamic = ["version"]
8
+ description = "GitHub Issues-backed backlog MCP server for Claude Code"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ dependencies = [
12
+ "mcp>=1.0.0",
13
+ ]
14
+
15
+ [project.scripts]
16
+ gh-backlog-mcp = "server:main"
17
+
18
+ [tool.setuptools]
19
+ py-modules = ["server"]
20
+
21
+ [tool.setuptools_scm]