jaimenbell-github-mcp 0.1.0__tar.gz

jaimenbell_github_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaimen Bell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

jaimenbell_github_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,187 @@
+Metadata-Version: 2.4
+Name: jaimenbell-github-mcp
+Version: 0.1.0
+Summary: Public read+write reference MCP server over the GitHub REST API. Env-gated tool groups (read always on, write off by default), fine-grained PAT auth that degrades to the unauthenticated tier, typed rate-limit/error payloads. Reference portfolio implementation, NOT the official GitHub MCP server.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: httpx==0.28.1
+Provides-Extra: test
+Requires-Dist: pytest==9.0.3; extra == "test"
+Requires-Dist: respx==0.23.1; extra == "test"
+Dynamic: license-file
+
+# github-mcp
+
+A public read+write MCP server over the GitHub REST API -- built to the
+[desktop-mcp](https://github.com)/rag-mcp/mcp-factory standard (own
+pyproject, fastmcp server, honest README, real test suite). Env-gated tool
+groups, **write disabled by default**.
+
+## What this is / is not
+
+This is a **reference portfolio implementation** demonstrating a hardened
+read+write MCP server pattern over a real external SaaS API (GitHub) --
+env-gated tool groups, typed error/rate-limit handling, auth that degrades
+gracefully, a real test suite. It exists to show, concretely, "I build
+read/write MCP servers over external APIs" with a link a client can click.
+
+**It is NOT the official GitHub MCP server.** It does not aim for parity
+with GitHub's own MCP offering (GraphQL, Actions, webhooks, GitHub Apps are
+all out of scope -- see below). It started life as a factory-scaffolded
+read-only demo ([mcp-factory](https://github.com)'s
+`generated/github_read_server.py`) and was hand-hardened into this
+standalone read+write server -- the scaffold-then-harden path is itself part
+of the story this repo tells.
+
+## Tool groups
+
+| Group | Tools | Default state |
+|---|---|---|
+| `read` | `get_repo`, `list_issues`, `get_issue`, `list_pull_requests`, `get_pull_request`, `get_file_content`, `search_repos`, `get_user`, `list_commits` | always on, works unauthenticated (GitHub's 60 req/hr tier) |
+| `write` | `create_issue`, `comment_on_issue`, `update_issue_state`, `add_labels`, `create_pr_review_comment` | env-gated, **OFF by default** -- requires `GITHUB_MCP_ENABLE_WRITE=1` **and** `GITHUB_TOKEN` |
+
+A disabled write call returns a structured `policy_refusal` error (never a
+silent no-op, never a crash). A write call with the group enabled but no
+token returns a structured `auth_required` error -- the group gate and the
+token precondition are checked independently, both before any network call.
+
+## Write-safety-off-by-default
+
+This is defense-in-depth, mirroring desktop-mcp's `input` group: harness-level
+permission prompts are the first gate, but the server itself refuses every
+write tool unless its own environment explicitly opts in with
+`GITHUB_MCP_ENABLE_WRITE=1`, and even then refuses without a `GITHUB_TOKEN`.
+A misconfigured or overly-permissive MCP host cannot turn on GitHub mutations
+this process wasn't deliberately configured to allow. The registration this
+repo ships with (see `~/.claude.json`'s `github-mcp` entry) has the write
+group **absent from env** -- enabling it is a deliberate per-registration
+operator choice, not a code change.
+
+## Honest-capabilities table
+
+Every claim below maps to the file that implements it and the test(s) that
+verify it -- no capability is asserted without a corresponding implementation
+and test.
+
+| Claim | Implementation | Verified by |
+|---|---|---|
+| Repo metadata (stars, language, license, default branch, archived flag...) | `github_mcp/groups/read.py::get_repo` | `tests/test_read.py::TestGetRepo`, live: `tests/test_live_smoke.py::test_live_get_repo_real_json` |
+| List / fetch issues (PRs filtered from list) | `github_mcp/groups/read.py::list_issues`, `get_issue` | `tests/test_read.py::TestListIssues`, `TestGetIssue` |
+| List / fetch pull requests | `github_mcp/groups/read.py::list_pull_requests`, `get_pull_request` | `tests/test_read.py::TestListPullRequests`, `TestGetPullRequest` |
+| Read a repo file's content (base64-decoded, binary detected not decoded) | `github_mcp/groups/read.py::get_file_content` | `tests/test_read.py::TestGetFileContent` |
+| Search public repositories | `github_mcp/groups/read.py::search_repos` | `tests/test_read.py::TestSearchRepos` |
+| Public user/org profile | `github_mcp/groups/read.py::get_user` | `tests/test_read.py::TestGetUser` |
+| List commits on a branch/ref | `github_mcp/groups/read.py::list_commits` | `tests/test_read.py::TestListCommits` |
+| Open an issue | `github_mcp/groups/write.py::create_issue` | `tests/test_write.py::TestCreateIssue` |
+| Comment on an issue/PR | `github_mcp/groups/write.py::comment_on_issue` | `tests/test_write.py::TestCommentOnIssue` |
+| Open/close an issue | `github_mcp/groups/write.py::update_issue_state` | `tests/test_write.py::TestUpdateIssueState` |
+| Add labels to an issue/PR | `github_mcp/groups/write.py::add_labels` | `tests/test_write.py::TestAddLabels` |
+| Create a PR review comment on a diff line | `github_mcp/groups/write.py::create_pr_review_comment` | `tests/test_write.py::TestCreatePrReviewComment` |
+| Write group OFF by default, structured refusal when disabled | `github_mcp/config.py::group_enabled`, `gated_write` | `tests/test_config.py::TestGroupEnabled`, `tests/test_write.py::TestGateDisabledByDefault` |
+| Write tools require a token even when the group is enabled | `github_mcp/config.py::check_write_preconditions` | `tests/test_config.py::TestCheckWritePreconditions`, `tests/test_write.py::TestAuthRequiredWhenGroupEnabled` |
+| Fine-grained PAT auth, degrades to unauthenticated tier when absent | `github_mcp/client.py::_headers` | `tests/test_client.py::TestAuthHeaderInjection`, `tests/test_read.py::TestUnauthDegrade` |
+| GitHub primary rate-limit (403 + `X-RateLimit-Reset`) and secondary rate-limit (403 + `Retry-After`, no `X-RateLimit-Remaining`) both surface as a typed error with reset/retry time, never a crash | `github_mcp/client.py::_rate_limit_error`, `_is_rate_limit_response` | `tests/test_client.py::TestRateLimitError`, `tests/test_client.py::TestRateLimitError::test_secondary_rate_limit_no_ratelimit_headers_retry_after_only`, `tests/test_read.py::TestUnauthDegrade::test_get_repo_rate_limited_without_token_is_typed` |
+| Malformed owner/repo/path (control chars etc.) that would raise `httpx.InvalidURL` surfaces as a typed error, never an uncaught exception | `github_mcp/client.py::request` | `tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error` |
+| Generic 4xx/5xx surfaces as a typed error, never a crash | `github_mcp/client.py::_api_error` | `tests/test_client.py::TestApiError` |
+| Non-JSON / malformed responses and network failures surface as typed errors | `github_mcp/client.py::_handle_response`, `request` | `tests/test_client.py::TestDecodeError`, `TestNetworkError` |
+
+## Limitations (read before relying on this)
+
+- **REST v1 only.** No GraphQL API coverage.
+- **No webhooks / GitHub App auth.** Fine-grained PAT only.
+- **No Actions/workflow-dispatch tools.** Issue/PR CRUD is the v1 write surface.
+- **Unauthenticated read is rate-limited to 60 req/hr** by GitHub itself (10
+  req/min for search) -- expect `rate_limited` errors under sustained
+  unauthenticated use; set `GITHUB_TOKEN` (even a read-only fine-grained PAT)
+  to raise this considerably.
+- **`get_file_content` truncates past 100KB** and reports (rather than
+  decodes) non-UTF-8 files.
+- **No pagination beyond a single page** for list endpoints (`limit`, capped
+  per-endpoint, is the only page-size control in v1).
+- **Not registered with the mcp-factory hub.** Ships as a standalone repo
+  (own pyproject, system Python312 install), matching the rag-mcp/desktop-mcp
+  model.
+
+## Env vars
+
+| Var | Effect | Default |
+|---|---|---|
+| `GITHUB_MCP_ENABLE_WRITE` | enable the `write` tool group | unset (off) |
+| `GITHUB_TOKEN` | fine-grained PAT; read works without it (degraded unauth rate), write requires it | unset |
+| `GITHUB_MCP_LIVE` | `1` to run the real-network smoke test (see Testing) | unset (skip) |
+
+## Usage examples
+
+```jsonc
+// A tool call from the MCP host, illustrative -- not a shell command.
+{"tool": "get_repo", "arguments": {"owner": "anthropics", "repo": "anthropic-sdk-python"}}
+// -> {"ok": true, "full_name": "anthropics/anthropic-sdk-python", "stargazers_count": 1234, ...}
+
+// write group disabled (default):
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "policy_refusal", "group": "write", "required_env": "GITHUB_MCP_ENABLE_WRITE", ...}}
+
+// write group enabled, no token set:
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "auth_required", "tool": "create_issue", ...}}
+```
+
+## Testing
+
+```
+# unit suite (respx-mocked api.github.com, no real network touched)
+python -m pytest -q
+
+# handshake check -- prints every registered tool name
+python scripts/list_tools.py
+
+# real-network read smoke (get_repo against a stable public repo;
+# no write smoke exists anywhere in this suite -- see safety rails above)
+GITHUB_MCP_LIVE=1 python -m pytest -q -k live_get_repo
+```
+
+## Install
+
+```
+pip install -r requirements.txt   # or: pip install .
+# deps: fastmcp==3.4.2, httpx==0.28.1
+# test-only: pytest==9.0.3, respx==0.23.1
+```
+
+## Setup / connect
+
+1. `pip install -r requirements.txt` on Python 3.12+.
+2. (Optional) generate a [fine-grained PAT](https://github.com/settings/tokens?type=beta)
+   scoped to the repos you want read+write access to (Issues: read/write,
+   Pull requests: read/write, Contents: read is enough for v1). Read tools
+   work with **no token at all** -- they just run at GitHub's unauthenticated
+   60 req/hr tier.
+3. Add to your MCP host config (e.g. `~/.claude.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "C:\\Users\\jaime\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
+      "args": ["C:\\Users\\jaime\\projects\\github-mcp\\run_server.py"],
+      "env": {
+        "GITHUB_TOKEN": "your-fine-grained-pat-here"
+        // GITHUB_MCP_ENABLE_WRITE intentionally absent -- write stays off
+        // until you deliberately opt in per-deployment.
+      }
+    }
+  }
+}
+```
+
+4. To enable write tools for a given deployment, add
+   `"GITHUB_MCP_ENABLE_WRITE": "1"` to that entry's `env` block. This is a
+   registration-time operator decision, not a code change.
+
+Registered in `~/.claude.json` as `github-mcp` (stdio, system Python312,
+`read` group always on, `write` group absent from env -- off).
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/github-mcp

jaimenbell_github_mcp-0.1.0/README.md

@@ -0,0 +1,173 @@
+# github-mcp
+
+A public read+write MCP server over the GitHub REST API -- built to the
+[desktop-mcp](https://github.com)/rag-mcp/mcp-factory standard (own
+pyproject, fastmcp server, honest README, real test suite). Env-gated tool
+groups, **write disabled by default**.
+
+## What this is / is not
+
+This is a **reference portfolio implementation** demonstrating a hardened
+read+write MCP server pattern over a real external SaaS API (GitHub) --
+env-gated tool groups, typed error/rate-limit handling, auth that degrades
+gracefully, a real test suite. It exists to show, concretely, "I build
+read/write MCP servers over external APIs" with a link a client can click.
+
+**It is NOT the official GitHub MCP server.** It does not aim for parity
+with GitHub's own MCP offering (GraphQL, Actions, webhooks, GitHub Apps are
+all out of scope -- see below). It started life as a factory-scaffolded
+read-only demo ([mcp-factory](https://github.com)'s
+`generated/github_read_server.py`) and was hand-hardened into this
+standalone read+write server -- the scaffold-then-harden path is itself part
+of the story this repo tells.
+
+## Tool groups
+
+| Group | Tools | Default state |
+|---|---|---|
+| `read` | `get_repo`, `list_issues`, `get_issue`, `list_pull_requests`, `get_pull_request`, `get_file_content`, `search_repos`, `get_user`, `list_commits` | always on, works unauthenticated (GitHub's 60 req/hr tier) |
+| `write` | `create_issue`, `comment_on_issue`, `update_issue_state`, `add_labels`, `create_pr_review_comment` | env-gated, **OFF by default** -- requires `GITHUB_MCP_ENABLE_WRITE=1` **and** `GITHUB_TOKEN` |
+
+A disabled write call returns a structured `policy_refusal` error (never a
+silent no-op, never a crash). A write call with the group enabled but no
+token returns a structured `auth_required` error -- the group gate and the
+token precondition are checked independently, both before any network call.
+
+## Write-safety-off-by-default
+
+This is defense-in-depth, mirroring desktop-mcp's `input` group: harness-level
+permission prompts are the first gate, but the server itself refuses every
+write tool unless its own environment explicitly opts in with
+`GITHUB_MCP_ENABLE_WRITE=1`, and even then refuses without a `GITHUB_TOKEN`.
+A misconfigured or overly-permissive MCP host cannot turn on GitHub mutations
+this process wasn't deliberately configured to allow. The registration this
+repo ships with (see `~/.claude.json`'s `github-mcp` entry) has the write
+group **absent from env** -- enabling it is a deliberate per-registration
+operator choice, not a code change.
+
+## Honest-capabilities table
+
+Every claim below maps to the file that implements it and the test(s) that
+verify it -- no capability is asserted without a corresponding implementation
+and test.
+
+| Claim | Implementation | Verified by |
+|---|---|---|
+| Repo metadata (stars, language, license, default branch, archived flag...) | `github_mcp/groups/read.py::get_repo` | `tests/test_read.py::TestGetRepo`, live: `tests/test_live_smoke.py::test_live_get_repo_real_json` |
+| List / fetch issues (PRs filtered from list) | `github_mcp/groups/read.py::list_issues`, `get_issue` | `tests/test_read.py::TestListIssues`, `TestGetIssue` |
+| List / fetch pull requests | `github_mcp/groups/read.py::list_pull_requests`, `get_pull_request` | `tests/test_read.py::TestListPullRequests`, `TestGetPullRequest` |
+| Read a repo file's content (base64-decoded, binary detected not decoded) | `github_mcp/groups/read.py::get_file_content` | `tests/test_read.py::TestGetFileContent` |
+| Search public repositories | `github_mcp/groups/read.py::search_repos` | `tests/test_read.py::TestSearchRepos` |
+| Public user/org profile | `github_mcp/groups/read.py::get_user` | `tests/test_read.py::TestGetUser` |
+| List commits on a branch/ref | `github_mcp/groups/read.py::list_commits` | `tests/test_read.py::TestListCommits` |
+| Open an issue | `github_mcp/groups/write.py::create_issue` | `tests/test_write.py::TestCreateIssue` |
+| Comment on an issue/PR | `github_mcp/groups/write.py::comment_on_issue` | `tests/test_write.py::TestCommentOnIssue` |
+| Open/close an issue | `github_mcp/groups/write.py::update_issue_state` | `tests/test_write.py::TestUpdateIssueState` |
+| Add labels to an issue/PR | `github_mcp/groups/write.py::add_labels` | `tests/test_write.py::TestAddLabels` |
+| Create a PR review comment on a diff line | `github_mcp/groups/write.py::create_pr_review_comment` | `tests/test_write.py::TestCreatePrReviewComment` |
+| Write group OFF by default, structured refusal when disabled | `github_mcp/config.py::group_enabled`, `gated_write` | `tests/test_config.py::TestGroupEnabled`, `tests/test_write.py::TestGateDisabledByDefault` |
+| Write tools require a token even when the group is enabled | `github_mcp/config.py::check_write_preconditions` | `tests/test_config.py::TestCheckWritePreconditions`, `tests/test_write.py::TestAuthRequiredWhenGroupEnabled` |
+| Fine-grained PAT auth, degrades to unauthenticated tier when absent | `github_mcp/client.py::_headers` | `tests/test_client.py::TestAuthHeaderInjection`, `tests/test_read.py::TestUnauthDegrade` |
+| GitHub primary rate-limit (403 + `X-RateLimit-Reset`) and secondary rate-limit (403 + `Retry-After`, no `X-RateLimit-Remaining`) both surface as a typed error with reset/retry time, never a crash | `github_mcp/client.py::_rate_limit_error`, `_is_rate_limit_response` | `tests/test_client.py::TestRateLimitError`, `tests/test_client.py::TestRateLimitError::test_secondary_rate_limit_no_ratelimit_headers_retry_after_only`, `tests/test_read.py::TestUnauthDegrade::test_get_repo_rate_limited_without_token_is_typed` |
+| Malformed owner/repo/path (control chars etc.) that would raise `httpx.InvalidURL` surfaces as a typed error, never an uncaught exception | `github_mcp/client.py::request` | `tests/test_client.py::TestNetworkError::test_malformed_path_raises_invalid_url_caught_as_network_error` |
+| Generic 4xx/5xx surfaces as a typed error, never a crash | `github_mcp/client.py::_api_error` | `tests/test_client.py::TestApiError` |
+| Non-JSON / malformed responses and network failures surface as typed errors | `github_mcp/client.py::_handle_response`, `request` | `tests/test_client.py::TestDecodeError`, `TestNetworkError` |
+
+## Limitations (read before relying on this)
+
+- **REST v1 only.** No GraphQL API coverage.
+- **No webhooks / GitHub App auth.** Fine-grained PAT only.
+- **No Actions/workflow-dispatch tools.** Issue/PR CRUD is the v1 write surface.
+- **Unauthenticated read is rate-limited to 60 req/hr** by GitHub itself (10
+  req/min for search) -- expect `rate_limited` errors under sustained
+  unauthenticated use; set `GITHUB_TOKEN` (even a read-only fine-grained PAT)
+  to raise this considerably.
+- **`get_file_content` truncates past 100KB** and reports (rather than
+  decodes) non-UTF-8 files.
+- **No pagination beyond a single page** for list endpoints (`limit`, capped
+  per-endpoint, is the only page-size control in v1).
+- **Not registered with the mcp-factory hub.** Ships as a standalone repo
+  (own pyproject, system Python312 install), matching the rag-mcp/desktop-mcp
+  model.
+
+## Env vars
+
+| Var | Effect | Default |
+|---|---|---|
+| `GITHUB_MCP_ENABLE_WRITE` | enable the `write` tool group | unset (off) |
+| `GITHUB_TOKEN` | fine-grained PAT; read works without it (degraded unauth rate), write requires it | unset |
+| `GITHUB_MCP_LIVE` | `1` to run the real-network smoke test (see Testing) | unset (skip) |
+
+## Usage examples
+
+```jsonc
+// A tool call from the MCP host, illustrative -- not a shell command.
+{"tool": "get_repo", "arguments": {"owner": "anthropics", "repo": "anthropic-sdk-python"}}
+// -> {"ok": true, "full_name": "anthropics/anthropic-sdk-python", "stargazers_count": 1234, ...}
+
+// write group disabled (default):
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "policy_refusal", "group": "write", "required_env": "GITHUB_MCP_ENABLE_WRITE", ...}}
+
+// write group enabled, no token set:
+{"tool": "create_issue", "arguments": {"owner": "o", "repo": "r", "title": "bug"}}
+// -> {"ok": false, "error": {"type": "auth_required", "tool": "create_issue", ...}}
+```
+
+## Testing
+
+```
+# unit suite (respx-mocked api.github.com, no real network touched)
+python -m pytest -q
+
+# handshake check -- prints every registered tool name
+python scripts/list_tools.py
+
+# real-network read smoke (get_repo against a stable public repo;
+# no write smoke exists anywhere in this suite -- see safety rails above)
+GITHUB_MCP_LIVE=1 python -m pytest -q -k live_get_repo
+```
+
+## Install
+
+```
+pip install -r requirements.txt   # or: pip install .
+# deps: fastmcp==3.4.2, httpx==0.28.1
+# test-only: pytest==9.0.3, respx==0.23.1
+```
+
+## Setup / connect
+
+1. `pip install -r requirements.txt` on Python 3.12+.
+2. (Optional) generate a [fine-grained PAT](https://github.com/settings/tokens?type=beta)
+   scoped to the repos you want read+write access to (Issues: read/write,
+   Pull requests: read/write, Contents: read is enough for v1). Read tools
+   work with **no token at all** -- they just run at GitHub's unauthenticated
+   60 req/hr tier.
+3. Add to your MCP host config (e.g. `~/.claude.json`):
+
+```jsonc
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "C:\\Users\\jaime\\AppData\\Local\\Programs\\Python\\Python312\\python.exe",
+      "args": ["C:\\Users\\jaime\\projects\\github-mcp\\run_server.py"],
+      "env": {
+        "GITHUB_TOKEN": "your-fine-grained-pat-here"
+        // GITHUB_MCP_ENABLE_WRITE intentionally absent -- write stays off
+        // until you deliberately opt in per-deployment.
+      }
+    }
+  }
+}
+```
+
+4. To enable write tools for a given deployment, add
+   `"GITHUB_MCP_ENABLE_WRITE": "1"` to that entry's `env` block. This is a
+   registration-time operator decision, not a code change.
+
+Registered in `~/.claude.json` as `github-mcp` (stdio, system Python312,
+`read` group always on, `write` group absent from env -- off).
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/github-mcp

jaimenbell_github_mcp-0.1.0/github_mcp/client.py

@@ -0,0 +1,155 @@
+"""Thin sync httpx wrapper around api.github.com.
+
+One function per HTTP verb used by the tool groups (get/post/patch). Auth
+header injection when a token is present; degrades to GitHub's unauthenticated
+60 req/hr tier otherwise. GitHub's 403 primary rate-limit response (hourly
+quota, X-RateLimit-Reset) and secondary rate-limit response (abuse-detection
+heuristics, Retry-After) both surface as a typed `rate_limited` error; any
+other 4xx/5xx surfaces as a typed `github_api_error` -- never a raw
+exception/crash. A dedicated httpx.Client is created per call so tests can
+respx-mock deterministically without managing a shared client lifecycle
+across the process.
+"""
+from __future__ import annotations
+
+import json as json_module
+from typing import Any
+
+import httpx
+
+from . import config
+
+DEFAULT_TIMEOUT_S = 10.0
+
+
+def _headers() -> dict:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "github-mcp",
+    }
+    token = config.get_token()
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+def _rate_limit_error(tool: str, response: httpx.Response) -> dict:
+    reset_header = response.headers.get("X-RateLimit-Reset")
+    remaining = response.headers.get("X-RateLimit-Remaining")
+    retry_after = response.headers.get("Retry-After")
+    if reset_header:
+        message = f"GitHub API rate limit exceeded. Resets at unix time {reset_header}."
+    elif retry_after:
+        # GitHub's secondary rate limit: no X-RateLimit-* headers, just Retry-After.
+        message = f"GitHub API secondary rate limit exceeded. Retry after {retry_after}s."
+    else:
+        message = "GitHub API rate limit exceeded."
+    return {
+        "ok": False,
+        "error": {
+            "type": "rate_limited",
+            "message": message,
+            "tool": tool,
+            "status_code": response.status_code,
+            "reset_time": int(reset_header) if reset_header and reset_header.isdigit() else None,
+            "remaining": int(remaining) if remaining and remaining.isdigit() else None,
+            "retry_after_s": int(retry_after) if retry_after and retry_after.isdigit() else None,
+        },
+    }
+
+
+def _api_error(tool: str, response: httpx.Response) -> dict:
+    try:
+        body = response.json()
+        message = body.get("message", response.text)
+    except (json_module.JSONDecodeError, ValueError):
+        message = response.text or f"HTTP {response.status_code}"
+    return {
+        "ok": False,
+        "error": {
+            "type": "github_api_error",
+            "message": message,
+            "tool": tool,
+            "status_code": response.status_code,
+        },
+    }
+
+
+def _is_rate_limit_response(response: httpx.Response) -> bool:
+    """True for GitHub's primary rate limit (403 + X-RateLimit-Remaining: 0)
+    and its secondary rate limit (403 + Retry-After, no X-RateLimit-Remaining
+    -- triggered by abuse-detection/concurrency/rapid-write heuristics rather
+    than the hourly quota)."""
+    if response.status_code != 403:
+        return False
+    if response.headers.get("X-RateLimit-Remaining") == "0":
+        return True
+    return "Retry-After" in response.headers
+
+
+def _handle_response(tool: str, response: httpx.Response) -> dict:
+    if _is_rate_limit_response(response):
+        return _rate_limit_error(tool, response)
+    if response.status_code >= 400:
+        return _api_error(tool, response)
+    try:
+        data = response.json() if response.content else {}
+    except (json_module.JSONDecodeError, ValueError) as exc:
+        return {
+            "ok": False,
+            "error": {
+                "type": "decode_error",
+                "message": f"GitHub returned non-JSON content: {exc}",
+                "tool": tool,
+                "status_code": response.status_code,
+            },
+        }
+    return {"ok": True, "data": data, "status_code": response.status_code}
+
+
+def request(
+    tool: str,
+    method: str,
+    path: str,
+    *,
+    params: dict[str, Any] | None = None,
+    json: dict[str, Any] | None = None,
+) -> dict:
+    """Issue one request to api.github.com and return a structured result:
+    {"ok": True, "data": ..., "status_code": ...} on success, or
+    {"ok": False, "error": {...}} on any 4xx/5xx/decode failure. Network-level
+    exceptions (timeout, connection refused, DNS failure) AND malformed-URL
+    errors (e.g. a caller-supplied owner/repo/path containing characters that
+    make the assembled URL invalid) are also caught and surfaced as a typed
+    error rather than propagating -- the tool caller always gets a dict back,
+    never an exception. `httpx.InvalidURL` does not subclass `httpx.HTTPError`
+    (it's raised during URL construction, before any network I/O), so it is
+    listed explicitly -- omitting it would let a bad path/owner/repo value
+    crash the call instead of returning a clean error."""
+    url = f"{config.GITHUB_API_BASE}{path}"
+    try:
+        with httpx.Client(timeout=DEFAULT_TIMEOUT_S) as client:
+            response = client.request(method, url, headers=_headers(), params=params, json=json)
+    except (httpx.HTTPError, httpx.InvalidURL) as exc:
+        return {
+            "ok": False,
+            "error": {
+                "type": "network_error",
+                "message": str(exc),
+                "tool": tool,
+            },
+        }
+    return _handle_response(tool, response)
+
+
+def get(tool: str, path: str, *, params: dict[str, Any] | None = None) -> dict:
+    return request(tool, "GET", path, params=params)
+
+
+def post(tool: str, path: str, *, json: dict[str, Any] | None = None) -> dict:
+    return request(tool, "POST", path, json=json)
+
+
+def patch(tool: str, path: str, *, json: dict[str, Any] | None = None) -> dict:
+    return request(tool, "PATCH", path, json=json)

jaimenbell_github_mcp-0.1.0/github_mcp/config.py

@@ -0,0 +1,127 @@
+"""Config/safety layer for github-mcp.
+
+Tool-group gating + token loading + structured refusal/error payloads. This
+is the server's own defense-in-depth layer: even if a caller gets past
+harness permission prompts, the server itself refuses write actions unless
+GITHUB_MCP_ENABLE_WRITE=1 is set, and never proceeds with a write call that
+lacks a token -- mirroring desktop-mcp's config.gated pattern.
+
+Groups:
+  read  -- repo/issue/PR/file/user/commit lookups (always on, works
+           unauthenticated at GitHub's 60 req/hr tier)
+  write -- issue/PR-comment mutations (env-gated, OFF by default, requires
+           GITHUB_TOKEN)
+
+Env vars:
+  GITHUB_MCP_ENABLE_WRITE=1 -- enable the write group
+  GITHUB_TOKEN              -- fine-grained PAT; read works without it
+                               (degraded unauth rate), write requires it
+"""
+from __future__ import annotations
+
+import os
+
+GROUP_READ = "read"
+GROUP_WRITE = "write"
+
+_ENV_GATES = {
+    GROUP_WRITE: "GITHUB_MCP_ENABLE_WRITE",
+}
+
+GITHUB_API_BASE = "https://api.github.com"
+
+
+def _env_truthy(name: str) -> bool:
+    val = os.environ.get(name, "")
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+def group_enabled(group: str) -> bool:
+    """read is always on; write requires its env gate."""
+    if group == GROUP_READ:
+        return True
+    env_name = _ENV_GATES.get(group)
+    if env_name is None:
+        return False
+    return _env_truthy(env_name)
+
+
+def get_token() -> str | None:
+    """Fine-grained PAT from GITHUB_TOKEN, or None. Never logged; callers
+    must not include this value in any error payload or diagnostic."""
+    token = os.environ.get("GITHUB_TOKEN")
+    return token if token else None
+
+
+def policy_refusal(group: str, tool: str) -> dict:
+    """Structured refusal payload for a disabled tool group."""
+    env_name = _ENV_GATES.get(group, f"GITHUB_MCP_ENABLE_{group.upper()}")
+    return {
+        "ok": False,
+        "error": {
+            "type": "policy_refusal",
+            "message": (
+                f"Tool group '{group}' is disabled. Set {env_name}=1 in the "
+                f"server's environment to enable it."
+            ),
+            "group": group,
+            "tool": tool,
+            "required_env": env_name,
+        },
+    }
+
+
+def auth_required(tool: str) -> dict:
+    """Structured refusal payload for a write call with no GITHUB_TOKEN.
+    Write actions always require a token even when the group is enabled --
+    GitHub's write endpoints reject unauthenticated requests, so this is a
+    fast, clean local refusal instead of a round-trip 401/403."""
+    return {
+        "ok": False,
+        "error": {
+            "type": "auth_required",
+            "message": (
+                f"Tool '{tool}' requires a GitHub token. Set GITHUB_TOKEN in "
+                f"the server's environment (fine-grained PAT with the needed "
+                f"repo write scopes)."
+            ),
+            "tool": tool,
+        },
+    }
+
+
+def check_group(group: str, tool: str) -> dict | None:
+    """Gate check for a tool call. Returns a structured refusal dict if the
+    group is disabled, else None (caller proceeds)."""
+    if not group_enabled(group):
+        return policy_refusal(group, tool)
+    return None
+
+
+def check_write_preconditions(tool: str) -> dict | None:
+    """Combined gate for write tools: group must be enabled AND a token must
+    be present. Returns a structured refusal dict, else None."""
+    refusal = check_group(GROUP_WRITE, tool)
+    if refusal is not None:
+        return refusal
+    if get_token() is None:
+        return auth_required(tool)
+    return None
+
+
+def gated_write(fn):
+    """Decorator applied directly to write-group module functions so the
+    policy gate + token precondition is enforced at the source -- not just in
+    the MCP tool wrapper -- and is unit-testable without spinning up the
+    fastmcp server or hitting the network."""
+
+    def wrapper(*args, **kwargs):
+        refusal = check_write_preconditions(fn.__name__)
+        if refusal is not None:
+            return refusal
+        return fn(*args, **kwargs)
+
+    wrapper.__name__ = fn.__name__
+    wrapper.__doc__ = fn.__doc__
+    wrapper.__wrapped__ = fn
+    return wrapper