mcp-github-project-manager

Instructions

Implementation Reference

• src/services/RoadmapPlanningService.ts:23-92 (handler)

  Core handler implementing the generate_roadmap tool logic: fetches project issues, uses AI to analyze and create roadmap structure with phases, milestones, and sprints

  async generateRoadmap(params: {
    projectId: string;
    projectTitle: string;
    projectDescription?: string;
    sprintDurationWeeks?: number;
    targetMilestones?: number;
  }): Promise<{
    roadmap: {
      phases: Array<{
        name: string;
        description: string;
        duration: string;
        milestones: Array<{
          title: string;
          description: string;
          dueDate?: string;
          issues: string[];
        }>;
      }>;
    };
    milestones: Array<{
      title: string;
      description: string;
      dueDate?: string;
      issueIds: string[];
    }>;
    sprints: Array<{
      title: string;
      description: string;
      startDate: string;
      endDate: string;
      issueIds: string[];
    }>;
  }> {
    try {
      this.logger.info(`Generating roadmap for project ${params.projectId}`);
  
      // Fetch all issues for the project
      const items = await this.projectService.listProjectItems({
        projectId: params.projectId,
        limit: 200
      });
  
      // Extract issue information
      const issues = items.map((item: any) => ({
        id: item.id,
        title: item.title || 'Untitled',
        type: item.type,
        content: item.content
      }));
  
      if (issues.length === 0) {
        throw new Error('No issues found in project. Cannot generate roadmap.');
      }
  
      // Generate roadmap using AI
      const roadmapAnalysis = await this.analyzeIssuesForRoadmap({
        projectTitle: params.projectTitle,
        projectDescription: params.projectDescription || '',
        issues,
        sprintDurationWeeks: params.sprintDurationWeeks || 2,
        targetMilestones: params.targetMilestones || 4
      });
  
      return roadmapAnalysis;
    } catch (error) {
      this.logger.error('Failed to generate roadmap', error);
      throw error;
    }
  }

• src/index.ts:620-654 (handler)

  MCP tool dispatch handler for generate_roadmap: calls RoadmapPlanningService and handles optional GitHub creation

  private async handleGenerateRoadmap(args: any): Promise<any> {
    try {
      const roadmap = await this.roadmapService.generateRoadmap({
        projectId: args.projectId,
        projectTitle: args.projectTitle,
        projectDescription: args.projectDescription,
        sprintDurationWeeks: args.sprintDurationWeeks,
        targetMilestones: args.targetMilestones
      });
  
      if (args.autoCreate) {
        const result = await this.roadmapService.createRoadmapInGitHub({
          projectId: args.projectId,
          roadmap
        });
  
        return {
          success: true,
          roadmap,
          created: result
        };
      }
  
      return {
        success: true,
        roadmap
      };
    } catch (error) {
      this.logger.error("Failed to generate roadmap:", error);
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to generate roadmap: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/infrastructure/tools/ToolSchemas.ts:2364-2382 (schema)

  ToolDefinition object registering generate_roadmap with schema reference, description, and usage examples

  export const generateRoadmapTool: ToolDefinition<GenerateRoadmapArgs> = {
    name: "generate_roadmap",
    description: "AI-powered roadmap generation from project issues. Creates milestones, sprints, and phases automatically.",
    schema: generateRoadmapSchema as unknown as ToolSchema<GenerateRoadmapArgs>,
    examples: [
      {
        name: "Generate roadmap",
        description: "Create a comprehensive roadmap from existing issues",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          projectTitle: "API Platform Development",
          projectDescription: "Build a scalable REST API platform",
          sprintDurationWeeks: 2,
          targetMilestones: 4,
          autoCreate: true
        }
      }
    ]
  };

• src/infrastructure/tools/ToolSchemas.ts:1390-1397 (schema)

  Zod input schema validating parameters for generate_roadmap tool

  export const generateRoadmapSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    projectTitle: z.string().min(1, "Project title is required"),
    projectDescription: z.string().optional(),
    sprintDurationWeeks: z.number().int().positive().default(2).optional(),
    targetMilestones: z.number().int().positive().default(4).optional(),
    autoCreate: z.boolean().default(false).optional()
  });

• src/infrastructure/tools/ToolRegistry.ts:295-300 (registration)

  Registers generateRoadmapTool in ToolRegistry during initialization of built-in tools

  this.registerTool(generateRoadmapTool);
  this.registerTool(enrichIssueTool);
  this.registerTool(enrichIssuesBulkTool);
  this.registerTool(triageIssueTool);
  this.registerTool(triageAllIssuesTool);
  this.registerTool(scheduleTriagingTool);