# GitHub MCP TypeScript SDK Server

A comprehensive Model Context Protocol (MCP) server for GitHub that provides access to repositories, issues, pull requests, commits, and user information through a standardized interface. Built with TypeScript and the official MCP SDK.

## 🚀 Features

### 📋 Available Tools (10 Total)

- **`get_my_info`** - Get information about the authenticated GitHub user
- **`get_repo_info`** - Get detailed information about a GitHub repository
- **`list_repo_issues`** - List issues in a repository (with state filtering)
- **`list_repo_prs`** - List pull requests in a repository
- **`list_repo_commits`** - List recent commits in a repository
- **`search_repositories`** - Search for repositories on GitHub
- **`get_user_info`** - Get information about any GitHub user
- **`list_user_repos`** - List repositories belonging to a user
- **`get_my_repos`** - List repositories belonging to the authenticated user
- **`get_github_stats`** - Get comprehensive GitHub statistics for a user

### 🔧 Capabilities

- ✅ **Repository Information** - Name, description, stars, forks, language, visibility
- ✅ **Issue Management** - List, filter, and view issue details
- ✅ **Pull Request Tracking** - View PR status, authors, and details
- ✅ **Commit History** - Browse recent commits with author and message info
- ✅ **User Profiles** - Access user information and statistics
- ✅ **Repository Search** - Advanced search with filters and sorting
- ✅ **Statistics & Analytics** - Comprehensive user and repository metrics
- ✅ **Error Handling** - Robust error handling with descriptive messages
- ✅ **Natural Language Queries** - Ask questions in plain English

## 📦 Installation

### Prerequisites

- Node.js 18+
- npm or yarn
- GitHub Personal Access Token

### Setup

1. **Clone the repository:**

   ```bash
   git clone <your-repo-url>
   cd github-mcp-ts-sdk
   ```

2. **Install dependencies:**

   ```bash
   npm install
   ```

3. **Set up environment variables:**

   ```bash
   cp env.example .env
   # Edit .env and add your GitHub token
   ```

4. **Build the project:**
   ```bash
   npm run build
   ```

## 🔑 GitHub Token Setup

