mcp-github-project-manager

Instructions

Implementation Reference

• src/services/ProjectManagementService.ts:186-259 (handler)

  Core handler implementation that validates input, creates GitHub project, milestones, and associated issues for the roadmap.

  async createRoadmap(data: {
    project: CreateProject;
    milestones: Array<{
      milestone: CreateMilestone;
      issues: CreateIssue[];
    }>;
  }): Promise<{
    project: Project;
    milestones: Array<Milestone & { issues: Issue[] }>;
  }> {
    try {
      // Validate input with Zod schema
      const validatedData = CreateRoadmapSchema.parse(data);
  
      // Create properly typed project without using 'any'
      const projectData = {
        ...validatedData.project,
        type: ResourceType.PROJECT,
        status: ResourceStatus.ACTIVE,
        visibility: validatedData.project.visibility || 'private',
        views: [] as ProjectView[],
        fields: [] as CustomField[],
        // Ensure shortDescription is used (description is handled via separate update)
        shortDescription: validatedData.project.shortDescription,
      };
  
      const project = await this.projectRepo.create(
        createResource(ResourceType.PROJECT, projectData)
      );
  
      const milestones = [];
  
      // Create milestones and issues with proper error handling
      for (const { milestone, issues } of validatedData.milestones) {
        try {
          // Ensure milestone description is not undefined
          const milestoneWithRequiredFields = {
            ...milestone,
            description: milestone.description || ''
          };
  
          const createdMilestone = await this.milestoneRepo.create(milestoneWithRequiredFields);
  
          const createdIssues = await Promise.all(
            issues.map(async (issue) => {
              try {
                return await this.issueRepo.create({
                  ...issue,
                  milestoneId: createdMilestone.id,
                });
              } catch (error) {
                throw this.mapErrorToMCPError(error);
              }
            })
          );
  
          milestones.push({
            ...createdMilestone,
            issues: createdIssues,
          });
        } catch (error) {
          throw this.mapErrorToMCPError(error);
        }
      }
  
      return { project, milestones };
    } catch (error) {
      if (error instanceof z.ZodError) {
        throw new ValidationError(`Invalid roadmap data: ${error.message}`);
      }
  
      throw this.mapErrorToMCPError(error);
    }
  }

• src/index.ts:240-241 (handler)

  MCP tool dispatcher that routes create_roadmap calls to ProjectManagementService.createRoadmap

  case "create_roadmap":
    return await this.service.createRoadmap(args);

• src/infrastructure/tools/ToolSchemas.ts:14-39 (schema)

  Zod input schema defining parameters for create_roadmap: project details and array of milestones with issues.

  export const createRoadmapSchema = z.object({
    project: z.object({
      title: z.string().min(1, "Project title is required"),
      shortDescription: z.string().optional(),
      visibility: z.enum(["private", "public"]),
    }),
    milestones: z.array(
      z.object({
        milestone: z.object({
          title: z.string().min(1, "Milestone title is required"),
          description: z.string().min(1, "Milestone description is required"),
          dueDate: z.string().datetime("Due date must be a valid ISO date string").optional(),
        }),
        issues: z.array(
          z.object({
            title: z.string().min(1, "Issue title is required"),
            description: z.string().min(1, "Issue description is required"),
            priority: z.enum(["high", "medium", "low"]).default("medium"),
            type: z.enum(["bug", "feature", "enhancement", "documentation"]).default("feature"),
            assignees: z.array(z.string()),
            labels: z.array(z.string()),
          })
        ).optional().default([]),
      })
    ),
  });

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

  Registers the createRoadmapTool in the central tool registry during built-in tools initialization.

  this.registerTool(createRoadmapTool);

• src/infrastructure/tools/ToolSchemas.ts:867-928 (schema)

  ToolDefinition object including name, description, schema reference, and usage examples for create_roadmap.

  export const createRoadmapTool: ToolDefinition<CreateRoadmapArgs> = {
    name: "create_roadmap",
    description: "Create a project roadmap with milestones and tasks",
    schema: createRoadmapSchema as unknown as ToolSchema<CreateRoadmapArgs>,
    examples: [
      {
        name: "Simple project roadmap",
        description: "Create a basic project with two milestones",
        args: {
          project: {
            title: "New Mobile App",
            shortDescription: "Develop a new mobile application for our users",
            visibility: "private",
          },
          milestones: [
            {
              milestone: {
                title: "Design Phase",
                description: "Complete all design work for the mobile app",
                dueDate: "2025-05-01T00:00:00Z",
              },
              issues: [
                {
                  title: "Create wireframes",
                  description: "Create wireframes for all app screens",
                  priority: "high",
                  type: "feature",
                  assignees: ["designer1"],
                  labels: ["design", "ui"],
                },
                {
                  title: "Design system",
                  description: "Develop a consistent design system",
                  priority: "medium",
                  type: "feature",
                  assignees: [],
                  labels: ["design"],
                },
              ],
            },
            {
              milestone: {
                title: "Development Phase",
                description: "Implement the designed features",
                dueDate: "2025-06-15T00:00:00Z",
              },
              issues: [
                {
                  title: "User authentication",
                  description: "Implement user login and registration",
                  priority: "high",
                  type: "feature",
                  assignees: ["developer1"],
                  labels: ["auth", "backend"],
                },
              ],
            },
          ],
        },
      },
    ],
  };