copilot-mcp-server/CLAUDE.md

MCP server that integrates with GitHub Copilot to provide code assistance

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **Copilot MCP Server** - a Model Context Protocol server that bridges GitHub Copilot AI models with MCP-compatible tools. It exposes Copilot's capabilities (chat, code explanation, suggestions, and reviews) through standardized MCP interfaces.

## Technology Stack

- **TypeScript** with Node.js >=18.0.0
- **Model Context Protocol SDK** for server implementation
- **GitHub APIs** via @octokit/rest and @octokit/auth-app
- **Zod** for request/response validation

## Essential Commands

```bash
# Development
npm run dev          # Watch mode development
npm run build        # Compile TypeScript
npm start           # Run compiled server
npm run lint        # ESLint checking
npm test            # Run Jest tests
```

## Architecture Overview

### Core Components

- **`src/server.ts`** - Main MCP server with tool/resource handlers
- **`src/copilot-client.ts`** - GitHub Copilot API client with auto-authentication
- **`src/index.ts`** - Entry point with configuration loading
- **`src/types.ts`** - Zod schemas and TypeScript types

### MCP Interface

**Tools:**
- `copilot_chat` - General programming assistance
- `copilot_explain` - Code analysis and explanation
- `copilot_suggest` - Code generation from descriptions
- `copilot_review` - Code reviews (security/performance/style/general)

**Resources:**
- `copilot://models` - Available AI models list
- `copilot://usage` - Usage statistics and rate limits

### Authentication Strategy

The server auto-detects GitHub Copilot authentication in this priority order:
1. `~/.config/github-copilot/hosts.json` (GitHub CLI config)
2. `GITHUB_TOKEN` environment variable (Codespaces)
3. Manual token configuration via environment

**Important**: No tokens are stored - only read from existing GitHub CLI configuration.

### Key Architectural Patterns

- **Zero-config design**: Works immediately with existing GitHub Copilot setup
- **Rate limiting**: Built-in 60 requests/minute limit with configurable overrides
- **Clean separation**: Server logic, client logic, and types are distinct
- **MCP compliance**: Strict adherence to Model Context Protocol standards
- **Error resilience**: Comprehensive error handling for auth/network/API failures

## Development Notes

- Uses **ES Modules** with strict TypeScript configuration
- Environment variables loaded via dotenv with `.env.example` template
- All requests validated using Zod schemas
- Stdio transport for MCP communication (not HTTP)
- Token caching with automatic refresh handling

## Testing MCP Integration

The server communicates via stdio. Test with MCP-compatible clients or use the provided npm scripts for development testing.