1. Go to [GitHub Settings > Personal Access Tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Select the following scopes:
   - `repo` (Full control of private repositories)
   - `user` (Read all user profile data)
   - `read:org` (Read org and team membership)
4. Copy the generated token and add it to your `.env` file:

```env
GITHUB_TOKEN=your_github_token_here
GITHUB_USERNAME=your_username_here  # Optional
```

## 🚀 Usage

### Development Mode

```bash
npm run dev
```

### Production Mode

```bash
npm run build
npm start
```

### Watch Mode (for development)

```bash
npm run build:watch
```

### Test the Server

```bash
npm test
npm run simple-test
npm run interactive-test
npm run demo
```

## 🛠 Tool Examples

### User Information

#### Get Your GitHub Profile

```json
{
  "tool": "get_my_info",
  "arguments": {}
}
```

**Response:**

```
👤 **My GitHub Profile**

**Username:** Om-Shree-0709
**Name:** Om Shree
**Bio:** Full Stack Developer
**Followers:** 25
**Following:** 50
**Public Repositories:** 15
**Profile URL:** https://github.com/Om-Shree-0709
```

#### Get User Information

```json
{
  "tool": "get_user_info",
  "arguments": {
    "username": "microsoft"
  }
}
```

### Repository Information

#### Get Repository Details

```json
{
  "tool": "get_repo_info",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode"
  }
}
```

**Response:**

```
📁 **Repository: microsoft/vscode**

**Description:** Visual Studio Code
**Language:** TypeScript
**Visibility:** public
**Stars:** ⭐ 150000
**Forks:** 🍴 25000
**Watchers:** 👀 5000
**Created:** 1/1/2015
**Updated:** 12/15/2024
**URL:** https://github.com/microsoft/vscode
```

#### Search Repositories

```json
{
  "tool": "search_repositories",
  "arguments": {
    "query": "language:typescript stars:>1000",
    "limit": 10
  }
}
```

**Advanced search examples:**

- `language:javascript` - Search by programming language
- `stars:>5000` - Filter by minimum stars
- `user:octocat` - Search within a specific user's repositories
- `language:python stars:>1000 forks:>100` - Combined filters
- `created:>2023-01-01` - Filter by creation date
- `topic:react` - Search by topic tags

### Issues and Pull Requests

#### List Repository Issues

```json
{
  "tool": "list_repo_issues",
  "arguments": {
    "owner": "facebook",
    "repo": "react",
    "state": "open"
  }
}
```

#### List Pull Requests

```json
{
  "tool": "list_repo_prs",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "state": "open"
  }
}
```

### Commit History

#### List Recent Commits

```json
{
  "tool": "list_repo_commits",
  "arguments": {
    "owner": "nodejs",
    "repo": "node",
    "limit": 20
  }
}
```

### Statistics

#### Get User Statistics

```json
{
  "tool": "get_github_stats",
  "arguments": {
    "username": "torvalds"
  }
}
```

**Response:**

```
📊 **GitHub Statistics for torvalds**

**User Info:**
• Followers: 50000
• Following: 0
• Public Repos: 1

**Repository Stats:**
• Total Repositories: 1
• Total Stars Received: ⭐ 200000
• Total Forks: 🍴 80000
• Average Stars per Repo: 200000.0

**Top Languages:**
C: 1
```

## 📚 Resources

### Repository Resource

Access repository data via URI: `github://repository/{owner}/{repo}`

**Examples:**

- `github://repository/microsoft/vscode`
- `github://repository/facebook/react`

### User Resource

Access user data via URI: `github://user/{username}`

**Examples:**

- `github://user/octocat`
- `github://user/Om-Shree-0709`

## 💬 Prompts

### Natural Language Queries

Ask questions in natural language about GitHub data:

```json
{
  "prompt": "github_query",
  "arguments": {
    "query": "Show me my most starred repositories"
  }
}
```

**Supported queries:**

- "Show me my most starred repositories"
- "Search for TypeScript repositories"
- "What are the open issues in microsoft/vscode?"
- "List my repositories"
- "Get statistics for user octocat"

## 🔧 Configuration

### Environment Variables

Create a `.env` file with:

```env
# Required
GITHUB_TOKEN=your_github_token_here

# Optional
GITHUB_USERNAME=your_username_here
```

### GitHub Token Scopes

Your GitHub token needs these scopes:

- `repo` - Full control of private repositories
- `user` - Read all user profile data
- `read:org` - Read org and team membership

## 🏗 Architecture

The server is built using:

- **TypeScript** - Type-safe development
- **MCP SDK** - Model Context Protocol framework
- **Octokit** - Official GitHub API client
- **Zod** - Schema validation
- **Stdio Transport** - Standard input/output communication

### Project Structure

```
src/
├── server.ts          # Main server implementation with all tools and resources

dist/                  # Compiled JavaScript
node_modules/          # Dependencies
```

## 🔗 Integration

### With Claude Desktop

Add to your Claude Desktop configuration:

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

### With Other MCP Clients

The server communicates via stdio and follows the MCP protocol specification. It works with any MCP-compatible client that can send JSON-RPC requests.

### Direct JSON-RPC Usage

Send JSON-RPC 2.0 requests to your server:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_repo_info",
    "arguments": {
      "owner": "microsoft",
      "repo": "vscode"
    }
  }
}
```

## 🛡 Error Handling

The server includes comprehensive error handling:

- ✅ **Authentication errors** - Clear messages for invalid tokens
- ✅ **Rate limiting** - Handles GitHub API rate limits gracefully
- ✅ **Network errors** - Robust handling of connection issues
- ✅ **Validation errors** - Input validation with helpful error messages
- ✅ **GitHub API errors** - Detailed error reporting from GitHub

## 📈 Performance Features

- **Efficient API usage** - Optimized requests with proper pagination
- **Caching-friendly** - Responses designed for easy caching
- **Rate limit aware** - Respects GitHub API rate limits
- **Batch operations** - Efficient handling of multiple requests

## 🎯 Practical Use Cases

### 1. Repository Research

```json
{"tool": "get_repo_info", "arguments": {"owner": "microsoft", "repo": "vscode"}}
{"tool": "list_repo_issues", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}
{"tool": "list_repo_prs", "arguments": {"owner": "microsoft", "repo": "vscode", "state": "open"}}
```

### 2. User Analysis

```json
{"tool": "get_user_info", "arguments": {"username": "torvalds"}}
{"tool": "get_github_stats", "arguments": {"username": "torvalds"}}
{"tool": "list_user_repos", "arguments": {"username": "torvalds", "type": "all"}}
```

### 3. Project Discovery

```json
{"tool": "search_repositories", "arguments": {"query": "language:typescript stars:>1000"}}
{"tool": "search_repositories", "arguments": {"query": "topic:machine-learning created:>2023-01-01"}}
```

### 4. Your Own Data

```json
{"tool": "get_my_info", "arguments": {}}
{"tool": "get_my_repos", "arguments": {"type": "all"}}
{"tool": "get_github_stats", "arguments": {"username": "Om-Shree-0709"}}
```

## 📝 Development

### Available Scripts

- `npm run build` - Build the TypeScript project
- `npm run build:watch` - Build with file watching
- `npm run dev` - Run in development mode
- `npm start` - Run the compiled server
- `npm test` - Test the server
- `npm run setup` - Run setup script
- `npm run demo` - Run demo script
- `npm run interactive-test` - Run interactive tests

### Adding New Tools

1. Create a new function in `src/server.ts`
2. Register the tool with `server.registerTool()`
3. Add proper error handling
4. Update this README

### Testing

```bash
# Build and test
npm run build
npm start

