# GitHub Stats MCP Server

A Model Context Protocol (MCP) server that provides tools for accessing GitHub repository and user statistics.

## Features

- **Repository Information**: Get detailed information about any public repository
- **User Statistics**: Fetch user profiles and statistics
- **Contributors**: List repository contributors with contribution counts
- **Issues**: Browse repository issues and pull requests
- **Search**: Search for repositories by keywords

## Installation

### Prerequisites

- Node.js 18 or higher
- npm or yarn

### Install Dependencies

```bash
npm install
npm run build
```

### GitHub Token (Optional)

For higher rate limits, create a GitHub personal access token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Create a token with `public_repo` scope (for public repositories)
3. Set the token as an environment variable: `GITHUB_TOKEN=your_token_here`

## Usage

### As a Local MCP Server

Add to your MCP configuration file:

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

### Available Tools

#### 1. Get Repository Information
```json
{
  "tool": "get_repository_info",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode"
  }
}
```

#### 2. Get User Information
```json
{
  "tool": "get_user_info",
  "arguments": {
    "username": "octocat"
  }
}
```

#### 3. Get Repository Contributors
```json
{
  "tool": "get_repository_contributors",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "limit": 10
  }
}
```

#### 4. Get Repository Issues
```json
{
  "tool": "get_repository_issues",
  "arguments": {
    "owner": "microsoft",
    "repo": "vscode",
    "state": "open",
    "limit": 20
  }
}
```

#### 5. Search Repositories
```json
{
  "tool": "search_repositories",
  "arguments": {
    "query": "language:typescript stars:>1000",
    "sort": "stars",
    "limit": 10
  }
}
```

## Development

### Build the Server
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

## API Rate Limits

- **Without token**: 60 requests per hour
- **With token**: 5,000 requests per hour

## License

MIT