MCP GitHub Project Manager

Instructions

Implementation Reference

• src/index.ts:284-292 (handler)

  Main tool handler in executeToolHandler switch statement. Maps tool arguments and delegates to ProjectManagementService.updateIssue method.

  case "update_issue":
    return await this.service.updateIssue(args.issueId, {
      title: args.title,
      description: args.description,
      status: args.status,
      milestoneId: args.milestoneId,
      assignees: args.assignees,
      labels: args.labels
    });

• src/services/ProjectManagementService.ts:801-834 (handler)

  Core business logic for updating GitHub issues. Maps input parameters to Issue partial, handles status conversion and milestone null handling, then delegates to GitHubIssueRepository.update.

  async updateIssue(
    issueId: string,
    updates: {
      title?: string;
      description?: string;
      status?: string;
      milestoneId?: string | null;
      assignees?: string[];
      labels?: string[];
    }
  ): Promise<Issue> {
    try {
      const data: Partial<Issue> = {};
  
      if (updates.title) data.title = updates.title;
      if (updates.description) data.description = updates.description;
      if (updates.status) {
        data.status = updates.status === 'open' ? ResourceStatus.ACTIVE : ResourceStatus.CLOSED;
      }
      if (updates.assignees) data.assignees = updates.assignees;
      if (updates.labels) data.labels = updates.labels;
  
      // Handle milestoneId explicitly
      if (updates.milestoneId === null) {
        data.milestoneId = undefined; // Remove milestone
      } else if (updates.milestoneId !== undefined) {
        data.milestoneId = updates.milestoneId;
      }
  
      return await this.issueRepo.update(issueId, data);
    } catch (error) {
      throw this.mapErrorToMCPError(error);
    }
  }

