Teamwork MCP

Instructions

Implementation Reference

• src/tools/projects/createProject.ts:57-98 (handler)

  The MCP tool handler function for createProject. It processes the input, maps it to CreateProjectData, calls the teamworkService.createProject, and formats the response.

  export async function handleCreateProject(input: any) {
    logger.info('Calling teamworkService.createProject()');
    logger.info(`Project name: ${input?.name}`);
  
    try {
      if (!input?.name) {
        throw new Error("Project name is required");
      }
      
      // Prepare project data
      const projectData: CreateProjectData = {
        name: input.name
      };
        
      // Add optional fields if provided
      if (input.description) projectData.description = input.description;
      if (input.companyId) projectData.companyId = input.companyId;
      if (input.categoryId) projectData.categoryId = input.categoryId;
      if (input.startDate) projectData.startDate = input.startDate;
      if (input.endDate) projectData.endDate = input.endDate;
      if (input.status) projectData.status = input.status;
      
      // Add any other properties that might be in the input
      Object.keys(input).forEach(key => {
        if (!['name', 'description', 'companyId', 'categoryId', 'startDate', 'endDate', 'status'].includes(key)) {
          projectData[key] = input[key];
        }
      });
      
      // Call the service to create the project
      const result = await teamworkService.createProject(projectData);
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error: any) {
      return createErrorResponse(error, 'Creating project');
    }
  } 

• src/tools/projects/createProject.ts:11-54 (schema)

  The tool definition object including name, description, inputSchema for validation, and annotations.

  export const createProjectDefinition = {
    name: "createProject",
    description: "Create a new project in Teamwork",
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "The name of the project (required)"
        },
        description: {
          type: "string",
          description: "The description of the project"
        },
        companyId: {
          type: "integer",
          description: "The ID of the company the project belongs to"
        },
        categoryId: {
          type: "integer",
          description: "The ID of the category the project belongs to"
        },
        startDate: {
          type: "string",
          description: "The start date of the project (format: YYYYMMDD)"
        },
        endDate: {
          type: "string",
          description: "The end date of the project (format: YYYYMMDD)"
        },
        status: {
          type: "string",
          description: "The status of the project"
        }
      },
      required: ["name"]
    },
    annotations: {
      title: "Create a Project",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

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

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

  { definition: createProject, handler: handleCreateProject },

• src/services/projects/createProject.ts:23-51 (helper)

  The service helper function that performs the actual API call to Teamwork to create a project using v1 endpoint.

  export const createProject = async (projectData: CreateProjectData) => {
    try {
      logger.info('Creating new project in Teamwork');
      
      if (!projectData.name) {
        throw new Error('Project name is required');
      }
      
      // The v1 API endpoint for creating projects is /projects.json
      const api = getApiClientForVersion('v1');
      
      // The API expects the project data to be wrapped in a 'project' object
      const requestData = {
        project: projectData
      };
      
      logger.info(`Creating project with name: ${projectData.name}`);
      
      const response = await api.post('/projects.json', requestData);
      
      logger.info(`Successfully created project: ${projectData.name}`);
      logger.info(`Project ID: ${response.data?.id || 'Unknown'}`);
      
      return response.data;
    } catch (error: any) {
      logger.error(`Failed to create project: ${error.message}`);
      throw new Error(`Failed to create project: ${error.message}`);
    }
  };