fix(mcp): improves docs accuracy and hardens validation

- Aligns fine-grained PAT permissions across all 4 doc surfaces
- Documents direct API mode limitations for failing/approved filters
- Adds owner/repo format note, scope default, GITHUB_TOKEN safety net
- Fixes needs_review filter in direct mode (review-requested: qualifier)
- Parallelizes dashboard summary API calls with Promise.allSettled
- Adds VALID_TRACKED_LOGIN regex validation to TrackedUserSchema
- Widens CSP connect-src to ws://127.0.0.1:* for configurable ports
- Improves publish workflow with job-level permissions (least privilege)
- Fixes relay snapshot effect to track lastRefreshedAt (excludes hot poll)
- Removes BUG/FIX/PERF/SEC/UI comment labels throughout MCP codebase
- Adds unit tests for octokit client and MCP resources

Author: wgordon17

.github/workflows/publish-mcp.yml

@@ -2,11 +2,11 @@ name: Publish MCP Server
 on:
   push:
     tags: ["mcp@*"]
-permissions:
-  contents: write
 jobs:
-  publish:
+  build-and-publish:
     runs-on: ubuntu-latest
+    permissions:
+      contents: read
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
       - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5
@@ -21,6 +21,13 @@ jobs:
       - run: cd mcp && pnpm publish --access public --no-git-checks
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+  create-release:
+    runs-on: ubuntu-latest
+    needs: build-and-publish
+    permissions:
+      contents: write
+    steps:
       - name: Create GitHub Release
         uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2
         with:

.gitignore

@@ -2,6 +2,7 @@ node_modules/
 dist/
 mcp/dist/
 dist/shared/
+*.tsbuildinfo
 .wrangler/
 .dev.vars
 *.local

CONTRIBUTING.md

@@ -21,7 +21,7 @@ To run the MCP server in standalone mode, set `GITHUB_TOKEN` before starting:
 GITHUB_TOKEN=ghp_... pnpm mcp:serve
 ```
 
-Fine-grained PATs with Contents (read) and Metadata (read) are sufficient for most tools.
+Fine-grained PATs need Actions (read), Contents (read), Issues (read), Metadata (read), and Pull requests (read) permissions.
 
 ## Running checks
 

README.md

@@ -92,6 +92,7 @@ Conditional requests using `If-None-Match` headers — GitHub doesn't count 304
 
 ```
 src/
+  shared/           # Browser-agnostic types, schemas, format utils shared with MCP server
   app/
     components/
       dashboard/    # DashboardPage, IssuesTab, PullRequestsTab, ActionsTab,
@@ -105,9 +106,9 @@ src/
                     # LoadingSpinner, SkeletonRows, ToastContainer, NotificationDrawer,
                     # RepoLockControls, UserAvatarBadge, ExpandCollapseButtons,
                     # RepoGitHubLink, ChevronIcon, ExternalLinkIcon, Tooltip/InfoTooltip
-    lib/            # 14 modules: format, errors, notifications, oauth, pat, url,
+    lib/            # 15 modules: format, errors, notifications, oauth, pat, url,
                     # flashDetection, grouping, reorderHighlight, collections,
-                    # emoji, label-colors, sentry, github-emoji-map.json
+                    # emoji, label-colors, sentry, mcp-relay, github-emoji-map.json
     pages/          # LoginPage, OAuthCallback, PrivacyPage
     services/
       api.ts        # GitHub API methods — issues, PRs, workflow runs, user validation,
@@ -121,8 +122,11 @@ src/
       view.ts       # View state (tabs, sorting, filters, ignored items, locked repos)
   worker/
     index.ts        # OAuth token exchange endpoint, CORS, security headers
-tests/              # unit/component tests across 70 test files
-e2e/                # 15 E2E tests across 3 spec files
+mcp/
+  src/              # MCP server: tools, resources, WebSocket relay, Octokit fallback
+  tests/            # MCP server unit + integration tests
+tests/              # SPA unit/component tests
+e2e/                # Playwright E2E tests
 ```
 
 ## Development
@@ -165,13 +169,15 @@ GITHUB_TOKEN=ghp_... pnpm mcp:serve
 
 | Tool | Description | Parameters |
 |------|-------------|------------|
-| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI | `scope` (involves_me\|all) |
+| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI, PRs needing review, approved but unmerged | `scope?` (involves_me\|all, default: involves_me) |
 | `get_open_prs` | Open PRs with check status and review decision | `repo?`, `status?` (all\|needs_review\|failing\|approved\|draft) |
 | `get_open_issues` | Open issues across tracked repos | `repo?` |
 | `get_failing_actions` | In-progress or recently failed workflow runs | `repo?` |
 | `get_pr_details` | Detailed info about a specific PR | `repo`, `number` |
 | `get_rate_limit` | Current GitHub API rate limit status | — |
 
+`repo` parameters use `owner/repo` format (e.g., `octocat/hello-world`).
+
 ### Resources
 
 - `tracker://config` — current dashboard configuration (selected repos, tracked users)
