# 🐙 GitHub MCP Server

[![npm version](https://badge.fury.io/js/@xingyuchen%2Fgithub-mcp-server.svg)](https://badge.fury.io/js/@xingyuchen%2Fgithub-mcp-server)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)

A powerful **Model Context Protocol (MCP)** server that enables AI assistants to analyze and read GitHub repositories with ease. Perfect for code analysis, repository exploration, and understanding project structures.

## ✨ Features

### 🔍 **Repository Structure Analysis**
- **Complete directory traversal** with configurable depth
- **File type distribution** analysis and statistics
- **Project architecture insights** with framework detection
- **Important file detection** (README, package.json, Dockerfile, etc.)
- **Visual tree structure** representation
- **Size analysis** and file counting

### 📖 **File Content Reading**
- **Multi-format support** (UTF-8, Base64, Raw)
- **Syntax highlighting** for 30+ programming languages
- **Code analysis** with function/class counting
- **Pattern detection** (TODO comments, async/await, etc.)
- **Smart content truncation** for large files
- **Binary file handling** with appropriate encoding

### 🚀 **Advanced Capabilities**
- **Rate limit optimization** with GitHub token support
- **Branch-specific analysis** (main, develop, feature branches)
- **Error handling** with detailed troubleshooting
- **Session management** for efficient API usage
- **Streamable HTTP** transport for modern AI clients

## 🛠️ Installation

### Quick Start

```bash
npm install -g @xingyuchen/github-mcp-server
```

### From Source

```bash
git clone https://github.com/guangxiangdebizi/github-mcp-server.git
cd github-mcp-server
npm install
npm run build
```

## ⚙️ Configuration

### Environment Setup

1. **Copy environment template:**
   ```bash
   cp .env.example .env
   ```

2. **Configure your settings:**
   ```env
   # GitHub Personal Access Token (recommended for higher rate limits)
   GITHUB_TOKEN=your_github_token_here
   
   # Server Configuration
   PORT=3000
   
   # Optional: Default repository
   DEFAULT_REPO=owner/repository
   ```

### GitHub Token Setup

For optimal performance and access to private repositories:

1. Go to [GitHub Settings > Developer settings > Personal access tokens](https://github.com/settings/tokens)
2. Generate a new token with `repo` scope
3. Add it to your `.env` file

## 🚀 Usage

### Starting the Server

```bash
# Production mode
npm start

# Development mode
npm run dev

# HTTP mode (recommended)
npm run start:http
```

The server will start at `http://localhost:3000` with the MCP endpoint at `/mcp`.

### Client Configuration

Add to your AI client's MCP configuration:

```json
{
  "mcpServers": {
    "github-analyzer": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}
```

## 🔧 Available Tools

### 1. `analyze_repository_structure`

Analyze the complete structure and architecture of a GitHub repository.

**Parameters:**
- `owner` (required): Repository owner/organization
- `repo` (required): Repository name
- `path` (optional): Specific directory to analyze
- `branch` (optional): Branch name (default: main)
- `max_depth` (optional): Maximum traversal depth (1-5, default: 3)

**Example:**
```json
{
  "owner": "microsoft",
  "repo": "vscode",
  "branch": "main",
  "max_depth": 3
}
```

### 2. `read_repository_file`

Read and analyze the contents of a specific file from a GitHub repository.

**Parameters:**
- `owner` (required): Repository owner/organization
- `repo` (required): Repository name
- `path` (required): File path within the repository
- `branch` (optional): Branch name (default: main)
- `encoding` (optional): File encoding (utf8/base64/raw, default: utf8)
- `max_size` (optional): Maximum file size in bytes (default: 1MB, max: 5MB)

**Example:**
```json
{
  "owner": "microsoft",
  "repo": "vscode",
  "path": "src/vs/code/electron-main/main.ts",
  "branch": "main"
}
```

## 📊 Example Output

### Repository Structure Analysis

```markdown
# 📊 Repository Structure Analysis

## 📋 Repository Information
- **Repository:** microsoft/vscode
- **Description:** Visual Studio Code
- **Language:** TypeScript
- **Stars:** 150,000 ⭐
- **Forks:** 25,000 🍴

## 📁 Directory Structure
📁 src/
  📁 vs/
    📄 main.ts (15.2 KB)
    📁 workbench/
      📄 workbench.main.ts (8.5 KB)

## 📈 Statistics
- **Total Files:** 12,450
- **Total Directories:** 1,200
- **Total Size:** 145.2 MB

## 🏗️ Project Architecture Insights
🟨 **TypeScript Project** - Modern web development stack detected
📦 **Node.js Ecosystem** - Uses npm package management
🐳 **Containerized** - Docker deployment ready
```

### File Content Analysis

```markdown
# 📄 File Content Analysis

## 📋 File Information
- **Repository:** microsoft/vscode
- **File Path:** `src/main.ts`
- **Branch:** main

## 📊 Content Analysis
**File Type:** TypeScript
**Size:** 15.2 KB
**Lines:** 450
**Functions:** 12
**Classes:** 3
**Imports:** 25

## 📝 File Content
```typescript
import { app, BrowserWindow } from 'electron';
// ... (file content with syntax highlighting)
```

## 🔍 Health Check

Monitor server status:

```bash
curl http://localhost:3000/health
```

Response:
```json
{
  "status": "healthy",
  "transport": "streamable-http",
  "activeSessions": 2,
  "serverInfo": {
    "name": "GitHub-MCP",
    "version": "1.0.0"
  }
}
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

## 📝 License

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

## 👨‍💻 Author

**Xingyu Chen**
- 🌐 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- 📧 Email: guangxiangdebizi@gmail.com
- 🐙 GitHub: [@guangxiangdebizi](https://github.com/guangxiangdebizi/)
- 📦 NPM: [@xingyuchen](https://www.npmjs.com/~xingyuchen)

## 🙏 Acknowledgments

- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Powered by [GitHub REST API](https://docs.github.com/en/rest)
- Inspired by the need for better AI-repository integration

---

<div align="center">
  <strong>⭐ Star this repository if you find it helpful! ⭐</strong>
</div>