# GitHub MCP

A TypeScript-based Model Context Protocol (MCP) server for inspecting public GitHub data through tools that can be consumed by MCP-compatible clients such as Cursor or Claude Desktop.

## What this project does

The server currently exposes two tools:

- `hello`: returns a friendly greeting and serves as a simple protocol sanity check.
- `github_user_stats`: fetches a GitHub username’s public profile metadata, repository activity totals, recent public events, and pull request insights in one response.

The implementation uses the GitHub REST API to gather public profile information and formats the output into human-readable summaries.

## Features

- Lightweight MCP server over stdio transport
- Public GitHub profile and repository stats gathering
- Pull request insights including:
  - total PR count
  - merged PR count
  - co-authored PR count
  - most targeted repository
- Optional authentication via a GitHub token to reduce unauthenticated rate-limit issues
- Test coverage for formatting and helper logic

## Getting started

### 1. Install dependencies

```bash
git clone https://github.com/<your-username>/github_mcp.git
cd github_mcp
npm install
```

### 2. Configure environment variables

Create a `.env` file in the project root if you want to use a GitHub token:

```env
GITHUB_TOKEN=your_github_personal_access_token
```

This is optional, but recommended for smoother API usage.

### 3. Run the server

```bash
npm run dev
```

The server runs over stdio, so stdout is reserved for MCP protocol traffic and logs are written to stderr.

## Example tool calls

### Hello

```json
{
  "name": "Mahesh"
}
```

### GitHub stats

```json
{
  "username": "Maheshkumarjena"
}
```

## Scripts

- `npm run dev` starts the MCP server in development mode
- `npm run build` compiles the TypeScript project
- `npm test` runs the Vitest test suite

## Project structure

- `src/index.ts` bootstraps the MCP server
- `src/tools.ts` registers the available MCP tools
- `src/github.ts` wraps GitHub API requests and data aggregation
- `src/schemas.ts` defines tool input validation with Zod
- `src/types.ts` contains shared TypeScript interfaces
- `src/utils.ts` formats and transforms data for output
- `tests/` contains unit tests for helper behavior

## Development notes

The current implementation is intentionally small and focused on a solid foundation for GitHub data access. It is a good starting point for adding more GitHub endpoints and exposing additional MCP tools.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Extend the GitHub client in `src/github.ts` or add new tools in `src/tools.ts`
4. Run `npm test` and `npm run build` before opening a pull request