.cursorrules

# Cursor AI Rules for GitHub MCP Server

## Project Context

This is a Model Context Protocol (MCP) server for GitHub operations. It enables LLMs to interact with GitHub repositories through a standardized interface.

## Architecture

- **MCP Server** (`src/server/index.ts`): Stdio-based MCP protocol implementation
- **GitHub Tools** (`src/server/tools/github-tools.ts`): GitHub API operations using Octokit
- **Validation** (`src/server/schemas/tools.ts`): Zod schemas for type-safe validation
- **Worker** (`src/worker.ts`): Cloudflare Workers HTTP endpoint
- **Types** (`src/types/github.ts`): TypeScript type definitions

## Coding Standards

### TypeScript
- Use strict typing
- No `any` types without justification
- Export types from schemas using `z.infer`
- Document public APIs with JSDoc

### Validation
- All tool inputs MUST have Zod schemas
- Validate before calling GitHub API
- Provide helpful error messages

### Error Handling
```typescript
try {
  // operation
} catch (error: any) {
  throw this.handleError(error);
}
```

### Testing
- Write golden tests for new tools
- Test both valid and invalid inputs
- Test edge cases

## Available Tools

1. list_prs - List pull requests
2. get_pr - Get PR details
3. create_pr - Create pull request
4. update_pr - Update pull request
5. add_pr_comment - Add comment to PR
6. merge_pr - Merge pull request
7. request_pr_reviewers - Request reviewers
8. add_pr_labels - Add labels
9. remove_pr_labels - Remove labels

## Common Tasks

### Adding a New Tool

1. Define types in `src/types/github.ts`
2. Create Zod schema in `src/server/schemas/tools.ts`
3. Implement method in `src/server/tools/github-tools.ts`
4. Register in `src/server/index.ts` (TOOLS array + switch case)
5. Add to `src/worker.ts` (TOOLS array + switch case)
6. Write tests in `tests/golden/github-tools.test.ts`
7. Update documentation

### Running Tests
```bash
npm test
```

### Building
```bash
npm run build
```

### Local Development
```bash
npm run dev
```

### Testing with Client
```bash
npm run client
```

## Dependencies

- `@modelcontextprotocol/sdk` - MCP protocol
- `@octokit/rest` - GitHub API client
- `zod` - Runtime validation
- `vitest` - Testing framework
- `esbuild` - Bundling for Workers

## Environment Variables

- `GITHUB_TOKEN` - GitHub Personal Access Token (required)

## File Structure

```
src/
├── server/
│   ├── index.ts              # MCP server entry
│   ├── tools/
│   │   └── github-tools.ts   # GitHub operations
│   └── schemas/
│       └── tools.ts          # Validation schemas
├── client/
│   └── test-client.ts        # Example client
├── types/
│   └── github.ts             # Type definitions
└── worker.ts                 # Cloudflare Workers entry

tests/
└── golden/
    ├── github-tools.test.ts  # Golden tests
    └── fixtures/             # Test fixtures
```

## Design Principles

1. **Type Safety**: TypeScript + Zod for compile-time and runtime safety
2. **Separation of Concerns**: Clear layers (protocol, validation, business logic)
3. **Testability**: Comprehensive test coverage
4. **Deployability**: Works locally (stdio) and in production (Cloudflare Workers)
5. **Extensibility**: Easy to add new GitHub operations

## Common Patterns

### Schema Definition
```typescript
export const ToolSchema = z.object({
  owner: z.string().min(1, 'Owner is required'),
  repo: z.string().min(1, 'Repository name is required'),
  // ...
});

export type ToolInput = z.infer<typeof ToolSchema>;
```

### Tool Implementation
```typescript
async toolName(params: ToolParams): Promise<ToolResult> {
  try {
    const response = await this.octokit.rest./* api call */;
    return this.mapResult(response.data);
  } catch (error: any) {
    throw this.handleError(error);
  }
}
```

### Error Mapping
```typescript
private handleError(error: any): Error {
  if (error.status) {
    const message = error.response?.data?.message || error.message;
    return new Error(`GitHub API error (${error.status}): ${message}`);
  }
  return error instanceof Error ? error : new Error(String(error));
}
```

## MCP Protocol Notes

- Tools are registered via `ListToolsRequestSchema` handler
- Tool execution via `CallToolRequestSchema` handler
- Responses must be in format: `{ content: [{ type: 'text', text: '...' }] }`
- Errors use MCP error codes: `InvalidParams`, `InternalError`, `MethodNotFound`

## GitHub API Notes

- Rate limit: 5,000 requests/hour (authenticated)
- Use Octokit for all GitHub operations
- PAT authentication via constructor
- Handle 404, 403, and rate limit errors

## Deployment

### Local (stdio)
```bash
npm run dev
```

### Cloudflare Workers
```bash
wrangler secret put GITHUB_TOKEN
npm run deploy
```

## Best Practices

- Validate all inputs with Zod schemas
- Return meaningful error messages
- Document complex logic
- Write tests for new features
- Keep tool implementations focused
- Use TypeScript strict mode
- Follow semantic versioning