MCP GitHub Project Manager

Instructions

Implementation Reference

• src/infrastructure/tools/ToolSchemas.ts:241-257 (schema)

  Tool definition including name, description, input schema (createProjectSchema), and usage examples for the create_project MCP tool.

  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"
        }
      }
    ]
  };

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

  Registration of the create_project tool in the central ToolRegistry singleton, making it available for list_tools responses.

  // Register project tools
  this.registerTool(createProjectTool);
  this.registerTool(listProjectsTool);

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

  MCP tool dispatcher switch case that routes create_project calls to the ProjectManagementService.

  case "create_project":
    return await this.service.createProject(args);

• src/services/ProjectManagementService.ts:571-588 (handler)

  Core tool handler method that validates input, constructs domain CreateProject object, and delegates to GitHubProjectRepository for execution.

  async createProject(data: {
    title: string;
    shortDescription?: string;
    visibility?: 'private' | 'public';
  }): Promise<Project> {
    try {
      const projectData: CreateProject = {
        title: data.title,
        shortDescription: data.shortDescription,
        owner: this.factory.getConfig().owner,
        visibility: data.visibility || 'private',
      };
  
      return await this.projectRepo.create(projectData);
    } catch (error) {
      throw this.mapErrorToMCPError(error);
    }
  }

• src/infrastructure/github/repositories/GitHubProjectRepository.ts:48-125 (helper)

  Low-level repository implementation that executes the GitHub GraphQL createProjectV2 mutation (with follow-up update for description) and converts response to domain Project model.

  async create(data: CreateProject): Promise<Project> {
    // Step 1: Create project with valid CreateProjectV2Input schema
    const createMutation = `
      mutation($input: CreateProjectV2Input!) {
        createProjectV2(input: $input) {
          projectV2 {
            id
            title
            shortDescription
            closed
            createdAt
            updatedAt
          }
        }
      }
    `;
  
    // Build input according to official GitHub schema
    const createInput: any = {
      ownerId: this.owner,
      title: data.title,
    };
  
    // Add optional repositoryId if available
    if (this.repo) {
      createInput.repositoryId = this.repo;
    }
  
    const createResponse = await this.graphql<CreateProjectResponse>(createMutation, {
      input: createInput,
    });
  
    let project = createResponse.createProjectV2.projectV2;
  
    // Step 2: Update project with description if provided (shortDescription is not part of CreateProjectV2Input)
    if (data.shortDescription) {
      const updateMutation = `
        mutation($input: UpdateProjectV2Input!) {
          updateProjectV2(input: $input) {
            projectV2 {
              id
              title
              shortDescription
              closed
              createdAt
              updatedAt
            }
          }
        }
      `;
  
      const updateResponse = await this.graphql<UpdateProjectResponse>(updateMutation, {
        input: {
          projectId: project.id,
          shortDescription: data.shortDescription,
        },
      });
  
      project = updateResponse.updateProjectV2.projectV2;
    }
  
    return {
      id: project.id,
      type: ResourceType.PROJECT,
      title: project.title,
      description: project.shortDescription || "",
      owner: this.owner,
      number: parseInt(project.id.split('_').pop() || '0'),
      url: `https://github.com/orgs/${this.owner}/projects/${parseInt(project.id.split('_').pop() || '0')}`,
      status: project.closed ? ResourceStatus.CLOSED : ResourceStatus.ACTIVE,
      visibility: data.visibility || "private",
      views: data.views || [],
      fields: data.fields || [],
      createdAt: project.createdAt,
      updatedAt: project.updatedAt,
      closed: project.closed
    };
  }