# 🚀 GitHub Activity MCP Server

An MCP (Model Context Protocol) server built with **FastMCP** and **PyGithub** that connects AI assistants to GitHub — search repos, manage issues & PRs, analyze contributions, and more.

> **What is MCP?** The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard that lets AI assistants connect to external data and tools through a unified interface. Think of it as "USB-C for AI".

---

## ✨ Features

This server exposes **13 tools**, **3 resource providers**, and **3 prompt templates** — covering all three MCP primitives.

### 🔧 Tools (Model-Controlled)
Actions the AI can take autonomously:

| Tool | Description |
|------|-------------|
| `search_repositories` | Search GitHub repos by query, language, stars |
| `get_repository` | Get detailed repo info (stars, forks, topics, etc.) |
| `get_file_contents` | Read any file from a repo |
| `list_commits` | List recent commits with filters |
| `list_issues` | List issues with state/label/assignee filters |
| `get_issue` | Get full issue details + comments |
| `create_issue` | Create a new issue |
| `add_issue_comment` | Comment on an issue |
| `list_pull_requests` | List PRs with state/branch filters |
| `get_pull_request` | Get PR details + merge status |
| `get_pull_request_diff` | View PR code changes |
| `get_user_profile` | Get a user's public profile |
| `list_user_repos` | List a user's repositories |

### 📦 Resources (Application-Controlled)
Contextual data the AI can read:

| Resource URI | Description |
|-------------|-------------|
| `github://repo/{owner}/{repo}/readme` | Repository README (markdown) |
| `github://repo/{owner}/{repo}/tree` | Full file tree listing |
| `github://repo/{owner}/{repo}/languages` | Language breakdown with percentages |

### 💬 Prompts (User-Triggered)
Pre-built workflow templates:

| Prompt | Description |
|--------|-------------|
| `analyze-repo` | Comprehensive repository analysis |
| `review-pr` | Code review with best practices |
| `issue-triage` | Categorize and prioritize open issues |

---

## 🏗️ Architecture

```mermaid
graph LR
    A[AI Assistant] <-->|MCP Protocol| B[GitHub MCP Server]
    B <-->|REST API| C[GitHub API]

    subgraph "MCP Server (FastMCP)"
        B --> D[Tools]
        B --> E[Resources]
        B --> F[Prompts]
    end

    subgraph "Tools"
        D --> D1[Repos]
        D --> D2[Issues]
        D --> D3[Pull Requests]
        D --> D4[Users]
    end
```

---

## 🚀 Quick Start

### Prerequisites

- **Python** ≥ 3.10
- **GitHub Personal Access Token** (optional, but recommended for higher rate limits)

### Installation

```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/github-mcp-server.git
cd github-mcp-server

# Install dependencies
pip install fastmcp PyGithub
```

### Set up your GitHub Token (Optional)

Create a [Personal Access Token](https://github.com/settings/tokens) with `repo` and `read:user` scopes:

```bash
# Linux/macOS
export GITHUB_TOKEN=ghp_your_token_here

# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_your_token_here"
```

> **Note:** Without a token, you're limited to 60 API requests/hour. With a token, you get 5,000/hour.

### Run the Server

```bash
# Run directly
fastmcp run src/server.py

# Or with Python
python -m src.server
```

### Test with FastMCP Dev Mode

```bash
fastmcp dev src/server.py
```

---

## ⚙️ Configuration

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, or `%APPDATA%\Claude\claude_desktop_config.json` on Windows):

```json
{
  "mcpServers": {
    "github": {
      "command": "fastmcp",
      "args": ["run", "src/server.py"],
      "cwd": "/absolute/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP config (`.cursor/mcp.json` in your project or global config):

```json
{
  "mcpServers": {
    "github": {
      "command": "fastmcp",
      "args": ["run", "src/server.py"],
      "cwd": "/absolute/path/to/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

### VS Code (GitHub Copilot)

Add to your VS Code settings (`.vscode/settings.json`):

```json
{
  "mcp": {
    "servers": {
      "github": {
        "command": "fastmcp",
        "args": ["run", "src/server.py"],
        "cwd": "/absolute/path/to/github-mcp-server",
        "env": {
          "GITHUB_TOKEN": "ghp_your_token_here"
        }
      }
    }
  }
}
```

---

## 📁 Project Structure

```
github-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py             # FastMCP server instance & entry point
│   ├── github_client.py      # PyGithub client wrapper & error handling
│   ├── resources.py          # Resource providers (README, tree, languages)
│   ├── prompts.py            # Prompt templates (analyze, review, triage)
│   └── tools/
│       ├── __init__.py
│       ├── repos.py          # Repository tools (search, get, file contents, commits)
│       ├── issues.py         # Issue tools (list, get, create, comment)
│       ├── pulls.py          # Pull request tools (list, get, diff)
│       └── users.py          # User tools (profile, repos)
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore
```

---

## 🛠️ Tech Stack

| Technology | Purpose |
|------------|---------|
| [FastMCP](https://gofastmcp.com) | High-level MCP server framework |
| [PyGithub](https://github.com/PyGithub/PyGithub) | GitHub REST API client |
| [Model Context Protocol](https://modelcontextprotocol.io) | The open standard for AI-tool integration |

---

## 🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

---

## 📄 License

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

---

<p align="center">
  Built with ❤️ using FastMCP and the Model Context Protocol
</p>