mcp-github-project-manager

Instructions

Implementation Reference

• src/services/ProjectManagementService.ts:2155-2343 (handler)

  The core handler implementation for the get_field_value tool. Uses GitHub GraphQL API to query and return the value of a specific field on a project item, handling all supported field types (text, number, date, single-select, iteration, milestone, assignees, labels).

  async getFieldValue(data: {
    projectId: string;
    itemId: string;
    fieldId: string;
  }): Promise<{ fieldName: string; value: any; fieldType: string }> {
    try {
      const query = `
        query($projectId: ID!, $itemId: ID!, $fieldId: ID!) {
          node(id: $projectId) {
            ... on ProjectV2 {
              item(id: $itemId) {
                fieldValueByName(name: $fieldId) {
                  ... on ProjectV2ItemFieldTextValue {
                    text
                    field {
                      ... on ProjectV2Field {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldNumberValue {
                    number
                    field {
                      ... on ProjectV2Field {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldDateValue {
                    date
                    field {
                      ... on ProjectV2Field {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldSingleSelectValue {
                    name
                    field {
                      ... on ProjectV2SingleSelectField {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldIterationValue {
                    iterationId
                    title
                    field {
                      ... on ProjectV2IterationField {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldMilestoneValue {
                    milestoneId
                    title
                    field {
                      ... on ProjectV2MilestoneField {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldUserValue {
                    users {
                      nodes {
                        id
                        login
                      }
                    }
                    field {
                      ... on ProjectV2AssigneesField {
                        name
                        dataType
                      }
                    }
                  }
                  ... on ProjectV2ItemFieldLabelValue {
                    labels {
                      nodes {
                        id
                        name
                      }
                    }
                    field {
                      ... on ProjectV2LabelsField {
                        name
                        dataType
                      }
                    }
                  }
                }
              }
            }
          }
        }
      `;
  
      interface FieldValueResponse {
        node: {
          item: {
            fieldValueByName: {
              text?: string;
              number?: number;
              date?: string;
              name?: string;
              iterationId?: string;
              title?: string;
              milestoneId?: string;
              users?: {
                nodes: Array<{
                  id: string;
                  login: string;
                }>;
              };
              labels?: {
                nodes: Array<{
                  id: string;
                  name: string;
                }>;
              };
              field: {
                name: string;
                dataType: string;
              }
            }
          }
        }
      }
  
      const response = await this.factory.graphql<FieldValueResponse>(query, {
        projectId: data.projectId,
        itemId: data.itemId,
        fieldId: data.fieldId
      });
  
      if (!response.node?.item?.fieldValueByName) {
        throw new ResourceNotFoundError(ResourceType.FIELD, data.fieldId);
      }
  
      const fieldValue = response.node.item.fieldValueByName;
      const field = fieldValue.field;
      let value = null;
  
      // Extract the value based on the field type
      if ('text' in fieldValue && fieldValue.text !== undefined) {
        value = fieldValue.text;
      } else if ('number' in fieldValue && fieldValue.number !== undefined) {
        value = fieldValue.number;
      } else if ('date' in fieldValue && fieldValue.date !== undefined) {
        value = fieldValue.date;
      } else if ('name' in fieldValue && fieldValue.name !== undefined) {
        value = fieldValue.name;
      } else if ('iterationId' in fieldValue && fieldValue.iterationId !== undefined) {
        value = {
          iterationId: fieldValue.iterationId,
          title: fieldValue.title
        };
      } else if ('milestoneId' in fieldValue && fieldValue.milestoneId !== undefined) {
        value = {
          milestoneId: fieldValue.milestoneId,
          title: fieldValue.title
        };
      } else if ('users' in fieldValue && fieldValue.users?.nodes) {
        value = fieldValue.users.nodes.map(user => ({
          id: user.id,
          login: user.login
        }));
      } else if ('labels' in fieldValue && fieldValue.labels?.nodes) {
        value = fieldValue.labels.nodes.map(label => ({
          id: label.id,
          name: label.name
        }));
      }
  
      return {
        fieldName: field.name,
        value,
        fieldType: field.dataType
      };
    } catch (error) {
      throw this.mapErrorToMCPError(error);
    }
  }

• src/infrastructure/tools/ToolSchemas.ts:1755-1815 (schema)

  ToolDefinition including input schema (zod), description, and examples for get_field_value. Input requires projectId, itemId, fieldId.

  export const getFieldValueTool: ToolDefinition<GetFieldValueArgs> = {
    name: "get_field_value",
    description: "Get a field value for a GitHub project item. Supports reading all field types: TEXT, NUMBER, DATE, SINGLE_SELECT, ITERATION, MILESTONE, ASSIGNEES, LABELS",
    schema: getFieldValueSchema as unknown as ToolSchema<GetFieldValueArgs>,
    examples: [
      {
        name: "Get text field value",
        description: "Get the current text value for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI1"
        }
      },
      {
        name: "Get status field value",
        description: "Get the current status (single select) value for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI2"
        }
      },
      {
        name: "Get iteration field value",
        description: "Get the current iteration/sprint assignment for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI3"
        }
      },
      {
        name: "Get milestone field value",
        description: "Get the current milestone assignment for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI4"
        }
      },
      {
        name: "Get assignees field value",
        description: "Get the current assignees for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI5"
        }
      },
      {
        name: "Get labels field value",
        description: "Get the current labels for an item",
        args: {
          projectId: "PVT_kwDOLhQ7gc4AOEbH",
          itemId: "PVTI_lADOLhQ7gc4AOEbHzM4AOAJ7",
          fieldId: "PVTF_lADOLhQ7gc4AOEbHzM4AOAI6"
        }
      }
    ]
  };

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

  Registers the getFieldValueTool in the central ToolRegistry singleton.

  this.registerTool(getFieldValueTool);

• src/index.ts:424-425 (handler)

  MCP server dispatch handler that routes get_field_value calls to the ProjectManagementService.getFieldValue method.

  case "get_field_value":
    return await this.service.getFieldValue(args);

• src/infrastructure/tools/ToolSchemas.ts:1130-1136 (schema)

  Zod input schema validation for get_field_value tool parameters.

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