# github-devhub-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) 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

| Tool | What it does |
| --- | --- |
| `github.get_repo` | Repo metadata (stars, language, default branch, archived…) |
| `github.list_repos` | Paginated, sorted repo list for an owner |
| `github.list_prs` | PRs filtered by state, with stats |
| `github.get_pr` | Full PR detail incl. head/base refs |
| `github.ci_status` | Check runs + combined commit status for a PR or ref |
| `github.code_search` | Code search across GitHub |
| `github.list_issues` | Issues filtered by state / labels / sort |
| `github.get_issue` | Single issue detail |
| `github.create_issue` | Create an issue (supports `dry_run` preview) |
| `github.add_issue_comment` | Comment on an issue/PR thread (supports `dry_run`) |
| `ai.review_pr` | Groq-powered code review of a PR diff |
| `ai.summarize_pr` | Concise "what/why/how/risks" PR summary |
| `ai.summarize_issue` | Issue + comment-thread summary |
| `ai.triage_issue` | Classify issue type/priority/labels with reasoning |
| `ai.gen_commit_message` | Conventional commit message from a PR |
| `ai.explain_repo` | Onboarding brief from README + file tree |
| `meta.health` | Connectivity + rate-limit + LLM ping check |

## 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

```bash
# 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:

```bash
# 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:

```bash
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

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

## Try these prompts

```text
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