mcp-diff-system

An MCP server that fetches, summarizes and reviews GitHub code diffs — built with FastMCP and deployed on AWS Fargate, with an SQS worker plane so that LLM calls never block the request/response cycle.

Built in phases. Each phase is tagged, runs on its own, and ends with something demonstrable. See ROADMAP.md for the full plan and docs/diagrams for the target architecture.

Current phase: 1 — walking skeleton. One tool, get_diff, hitting the real GitHub API. No auth, no AWS, no LLM.

---

The core design decision

A large diff takes 30–90 seconds to summarize. ALB idle timeouts — and MCP client patience — are both shorter than that.

So the summarize/review tools (Phase 3) don't call the LLM inline. They persist the diff, enqueue a job, and return a job_id in ~50ms. A separate worker tier, autoscaled on queue depth, does the slow work. One large diff can then never hold a connection open or starve capacity for anyone else.

get_diff stays synchronous, because a GitHub API call is a fast network round trip and the async job machinery would be overhead for no benefit.

---

Phase 1: running it

Requires Python 3.11+.

pip install -e ".[dev]"
cp .env.example .env        # optionally add a GitHub token

A token is optional for public repos, but without one GitHub allows only 60 requests/hour instead of 5000. You will hit that.

Start the server:

python -m src.api.server        # HTTP transport on :8000

Or poke at the tools interactively:

fastmcp dev src/api/server.py   # opens MCP Inspector

Then call get_diff with, say, repo=psf/requests, base=v2.31.0, head=v2.32.0.

Connecting Claude Desktop

{
  "mcpServers": {
    "diff": {
      "command": "python",
      "args": ["-m", "src.api.server"],
      "cwd": "/absolute/path/to/mcp-diff-system"
    }
  }
}

Tests

pytest
ruff check src tests

---

Two things about GitHub's diff API

Both are easy to get wrong, and both are pinned by tests in tests/test_github_client.py:

1. The diff media type goes in the Accept header, not a query parameter. Send Accept: application/vnd.github.diff. Get this wrong and GitHub quietly returns JSON instead of a diff — no error, just garbage flowing downstream.

2. Rate limiting is a 403, not a 429. The signal is x-ratelimit-remaining: 0. Keying off that header beats string-matching the response body.

---

Roadmap

Phase	Adds	Status
0	Repo skeleton, CI, lint, tests	Done
1	FastMCP server, get_diff	Done
2	S3 + DynamoDB + SQS job plane (stub worker, no LLM)	Next
3	Diff chunker + Anthropic client — real summaries
4	Circuit breakers, retries, DLQ, idempotent claim
5	JWT auth, atomic Redis rate limiting, payload guard
6	Correlation IDs, CloudWatch metrics, X-Ray
7	Terraform, dual ECS services, autoscaling, OIDC CI/CD

License

MIT