Conduit

An MCP (Model Context Protocol) server that exposes real GitHub repository and issue data to any MCP client — Claude Desktop, or any other tool that speaks the protocol — through five standardized tools instead of a one-off integration per client.

Why MCP instead of a custom API wrapper

Without MCP, "let an LLM query GitHub" means writing a bespoke integration for every client that wants it. MCP standardizes that: build the server once, and Claude Desktop, a custom agent, or any other MCP-speaking client can call it the same way. This server is the data side of that — read-only access to public repos and issues, with a caching layer in front of it.

Tools exposed

Tool	What it does
list_repos(username, limit)	A user's public repos, most recently updated first
get_repo(owner, repo)	Description, language, stars, open issue count
list_issues(owner, repo, state, limit)	Issues only — pull requests filtered out
get_issue(owner, repo, number)	Full issue detail, including body text
get_readme(owner, repo)	Raw README content

Every tool response is slimmed down to the fields that matter (conduit/github_client.py) — GitHub's raw API payloads run 60+ keys deep, and handing an LLM all of it burns context for no reason.

Caching, and why it's not optional here

GitHub's unauthenticated REST API allows 60 requests/hour per IP. An LLM calling tools in a loop can burn through that in minutes. Every tool response is cached in SQLite (conduit/cache.py) with a configurable TTL (CACHE_TTL_SECONDS, default 300s) — a real engineering constraint this project actually has to handle, not a hypothetical one.

Two real bugs this caught while being built

1. A run stuck silently on a closed event loop. The first working version created its httpx.AsyncClient once at import time and reused it for every tool call. On Windows, that client's connection pool would occasionally try to close a pooled connection whose cleanup got scheduled against an event loop that had already moved on — RuntimeError: Event loop is closed, with no indication of why. Fixed two ways: the client is now built lazily on first real use instead of at import time, and connection keep-alive pooling is disabled (httpx.Limits(max_keepalive_connections=0)) so there's no pooled connection left around to race on.
2. Tests failing on GitHub's rate limit looked like code failures. Unauthenticated testing hit the 60/hour cap partway through development, and those failures were indistinguishable from real bugs in the output. tests/conftest.py now catches a 403 rate-limit response and skips with a clear reason instead of failing red for a constraint that has nothing to do with correctness.

Using it with Claude Desktop

Add to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "conduit": {
      "command": "python",
      "args": ["-m", "conduit"],
      "cwd": "/path/to/conduit",
      "env": { "GITHUB_TOKEN": "your-token-here" }
    }
  }
}

GITHUB_TOKEN is optional — public data works without one, just at the lower rate limit.

Running it

pip install -r requirements.txt
python -m conduit

Runs over stdio, which is what Claude Desktop (and most MCP clients) expect — there's no web dashboard for this one, since an MCP server's actual interface is the protocol itself, not a UI.

Running the tests

pytest -q

12 tests. test_cache.py is fully offline. test_github_client.py and test_server.py hit the real GitHub API on purpose — a mocked response would never have caught either bug above — and skip cleanly if the rate limit is already exhausted rather than failing.

Known limitations

• Read-only by design. A version that could open issues or comment would be a legitimately different, higher-risk project — this one doesn't attempt it.
• No auth beyond an optional personal access token — fine for public repos, not built for private repo access control.
• The SQLite cache is unbounded — nothing evicts old entries beyond TTL expiry. Fine at the scale one developer's tool calls generate; not designed for high-volume multi-user deployment.

License

MIT — see LICENSE.