# GitHub Dev Copilot - MCP Server

A production-ready Model Context Protocol (MCP) server that acts as a GitHub Copilot for AI agents. It provides tools to interact with the GitHub API, allowing agents to manage repositories, issues, PRs, and analyze repository health.

## Architecture

```
+----------------+      +-----------------------+      +-------------+
|    AI Agent    | ---> |  GitHub MCP Server    | <--> |  GitHub API |
| (Client)       | STDI |  (Python / FastMCP)   | HTTP |             |
+----------------+      +-----------------------+      +-------------+
                                   |
                        +-----------------------+
                        |        Tools          |
                        | - list_repositories   |
                        | - read_issues         |
                        | - create_issue        |
                        | - comment_on_pr       |
                        | - analyze_repo_health |
                        +-----------------------+
```

## Features

- **Authentication**: Securely connects using a GitHub Personal Access Token (PAT).
- **Tooling**: Exposes robust, strictly-typed MCP tools.
- **Safety**: 
  - Validates inputs using Pydantic.
  - Rate limits API calls to prevent blocking.
  - Never exposes tokens.
- **Analysis**: intelligent `analyze_repo_health` tool to score repositories.

## Setup

1. **Clone the repository** (if applicable) or navigate to the project directory.

2. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Configure Environment**:
   Copy `.env.example` to `.env` and add your GitHub PAT.
   ```bash
   cp .env.example .env
   # Edit .env and set GITHUB_TOKEN
   ```

4. **Run the Server**:
   You can run it directly with Python, or via an MCP client inspector.
   ```bash
   python main.py
   ```

## Using with Claude Desktop or MCP Clients

Add the server config to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github-copilot": {
      "command": "python",
      "args": ["/path/to/mcp_github_dev_copilot/main.py"]
    }
  }
}
```

## Available Tools

### 1. `list_repositories`
Lists repositories accessible to the authenticated user.
- **Returns**: Name, owner, private/public status, stars, language.

### 2. `read_issues`
Fetches issues from a repository.
- **Input**: `repo_owner`, `repo_name`, `state` ("open", "closed", "all")
- **Output**: List of issues with ID, title, labels.

### 3. `create_issue`
Creates a new issue.
- **Input**: `repo_owner`, `repo_name`, `title`, `body` (markdown), `labels`
- **Output**: Issue URL and number.

### 4. `comment_on_pr`
Adds a comment to a Pull Request.
- **Input**: `repo_owner`, `repo_name`, `pr_number`, `comment_text`
- **Output**: Comment URL.

### 5. `analyze_repo_health`
Performs a health check on a repository.
- **Checks**: Open issues count, stale issues (>30 days), recent commit activity, tests presence, CI config.
- **Output**: Health score (0-100) and improvement suggestions.

## Security & Limitations

- **Rate Limiting**: The server implements a decorator to handle GitHub rate limits by waiting or retrying.
- **Scopes**: Ensure your PAT has `repo`, `read:org`, and `workflow` scopes.
- **No Browser**: This server uses the official GitHub API, not web scraping.
- **Logs**: Activities are logged to `stderr` to avoid interfering with MCP stdio communication.

## Future Improvements

- Add `update_issue` and `merge_pr` tools.
- Implement file content reading/searching.
- Add support for GitHub App authentication.