@@ -213,7 +219,7 @@ Add to `~/.claude.json` (global) or `.claude/settings.json` (project):
 }
 ```
 
-> **Security:** Don't commit `GITHUB_TOKEN` to source control. Fine-grained PATs with Contents (read) and Metadata (read) permissions are recommended for tighter security.
+> **Security:** Don't commit `GITHUB_TOKEN` to source control. Classic PATs with `repo` and `read:org` scopes are recommended for full functionality. Fine-grained PATs also work (Actions, Contents, Issues, Metadata, Pull requests — all read) but skip scope validation at startup.
 
 ## Contributing
 

docs/USER_GUIDE.md

@@ -34,6 +34,7 @@ GitHub Tracker is a dashboard that aggregates open issues, pull requests, and Gi
 - [Notifications](#notifications)
 - [Tracked Items](#tracked-items)
 - [Repo Pinning](#repo-pinning)
+- [MCP Server Integration](#mcp-server-integration)
 - [Settings Reference](#settings-reference)
 - [Troubleshooting](#troubleshooting)
 
@@ -54,7 +55,7 @@ If you prefer not to use OAuth, you can sign in with a GitHub Personal Access To
 Two token formats are accepted:
 
 - **Classic tokens** (starts with `ghp_`) — recommended. Works across all organizations you belong to. Required scopes: `repo`, `read:org` (under admin:org), `notifications`.
-- **Fine-grained tokens** (starts with `github_pat_`) — also work, but have limitations: they only access one organization at a time, do not support the `notifications` scope, and therefore cannot use the background-poll optimization. Required permissions: Actions (read), Contents (read), Issues (read), Pull requests (read).
+- **Fine-grained tokens** (starts with `github_pat_`) — also work, but have limitations: they only access one organization at a time, do not support the `notifications` scope, and therefore cannot use the background-poll optimization. Required permissions: Actions (read), Contents (read), Issues (read), Metadata (read), Pull requests (read).
 
 The token is validated against the GitHub API before being stored. It is saved permanently in your browser's `localStorage` — you will not need to re-enter it on revisit.
 
@@ -359,6 +360,45 @@ Pin state is per-tab — a repo can be pinned on the Issues tab but not the Pull
 
 ---
 
+## MCP Server Integration
+
+The MCP (Model Context Protocol) server lets AI clients like Claude Code and Cursor query your dashboard data — open PRs, issues, failing CI — without leaving the editor.
+
+### Standalone mode
+
+Run the MCP server with a GitHub token for direct API access:
+
+```bash
+GITHUB_TOKEN=ghp_... npx github-tracker-mcp
+```
+
+This works without the dashboard open. The server fetches data directly from GitHub using the token. See the [MCP server README](https://github.com/gordon-code/github-tracker/tree/main/mcp) for Claude Code configuration and the full tool reference.
+
+### WebSocket relay mode
+
+For richer data without extra API calls, connect the MCP server to the running dashboard:
+
+1. Open **Settings > MCP Server Relay**
+2. Toggle **Enable relay** on
+3. The status indicator shows "Connected" when the MCP server is running and linked
+
+When connected, the MCP server receives live dashboard data over a local WebSocket connection (`ws://127.0.0.1:9876`). This provides the same enriched data you see in the dashboard — GraphQL-sourced review decisions, check statuses, and reviewer lists — without consuming additional API quota.
+
+The relay falls back to direct GitHub API calls automatically when the dashboard is closed. Set `GITHUB_TOKEN` even when using the relay as a safety net — without it, all tool calls fail if the relay disconnects.
+
+### Available tools
+
+| Tool | What it returns |
+|------|----------------|
+| `get_dashboard_summary` | Counts: open PRs, open issues, failing CI, PRs needing review, approved but unmerged |
+| `get_open_prs` | Open PRs with CI status, review decision, size, reviewers |
+| `get_open_issues` | Open issues across tracked repos |
+| `get_failing_actions` | In-progress or recently failed workflow runs |
+| `get_pr_details` | Full details for a specific PR |
+| `get_rate_limit` | Current GitHub API quota |
+
+---
+
 ## Settings Reference
 
 Settings are saved automatically to `localStorage` and persist across sessions. All settings can be exported as a JSON file via **Settings > Data > Export**.
@@ -382,6 +422,8 @@ Settings are saved automatically to `localStorage` and persist across sessions.
 | Remember last tab | On | Return to the last active tab on revisit. |
 | Enable tracked items | Off | Show the Tracked tab for pinning issues and PRs to a personal TODO list. |
 | API Usage | — | Displays per-source API call counts, pool labels (Core/GraphQL), and last-called timestamps for the current rate limit window. Counts auto-reset when the rate limit window expires. Use "Reset counts" to clear manually. |
