<div align="center">
  <img src="https://socialify.git.ci/github/mcp/image?description=1&font=Inter&language=1&name=1&owner=1&pattern=Plus&theme=Auto" alt="GitHub-MCP" width="600" />

  # GitHub-MCP 🚀

  **A Production-Grade Model Context Protocol (MCP) Server for GitHub**

  [![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](https://www.python.org/)
  [![MCP](https://img.shields.io/badge/MCP-2.0.0-green.svg)](https://modelcontextprotocol.io/)
  [![License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)
  [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
</div>

---

## 2. Project Description

**GitHub-MCP** is an advanced, fully asynchronous Model Context Protocol (MCP) server that seamlessly bridges Claude Desktop (and other MCP clients) with the GitHub API. It goes beyond simple API wrapping by providing a sophisticated **Intelligence Layer** that generates deterministic, analytical insights into developers, repositories, issues, and pull requests—without relying on secondary AI models or embeddings.

## 3. Features

✨ **Seamless Integration:** Native support for the MCP `stdio` transport.  
🧠 **Developer Intelligence:** Generate deep, deterministic profiles of developers based on their open-source footprint.  
📊 **Repository Analytics:** Compare repositories, evaluate health scores, and receive tailored project recommendations.  
🤝 **Collaboration Intelligence:** Analyze issues and pull requests for code churn, complexity, and maintenance bottlenecks.  
🏗️ **Clean Architecture:** Built on SOLID principles with strict separation between HTTP clients, business logic, and presentation layers.  
⚡ **High Performance:** Fully asynchronous design leveraging `asyncio.gather` for concurrent API fetches, smartly capped to respect GitHub rate limits.

## 4. Why GitHub-MCP?

While Claude and other LLMs can browse the web or read raw JSON, providing them with pre-synthesized, strictly-typed analytical models drastically improves their contextual reasoning. GitHub-MCP mathematically calculates metrics like "Repository Health" and "Merge Complexity" so the LLM doesn't have to guess, resulting in faster, more accurate, and highly deterministic answers.

## 5. Architecture Overview

GitHub-MCP is built using a tiered architecture:
- **Presentation Layer (Tools):** Exposes MCP functions and handles raw I/O.
- **Intelligence/Analysis Layer:** Pure Python business logic. No HTTP requests, no LLMs.
- **Service Layer:** Wraps raw API data into strongly-typed Pydantic domain models.
- **Client Layer:** Manages `httpx` asynchronous communication with GitHub, including dynamic 404 routing.

## 6. System Architecture Diagram

```mermaid
graph TD
    Client[Claude Desktop] <-->|stdio / JSON-RPC| MCP[MCP Server Layer]
    
    subgraph GitHub-MCP
        MCP --> Tools[Tools Presentation]
        Tools -->|Raw Data| Intel[Intelligence & Analysis Layer]
        Intel -->|Synthesized Reports| Tools
        Tools -->|Fetch Data| Service[GitHub Service]
        Service -->|HTTP Requests| APIClient[GitHub Client]
    end
    
    APIClient <-->|REST| GitHub[GitHub API]
```

## 7. Technology Stack

- **Language:** Python 3.11+
- **Protocol:** `mcp` (v2.0.0)
- **Validation:** `pydantic` (v2)
- **HTTP Client:** `httpx`
- **Linting & Formatting:** `ruff`

## 8. Project Structure

```text
src/github_mcp/
├── analysis/         # Developer Intelligence logic
├── collaboration/    # Issues & PR Intelligence logic
├── github/           # HTTP Client & Pydantic domain models
├── intelligence/     # Repository Health & Recommendation logic
├── tools/            # MCP Tool registration and presentation
└── server.py         # Application entry point and DI container
```

## 9. Installation

Requires Python 3.11 or higher.

```bash
git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

## 10. Configuration

Generate a GitHub Personal Access Token (PAT).
```bash
export GITHUB_TOKEN="github_pat_1234567890..."
```

## 11. Running the MCP Server

You can run the server manually to verify it starts (it communicates via stdin/stdout, so you will see raw JSON-RPC if you type into it):
```bash
github-mcp
```

## 12. Claude Desktop Configuration

Add the following to your Claude Desktop MCP configuration file (typically `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "/absolute/path/to/github-mcp/.venv/bin/github-mcp",
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}
```

Restart Claude Desktop for the changes to take effect.

## 13. Available MCP Tools

GitHub-MCP exposes 15 highly specialized tools:
1. `hello_world` - Verify server connection.
2. `get_user_profile` - Fetch raw user profile.
3. `list_user_repositories` - List a user's repositories.
4. `get_repository` - Fetch repository details.
5. `get_repository_languages` - Fetch language bytes.
6. `analyze_developer` - 🧠 Generate a developer intelligence report.
7. `compare_repositories` - 📊 Compare two repositories.
8. `repository_health` - 📊 Evaluate repository health out of 100.
9. `recommend_repositories` - 📊 Suggest new repositories based on stack.
10. `list_repository_issues` - List open issues (excluding PRs).
11. `get_issue` - Fetch specific issue details.
12. `list_pull_requests` - List open pull requests.
13. `get_pull_request` - Fetch specific PR details.
14. `analyze_issue` - 🤝 Generate issue maintenance insights.
15. `analyze_pull_request` - 🤝 Generate PR complexity insights.

## 14. Example Usage

In Claude Desktop, you can use natural language:
- *"Compare the repositories facebook/react and vuejs/core."*
- *"Analyze the developer profile for octocat."*
- *"What is the repository health of torvalds/linux?"*
- *"Analyze issue #12 in octocat/Hello-World."*

## 15. Sample Outputs

**Repository Health Output:**
```text
Repository Health Report: octocat/Hello-World
Overall Score: 55/100
- Documentation: 15/30
- Metadata: 0/30
- Maintenance: 40/40

Strengths:
- Has a clear description
- Highly active maintenance

Weaknesses:
- No homepage or documentation link
- No explicit license
```

## 16. Development Setup

```bash
git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

## 17. Running Tests

Testing is currently performed via bash script injection into the `stdio` transport. See `docs/troubleshooting.md` for manual testing instructions.
```bash
# Example
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | github-mcp
```

## 18. Code Quality

We strictly enforce standard Python formatting using `ruff`.
```bash
python -m ruff check . --fix
```

## 19. Future Roadmap

- Additional Intelligence layers (e.g., Code Quality Analysis).
- Pagination support for deeply traversing issues and PRs.
- Automated `pytest` suite simulating JSON-RPC payloads.

## 20. Contributing

We welcome contributions! Please see our [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to submit pull requests, our coding conventions, and our architectural constraints.

## 21. License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 22. Acknowledgements

- Built using the official [Model Context Protocol (MCP) Python SDK](https://github.com/modelcontextprotocol/python-sdk).
- Powered by the robust [GitHub REST API](https://docs.github.com/en/rest).