# Test with various scripts
npm test
npm run simple-test
npm run interactive-test
npm run demo
```

## 🚨 Troubleshooting

### Common Issues

1. **"Cannot find module" errors**
   - Run `npm install` to install dependencies
   - Run `npm run build` to compile TypeScript

2. **Authentication failures**
   - Check your GitHub token is valid
   - Ensure token has required scopes
   - Verify `.env` file exists and is readable

3. **Rate limit errors**
   - Wait before making more requests
   - Consider using a token with higher rate limits

4. **Repository not found**
   - Check owner and repository names are correct
   - Ensure repository is public or you have access

### Debug Mode

Run in development mode for detailed logging:

```bash
npm run dev
```

## 📊 Response Format

All tools return responses in the MCP standard format with `content` arrays containing text blocks:

```json
{
  "content": [
    {
      "type": "text",
      "text": "📁 **Repository: microsoft/vscode**\n\n**Description:** Visual Studio Code\n**Stars:** ⭐ 150000\n..."
    }
  ]
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add your changes
4. Test thoroughly
5. Submit a pull request

## 📄 License

MIT License - see LICENSE file for details

## 🆘 Support

- **Issues**: Report bugs and feature requests via GitHub Issues
- **Documentation**: Check the MCP specification for protocol details
- **GitHub API**: Refer to [GitHub's API documentation](https://docs.github.com/en/rest)

## 🔗 Related Links

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [GitHub API Documentation](https://docs.github.com/en/rest)
- [Octokit.js](https://octokit.github.io/rest.js/)
- [TypeScript](https://www.typescriptlang.org/)

---

**Happy coding! 🚀**

Your GitHub MCP Server is ready with 10 powerful tools! You can:

- ✅ Get any repository information
- ✅ Search repositories with advanced filters
- ✅ List issues and pull requests
- ✅ Browse commit history
- ✅ Get user profiles and statistics
- ✅ Access your own GitHub data
- ✅ Use natural language queries