mcp-github-agent 0.1.0__py3-none-any.whl

mcp_github_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,153 @@
+Metadata-Version: 2.4
+Name: mcp-github-agent
+Version: 0.1.0
+Summary: MCP server giving AI agents controlled GitHub access with policy guard and audit trail
+Author-email: Morgan Fu <maogenfu0121@163.com>
+License: MIT
+Project-URL: Homepage, https://github.com/FMorgan-111/github-mcp-server
+Project-URL: Repository, https://github.com/FMorgan-111/github-mcp-server
+Project-URL: Issues, https://github.com/FMorgan-111/github-mcp-server/issues
+Keywords: mcp,github,ai-agent,claude-code,codex,policy,audit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+
+# GitHub MCP Agent Server
+
+[![CI](https://github.com/FMorgan-111/github-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/FMorgan-111/github-mcp-server/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/downloads/release/python-3100/)
+[![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+> MCP server giving AI agents controlled GitHub access with policy guard and audit trail.
+
+---
+
+## Architecture
+
+```
+   ┌───────────────┐        MCP stdio         ┌───────────────────┐
+   │   AI Agent    │ ◄──────────────────────► │ GitHub MCP Server │
+   │ (Claude, Codex│      JSON-RPC 2.0        │                   │
+   │   or any MCP  │                         ┌─┴───────────────┐   │
+   │    client)    │                         │ Policy Guard    │   │
+   └───────────────┘                         ├─────────────────┤   │
+                                             │ Audit Log       │   │
+                                             └─────────────────┘   │
+           ┌──────────────────────────────────────────────┐      │
+           │                 github_client.py               │      │
+           │                    (httpx)                     │      │
+           │                   GitHub API                   │      │
+           └──────────────────────────────────────────────┘      │
+           ┌──────────────────────────────────────────────┐      │
+           │          Review Engine (ruff + regex)          │      │
+           └──────────────────────────────────────────────┘      │
+                                                                └───┘
+```
+
+---
+
+## Features & Tools
+
+| Tool              | Description                                | Example Input                                                                 | Example Output                              |
+|-------------------|--------------------------------------------|-------------------------------------------------------------------------------|---------------------------------------------|
+| `search_code`     | Search GitHub repo code by query            | `search_code("def main", "owner/repo")`                                       | List of matching files with paths & URLs    |
+| `list_issues`     | List open or closed issues                   | `list_issues("owner/repo", state="open")`                                     | Formatted list of issues                    |
+| `create_issue`    | Create a new issue (policy-guarded)          | `create_issue("owner/repo", "Bug: timeout", "Steps to reproduce...")`         | Confirmation with issue URL                 |
+| `get_pr_diff`     | Fetch raw diff of a pull request             | `get_pr_diff("owner/repo", pr_number=7)`                                      | Unified diff as text                        |
+| `create_pr`       | Create a pull request between branches       | `create_pr("owner/repo", "Add feature", "Details...", head="feat", base="main")` | Confirmation with PR URL                   |
+| `review_pr_diff`  | Run local automated code review rules        | `review_pr_diff("owner/repo", pr_number=7)`                                   | List of warnings and errors found           |
+| `comment_pr_review`| Post review findings as PR comments         | `comment_pr_review("owner/repo", pr_number=7)`                                | Number of comments posted                   |
+
+---
+
+## Security Model
+
+- **Repository Allowlist:** Only repositories explicitly allowed by policy can be accessed.
+- **Branch Protection:** PRs to protected branches are subject to branch protection rules before merging.
+- **Dry-Run Mode:** Execute operations without side effects for safe testing and auditing.
+- **Audit Logging:** All actions logged in JSONL format with precise timestamps to maintain traceability.
+- **Policy Configuration:** Start from `policy.example.json` to configure repository allowlists and protected branches.
+
+---
+
+## FAQ
+
+**Why not call the GitHub API directly?**  
+Direct API calls lack centralized policy enforcement, audit logging, and uniform tooling support for AI agents. This MCP server adds a controlled, auditable layer for safer automation.
+
+**What MCP clients work with this?**  
+Agents like Claude Code, OpenAI Codex, and any client supporting the MCP JSON-RPC 2.0 transport can connect to this server.
+
+**How is this different from the official GitHub MCP server?**  
+This project's key differentiator is policy enforcement. Repository allowlists prevent agents from touching unauthorized repos, branch protection blocks accidental PRs to sensitive branches, dry-run mode supports safe validation, and write actions are audit-logged with timestamps.
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.10+
+- GitHub personal access token with `repo` scope
+
+### Install
+
+```bash
+pip install fastmcp httpx python-dotenv
+```
+
+### Configure and Run
+
+```bash
+git clone https://github.com/FMorgan-111/github-mcp-server.git
+cd github-mcp-server
+cp .env.example .env && nano .env
+python3 -m src.main
+```
+
+### Connect with Claude Code
+
+```bash
+claude mcp add github-agent -- python3 /path/to/github-mcp-server/src/main.py
+```
+
+---
+
+## Development
+
+```bash
+pip install -e . --break-system-packages
+python3 -m pytest tests/ -v
+python3 -m src.main
+```
+
+23 tests, all passing.
+
+---
+
+## Deployment with Docker
+
+```bash
+docker build -t github-mcp-server .
+docker run -e GITHUB_TOKEN=ghp_your_token_here -i github-mcp-server
+```
+
+The `-e GITHUB_TOKEN=...` flag passes the token into the container because the local `.env` file is not copied into the image.
+
+---
+
+## License
+
+MIT

mcp_github_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+src/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+src/audit.py,sha256=g6A_eFiE8J7JR1sCXuVnIhvFTNX3en2fkEO3u57B1Pw,4072
+src/config.py,sha256=yQNjY8-cwbpsmoHJQM510bSjsHtMzlsdEeHCkaLDiZE,923
+src/diff_parser.py,sha256=_Kov_1Rca3yCG14vmhwlHlcdRv5qjtI1sttGzTNnGRE,1282
+src/github_client.py,sha256=r33uLy0qSiKI9QOUxSu4WKPx6OXL4mWyAG2Iwh9SsjE,4476
+src/main.py,sha256=QF9cGxSUH7HsiQHgdh6SbhRJbDQuB4l-sFRVhwP8NyA,727
+src/policy.py,sha256=p3Nl4FywiEbb9gSbGjlRxW4A6wlLsY8IOhPEIrdQ7Fk,4647
+src/review.py,sha256=I0_gSxNyBiLKG4dvFsqzu_QV-rZHXMNDZm8WJ_UI0PM,4299
+src/review_engine.py,sha256=snsa7MjHwd94rueENuTdGOArHO5cAd8qhX0in4YmY-M,2804
+src/tools.py,sha256=C7vLFL8rMWTkHgg06jvufUlfp854BEy9brCB-AhfrjE,9956
+src/analyzers/base.py,sha256=B82EoBGWBikAVUo9t2vHLA7uQQxNWLGh-kB9zrjlMEA,544
+src/analyzers/ruff.py,sha256=gcP6lFO-agYesDxHoldUnBfbpkFTI96vXWkaqd7tgQs,1498
+tests/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+tests/test_audit.py,sha256=LuP0d6T6Q1AyhJBqoJc1XK-Zjzex7AG7RFk8-nvvVsc,6612
+tests/test_config.py,sha256=uVFgkmo3IOfnYPziBgdr5fAv5xziTcTIqTd4oulyVz4,1610
+tests/test_diff_parser.py,sha256=JRH2xWL0zQYQOtJalecplWRE44tFTVT6QbCQ2gPlExk,1648
+tests/test_github_client.py,sha256=rEO3RnT9jc0y9ePqji18D0j1kYghYboKJFffAvjJom4,6307
+tests/test_main.py,sha256=1Yugo8k_B8WbuLBm2ovyDojMmGHwQL4rexyqfv5x1Pk,1489
+tests/test_policy.py,sha256=KiyFJjvyV-qSS5dwChRtgC3Ec77Ev9OLbKSHk0LAczg,5142
+tests/test_review_engine.py,sha256=lmpN9Jd3VQ7QI4udr-EH7j0T7DeJafoo-6VQeuQ9xaI,5624
+tests/test_ruff_analyzer.py,sha256=CdDhIRZtjF-py1zGWpwiJRjGrwfrjO51K47DSFBnruM,2451
+tests/test_tools.py,sha256=5dSkd1rPwDsRGRL2kBQ_UVmwveQp4TpL2aN4SFC5ADs,14269
+mcp_github_agent-0.1.0.dist-info/METADATA,sha256=J3iBTSJ2ZPg04wsRsBiTVpF2FLsOf6LHmHv8ioSFIsU,7558
+mcp_github_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mcp_github_agent-0.1.0.dist-info/entry_points.txt,sha256=9NAVe9kKlXQM0qPY4-hFkjPzrk8GrrknzGYuBDnKBUg,45
+mcp_github_agent-0.1.0.dist-info/top_level.txt,sha256=KW3xgkz9NLMTcmmzgKvW8RFpCFkRIQ085qzq2diFf68,10
+mcp_github_agent-0.1.0.dist-info/RECORD,,

mcp_github_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcp_github_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+github-mcp = src.main:main

mcp_github_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+src
+tests

src/analyzers/base.py

@@ -0,0 +1,21 @@
+"""Analyzer protocol — pluggable code analysis backends."""
+from dataclasses import dataclass, field
+from typing import Protocol
+
+
+@dataclass
+class Finding:
+    severity: str       # "error" | "warning" | "info"
+    file: str
+    line: int
+    rule: str           # e.g. "F401", "E501"
+    message: str
+    suggestion: str = ""
+    source: str = ""    # "ruff", "bandit", "regex"
+
+
+class Analyzer(Protocol):
+    """Any backend that takes file path → list of Findings."""
+
+    def analyze(self, file_path: str) -> list[Finding]:
+        ...

src/analyzers/ruff.py

@@ -0,0 +1,49 @@
+"""Ruff subprocess analyzer — run ruff check as JSON, return Findings."""
+import json
+import subprocess
+from pathlib import Path
+
+from .base import Finding
+
+
+class RuffAnalyzer:
+    """Run ruff check on a file, return structured findings."""
+
+    def __init__(self, ruff_cmd: str = "ruff"):
+        self.cmd = ruff_cmd
+
+    def analyze(self, file_path: str) -> list[Finding]:
+        path = Path(file_path)
+        if path.suffix != ".py":
+            return []
+
+        try:
+            result = subprocess.run(
+                [self.cmd, "check", "--output-format", "json", str(path)],
+                capture_output=True,
+                text=True,
+                timeout=30,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return []
+
+        if result.returncode not in (0, 1):
+            return []  # ruff crash / config error? skip
+
+        try:
+            violations = json.loads(result.stdout or "[]")
+        except json.JSONDecodeError:
+            return []
+
+        findings = []
+        for v in violations:
+            findings.append(Finding(
+                severity="error" if v.get("fix") else "warning",
+                file=v.get("filename", str(path)),
+                line=v.get("location", {}).get("row", 0),
+                rule=v.get("code", ""),
+                message=v.get("message", ""),
+                suggestion=v.get("fix", {}).get("message", ""),
+                source="ruff",
+            ))
+        return findings

src/audit.py

@@ -0,0 +1,120 @@
+"""Audit logger — JSONL write operations for traceability."""
+import json
+import os
+import sys
+import uuid
+from datetime import datetime, timezone
+from typing import Optional
+
+
+class AuditLogger:
+    """Write structured operation audits as JSONL to a sink."""
+
+    REDACT_KEYS = {
+        "GITHUB_TOKEN", "token", "password", "api_key",
+        "authorization", "auth", "secret"
+    }
+    ALLOWED_DIRS = {"/var/log/github-mcp", "stdout", "stderr"}
+
+    def __init__(self, sink: str = "stdout"):
+        """
+        Args:
+            sink: "stdout", "stderr", or an absolute path under allowed dirs.
+        """
+        self.sink = sink
+        self._validate_sink()
+        self._fobj: Optional[object] = None
+
+    def _validate_sink(self) -> None:
+        if self.sink in ("stdout", "stderr"):
+            return
+        if not os.path.isabs(self.sink):
+            raise ValueError(
+                f"Audit file sink must be absolute path, got: {self.sink}"
+            )
+        # Prevent traversal: resolve symlinks, then check the canonical
+        # parent directory is under an allowed tree (if configured).
+        # For production, restrict via GITHUB_AUDIT_DIR_ALLOWLIST.
+        parent = os.path.dirname(os.path.abspath(self.sink))
+        allowlist_str = os.environ.get("GITHUB_AUDIT_DIR_ALLOWLIST", "")
+        if allowlist_str:
+            allowed = allowlist_str.split(",")
+            if not any(
+                os.path.commonpath([parent, d]) == d for d in allowed
+            ):
+                raise ValueError(
+                    f"Audit sink parent {parent} not in "
+                    f"GITHUB_AUDIT_DIR_ALLOWLIST ({allowlist_str})"
+                )
+
+    def _get_stream(self):
+        if self.sink == "stdout":
+            return sys.stdout
+        if self.sink == "stderr":
+            return sys.stderr
+        if self._fobj is None:
+            parent = os.path.dirname(self.sink)
+            if parent:
+                os.makedirs(parent, exist_ok=True)
+            self._fobj = open(self.sink, "a", encoding="utf-8")
+        return self._fobj
+
+    def log(
+        self,
+        tool: str,
+        action: str,
+        repo: str,
+        dry_run: bool = False,
+        policy_decision: str = "allow",
+        policy_rule: str = "",
+        request_body: Optional[dict] = None,
+        response: Optional[dict] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        """Write one audit entry."""
+        entry = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "request_id": uuid.uuid4().hex[:12],
+            "tool": tool,
+            "action": action,
+            "repo": repo,
+            "dry_run": dry_run,
+            "policy": {
+                "decision": policy_decision,
+                "matched_rule": policy_rule,
+            },
+            "request": _redact(request_body) if isinstance(request_body, dict) else None,
+            "response": _redact(response) if isinstance(response, dict) else None,
+            "error": error,
+        }
+        try:
+            stream = self._get_stream()
+            stream.write(json.dumps(entry, ensure_ascii=False, default=str) + "\n")
+            stream.flush()
+        except Exception as e:
+            # Audit must never crash the tool, but log the failure somewhere
+            print(f"[audit] write failed: {e}", file=sys.stderr)
+
+    def close(self) -> None:
+        if self._fobj:
+            self._fobj.close()
+            self._fobj = None
+
+
+def _redact(obj):
+    """Recursively redact sensitive keys from dicts and lists."""
+    if isinstance(obj, dict):
+        out = {}
+        for k, v in obj.items():
+            if k.lower() in AuditLogger.REDACT_KEYS:
+                out[k] = "***REDACTED***"
+            elif isinstance(v, (dict, list)):
+                out[k] = _redact(v)
+            elif isinstance(v, str) and len(v) > 200:
+                out[k] = v[:200] + "..."
+            else:
+                out[k] = v
+        return out
+    if isinstance(obj, list):
+        return [_redact(item) for item in obj]
+    return obj

src/config.py

@@ -0,0 +1,36 @@
+"""GitHub MCP Agent — configuration"""
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+def get_github_token() -> str:
+    token = os.environ.get("GITHUB_TOKEN", "")
+    if not token:
+        raise ValueError(
+            "GITHUB_TOKEN not set. "
+            "Create a .env file with GITHUB_TOKEN=ghp_xxx "
+            "or set the environment variable."
+        )
+    return token
+
+
+def get_github_api_base() -> str:
+    return os.environ.get("GITHUB_API_BASE", "https://api.github.com")
+
+
+def get_policy_path() -> str:
+    return os.environ.get("GITHUB_POLICY_PATH", "policy.json")
+
+
+def get_policy_required() -> bool:
+    return os.environ.get("GITHUB_POLICY_REQUIRED", "").lower() in ("true", "1", "yes")
+
+
+def get_audit_sink() -> str:
+    return os.environ.get("GITHUB_AUDIT_LOG", "stdout")
+
+
+def get_dry_run_enabled() -> bool:
+    return os.environ.get("GITHUB_DRY_RUN", "").lower() in ("true", "1", "yes")

src/diff_parser.py

@@ -0,0 +1,36 @@
+"""Parse unified diff → changed files + line map."""
+import re
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ChangedFile:
+    path: str
+    added_lines: set[int] = field(default_factory=set)
+    removed_lines: set[int] = field(default_factory=set)
+
+
+def parse_diff(diff_text: str) -> list[ChangedFile]:
+    """Parse unified diff, return changed files with line numbers."""
+    files: dict[str, ChangedFile] = {}
+    current_file = ""
+    new_line = 0
+
+    for line in diff_text.split("\n"):
+        if line.startswith("+++ b/"):
+            current_file = line[6:]
+            files[current_file] = ChangedFile(path=current_file)
+            new_line = 0
+        elif line.startswith("@@") and current_file:
+            m = re.search(r"\+(\d+)", line)
+            if m:
+                new_line = int(m.group(1)) - 1
+        elif line.startswith("+") and not line.startswith("+++") and current_file:
+            new_line += 1
+            files[current_file].added_lines.add(new_line)
+        elif line.startswith(" ") and current_file:
+            new_line += 1
+        elif line.startswith("-") and not line.startswith("---") and current_file:
+            files[current_file].removed_lines.add(new_line + 1)
+
+    return [f for f in files.values() if f.added_lines]

src/github_client.py

@@ -0,0 +1,111 @@
+"""GitHub API client wrapper using httpx"""
+import httpx
+from typing import Optional, Dict, Any, List, Union
+
+
+class GitHubClient:
+    def __init__(self, token: str, base_url: str = "https://api.github.com"):
+        self.base_url = base_url.rstrip('/')
+        self.headers = {
+            "Authorization": f"Bearer {token}",
+            "Accept": "application/vnd.github+json",
+            "X-GitHub-Api-Version": "2022-11-28",
+        }
+
+    def search_code(self, query: str, repo: Optional[str] = None) -> Dict[str, Any]:
+        try:
+            q = f"repo:{repo} {query}" if repo else query
+            with httpx.Client(timeout=20) as client:
+                response = client.get(
+                    f"{self.base_url}/search/code",
+                    headers=self.headers,
+                    params={"q": q}
+                )
+                response.raise_for_status()
+                data = response.json()
+                return {
+                    "items": [
+                        {
+                            "path": item["path"],
+                            "repo": item["repository"]["full_name"],
+                            "url": item["html_url"]
+                        }
+                        for item in data.get("items", [])
+                    ]
+                }
+        except Exception as e:
+            return {"error": f"Search failed: {str(e)}"}
+
+    def list_issues(self, repo: str, state: str = "open") -> Dict[str, Any]:
+        try:
+            with httpx.Client(timeout=20) as client:
+                response = client.get(
+                    f"{self.base_url}/repos/{repo}/issues",
+                    headers=self.headers,
+                    params={"state": state}
+                )
+                response.raise_for_status()
+                return response.json()
+        except Exception as e:
+            return {"error": f"List issues failed: {str(e)}"}
+
+    def create_issue(self, repo: str, title: str, body: str) -> Dict[str, Any]:
+        try:
+            with httpx.Client(timeout=20) as client:
+                response = client.post(
+                    f"{self.base_url}/repos/{repo}/issues",
+                    headers=self.headers,
+                    json={"title": title, "body": body}
+                )
+                response.raise_for_status()
+                return response.json()
+        except Exception as e:
+            return {"error": f"Create issue failed: {str(e)}"}
+
+    def get_pr_diff(self, repo: str, pr_number: int) -> Dict[str, Any]:
+        try:
+            headers = {**self.headers, "Accept": "application/vnd.github.v3.diff"}
+            with httpx.Client(timeout=20) as client:
+                response = client.get(
+                    f"{self.base_url}/repos/{repo}/pulls/{pr_number}",
+                    headers=headers
+                )
+                response.raise_for_status()
+                return {"diff": response.text}
+        except Exception as e:
+            return {"error": f"Get PR diff failed: {str(e)}"}
+
+    def create_pr(self, repo: str, title: str, body: str, head: str, base: str) -> Dict[str, Any]:
+        try:
+            with httpx.Client(timeout=20) as client:
+                response = client.post(
+                    f"{self.base_url}/repos/{repo}/pulls",
+                    headers=self.headers,
+                    json={"title": title, "body": body, "head": head, "base": base}
+                )
+                response.raise_for_status()
+                return response.json()
+        except Exception as e:
+            return {"error": f"Create PR failed: {str(e)}"}
+
+    def create_review_comment(
+        self, repo: str, pr_number: int, body: str,
+        commit_id: str = "", path: str = "", line: int = 0
+    ) -> Dict[str, Any]:
+        """Post a review comment on a PR line."""
+        try:
+            payload = {"body": body}
+            if commit_id and path and line > 0:
+                payload["commit_id"] = commit_id
+                payload["path"] = path
+                payload["line"] = line
+            with httpx.Client(timeout=20) as client:
+                resp = client.post(
+                    f"{self.base_url}/repos/{repo}/pulls/{pr_number}/reviews",
+                    headers=self.headers,
+                    json=payload,
+                )
+                resp.raise_for_status()
+                return resp.json()
+        except Exception as e:
+            return {"error": f"Review comment failed: {str(e)}"}

src/main.py

@@ -0,0 +1,29 @@
+"""GitHub MCP Server entry point"""
+import os
+import sys
+import signal
+
+# Ensure the project dir is on the path so imports work regardless of cwd
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from src.tools import mcp
+
+
+def main():
+    """Run the MCP server"""
+    try:
+        # Handle SIGTERM gracefully for container environments
+        def signal_handler(signum, frame):
+            sys.exit(0)
+
+        signal.signal(signal.SIGTERM, signal_handler)
+        mcp.run(transport="stdio")
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        print(f"Error starting MCP server: {e}", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()