• src/infrastructure/tools/ToolSchemas.ts:165-395 (schema)

  Zod schema definition for update_issue tool input validation (lines 166-176) and complete ToolDefinition including description and examples (380-395).

  // Schema for update_issue tool
  export const updateIssueSchema = z.object({
    issueId: z.string().min(1, "Issue ID is required"),
    title: z.string().optional(),
    description: z.string().optional(),
    status: z.enum(["open", "closed"]).optional(),
    milestoneId: z.string().optional().nullable(),
    assignees: z.array(z.string()).optional(),
    labels: z.array(z.string()).optional(),
  });
  
  export type UpdateIssueArgs = z.infer<typeof updateIssueSchema>;
  
  // Schema for create_sprint tool
  export const createSprintSchema = z.object({
    title: z.string().min(1, "Sprint title is required"),
    description: z.string().min(1, "Sprint description is required"),
    startDate: z.string().datetime("Start date must be a valid ISO date string"),
    endDate: z.string().datetime("End date must be a valid ISO date string"),
    issueIds: z.array(z.string()).default([]),
  });
  
  export type CreateSprintArgs = z.infer<typeof createSprintSchema>;
  
  // Schema for list_sprints tool
  export const listSprintsSchema = z.object({
    status: z.enum(["planned", "active", "completed", "all"]).default("all"),
  });
  
  export type ListSprintsArgs = z.infer<typeof listSprintsSchema>;
  
  // Schema for get_current_sprint tool
  export const getCurrentSprintSchema = z.object({
    includeIssues: z.boolean().default(true),
  });
  
  export type GetCurrentSprintArgs = z.infer<typeof getCurrentSprintSchema>;
  
  // Schema for create_project_field tool
  export const createProjectFieldSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    name: z.string().min(1, "Field name is required"),
    type: z.enum([
      "text",
      "number",
      "date",
      "single_select",
      "iteration",
      "milestone",
      "assignees",
      "labels"
    ]),
    options: z.array(
      z.object({
        name: z.string().min(1),
        description: z.string().optional(),
        color: z.string().optional(),
      })
    ).optional(),
    description: z.string().optional(),
    required: z.boolean().optional(),
  });
  
  export type CreateProjectFieldArgs = z.infer<typeof createProjectFieldSchema>;
  
  // Schema for create_project_view tool
  export const createProjectViewSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    name: z.string().min(1, "View name is required"),
    layout: z.enum(["board", "table", "timeline", "roadmap"]),
  });
  
  export type CreateProjectViewArgs = z.infer<typeof createProjectViewSchema>;
  
  // Tool definitions with schemas, descriptions, and examples
  // Project tools
  export const createProjectTool: ToolDefinition<CreateProjectArgs> = {
    name: "create_project",
    description: "Create a new GitHub project",
    schema: createProjectSchema as unknown as ToolSchema<CreateProjectArgs>,
    examples: [
      {
        name: "Create private project",
        description: "Create a new private GitHub project",
        args: {
          title: "Backend API Development",
          shortDescription: "Project for tracking backend API development tasks",
          owner: "example-owner",
          visibility: "private"
        }
      }
    ]
  };
  
  export const listProjectsTool: ToolDefinition<ListProjectsArgs> = {
    name: "list_projects",
    description: "List GitHub projects",
    schema: listProjectsSchema as unknown as ToolSchema<ListProjectsArgs>,
    examples: [
      {
        name: "List active projects",
        description: "List all active GitHub projects",
        args: {
          status: "active",
          limit: 5
        }
      }
    ]
  };
  
  export const getProjectTool: ToolDefinition<GetProjectArgs> = {
    name: "get_project",
    description: "Get details of a specific GitHub project",
    schema: getProjectSchema as unknown as ToolSchema<GetProjectArgs>,
    examples: [
      {
        name: "Get project details",
        description: "Get details for a specific project",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH"
        }
      }
    ]
  };
  
  // Milestone tools
  export const createMilestoneTool: ToolDefinition<CreateMilestoneArgs> = {
    name: "create_milestone",
    description: "Create a new milestone",
    schema: createMilestoneSchema as unknown as ToolSchema<CreateMilestoneArgs>,
    examples: [
      {
        name: "Create milestone with due date",
        description: "Create a milestone with title, description and due date",
        args: {
          title: "Beta Release",
          description: "Complete all features for beta release",
          dueDate: "2025-06-30T00:00:00Z"
        }
      }
    ]
  };
  
  export const listMilestonesTool: ToolDefinition<ListMilestonesArgs> = {
    name: "list_milestones",
    description: "List milestones",
    schema: listMilestonesSchema as unknown as ToolSchema<ListMilestonesArgs>,
    examples: [
      {
        name: "List open milestones",
        description: "List all open milestones sorted by due date",
        args: {
          status: "open",
          sort: "due_date",
          direction: "asc"
        }
      }
    ]
  };
  
  // Issue tools
  export const createIssueTool: ToolDefinition<CreateIssueArgs> = {
    name: "create_issue",
    description: "Create a new GitHub issue",
    schema: createIssueSchema as unknown as ToolSchema<CreateIssueArgs>,
    examples: [
      {
        name: "Create bug issue",
        description: "Create a bug issue with high priority",
        args: {
          title: "Fix authentication bug",
          description: "Users cannot log in with social media accounts",
          priority: "high",
          type: "bug",
          assignees: ["developer1"],
          labels: ["bug", "authentication"]
        }
      }
    ]
  };
  
  export const listIssuesTool: ToolDefinition<ListIssuesArgs> = {
    name: "list_issues",
    description: "List GitHub issues",
    schema: listIssuesSchema as unknown as ToolSchema<ListIssuesArgs>,
    examples: [
      {
        name: "List open issues for milestone",
        description: "List open issues assigned to a specific milestone",
        args: {
          status: "open",
          milestone: "1",
          sort: "updated",
          direction: "desc",
          limit: 10
        }
      }
    ]
  };
  
  export const getIssueTool: ToolDefinition<GetIssueArgs> = {
    name: "get_issue",
    description: "Get details of a specific GitHub issue",
    schema: getIssueSchema as unknown as ToolSchema<GetIssueArgs>,
    examples: [
      {
        name: "Get issue details",
        description: "Get detailed information about an issue",
        args: {
          issueId: "42"
        }
      }
    ]
  };
  
  export const updateIssueTool: ToolDefinition<UpdateIssueArgs> = {
    name: "update_issue",
    description: "Update a GitHub issue",
    schema: updateIssueSchema as unknown as ToolSchema<UpdateIssueArgs>,
    examples: [
      {
        name: "Update issue status and milestone",
        description: "Close an issue and assign it to a milestone",
        args: {
          issueId: "42",
          status: "closed",
          milestoneId: "3"
        }
      }
    ]
  };

