triage-mcp

A read-only Model Context Protocol server that lets a coding agent check a GitHub issue properly before it writes a fix.

I have had around a hundred pull requests merged into open-source projects, and the most common way to waste an afternoon is to fix something that already has an open PR, or to miss a contribution rule. Before I start on an issue I check the same four things by hand. This server gives an agent those checks as tools, so it does them too.

Tools

Every tool is read-only. There is no tool that comments, assigns, labels or opens a pull request.

check_existing_fix

This is the one that saves the most time. It collects pull requests that reference the issue from two places, the issue timeline and a search, merges duplicates, and returns one verdict:

A pull request that was closed without merging does not count as a fix.

Real output for markedjs/marked#4099, trimmed:

{
  "verdict": "open_pr_exists",
  "reason": "Open PR #4196 by VadimToptunov references issue #4099.",
  "pullRequests": [{ "number": 4196, "state": "open", "foundVia": ["timeline", "search"] }]
}

Related MCP server: slim-github-mcp

Run it

Needs Node 20 or newer. It is not published to npm, so build it from a clone:

git clone https://github.com/shaurya703/triage-mcp && cd triage-mcp
npm install
npm run build

Then point an MCP client at it. For Claude Code or Claude Desktop:

{
  "mcpServers": {
    "triage": {
      "command": "node",
      "args": ["/absolute/path/to/triage-mcp/dist/index.js"],
      "env": { "GITHUB_TOKEN": "<a token with public read access>" }
    }
  }
}

GITHUB_TOKEN is optional. Without it you get GitHub's lower unauthenticated rate limit, and find_related_code returns an error, because GitHub's code search refuses requests with no token.

Rate limits

GitHub rate limits are easy to handle badly: either the tool hangs for an hour or it hammers the API. This server does neither.

• If GitHub says to retry within 10 seconds, it waits and retries, twice at most.

• If the wait is longer, it does not wait. The agent gets an error that says when the limit resets.

• A 403 that is not a rate limit is reported as a permission error and is not retried.

The longest wait is configurable with TRIAGE_MAX_WAIT_MS.

Tests

npm test            # 43 tests, no network: fetch is mocked
npm run typecheck

The tests cover every verdict, duplicate pull requests found by both routes, closed-but-unmerged pull requests, each rate-limit path (with an injected clock, so nothing really sleeps), bad input, 404s, body truncation, and one end-to-end test that starts the real server over the SDK's in-memory transport and calls a tool through a real MCP client.

Limits worth knowing

• A pull request that only mentions an issue ("see #42") is treated the same as one that fixes it. When a pull request was merged but the issue is still open, the reason says so, so the agent can look.

• "I'll take this" in a comment is not detected as a claim.

• The AI-policy check is a keyword match. It returns the matching lines so the agent reads them instead of trusting a yes or no.

• The issue timeline is read for up to 500 events, and the search looks at the 30 most recently updated pull requests.

Design notes are in docs/DESIGN.md.

License

MIT