main

Cursor Rules for GitHub PR Review MCP

You are an AI assistant helping develop a GitHub PR Review MCP Server built with TypeScript, FastMCP, and GitHub API.

Project Overview

• Type: Model Context Protocol (MCP) server
• Language: TypeScript (ES2022, strict mode)
• Framework: FastMCP
• Purpose: Provides GitHub PR review capabilities to LLMs in VSCode/Cursor

Core Architecture

File Structure

• src/index.ts - Main MCP server entry point (register tools here)
• src/github-service.ts - GitHub API abstraction layer (all GitHub API calls go here)
• src/code-analyzer.ts - Code analysis engine (static analysis logic)
• src/review-prompt.ts - Review prompt generation
• src/types.ts - Zod schemas and TypeScript types (all tool parameters defined here)
• dist/ - Compiled output (NEVER edit directly)

Adding New MCP Tools (3-Step Process)

1. Define Schema and Type in src/types.ts:

   // Define schema for runtime validation
   export const NewToolSchema = z.object({
     param1: z.string().describe("Parameter description"),
   });
   
   // Define explicit type (preferred over z.infer<typeof>)
   export interface NewToolParams {
     param1: string;
   }
   

2. Add Service Method in src/github-service.ts:

   async newMethod(params: NewToolParams): Promise<ResultType> {
     // Use this.octokit for GitHub API calls
     // Handle errors with try-catch
     // Return typed result
   }
   

3. Register Tool in src/index.ts:

   server.addTool({
     name: "new_tool_name",
     description: "Clear description",
     parameters: NewToolSchema,
     execute: async (params) => {
       const result = await githubService.newMethod(params);
       return {
         content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
       };
     },
   });
   

Code Standards

TypeScript

• Strict mode: Always enabled (no implicit any, strict null checks)
• Strong typing: Always use explicit, strong types. Avoid any types (warnings acceptable for external APIs only)
• Use ? for optional: Don't use | null | undefined, use optional properties (?) instead
• Zod schemas: All tool parameters MUST have Zod schemas for runtime validation
• Type definitions: Prefer explicit interface or type definitions over z.infer<typeof Schema>
• Modules: ES2022 modules (import/export)
• Imports: Use .js extension for compiled output (TypeScript requirement)