mcp-github-project-manager

Instructions

Implementation Reference

• src/services/ProjectManagementService.ts:1195-1258 (handler)

  Main handler that executes the GitHub GraphQL 'addProjectV2ItemById' mutation to add an issue or pull request to a GitHub project.

  async addProjectItem(data: {
    projectId: string;
    contentId: string;
    contentType: 'issue' | 'pull_request';
  }): Promise<ProjectItem> {
    try {
      // GraphQL mutation to add an item to a project
      const mutation = `
        mutation($input: AddProjectV2ItemByIdInput!) {
          addProjectV2ItemById(input: $input) {
            item {
              id
              content {
                ... on Issue {
                  id
                  title
                }
                ... on PullRequest {
                  id
                  title
                }
              }
            }
          }
        }
      `;
  
      interface AddProjectItemResponse {
        addProjectV2ItemById: {
          item: {
            id: string;
            content: {
              id: string;
              title: string;
            };
          };
        };
      }
  
      const response = await this.factory.graphql<AddProjectItemResponse>(mutation, {
        input: {
          projectId: data.projectId,
          contentId: data.contentId
        }
      });
  
      const itemId = response.addProjectV2ItemById.item.id;
      const contentId = response.addProjectV2ItemById.item.content.id;
  
      const resourceType = data.contentType === 'issue' ? ResourceType.ISSUE : ResourceType.PULL_REQUEST;
  
      return {
        id: itemId,
        contentId,
        contentType: resourceType,
        projectId: data.projectId,
        fieldValues: {},
        createdAt: new Date().toISOString(),
        updatedAt: new Date().toISOString()
      };
    } catch (error) {
      throw this.mapErrorToMCPError(error);
    }
  }

