github-devhub-mcp

A Model Context Protocol server (built on the official Python MCP SDK) that brings GitHub workflow tools and cost-free LLM-powered engineering tools to any MCP client (Claude Desktop, Claude Code, Cursor, …).

Two halves, one server:

• github.* — read/write tools over the GitHub REST API (typed, rate-limit-aware, paginated).

• ai.* — LLM tools powered by the Groq free tier (no billing setup): PR review, PR summary, issue summary, issue triage, commit messages, and repo onboarding briefs.

Built to demonstrate MCP SDK integration, third-party API integration, and careful tool design — the three things this project is for.

What it can do

Architecture

┌─────────────────────────┐         stdio (Claude Desktop / Code)
│        MCP client       │ ◄────── or streamable HTTP (--http)
└─────────────────────────┘
              │  JSON-RPC (MCPServer)
              ▼
┌────────────────────────────────────────────┐
│  github_devhub (server.py)                 │
│  ┌──────────────┐  ┌──────────────┐  ┌─────┴───┐
│  │ github.*     │  │ ai.*         │  │ meta.*  │
│  │ tools        │  │ tools        │  │ health  │
│  └──────┬───────┘  └──────┬───────┘  └─────────┘
│         ▼                 ▼
│  GithubClient      LLMProvider (Protocol)
│  (httpx,           GroqProvider (free tier)
│   rate-limit,      swap for Ollama / vLLM / any
│   structured       OpenAI-compatible endpoint)
│   errors)
└────────────────────────────────────────────┘

Quickstart

# 1. Python 3.10+; install the package (with dev deps for testing)
python -m pip install -e ".[dev]"

# 2. Configure
cp .env.example .env        # fill in GITHUB_TOKEN and GROQ_API_KEY

# 3. Run — the MCP Inspector is the easiest interactive demo
npx @modelcontextprotocol/inspector python -m github_devhub

# No Node.js installed? Same things work through the Python SDK client:
python scripts/smoke_client.py

Run with a client:

# Claude Desktop — claude_desktop_config.json
{
  "mcpServers": {
    "github-devhub": {
      "command": "python",
      "args": ["-m", "github_devhub"],
      "env": {
        "GITHUB_TOKEN": "ghp_...",
        "GROQ_API_KEY": "gsk_..."
      }
    }
  }
}

Or over HTTP:

python -m github_devhub --http   # streamable HTTP on http://localhost:8787/mcp

Getting the two free keys

1. GitHub — a classic personal access token (repo scope) or a fine-grained token with read access to contents/pulls/issues. → https://github.com/settings/tokens

2. Groq — free API key, no card required. → https://console.groq.com/keys

Design decisions (the resume part)

These are deliberate, and each maps to a thing engineering teams screen for:

1. LLM-actionable errors — every failure carries a stable code, a recoverable flag, and a plain-language remediation hint (errors.py). Tool errors are returned as structured JSON the calling agent can parse and self-correct (e.g. GITHUB_404 → verify the owner/repo and retry; GROQ_429 → back off). Opaque errors are the #1 agent-killer; this server never returns one.

2. Safety-first tool design — write tools (github.create_issue, github.add_issue_comment) default to a dry_run preview so an agent can show intent before mutating anything. Reads are read-only; page sizes are capped.

3. Rate-limit awareness — the GitHub client parses x-ratelimit-remaining on every call, surfaces it in results, and converts an exhausted quota into a dedicated recoverable error instead of a generic 403. The health tool reports current headroom.

4. Provider abstraction — tools depend on an LLMProvider protocol, not on Groq. Groq (free tier) is the default implementation; pointing the same server at a local Ollama or vLLM OpenAI-compatible endpoint is a config change. See llm/provider.py.

5. Context-budget guard — every prompt is truncated to a configurable char budget before hitting the LLM, so huge diffs can't blow a model's context window (LLM_MAX_INPUT_CHARS).

6. Protocol-level tests — the test suite drives the server through a real in-process MCP Client, so tool registration, arguments, dry-run behavior, and error serialization are verified over the protocol, not just as unit functions.

7. Two transports — stdio for local clients, streamable HTTP for remote tools.

Testing

python -m pip install -e ".[dev]"
python -m pytest          # or just: pytest

Try these prompts

List open PRs in octocat/Hello-World, then review PR #1 for me.

Triage issue #5 in octocat/Hello-World and propose labels.

Explain the architecture of facebook/react to a new contributor.

Summarize PR #3 in octocat/Hello-World and draft a commit message for it.

Check health, then show me open issues labeled bug in octocat/Hello-World.

See DEMO.md for a scripted walkthrough.

Resume bullets

• Built an MCP server on the official Python SDK exposing 17 typed tools across GitHub API integration and LLM-powered analysis, with stdio + streamable HTTP transports.

• Integrated the Groq free-tier API behind a swappable LLM provider abstraction with config-bounded context budgets.

• Designed LLM-actionable error protocol (stable codes + recoverable + remediation hints) and dry_run-safe write tools, validated by protocol-level tests over the MCP wire.

Roadmap

• OAuth device flow instead of a static token

• Webhook → MCP notifications for live PR/CI events

• Per-session session pools on the HTTP transport

• Cached embeddings for repo-wide semantic search