Teamwork MCP

Instructions

Implementation Reference

• src/tools/people/updatePerson.ts:70-112 (handler)

  The handler function that implements the core logic of the updatePerson tool. It processes the input, validates personId, constructs the updateData object, calls the teamwork service, and returns the result or error response.

  export async function handleUpdatePerson(input: any) {
    logger.info('Calling teamworkService.updatePerson()');
    logger.info(`Person ID: ${input.personId}`);
    
    try {
      const personId = input.personId;
      
      if (!personId) {
        throw new Error("Person ID is required");
      }
      
      // Create update data object with the person wrapper
      const updateData: { person: Record<string, any> } = {
        person: {}
      };
      
      // Copy all fields from input to updateData.person 
      // except personId which is used for the API path
      Object.keys(input).forEach(key => {
        if (key !== 'personId') {
          updateData.person[key] = input[key];
        }
      });
      
      // Make sure we're not sending an empty update
      if (Object.keys(updateData.person).length === 0) {
        throw new Error("At least one field to update must be provided");
      }
      
      logger.info(`Sending update data: ${JSON.stringify(updateData)}`);
      const result = await teamworkService.updatePerson(personId, updateData);
      logger.info(`Successfully updated person with ID: ${personId}`);
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error: any) {
      return createErrorResponse(error, 'Updating person');
    }
  } 

• src/tools/people/updatePerson.ts:11-67 (schema)

  The tool definition including name, description, input schema with properties for person updates, and annotations.

  export const updatePersonDefinition = {
    name: "updatePerson",
    description: "Update a person in Teamwork. This endpoint allows you to modify user information like timezone, name, email, etc.",
    inputSchema: {
      type: 'object',
      properties: {
        personId: {
          type: 'integer',
          description: 'The ID of the person to update'
        },
        // Field names match the Swagger definition
        "first-name": {
          type: 'string',
          description: 'First name of the person'
        },
        "last-name": {
          type: 'string',
          description: 'Last name of the person'
        },
        "email-address": {
          type: 'string',
          description: 'Email address of the person'
        },
        "title": {
          type: 'string',
          description: 'Job title or position of the person'
        },
        "phone-number-office": {
          type: 'string',
          description: 'Office phone number'
        },
        "timezoneId": {
          type: 'integer',
          description: 'Timezone ID for the person'
        },
        "administrator": {
          type: 'boolean',
          description: 'Make this person an administrator'
        },
        "user-type": {
          type: 'string',
          description: 'User type (account, collaborator, contact)'
        },
        "company-id": {
          type: 'integer',
          description: 'ID of the company the person belongs to'
        }
      },
      required: ['personId']
    },
    annotations: {
      title: "Update a Person",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

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

  Registration of the updatePerson tool: import of definition and handler, inclusion in toolPairs array for mapping, and re-export.

  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 },
    { definition: getProjectPeople, handler: handleGetProjectPeople },
    { definition: addPeopleToProject, handler: handleAddPeopleToProject },
    { definition: deletePerson, handler: handleDeletePerson },
    { definition: updatePerson, handler: handleUpdatePerson },
    { definition: createCompany, handler: handleCreateCompany },
    { definition: updateCompany, handler: handleUpdateCompany },
    { definition: deleteCompany, handler: handleDeleteCompany },
    { definition: getCompanies, handler: handleGetCompanies },
    { definition: getCompanyById, handler: handleGetCompanyById },
    { definition: getProjectsPeopleMetricsPerformance, handler: handleGetProjectsPeopleMetricsPerformance },
    { definition: getProjectsPeopleUtilization, handler: handleGetProjectsPeopleUtilization },
    { definition: getAllocationTime, handler: handleGetProjectsAllocationsTime },
    { definition: getTime, handler: handleGetTime },
    { definition: getProjectPerson, handler: handleGetProjectPerson },
    { definition: getProjectsReportingUserTaskCompletion, handler: handleGetProjectsReportingUserTaskCompletion },
    { definition: getProjectsReportingUtilization, handler: handleGetProjectsReportingUtilization },
    { definition: getTimezones, handler: handleGetTimezones }
  ];
  
  // Extract just the definitions for the toolDefinitions array
  export const toolDefinitions = toolPairs.map(pair => pair.definition);
  
  // Create a map of tool names to their handler functions
  export const toolHandlersMap: Record<string, Function> = toolPairs.reduce((map, pair) => {
    map[pair.definition.name] = pair.handler;
    return map;
  }, {} as Record<string, Function>);
  
  // Export all tool handlers
  export { handleGetProjects } from './projects/getProjects.js';
  export { handleGetCurrentProject } from './projects/getCurrentProject.js';
  export { handleCreateProject } from './projects/createProject.js';
  export { handleGetTasks } from './tasks/getTasks.js';
  export { handleGetTasksByProjectId } from './tasks/getTasksByProjectId.js';
  export { handleGetTaskListsByProjectId } from './tasks/getTaskListsByProjectId.js';
  export { handleGetTaskById } from './tasks/getTaskById.js';
  export { handleGetTasksByTaskListId } from './tasks/getTasksByTaskListId.js';
  export { handleCreateTask } from './tasks/createTask.js';
  export { handleCreateSubTask } from './tasks/createSubTask.js';
  export { handleUpdateTask } from './tasks/updateTask.js';
  export { handleDeleteTask } from './tasks/deleteTask.js';
  export { handleGetTasksMetricsComplete } from './tasks/getTasksMetricsComplete.js';
  export { handleGetTasksMetricsLate } from './tasks/getTasksMetricsLate.js';
  export { handleGetTaskSubtasks } from './tasks/getTaskSubtasks.js';
  export { handleGetTaskComments } from './tasks/getTaskComments.js';
  export { handleCreateComment } from './comments/createComment.js';
  export { handleGetPeople } from './people/getPeople.js';
  export { handleGetPersonById } from './people/getPersonById.js';
  export { handleGetProjectPeople } from './people/getProjectPeople.js';
  export { handleAddPeopleToProject } from './people/addPeopleToProject.js';
  export { handleDeletePerson } from './people/deletePerson.js';
  export { handleUpdatePerson } from './people/updatePerson.js';

• src/services/people/updatePerson.ts:10-25 (helper)

  The service function called by the tool handler to perform the actual API update on the person via the Teamwork API.

  export const updatePerson = async (personId: number, updateData: any) => {
    try {
      logger.info(`Updating person with ID ${personId}`);
      logger.info(`Update data: ${JSON.stringify(updateData)}`);
      
      const api = getApiClientForVersion('v1');
      // Note: We use put because this is a v1 API endpoint (the base path is handled by the API client)
      const response = await api.put(`people/${personId}.json`, updateData);
      
      logger.info(`Successfully updated person with ID ${personId}`);
      return response.data;
    } catch (error: any) {
      logger.error(`Error updating person with ID ${personId}: ${error.message}`);
      throw new Error(`Failed to update person with ID ${personId}: ${error.message}`);
    }
  };