+| MCP relay enabled | Off | Allow a local MCP server to receive live dashboard data over WebSocket. |
+| MCP relay port | 9876 | Port for the WebSocket relay connection. Must match the MCP server's `MCP_WS_PORT`. |
 
 ### View State Settings
 
@@ -430,6 +472,18 @@ When a tab has been hidden for more than 2 minutes, a catch-up fetch fires autom
 
 Go to **Settings > Repositories > Manage Repositories**, find the repo, and deselect it. If it was in the monitored list, it will be removed from monitoring automatically.
 
+**MCP relay shows "Connecting..." but never connects.**
+
+- Verify the MCP server is running (`GITHUB_TOKEN=ghp_... npx github-tracker-mcp` or `pnpm mcp:serve`)
+- Check that the port in Settings matches the MCP server's port (default: 9876)
+- The MCP server binds to `127.0.0.1` only — it must run on the same machine as your browser
+
+**MCP tools return empty or stale data.**
+
+- If the dashboard is open with the relay enabled, the MCP server uses live dashboard data. Navigate to the Dashboard tab to trigger a data load.
+- If the dashboard is closed, the MCP server falls back to direct API calls using `GITHUB_TOKEN`. REST search lacks check status and review decision data, so PR filters like `failing` and `approved` may return empty results. Use the relay for full filter accuracy.
+- The relay snapshot updates on each full refresh (every 5 minutes by default). Hot poll updates are not forwarded to the relay.
+
 **How do I sign out or reset everything?**
 
 - **Sign out**: Settings > Data > Sign out. This clears your auth token and returns you to the login page. Your config is preserved.

mcp/README.md

@@ -16,7 +16,7 @@ npm install -g github-tracker-mcp
 
 | Variable | Required | Default | Description |
 |----------|----------|---------|-------------|
-| `GITHUB_TOKEN` | Yes* | — | GitHub PAT or OAuth token. Fine-grained PATs with Contents (read) and Metadata (read) are sufficient. |
+| `GITHUB_TOKEN` | Yes* | — | Classic PAT with `repo` and `read:org` scopes (recommended), or fine-grained PAT with Actions (read), Contents (read), Issues (read), Metadata (read), and Pull requests (read) permissions. Fine-grained PATs skip scope validation at startup. |
 | `MCP_WS_PORT` | No | `9876` | WebSocket relay port for receiving live data from the dashboard SPA. |
 
 *`GITHUB_TOKEN` is required for direct API mode. If the dashboard's WebSocket relay is connected, the server can serve data without it.
@@ -43,24 +43,36 @@ Add to `~/.claude.json` (global) or `.claude/settings.json` (project):
 
 | Tool | Description | Parameters |
 |------|-------------|------------|
-| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI | `scope` (involves_me\|all) |
+| `get_dashboard_summary` | Aggregated counts of open PRs, issues, failing CI, PRs needing review, approved but unmerged | `scope?` (involves_me\|all, default: involves_me) |
 | `get_open_prs` | Open PRs with check status and review decision | `repo?`, `status?` (all\|needs_review\|failing\|approved\|draft) |
 | `get_open_issues` | Open issues across tracked repos | `repo?` |
 | `get_failing_actions` | In-progress or recently failed workflow runs | `repo?` |
 | `get_pr_details` | Detailed info about a specific PR | `repo`, `number` |
 | `get_rate_limit` | Current GitHub API rate limit status | — |
 
+`repo` parameters use `owner/repo` format (e.g., `octocat/hello-world`).
+
 ## Resources
 
 - `tracker://config` — current dashboard configuration (selected repos, tracked users)
 - `tracker://repos` — list of tracked repositories
 
 ## WebSocket relay
 
-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.
+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 the same enriched data visible in the dashboard without separate polling.
 
 The relay listens on `ws://127.0.0.1:9876` by default. Override with `MCP_WS_PORT`.
 
+### Direct API mode limitations
+
+Without the relay, the MCP server uses REST search which lacks some GraphQL-sourced fields. This affects:
+
+- `get_open_prs` — `status=failing` and `status=approved` filters return empty results (REST search lacks check status and review decision data). `status=needs_review` works correctly via the `review-requested:` search qualifier.
+- `get_dashboard_summary` — `approvedUnmergedCount` is always 0; `scope` parameter works as expected
+- `get_dashboard_summary` — when the relay IS connected, `scope` is ignored (the relay always reflects the dashboard's current data set)
+
+For full filter accuracy for `failing` and `approved` statuses, use the WebSocket relay.
+
 ## Full documentation
 
 See the [GitHub Tracker repository](https://github.com/gordon-code/github-tracker) for deployment, contributing, and architecture details.