# mcp-github-server

A production-grade Model Context Protocol (MCP) server that gives LLMs deep access to GitHub repositories, issues, pull requests, actions, code search, and more.

## Features

- **18 tools** for comprehensive GitHub interaction
- **Dynamic resources** for repos, issues, PRs, and files
- **4 prompt templates** for PR review, issue triage, code review, and repo summaries
- **GitHub App + Personal Access Token** authentication
- **Redis caching** with in-memory fallback
- **Rate limit handling** with exponential backoff and jitter
- **Full Zod validation** on all inputs
- **Docker support** for containerized deployment

## Quick Start

### Prerequisites

- Node.js 20+
- A GitHub Personal Access Token or GitHub App credentials

### Installation

```bash
npm install
```

### Configuration

Copy the example environment file and fill in your credentials:

```bash
cp .env.example .env
```

Required:
```
GITHUB_TOKEN=ghp_your_personal_access_token
```

Or for GitHub App authentication:
```
GITHUB_APP_ID=12345
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\n..."
GITHUB_APP_INSTALLATION_ID=67890
```

### Running

```bash
# Development
npm run dev

# Production
npm run build
npm start
```

### Docker

```bash
# Build and run with Redis
docker compose up -d

# Or build manually
docker build -t mcp-github-server .
docker run -e GITHUB_TOKEN=ghp_xxx mcp-github-server
```

## MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/path/to/mcp-github-server/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}
```

## Tools

### Repository Tools

| Tool | Description |
|------|-------------|
| `search_repos` | Search GitHub repositories with language, topic, and star filters |
| `get_repo_info` | Get detailed repository information including stats and metadata |
| `get_repo_stats` | Get contributor stats, commit activity, and code frequency |

### File Tools

| Tool | Description |
|------|-------------|
| `get_file_content` | Read file content from a repository (auto-decodes base64) |
| `list_directory` | List directory contents with type sorting |
| `search_code` | Search code across repos with language/file/path filters |

### Issue Tools

| Tool | Description |
|------|-------------|
| `list_issues` | List/filter issues with pagination (excludes PRs) |
| `create_issue` | Create new issues with labels, assignees, and milestones |
| `get_issue` | Get detailed issue info with comments |

### Pull Request Tools

| Tool | Description |
|------|-------------|
| `list_pull_requests` | List PRs with state/branch filtering |
| `get_pull_request` | Get PR details with diff, files, and reviews |
| `review_pull_request` | Submit PR reviews (approve, request changes, comment) |
| `merge_pull_request` | Merge PRs with merge/squash/rebase strategies |

### Branch Tools

| Tool | Description |
|------|-------------|
| `create_branch` | Create branches from ref, branch, or SHA |
| `compare_branches` | Compare branches with commit and file diffs |

### Other Tools

| Tool | Description |
|------|-------------|
| `get_actions_status` | Get CI/CD workflow run status with optional job details |
| `manage_labels` | Create, update, delete, and list repository labels |
| `get_commit_history` | Get commit log with author/path/date filtering |

## Resources

Dynamic resource templates available via MCP resource protocol:

- `github://repos/{owner}/{repo}` - Repository details
- `github://repos/{owner}/{repo}/readme` - Repository README
- `github://repos/{owner}/{repo}/languages` - Language breakdown
- `github://repos/{owner}/{repo}/topics` - Repository topics
- `github://repos/{owner}/{repo}/issues` - Open issues list
- `github://repos/{owner}/{repo}/issues/{number}` - Issue details
- `github://repos/{owner}/{repo}/pulls` - Open PRs list
- `github://repos/{owner}/{repo}/pulls/{number}` - PR details
- `github://repos/{owner}/{repo}/contents/{path}` - File content
- `github://repos/{owner}/{repo}/tree/{path}` - Directory listing

## Prompts

| Prompt | Description |
|--------|-------------|
| `pr_review` | Structured PR review with security/performance/architecture focus |
| `issue_triage` | Single or batch issue triage with priority classification |
| `code_review` | File/directory code review with depth levels |
| `repo_summary` | Comprehensive repository health and activity summary |

## Configuration Reference

| Variable | Default | Description |
|----------|---------|-------------|
| `GITHUB_TOKEN` | - | Personal access token |
| `GITHUB_APP_ID` | - | GitHub App ID |
| `GITHUB_APP_PRIVATE_KEY` | - | GitHub App private key |
| `GITHUB_APP_INSTALLATION_ID` | - | GitHub App installation ID |
| `REDIS_URL` | - | Redis connection URL (optional) |
| `REDIS_KEY_PREFIX` | `mcp-github:` | Redis key prefix |
| `CACHE_TTL_SECONDS` | `300` | Default cache TTL |
| `RATE_LIMIT_MAX_RETRIES` | `3` | Max retries on rate limit |
| `RATE_LIMIT_BASE_DELAY_MS` | `1000` | Base delay for exponential backoff |
| `LOG_LEVEL` | `info` | Logging level |
| `SERVER_NAME` | `mcp-github-server` | Server name |
| `SERVER_VERSION` | `1.0.0` | Server version |

## Development

```bash
# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Format
npm run format
```

## Architecture

```
src/
  index.ts          - Entry point, stdio transport setup
  server.ts         - MCP server with handler registration
  config.ts         - Environment-based configuration
  types.ts          - Shared TypeScript types and Zod schemas
  schema_utils.ts   - Zod-to-JSON-Schema converter
  tools/            - 18 tool implementations with Zod validation
  resources/        - Dynamic resource resolution (repos, issues, PRs, files)
  prompts/          - 4 prompt templates for common workflows
  github/
    client.ts       - Octokit wrapper with caching and retry
    auth.ts         - Token and GitHub App authentication
    rate_limiter.ts - Exponential backoff with jitter
    errors.ts       - Typed GitHub error hierarchy
  cache/
    index.ts        - Cache interface and in-memory implementation
    redis_cache.ts  - Redis-backed cache with TTL
```

## License

MIT