mcp-github-project-manager

Instructions

Implementation Reference

• src/index.ts:290-291 (handler)

  Top-level MCP tool handler that dispatches 'list_milestones' calls to ProjectManagementService.listMilestones with parsed arguments.

  case "list_milestones":
    return await this.service.listMilestones(args.status, args.sort, args.direction);

• src/services/ProjectManagementService.ts:639-682 (handler)

  Core handler function in ProjectManagementService that fetches all milestones from repository, applies status filter, sorts by specified criteria (due_date, title, created_at), and returns the list.

  async listMilestones(
    status: string = 'open',
    sort: string = 'created_at',
    direction: string = 'asc'
  ): Promise<Milestone[]> {
    try {
      // Get all milestones
      const milestones = await this.milestoneRepo.findAll();
  
      // Filter by status if needed
      let filteredMilestones = milestones;
      if (status !== 'all') {
        const resourceStatus = status === 'open' ? ResourceStatus.ACTIVE : ResourceStatus.CLOSED;
        filteredMilestones = milestones.filter(milestone => milestone.status === resourceStatus);
      }
  
      // Sort the milestones
      filteredMilestones.sort((a, b) => {
        let valueA, valueB;
  
        switch(sort) {
          case 'due_date':
            valueA = a.dueDate || '';
            valueB = b.dueDate || '';
            break;
          case 'title':
            valueA = a.title;
            valueB = b.title;
            break;
          case 'created_at':
          default:
            valueA = a.createdAt;
            valueB = b.createdAt;
        }
  
        const comparison = valueA.localeCompare(valueB);
        return direction === 'asc' ? comparison : -comparison;
      });
  
      return filteredMilestones;
    } catch (error) {
      throw this.mapErrorToMCPError(error);
    }
  }

• src/infrastructure/github/repositories/GitHubMilestoneRepository.ts:172-200 (helper)

  GitHub repository helper that executes GraphQL query to list all milestones and maps GitHub response to domain Milestone objects.

  async findAll(): Promise<Milestone[]> {
    const query = `
      query($owner: String!, $repo: String!) {
        repository(owner: $owner, name: $repo) {
          milestones(first: 100) {
            nodes {
              id
              number
              title
              description
              dueOn
              state
              createdAt
              updatedAt
            }
          }
        }
      }
    `;
  
    const response = await this.graphql<ListMilestonesResponse>(query, {
      owner: this.owner,
      repo: this.repo,
    });
  
    return response.repository.milestones.nodes.map(milestone => 
      this.mapGitHubMilestoneToMilestone(milestone)
    );
  }

• src/infrastructure/tools/ToolSchemas.ts:433-448 (schema)

  ToolDefinition for list_milestones including Zod input schema (status, sort, direction), description, and usage examples.

  export const listMilestonesTool: ToolDefinition<ListMilestonesArgs> = {
    name: "list_milestones",
    description: "List milestones",
    schema: listMilestonesSchema as unknown as ToolSchema<ListMilestonesArgs>,
    examples: [
      {
        name: "List open milestones",
        description: "List all open milestones sorted by due date",
        args: {
          status: "open",
          sort: "due_date",
          direction: "asc"
        }
      }
    ]
  };

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

  Registers listMilestonesTool (imported from ToolSchemas) in the central ToolRegistry singleton used by MCP server.

  this.registerTool(createMilestoneTool);
  this.registerTool(listMilestonesTool);
  this.registerTool(updateMilestoneTool);
  this.registerTool(deleteMilestoneTool);