Teamwork MCP

Instructions

Implementation Reference

• src/tools/people/getProjectPeople.ts:63-136 (handler)

  The handler function that executes the getProjectPeople tool logic. Validates input (requires projectId), calls the teamworkService.getProjectPeople, handles errors, and returns JSON stringified response.
  export async function handleGetProjectPeople(input: any) { logger.info('=== getProjectPeople tool called ==='); logger.info(`Input parameters: ${JSON.stringify(input || {})}`); try { if (!input.projectId) { logger.error('Missing required parameter: projectId'); return { content: [{ type: "text", text: "Error: Missing required parameter 'projectId'" }] }; } const projectId = parseInt(input.projectId, 10); if (isNaN(projectId)) { logger.error(`Invalid projectId: ${input.projectId}`); return { content: [{ type: "text", text: `Error: Invalid projectId. Must be a number.` }] }; } // Extract projectId from input and create a new params object without it const { projectId: _, ...params } = input; logger.info(`Calling teamworkService.getProjectPeople(${projectId})`); const people = await teamworkService.getProjectPeople(projectId, params); // Debug the response logger.info(`Project people response type: ${typeof people}`); if (people === null || people === undefined) { logger.warn(`No people found for project ID ${projectId} or API returned empty response`); return { content: [{ type: "text", text: `No people found for project ID ${projectId} or API returned empty response.` }] }; } try { const jsonString = JSON.stringify(people, null, 2); logger.info(`Successfully stringified project people response`); logger.info('=== getProjectPeople 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) { logger.error(`Error in getProjectPeople tool: ${error.message}`); return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } }
• src/tools/people/getProjectPeople.ts:10-60 (schema)

  The schema definition for the getProjectPeople tool, including input schema with properties like projectId (required), userType, searchTerm, etc., description, and annotations.
  export const getProjectPeopleDefinition = { name: "getProjectPeople", description: "Get all people assigned to a specific project from Teamwork", inputSchema: { type: "object", properties: { projectId: { type: "integer", description: "The ID of the project to get people from" }, userType: { type: "string", enum: ["account", "collaborator", "contact"], description: "Filter by user type" }, searchTerm: { type: "string", description: "Filter by name or email" }, orderMode: { type: "string", enum: ["asc", "desc"], description: "Order mode" }, orderBy: { type: "string", enum: ["name", "namecaseinsensitive", "company"], description: "Order by field" }, pageSize: { type: "integer", description: "Number of items per page" }, page: { type: "integer", description: "Page number" }, includeObservers: { type: "boolean", description: "Include project observers" } }, required: ["projectId"] }, annotations: { title: "Get People in a Project", readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
• src/tools/index.ts:32-85 (registration)

  Registration of the getProjectPeople tool in the tools index: import of definition and handler, and inclusion in the toolPairs array for mapping.
  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 }, { definition: getProjectPeople, handler: handleGetProjectPeople },
• src/services/people/getProjectPeople.ts:11-23 (helper)

  Helper service function that makes the actual API call to Teamwork to fetch people for a project. Called by the tool handler.
  export const getProjectPeople = async (projectId: number, params?: Omit<PeopleQueryParams, 'projectId'>) => { try { logger.info(`Fetching people for project ID ${projectId} from Teamwork API`); const api = ensureApiClient(); const response = await api.get(`/projects/${projectId}/people.json`, { params }); logger.info(`Successfully fetched people for project ID ${projectId}`); return response.data; } catch (error: any) { logger.error(`Teamwork API error: ${error.message}`); throw new Error(`Failed to fetch people for project ID ${projectId} from Teamwork API`); } };
• src/services/index.ts:27-54 (registration)

  Re-export of the getProjectPeople service function in services index for use by teamworkService.
  import getProjectPeople from './people/getProjectPeople.js'; import addPeopleToProject, { AddPeopleToProjectPayload } from './people/addPeopleToProject.js'; import deletePerson from './people/deletePerson.js'; import updatePerson from './people/updatePerson.js'; import getPeopleMetricsPerformance from './people/getPeopleMetricsPerformance.js'; import getPeopleUtilization from './people/getPeopleUtilization.js'; import getProjectPerson from './people/getProjectPerson.js'; // Company-related exports import createCompany from './companies/createCompany.js'; import updateCompany from './companies/updateCompany.js'; import deleteCompany from './companies/deleteCompany.js'; import getCompanies from './companies/getCompanies.js'; import getCompanyById from './companies/getCompanyById.js'; // Time-related exports import getTime, { GetTimeParams } from './time/getTime.js'; import getTimezones from './core/getTimezones.js'; // Reporting exports import getUserTaskCompletion from './reporting/getUserTaskCompletion.js'; import getUtilizationCsv from './reporting/getUtilizationCsv.js'; // Re-export all functions export { getProjects, getCurrentProject, createProject, CreateProjectData }; export { getTasks, getTasksByProjectId, getTaskListsByProjectId, getTaskById, createTask, createSubTask, updateTask, deleteTask }; export { createComment }; export { getPeople, PeopleQueryParams, getPersonById, getProjectPeople, addPeopleToProject, AddPeopleToProjectPayload, deletePerson, updatePerson, getPeopleMetricsPerformance, getPeopleUtilization, getProjectPerson };