• src/infrastructure/tools/ToolSchemas.ts:1079-1581 (schema)

  Zod input schema definition and ToolDefinition object for the add_project_item tool, including description and examples.

  export const addProjectItemSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    contentId: z.string().min(1, "Content ID is required"),
    contentType: z.enum(["issue", "pull_request"]),
  });
  
  export type AddProjectItemArgs = z.infer<typeof addProjectItemSchema>;
  
  // Schema for remove_project_item tool
  export const removeProjectItemSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
  });
  
  export type RemoveProjectItemArgs = z.infer<typeof removeProjectItemSchema>;
  
  // Schema for list_project_items tool
  export const listProjectItemsSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    limit: z.number().int().positive().default(50).optional(),
  });
  
  export type ListProjectItemsArgs = z.infer<typeof listProjectItemsSchema>;
  
  // Schema for archive_project_item tool
  export const archiveProjectItemSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
  });
  
  export type ArchiveProjectItemArgs = z.infer<typeof archiveProjectItemSchema>;
  
  // Schema for unarchive_project_item tool
  export const unarchiveProjectItemSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
  });
  
  export type UnarchiveProjectItemArgs = z.infer<typeof unarchiveProjectItemSchema>;
  
  // Schema for set_field_value tool
  export const setFieldValueSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
    fieldId: z.string().min(1, "Field ID is required"),
    value: z.any(),
  });
  
  export type SetFieldValueArgs = z.infer<typeof setFieldValueSchema>;
  
  // Schema for get_field_value tool
  export const getFieldValueSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
    fieldId: z.string().min(1, "Field ID is required"),
  });
  
  export type GetFieldValueArgs = z.infer<typeof getFieldValueSchema>;
  
  // Schema for clear_field_value tool
  export const clearFieldValueSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemId: z.string().min(1, "Item ID is required"),
    fieldId: z.string().min(1, "Field ID is required"),
  });
  
  export type ClearFieldValueArgs = z.infer<typeof clearFieldValueSchema>;
  
  // Schema for list_project_views tool
  export const listProjectViewsSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
  });
  
  export type ListProjectViewsArgs = z.infer<typeof listProjectViewsSchema>;
  
  // Schema for update_project_view tool
  export const updateProjectViewSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    viewId: z.string().min(1, "View ID is required"),
    name: z.string().optional(),
    layout: z.enum(["board", "table", "timeline", "roadmap"]).optional(),
  });
  
  export type UpdateProjectViewArgs = z.infer<typeof updateProjectViewSchema>;
  
  // Schema for delete_project_view tool
  export const deleteProjectViewSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    viewId: z.string().min(1, "View ID is required"),
  });
  
  export type DeleteProjectViewArgs = z.infer<typeof deleteProjectViewSchema>;
  
  // Schema for update_milestone tool
  export const updateMilestoneSchema = z.object({
    milestoneId: z.string().min(1, "Milestone ID is required"),
    title: z.string().optional(),
    description: z.string().optional(),
    dueDate: z.string().datetime().optional().nullable(),
    state: z.enum(["open", "closed"]).optional(),
  });
  
  export type UpdateMilestoneArgs = z.infer<typeof updateMilestoneSchema>;
  
  // Schema for delete_milestone tool
  export const deleteMilestoneSchema = z.object({
    milestoneId: z.string().min(1, "Milestone ID is required"),
  });
  
  export type DeleteMilestoneArgs = z.infer<typeof deleteMilestoneSchema>;
  
  // Schema for update_sprint tool
  export const updateSprintSchema = z.object({
    sprintId: z.string().min(1, "Sprint ID is required"),
    title: z.string().optional(),
    description: z.string().optional(),
    startDate: z.string().datetime().optional(),
    endDate: z.string().datetime().optional(),
    status: z.enum(["planned", "active", "completed"]).optional(),
  });
  
  export type UpdateSprintArgs = z.infer<typeof updateSprintSchema>;
  
  // Schema for add_issues_to_sprint tool
  export const addIssuesToSprintSchema = z.object({
    sprintId: z.string().min(1, "Sprint ID is required"),
    issueIds: z.array(z.string()).min(1, "At least one issue ID is required"),
  });
  
  export type AddIssuesToSprintArgs = z.infer<typeof addIssuesToSprintSchema>;
  
  // Schema for remove_issues_from_sprint tool
  export const removeIssuesFromSprintSchema = z.object({
    sprintId: z.string().min(1, "Sprint ID is required"),
    issueIds: z.array(z.string()).min(1, "At least one issue ID is required"),
  });
  
  export type RemoveIssuesFromSprintArgs = z.infer<typeof removeIssuesFromSprintSchema>;
  
  // Schema for create_label tool
  export const createLabelSchema = z.object({
    name: z.string().min(1, "Label name is required"),
    color: z.string().regex(/^[0-9a-fA-F]{6}$/, "Color must be a valid 6-digit hex color code without #"),
    description: z.string().optional(),
  });
  
  export type CreateLabelArgs = z.infer<typeof createLabelSchema>;
  
  // Schema for list_labels tool
  export const listLabelsSchema = z.object({
    limit: z.number().int().positive().default(100).optional(),
  });
  
  export type ListLabelsArgs = z.infer<typeof listLabelsSchema>;
  
  // ============================================================================
  // Automation Service Tools
  // ============================================================================
  
  // Schema for create_automation_rule tool
  export const createAutomationRuleSchema = z.object({
    name: z.string().min(1, "Rule name is required"),
    description: z.string().optional(),
    projectId: z.string().min(1, "Project ID is required"),
    enabled: z.boolean().optional().default(true),
    triggers: z.array(z.object({
      type: z.enum([
        "resource_created", "resource_updated", "resource_deleted",
        "issue_opened", "issue_closed", "issue_labeled", "issue_assigned",
        "pr_opened", "pr_closed", "pr_merged", "pr_approved",
        "sprint_started", "sprint_ended", "milestone_reached", "schedule"
      ]),
      resourceType: z.string().optional(),
      conditions: z.array(z.object({
        field: z.string(),
        operator: z.string(),
        value: z.any()
      })).optional()
    })),
    actions: z.array(z.object({
      type: z.enum([
        "update_resource", "create_resource", "delete_resource",
        "add_label", "remove_label", "assign_user", "unassign_user",
        "create_relationship", "delete_relationship", "notify", "webhook", "custom_script"
      ]),
      parameters: z.record(z.any())
    }))
  });
  
  export type CreateAutomationRuleArgs = z.infer<typeof createAutomationRuleSchema>;
  
  // Schema for update_automation_rule tool
  export const updateAutomationRuleSchema = z.object({
    ruleId: z.string().min(1, "Rule ID is required"),
    name: z.string().optional(),
    description: z.string().optional(),
    enabled: z.boolean().optional(),
    triggers: z.array(z.object({
      type: z.enum([
        "resource_created", "resource_updated", "resource_deleted",
        "issue_opened", "issue_closed", "issue_labeled", "issue_assigned",
        "pr_opened", "pr_closed", "pr_merged", "pr_approved",
        "sprint_started", "sprint_ended", "milestone_reached", "schedule"
      ]),
      resourceType: z.string().optional(),
      conditions: z.array(z.object({
        field: z.string(),
        operator: z.string(),
        value: z.any()
      })).optional()
    })).optional(),
    actions: z.array(z.object({
      type: z.enum([
        "update_resource", "create_resource", "delete_resource",
        "add_label", "remove_label", "assign_user", "unassign_user",
        "create_relationship", "delete_relationship", "notify", "webhook", "custom_script"
      ]),
      parameters: z.record(z.any())
    })).optional()
  });
  
  export type UpdateAutomationRuleArgs = z.infer<typeof updateAutomationRuleSchema>;
  
  // Schema for delete_automation_rule tool
  export const deleteAutomationRuleSchema = z.object({
    ruleId: z.string().min(1, "Rule ID is required")
  });
  
  export type DeleteAutomationRuleArgs = z.infer<typeof deleteAutomationRuleSchema>;
  
  // Schema for get_automation_rule tool
  export const getAutomationRuleSchema = z.object({
    ruleId: z.string().min(1, "Rule ID is required")
  });
  
  export type GetAutomationRuleArgs = z.infer<typeof getAutomationRuleSchema>;
  
  // Schema for list_automation_rules tool
  export const listAutomationRulesSchema = z.object({
    projectId: z.string().min(1, "Project ID is required")
  });
  
  export type ListAutomationRulesArgs = z.infer<typeof listAutomationRulesSchema>;
  
  // Schema for enable_automation_rule tool
  export const enableAutomationRuleSchema = z.object({
    ruleId: z.string().min(1, "Rule ID is required")
  });
  
  export type EnableAutomationRuleArgs = z.infer<typeof enableAutomationRuleSchema>;
  
  // Schema for disable_automation_rule tool
  export const disableAutomationRuleSchema = z.object({
    ruleId: z.string().min(1, "Rule ID is required")
  });
  
  export type DisableAutomationRuleArgs = z.infer<typeof disableAutomationRuleSchema>;
  
  // ============================================================================
  // Iteration Management Tools
  // ============================================================================
  
  // Schema for get_iteration_configuration tool
  export const getIterationConfigurationSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    fieldName: z.string().optional()
  });
  
  export type GetIterationConfigurationArgs = z.infer<typeof getIterationConfigurationSchema>;
  
  // Schema for get_current_iteration tool
  export const getCurrentIterationSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    fieldName: z.string().optional()
  });
  
  export type GetCurrentIterationArgs = z.infer<typeof getCurrentIterationSchema>;
  
  // Schema for get_iteration_items tool
  export const getIterationItemsSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    iterationId: z.string().min(1, "Iteration ID is required"),
    limit: z.number().int().positive().default(50).optional()
  });
  
  export type GetIterationItemsArgs = z.infer<typeof getIterationItemsSchema>;
  
  // Schema for get_iteration_by_date tool
  export const getIterationByDateSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    date: z.string().datetime("Date must be a valid ISO date string"),
    fieldName: z.string().optional()
  });
  
  export type GetIterationByDateArgs = z.infer<typeof getIterationByDateSchema>;
  
  // Schema for assign_items_to_iteration tool
  export const assignItemsToIterationSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    itemIds: z.array(z.string()).min(1, "At least one item ID is required"),
    iterationId: z.string().min(1, "Iteration ID is required"),
    fieldName: z.string().optional()
  });
  
  export type AssignItemsToIterationArgs = z.infer<typeof assignItemsToIterationSchema>;
  
  // ============================================================================
  // AI-Powered Automation Tools
  // ============================================================================
  
  // Schema 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()
  });
  
  export type GenerateRoadmapArgs = z.infer<typeof generateRoadmapSchema>;
  
  // Schema for enrich_issue tool
  export const enrichIssueSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    issueId: z.string().min(1, "Issue ID is required"),
    issueNumber: z.number().int().positive(),
    issueTitle: z.string().min(1, "Issue title is required"),
    issueDescription: z.string().optional(),
    projectContext: z.string().optional(),
    autoApply: z.boolean().default(false).optional()
  });
  
  export type EnrichIssueArgs = z.infer<typeof enrichIssueSchema>;
  
  // Schema for enrich_issues_bulk tool
  export const enrichIssuesBulkSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    issueIds: z.array(z.string()).optional(),
    projectContext: z.string().optional(),
    autoApply: z.boolean().default(false).optional()
  });
  
  export type EnrichIssuesBulkArgs = z.infer<typeof enrichIssuesBulkSchema>;
  
  // Schema for triage_issue tool
  export const triageIssueSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    issueId: z.string().min(1, "Issue ID is required"),
    issueNumber: z.number().int().positive(),
    issueTitle: z.string().min(1, "Issue title is required"),
    issueDescription: z.string().optional(),
    projectContext: z.string().optional(),
    autoApply: z.boolean().default(false).optional()
  });
  
  export type TriageIssueArgs = z.infer<typeof triageIssueSchema>;
  
  // Schema for triage_all_issues tool
  export const triageAllIssuesSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    onlyUntriaged: z.boolean().default(true).optional(),
    autoApply: z.boolean().default(false).optional(),
    projectContext: z.string().optional()
  });
  
  export type TriageAllIssuesArgs = z.infer<typeof triageAllIssuesSchema>;
  
  // Schema for schedule_triaging tool
  export const scheduleTriagingSchema = z.object({
    projectId: z.string().min(1, "Project ID is required"),
    schedule: z.enum(['hourly', 'daily', 'weekly']),
    autoApply: z.boolean().default(false)
  });
  
  export type ScheduleTriagingArgs = z.infer<typeof scheduleTriagingSchema>;
  
  // Project tools
  export const updateProjectTool: ToolDefinition<UpdateProjectArgs> = {
    name: "update_project",
    description: "Update an existing GitHub project",
    schema: updateProjectSchema as unknown as ToolSchema<UpdateProjectArgs>,
    examples: [
      {
        name: "Update project title and visibility",
        description: "Change a project's title and make it public",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          title: "Updated API Development",
          visibility: "public"
        }
      },
      {
        name: "Close a project",
        description: "Mark a project as closed",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          status: "closed"
        }
      }
    ]
  };
  
  export const deleteProjectTool: ToolDefinition<DeleteProjectArgs> = {
    name: "delete_project",
    description: "Delete a GitHub project",
    schema: deleteProjectSchema as unknown as ToolSchema<DeleteProjectArgs>,
    examples: [
      {
        name: "Delete project",
        description: "Delete a GitHub project by ID",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH"
        }
      }
    ]
  };
  
  export const getProjectReadmeTool: ToolDefinition<GetProjectReadmeArgs> = {
    name: "get_project_readme",
    description: "Get the README content of a GitHub project",
    schema: getProjectReadmeSchema as unknown as ToolSchema<GetProjectReadmeArgs>,
    examples: [
      {
        name: "Get project README",
        description: "Retrieve the README for a project",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH"
        }
      }
    ]
  };
  
  export const updateProjectReadmeTool: ToolDefinition<UpdateProjectReadmeArgs> = {
    name: "update_project_readme",
    description: "Update the README content of a GitHub project",
    schema: updateProjectReadmeSchema as unknown as ToolSchema<UpdateProjectReadmeArgs>,
    examples: [
      {
        name: "Set project README",
        description: "Update the project README with documentation",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          readme: "# Project Overview\n\nThis project tracks our development roadmap..."
        }
      }
    ]
  };
  
  export const listProjectFieldsTool: ToolDefinition<ListProjectFieldsArgs> = {
    name: "list_project_fields",
    description: "List all fields in a GitHub project",
    schema: listProjectFieldsSchema as unknown as ToolSchema<ListProjectFieldsArgs>,
    examples: [
      {
        name: "List project fields",
        description: "Get all fields for a specific project",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH"
        }
      }
    ]
  };
  
  export const updateProjectFieldTool: ToolDefinition<UpdateProjectFieldArgs> = {
    name: "update_project_field",
    description: "Update a custom field in a GitHub project",
    schema: updateProjectFieldSchema as unknown as ToolSchema<UpdateProjectFieldArgs>,
    examples: [
      {
        name: "Update field options",
        description: "Update options for a single-select field",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI1",
          name: "Updated Status",
          options: [
            { name: "Not Started", color: "red" },
            { name: "In Progress", color: "yellow" },
            { name: "Review", color: "blue" },
            { name: "Complete", color: "green" }
          ]
        }
      }
    ]
  };
  
  export const addProjectItemTool: ToolDefinition<AddProjectItemArgs> = {
    name: "add_project_item",
    description: "Add an item to a GitHub project",
    schema: addProjectItemSchema as unknown as ToolSchema<AddProjectItemArgs>,
    examples: [
      {
        name: "Add issue to project",
        description: "Add an existing issue to a project",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          contentId: "I_kwDOJrIzLs5eGXAT",
          contentType: "issue"
        }
      }
    ]
  };

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

  Registration of the addProjectItemTool (and related project item tools) in the central ToolRegistry during initialization.

  // Register project item tools
  this.registerTool(addProjectItemTool);
  this.registerTool(removeProjectItemTool);
  this.registerTool(listProjectItemsTool);
  this.registerTool(archiveProjectItemTool);
  this.registerTool(unarchiveProjectItemTool);

• src/index.ts:406-407 (handler)

  MCP server request handler router that dispatches 'add_project_item' tool calls to the ProjectManagementService.addProjectItem method.

  case "add_project_item":
    return await this.service.addProjectItem(args);