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);