Teamwork MCP

Instructions

Implementation Reference

• src/tools/people/addPeopleToProject.ts:47-121 (handler)

  The handler function for the 'addPeopleToProject' tool. Validates input parameters (projectId, userIds, optional checkTeamIds), prepares the payload, calls the teamwork service, handles the response, and returns formatted output or errors.

  export async function handleAddPeopleToProject(input: any) {
    logger.info('=== addPeopleToProject 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'"
          }]
        };
      }
      
      if (!input.userIds || !Array.isArray(input.userIds) || input.userIds.length === 0) {
        logger.error('Missing or invalid required parameter: userIds');
        return {
          content: [{
            type: "text",
            text: "Error: Missing or invalid required parameter 'userIds'. Must be a non-empty array of user IDs."
          }]
        };
      }
      
      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.`
          }]
        };
      }
      
      // Prepare the payload with proper typing
      const payload: AddPeopleToProjectPayload = {
        userIds: input.userIds
      };
      
      // Add checkTeamIds if provided
      if (input.checkTeamIds && Array.isArray(input.checkTeamIds)) {
        payload.checkTeamIds = input.checkTeamIds;
      }
      
      logger.info(`Calling teamworkService.addPeopleToProject(${projectId}, ${JSON.stringify(payload)})`);
      const result = await teamworkService.addPeopleToProject(projectId, payload);
      
      // Debug the response
      logger.info(`Add people to project response type: ${typeof result}`);
      
      try {
        const jsonString = JSON.stringify(result, null, 2);
        logger.info(`Successfully stringified response`);
        logger.info('=== addPeopleToProject 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, 'Adding people to project');
    }
  } 

• src/tools/people/addPeopleToProject.ts:11-44 (schema)

  The tool definition object including the name, description, inputSchema for parameter validation (projectId: integer required, userIds: array of integers required, checkTeamIds: optional array of integers), and annotations.

  export const addPeopleToProjectDefinition = {
    name: "addPeopleToProject",
    description: "Add people to a specific project in Teamwork",
    inputSchema: {
      type: "object",
      properties: {
        projectId: {
          type: "integer",
          description: "The ID of the project to add people to"
        },
        userIds: {
          type: "array",
          items: {
            type: "integer"
          },
          description: "Array of user IDs to add to the project"
        },
        checkTeamIds: {
          type: "array",
          items: {
            type: "integer"
          },
          description: "Optional array of team IDs to check"
        }
      },
      required: ["projectId", "userIds"]
    },
    annotations: {
      title: "Add People to Project",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

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

  Registration of the 'addPeopleToProject' tool in the toolPairs array, pairing the definition and handler for inclusion in toolDefinitions and toolHandlersMap.

  { definition: addPeopleToProject, handler: handleAddPeopleToProject },

• src/services/people/addPeopleToProject.ts:18-31 (helper)

  The core service function that performs the API call to add people to a project using the Teamwork API PUT /projects/{projectId}/people.json endpoint.

  export const addPeopleToProject = async (projectId: number, payload: AddPeopleToProjectPayload) => {
    try {
      logger.info(`Adding people to project ID ${projectId} in Teamwork API`);
      logger.info(`Payload: ${JSON.stringify(payload)}`);
      
      const api = ensureApiClient();
      const response = await api.put(`/projects/${projectId}/people.json`, payload);
      logger.info(`Successfully added people to project ID ${projectId}`);
      return response.data;
    } catch (error: any) {
      logger.error(`Teamwork API error: ${error.message}`);
      throw new Error(`Failed to add people to project ID ${projectId} in Teamwork API`);
    }
  };

• src/services/people/addPeopleToProject.ts:7-10 (schema)

  TypeScript interface defining the payload structure for adding people to a project: required userIds array and optional checkTeamIds array.

  export interface AddPeopleToProjectPayload {
    userIds: number[];
    checkTeamIds?: number[];
  }