Teamwork MCP

Instructions

Implementation Reference

• src/tools/people/getPersonById.ts:33-97 (handler)

  The handler function that implements the core logic of the getPersonById tool. It validates the input personId, calls the underlying teamworkService.getPersonById, handles the response by stringifying to JSON, and manages errors appropriately.

  export async function handleGetPersonById(input: any) {
    logger.info('=== getPersonById tool called ===');
    logger.info(`Input parameters: ${JSON.stringify(input || {})}`);
    
    try {
      if (!input.personId) {
        logger.error('Missing required parameter: personId');
        return {
          content: [{
            type: "text",
            text: "Error: Missing required parameter 'personId'"
          }]
        };
      }
      
      const personId = parseInt(input.personId, 10);
      if (isNaN(personId)) {
        logger.error(`Invalid personId: ${input.personId}`);
        return {
          content: [{
            type: "text",
            text: `Error: Invalid personId. Must be a number.`
          }]
        };
      }
      
      logger.info(`Calling teamworkService.getPersonById(${personId})`);
      const person = await teamworkService.getPersonById(personId);
      
      // Debug the response
      logger.info(`Person response type: ${typeof person}`);
      
      if (person === null || person === undefined) {
        logger.warn(`Person with ID ${personId} not found or API returned empty response`);
        return {
          content: [{
            type: "text",
            text: `No person found with ID ${personId} or API returned empty response.`
          }]
        };
      }
      
      try {
        const jsonString = JSON.stringify(person, null, 2);
        logger.info(`Successfully stringified person response`);
        logger.info('=== getPersonById tool completed successfully ===');
        return {
          content: [{
            type: "text",
            text: jsonString
          }]
        };
      } catch (jsonError: any) {
        logger.error(`JSON stringify error: ${jsonError.message}`);
        return {
          content: [{
            type: "text",
            text: `Error formatting response: ${jsonError.message}`
          }]
        };
      }
    } catch (error: any) {
      return createErrorResponse(error, 'Retrieving person');
    }
  } 

• src/tools/people/getPersonById.ts:11-30 (schema)

  The tool schema definition, including name, description, inputSchema for personId (required integer), and annotations for UI hints.

  export const getPersonByIdDefinition = {
    name: "getPersonById",
    description: "Get a specific person by ID from Teamwork",
    inputSchema: {
      type: "object",
      properties: {
        personId: {
          type: "integer",
          description: "The ID of the person to retrieve"
        }
      },
      required: ["personId"]
    },
    annotations: {
      title: "Get a Person by their ID",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

• src/tools/index.ts:84-84 (registration)

  Registration of the getPersonById tool in the central toolPairs array, which populates toolDefinitions and toolHandlersMap for MCP tool exposure.

  { definition: getPersonById, handler: handleGetPersonById },

• src/services/people/getPersonById.ts:11-23 (helper)

  Helper service function that performs the actual API call to Teamwork to retrieve person data by ID, used by the tool handler.

  export const getPersonById = async (personId: number, params?: Omit<PeopleQueryParams, 'personId'>) => {
    try {
      logger.info(`Fetching person with ID ${personId} from Teamwork API`);
      
      const api = ensureApiClient();
      const response = await api.get(`/people/${personId}.json`, { params });
      logger.info(`Successfully fetched person with ID ${personId}`);
      return response.data;
    } catch (error: any) {
      logger.error(`Teamwork API error: ${error.message}`);
      throw new Error(`Failed to fetch person with ID ${personId} from Teamwork API`);
    }
  };