Skip to content

Commit d911d2d

Browse files
wgordon17wgordon17
committed
docs: adds MCP server docs and npm publish workflow
1 parent 57fff7f commit d911d2d

File tree

4 files changed

+190
-2
lines changed

4 files changed

+190
-2
lines changed

‎.github/workflows/publish-mcp.yml‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
name: Publish MCP Server
2+
on:
3+
push:
4+
tags: ["mcp@*"]
5+
permissions:
6+
contents: write
7+
jobs:
8+
publish:
9+
runs-on: ubuntu-latest
10+
steps:
11+
- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
12+
- uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5
13+
- uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
14+
with:
15+
node-version: 24
16+
registry-url: "https://registry.npmjs.org"
17+
- run: pnpm install --frozen-lockfile
18+
- run: pnpm --filter github-tracker-mcp run typecheck
19+
- run: pnpm --filter github-tracker-mcp run build
20+
- run: pnpm --filter github-tracker-mcp test
21+
- run: cd mcp && pnpm publish --access public --no-git-checks
22+
env:
23+
NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
24+
- name: Create GitHub Release
25+
uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
26+
with:
27+
tag_name: ${{ github.ref_name }}
28+
name: "MCP Server ${{ github.ref_name }}"
29+
body: |
30+
## Install
31+
```bash
32+
npx github-tracker-mcp
33+
```
34+
See [npm package](https://www.npmjs.com/package/github-tracker-mcp) for full documentation.
35+
generate_release_notes: true

‎CONTRIBUTING.md‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,13 +13,30 @@ pnpm run dev
1313

1414
The dev server starts at `http://localhost:5173`. You'll need a GitHub OAuth app client ID in `.env` (copy `.env.example` and fill in your value).
1515

16+
The repo uses a pnpm workspace: the root package is the SolidJS SPA; `mcp/` is a separate package (`github-tracker-mcp`) built with tsup. Running `pnpm install` at the root installs both.
17+
18+
To run the MCP server in standalone mode, set `GITHUB_TOKEN` before starting:
19+
20+
```bash
21+
GITHUB_TOKEN=ghp_... pnpm mcp:serve
22+
```
23+
24+
Fine-grained PATs with Contents (read) and Metadata (read) are sufficient for most tools.
25+
1626
## Running checks
1727

1828
```bash
19-
pnpm test # unit tests (Vitest)
29+
pnpm test # unit tests (Vitest — root + mcp/)
2030
pnpm test:e2e # Playwright E2E tests (chromium)
21-
pnpm run typecheck # TypeScript validation
31+
pnpm run typecheck # TypeScript validation (root + mcp/)
2232
pnpm run screenshot # Capture dashboard screenshot (saves to docs/)
33+
pnpm mcp:serve # Start the MCP server (requires GITHUB_TOKEN)
34+
```
35+
36+
To test MCP tools interactively, use the MCP Inspector:
37+
38+
```bash
39+
npx @modelcontextprotocol/inspector tsx mcp/src/index.ts
2340
```
2441

2542
CI runs typecheck, unit tests, and E2E tests on every PR. Make sure they pass locally before pushing.

‎README.md‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -145,6 +145,76 @@ OAuth tokens are stored in `localStorage` under an app-specific key — this is
145145

146146
See [DEPLOY.md](./DEPLOY.md) for Cloudflare, OAuth App, and CI/CD setup.
147147

148+
## MCP Server
149+
150+
The MCP (Model Context Protocol) server exposes curated dashboard data to AI clients like Claude Code and Cursor, letting them query your GitHub activity without leaving the editor.
151+
152+
### Quick start (published package)
153+
154+
```bash
155+
GITHUB_TOKEN=ghp_... npx github-tracker-mcp
156+
```
157+
158+
### Quick start (local dev)
159+
160+
```bash
161+
GITHUB_TOKEN=ghp_... pnpm mcp:serve
162+
```
163+
164+
### Available tools
165+
166+
| Tool | Description | Parameters |
167+
|------|-------------|------------|
168+
| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI | `scope` (involves_me\|all) |
169+
| `get_open_prs` | Open PRs with check status and review decision | `repo?`, `status?` (all\|needs_review\|failing\|approved\|draft) |
170+
| `get_open_issues` | Open issues across tracked repos | `repo?` |
171+
| `get_failing_actions` | In-progress or recently failed workflow runs | `repo?` |
172+
| `get_pr_details` | Detailed info about a specific PR | `repo`, `number` |
173+
| `get_rate_limit` | Current GitHub API rate limit status | — |
174+
175+
### Resources
176+
177+
- `tracker://config` — current dashboard configuration (selected repos, tracked users)
178+
- `tracker://repos` — list of tracked repositories
179+
180+
### WebSocket relay
181+
182+
Enable the WebSocket relay in Settings to let the MCP server receive live data directly from the dashboard without making extra API calls. When the relay is active, the MCP server uses dashboard data first and falls back to direct GitHub API calls.
183+
184+
### Claude Code integration
185+
186+
**Option A: Published package (recommended)**
187+
188+
Add to `~/.claude.json` (global) or `.claude/settings.json` (project):
189+
190+
```json
191+
{
192+
"mcpServers": {
193+
"github-tracker": {
194+
"command": "npx",
195+
"args": ["-y", "github-tracker-mcp"],
196+
"env": { "GITHUB_TOKEN": "ghp_..." }
197+
}
198+
}
199+
}
200+
```
201+
202+
**Option B: Local development**
203+
204+
```json
205+
{
206+
"mcpServers": {
207+
"github-tracker": {
208+
"command": "pnpm",
209+
"args": ["--prefix", "/path/to/github-tracker", "mcp:serve"],
210+
"env": { "GITHUB_TOKEN": "ghp_..." }
211+
}
212+
}
213+
}
214+
```
215+
216+
> **Security:** Don't commit `GITHUB_TOKEN` to source control. Fine-grained PATs with Contents (read) and Metadata (read) permissions are recommended for tighter security.
217+
148218
## Contributing
149219

150220
See [CONTRIBUTING.md](./CONTRIBUTING.md).

‎mcp/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# github-tracker-mcp
2+
3+
MCP server for [GitHub Tracker](https://github.com/gordon-code/github-tracker) — exposes dashboard data (open PRs, issues, failing CI) to AI clients like Claude Code and Cursor.
4+
5+
## Install
6+
7+
```bash
8+
# Run without installing
9+
npx github-tracker-mcp
10+
11+
# Or install globally
12+
npm install -g github-tracker-mcp
13+
```
14+
15+
## Configuration
16+
17+
| Variable | Required | Default | Description |
18+
|----------|----------|---------|-------------|
19+
| `GITHUB_TOKEN` | Yes* | — | GitHub PAT or OAuth token. Fine-grained PATs with Contents (read) and Metadata (read) are sufficient. |
20+
| `MCP_WS_PORT` | No | `9876` | WebSocket relay port for receiving live data from the dashboard SPA. |
21+
22+
*`GITHUB_TOKEN` is required for direct API mode. If the dashboard's WebSocket relay is connected, the server can serve data without it.
23+
24+
## Claude Code setup
25+
26+
Add to `~/.claude.json` (global) or `.claude/settings.json` (project):
27+
28+
```json
29+
{
30+
"mcpServers": {
31+
"github-tracker": {
32+
"command": "npx",
33+
"args": ["-y", "github-tracker-mcp"],
34+
"env": { "GITHUB_TOKEN": "ghp_..." }
35+
}
36+
}
37+
}
38+
```
39+
40+
> Don't commit `GITHUB_TOKEN` to source control. Use environment variables or a secrets manager.
41+
42+
## Available tools
43+
44+
| Tool | Description | Parameters |
45+
|------|-------------|------------|
46+
| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI | `scope` (involves_me\|all) |
47+
| `get_open_prs` | Open PRs with check status and review decision | `repo?`, `status?` (all\|needs_review\|failing\|approved\|draft) |
48+
| `get_open_issues` | Open issues across tracked repos | `repo?` |
49+
| `get_failing_actions` | In-progress or recently failed workflow runs | `repo?` |
50+
| `get_pr_details` | Detailed info about a specific PR | `repo`, `number` |
51+
| `get_rate_limit` | Current GitHub API rate limit status | — |
52+
53+
## Resources
54+
55+
- `tracker://config` — current dashboard configuration (selected repos, tracked users)
56+
- `tracker://repos` — list of tracked repositories
57+
58+
## WebSocket relay
59+
60+
Enable the WebSocket relay in the dashboard's Settings page to let the MCP server receive live data directly from the SPA. When connected, the server prefers relay data and falls back to direct GitHub API calls. This reduces API usage and gives the AI client real-time data without polling.
61+
62+
The relay listens on `ws://127.0.0.1:9876` by default. Override with `MCP_WS_PORT`.
63+
64+
## Full documentation
65+
66+
See the [GitHub Tracker repository](https://github.com/gordon-code/github-tracker) for deployment, contributing, and architecture details.

0 commit comments

Comments
 (0)