• src/infrastructure/tools/ToolRegistry.ts:17-158 (registration)

  Imports updateIssueTool from ToolSchemas and registers it in the central ToolRegistry singleton instance.

    getIssueTool,
    updateIssueTool,
    createSprintTool,
    listSprintsTool,
    getCurrentSprintTool,
    createProjectFieldTool,
    createProjectViewTool,
  
    // New project tools
    updateProjectTool,
    deleteProjectTool,
    listProjectFieldsTool,
    updateProjectFieldTool,
  
    // Project item tools
    addProjectItemTool,
    removeProjectItemTool,
    listProjectItemsTool,
  
    // Field values tools
    setFieldValueTool,
    getFieldValueTool,
  
    // View tools
    listProjectViewsTool,
    updateProjectViewTool,
  
    // Milestone tools
    updateMilestoneTool,
    deleteMilestoneTool,
  
    // Sprint tools
    updateSprintTool,
    addIssuesToSprintTool,
    removeIssuesFromSprintTool,
  
    // Label tools
    createLabelTool,
    listLabelsTool,
  
    // AI task management tools
    addFeatureTool,
    generatePRDTool,
    parsePRDTool,
    getNextTaskTool,
    analyzeTaskComplexityTool,
    expandTaskTool,
    enhancePRDTool,
    createTraceabilityMatrixTool,
  } from "./ToolSchemas.js";
  
  /**
   * Central registry of all available tools
   */
  export class ToolRegistry {
    private static _instance: ToolRegistry;
    private _tools: Map<string, ToolDefinition<any>>;
  
    private constructor() {
      this._tools = new Map();
      this.registerBuiltInTools();
    }
  
    /**
     * Get the singleton instance
     */
    public static getInstance(): ToolRegistry {
      if (!ToolRegistry._instance) {
        ToolRegistry._instance = new ToolRegistry();
      }
      return ToolRegistry._instance;
    }
  
    /**
     * Register a new tool
     */
    public registerTool<T>(tool: ToolDefinition<T>): void {
      if (this._tools.has(tool.name)) {
        process.stderr.write(`Tool '${tool.name}' is already registered and will be overwritten.\n`);
      }
      this._tools.set(tool.name, tool);
    }
  
    /**
     * Get a tool by name
     */
    public getTool<T>(name: string): ToolDefinition<T> | undefined {
      return this._tools.get(name) as ToolDefinition<T> | undefined;
    }
  
    /**
     * Get all registered tools
     */
    public getAllTools(): ToolDefinition<any>[] {
      return Array.from(this._tools.values());
    }
  
    /**
     * Convert tools to MCP format for list_tools response
     */
    public getToolsForMCP(): Array<{
      name: string;
      description: string;
      inputSchema: any;
    }> {
      return this.getAllTools().map(tool => ({
        name: tool.name,
        description: tool.description,
        inputSchema: this.convertZodToJsonSchema(tool.schema),
      }));
    }
  
    /**
     * Register all built-in tools
     */
    private registerBuiltInTools(): void {
      // Register roadmap and planning tools
      this.registerTool(createRoadmapTool);
      this.registerTool(planSprintTool);
      this.registerTool(getMilestoneMetricsTool);
      this.registerTool(getSprintMetricsTool);
      this.registerTool(getOverdueMilestonesTool);
      this.registerTool(getUpcomingMilestonesTool);
  
      // Register project tools
      this.registerTool(createProjectTool);
      this.registerTool(listProjectsTool);
      this.registerTool(getProjectTool);
      this.registerTool(updateProjectTool);
      this.registerTool(deleteProjectTool);
  
      // Register milestone tools
      this.registerTool(createMilestoneTool);
      this.registerTool(listMilestonesTool);
      this.registerTool(updateMilestoneTool);
      this.registerTool(deleteMilestoneTool);
  
      // Register issue tools
      this.registerTool(createIssueTool);
      this.registerTool(listIssuesTool);
      this.registerTool(getIssueTool);
      this.registerTool(updateIssueTool);