GitHub Code MCP

An MCP server that gives the Rapid7 SI Triage agent read access to source code on GitHub — by default, anands-bounteous/nexpose. It fills the gap the other two servers don't cover: jira-confluence-mcp owns tickets/KB, log-intelligence-mcp owns log retrieval, but a Phase 2 investigation also needs to pull the actual Java source that produced a stack trace or defect. This server hits the real GitHub REST + Search APIs directly (no mocking, no local cloning) and is scoped specifically to reading code and returning fragments of it — issue/PR management stays out of scope.

owner/repo are optional per-call overrides on every tool, on top of the GITHUB_OWNER/GITHUB_REPO defaults, so the server can be pointed at another repo without a restart.

---

Tools

Tool	Purpose
search_code(query, path?, extension?, max_results=10, owner?, repo?)	The core "fetch fragments for input text" tool — GitHub code search with highlighted match fragments showing exactly where the query hit. Requires GITHUB_TOKEN (GitHub rejects unauthenticated code search).
get_file_contents(path, ref?, start_line?, end_line?, owner?, repo?)	Fetch a file, or just a 1-indexed inclusive line range of it.
list_symbols(path, ref?, owner?, repo?)	Enumerate the classes/interfaces/enums/records/methods/constructors declared in a Java file, with line ranges — use this to find a symbol name for get_code_fragment.
get_code_fragment(path, symbol, ref?, owner?, repo?)	Java-aware extraction of one method/class/constructor body by name. Falls back to a plain text context window if the symbol isn't a recognisable declaration.
list_directory(path="", ref?, owner?, repo?)	Browse the repo tree.
get_repository_info(owner?, repo?)	Description, default branch, language, topics, stars.
get_readme(ref?, owner?, repo?)	Project overview as plain text.
list_branches(max_results=25, owner?, repo?)	Branch names + latest commit sha.
list_commits(path?, max_results=10, owner?, repo?)	Recent history, optionally scoped to one file.

---

Java-aware fragment extraction

get_code_fragment/list_symbols are backed by a pluggable FRAGMENT_BACKEND:

• tree-sitter (AST-accurate) — parses with tree-sitter + tree-sitter-java. Correctly handles generics (Map<String, List<Foo>>), annotations, records, nested/anonymous classes, and text blocks — anything a hand-rolled brace-counter gets wrong on real Java. Optional dependency: pip install -e ".[java]".
• regex (dependency-free fallback) — matches Java declaration syntax to find a symbol's header line, then a string/char/comment-aware balanced-brace scanner (aware of ", ', //, /* */, and Java 15+ """ text blocks, so a {/} inside a literal or comment can't throw off the count) finds the matching close.
• auto (default) — tries tree-sitter first; if the optional dependency isn't installed, logs a warning and degrades to regex. Explicit choices (tree-sitter / regex) raise instead of silently degrading.

If a requested symbol isn't a recognisable Java declaration (e.g. it's a field name, or doesn't exist), both backends fall back to a plain ±FRAGMENT_CONTEXT_LINES text window around its first literal occurrence, with match_type="context_window" in the response so the caller can tell it's a lower-confidence result rather than an exact definition.

---

Auth & configuration

Copy .env.example to .env:

GITHUB_TOKEN=<create at github.com/settings/tokens>
GITHUB_API_BASE_URL=https://api.github.com
GITHUB_OWNER=anands-bounteous
GITHUB_REPO=nexpose
GITHUB_DEFAULT_REF=
MAX_FILE_KB=500
FRAGMENT_CONTEXT_LINES=20
FRAGMENT_BACKEND=auto
HTTP_TIMEOUT=30
HTTP_MAX_RETRIES=4
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8082

GITHUB_TOKEN is a GitHub personal access token (github.com/settings/tokens). It's optional for reading public repos — but required for search_code (GitHub's code search API rejects unauthenticated requests outright) and strongly recommended for everything else (5,000 requests/hour authenticated vs. 60/hour anonymous). A fine-grained PAT with read-only "Contents" access is enough; no repo write scope is needed since this server never writes to GitHub.

GITHUB_API_BASE_URL is overridable for GitHub Enterprise Server. It's normalised to just the scheme+host, same as any pasted API URL.

The HTTP client retries 429/5xx with exponential backoff (honouring Retry-After), and additionally watches GitHub's primary rate-limit signal (X-RateLimit-Remaining: 0 + X-RateLimit-Reset) to sleep until the limit resets rather than blindly backing off — controlled by HTTP_MAX_RETRIES and HTTP_TIMEOUT.

---

Install & run

cd github-mcp
python -m venv .venv && source .venv/bin/activate   # .venv\Scripts\Activate.ps1 on Windows
pip install -e .                # base install: mcp, httpx, uvicorn
pip install -e ".[java]"        # + tree-sitter/tree-sitter-java for AST-accurate fragments
cp .env.example .env            # fill in GITHUB_TOKEN

# stdio:
python -m github_mcp --transport stdio

# HTTP (streamable-http at http://127.0.0.1:8082/mcp):
python -m github_mcp --transport http

Register with an MCP client (stdio example)

{
  "mcpServers": {
    "github": {
      "command": "python",
      "args": ["-m", "github_mcp", "--transport", "stdio"],
      "env": {
        "GITHUB_TOKEN": "…",
        "GITHUB_OWNER": "anands-bounteous",
        "GITHUB_REPO": "nexpose"
      }
    }
  }
}

---

Ports

This server's HTTP transport defaults to 8082 — jira-confluence-mcp uses 8080 and log-intelligence-mcp uses 8081, so all three can run simultaneously.

---

Tests

pytest                      # in an environment with pytest installed
python tests/_runner.py     # offline harness when pytest isn't installed

Covers base-URL normalisation, content decoding, line-slicing, directory/repo/ branch/commit normalisation, search-query building and result normalisation, and — via a stub HTTP transport (FakeClient, no network needed) — file fetch with the MAX_FILE_KB size guard, directory listing, repo info/readme/ branches/commits, the search_code no-token guard, and the fragment-backend factory. The Java regex backend is exercised directly against a realistic fixture source file (tests/fixtures/Sample.java) covering nested classes, an interface, a generic method, an annotated method, and a string literal containing {/} to prove brace-in-string masking works. 30 tests, all offline — none need GITHUB_TOKEN or network access.

If tree-sitter-java isn't installed, tests target RegexJavaBackend explicitly rather than relying on FRAGMENT_BACKEND=auto resolution, so the suite stays runnable regardless of what's pip-installed.

Live GitHub API calls (a real search_code/get_file_contents against anands-bounteous/nexpose) need a real GITHUB_TOKEN and network access, which the automated test suite doesn't exercise — see "Install & run" above to try them manually.