getPersonById

Instructions

Implementation Reference

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

  The tool handler function that receives the input, validates personId, calls the service, and returns the person data as JSON text.

  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 definition including name, description, input schema (requires an integer personId), and annotations.

  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:31-84 (registration)

  Import and paired registration of getPersonById definition with handler in the toolPairs array (line 84).

  import { getPersonByIdDefinition as getPersonById, handleGetPersonById } from './people/getPersonById.js';
  import { getProjectPeopleDefinition as getProjectPeople, handleGetProjectPeople } from './people/getProjectPeople.js';
  import { addPeopleToProjectDefinition as addPeopleToProject, handleAddPeopleToProject } from './people/addPeopleToProject.js';
  import { deletePersonDefinition as deletePerson, handleDeletePerson } from './people/deletePerson.js';
  import { updatePersonDefinition as updatePerson, handleUpdatePerson } from './people/updatePerson.js';
  
  // Companies
  import { createCompanyDefinition as createCompany, handleCreateCompany } from './companies/createCompany.js';
  import { updateCompanyDefinition as updateCompany, handleUpdateCompany } from './companies/updateCompany.js';
  import { deleteCompanyDefinition as deleteCompany, handleDeleteCompany } from './companies/deleteCompany.js';
  import { getCompaniesDefinition as getCompanies, handleGetCompanies } from './companies/getCompanies.js';
  import { getCompanyByIdDefinition as getCompanyById, handleGetCompanyById } from './companies/getCompanyById.js';
  
  // Reporting
  import { getProjectsPeopleMetricsPerformanceDefinition as getProjectsPeopleMetricsPerformance, handleGetProjectsPeopleMetricsPerformance } from './people/getPeopleMetricsPerformance.js';
  import { getProjectsPeopleUtilizationDefinition as getProjectsPeopleUtilization, handleGetProjectsPeopleUtilization } from './people/getPeopleUtilization.js';
  import { getProjectPersonDefinition as getProjectPerson, handleGetProjectPerson } from './people/getProjectPerson.js';
  import { getProjectsReportingUserTaskCompletionDefinition as getProjectsReportingUserTaskCompletion, handleGetProjectsReportingUserTaskCompletion } from './reporting/getUserTaskCompletion.js';
  import { getProjectsReportingUtilizationDefinition as getProjectsReportingUtilization, handleGetProjectsReportingUtilization } from './people/getUtilization.js';
  
  // Time-related imports
  import { getTimeDefinition as getTime, handleGetTime } from './time/getTime.js';
  import { getProjectsAllocationsTimeDefinition as getAllocationTime, handleGetProjectsAllocationsTime } from './time/getAllocationTime.js';
  
  // Core
  import { getTimezonesDefinition as getTimezones, handleGetTimezones } from './core/getTimezones.js';
  
  // Define a structure that pairs tool definitions with their handlers
  interface ToolPair {
    definition: any;
    handler: Function;
  }
  
  // Create an array of tool pairs
  const toolPairs: ToolPair[] = [
    { definition: getProjects, handler: handleGetProjects },
    { definition: getCurrentProject, handler: handleGetCurrentProject },
    { definition: createProject, handler: handleCreateProject },
    { definition: getTasks, handler: handleGetTasks },
    { definition: getTasksByProjectId, handler: handleGetTasksByProjectId },
    { definition: getTaskListsByProjectId, handler: handleGetTaskListsByProjectId },
    { definition: getTasksByTaskListId, handler: handleGetTasksByTaskListId },
    { definition: getTaskById, handler: handleGetTaskById },
    { definition: createTask, handler: handleCreateTask },
    { definition: createSubTask, handler: handleCreateSubTask },
    { definition: updateTask, handler: handleUpdateTask },
    { definition: deleteTask, handler: handleDeleteTask },
    { definition: getTasksMetricsComplete, handler: handleGetTasksMetricsComplete },
    { definition: getTasksMetricsLate, handler: handleGetTasksMetricsLate },
    { definition: getTaskSubtasks, handler: handleGetTaskSubtasks },
    { definition: getTaskComments, handler: handleGetTaskComments },
    { definition: createComment, handler: handleCreateComment },
    { definition: getPeople, handler: handleGetPeople },
    { definition: getPersonById, handler: handleGetPersonById },

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

  Service helper that calls the Teamwork API '/people/{personId}.json' endpoint using the API client and returns the response data.

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

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

  Re-export of handleGetPersonById from the tools index for external consumers.

  export { handleGetPersonById } from './people/getPersonById.js';