Teamwork MCP

Instructions

Implementation Reference

• src/tools/companies/getCompanies.ts:68-88 (handler)

  The main handler function for the 'getCompanies' tool. It processes input parameters, calls the underlying teamwork service, formats the response as text content, and handles errors.

  export async function handleGetCompanies(input: any) {
    logger.info('Calling teamworkService.getCompanies()');
    
    try {
      // Prepare query parameters
      const params = { ...input };
      logger.info(`Query parameters: ${JSON.stringify(params)}`);
      
      const result = await teamworkService.getCompanies(params);
      logger.info(`Successfully retrieved companies. Count: ${result?.companies?.length || 0}`);
      
      return {
        content: [{
          type: "text",
          text: JSON.stringify(result, null, 2)
        }]
      };
    } catch (error: any) {
      return createErrorResponse(error, 'Retrieving companies');
    }
  } 

• src/tools/companies/getCompanies.ts:11-65 (schema)

  The tool definition including name, description, input schema for parameters like searchTerm, page, etc., and annotations.

  export const getCompaniesDefinition = {
    name: "getCompanies",
    description: "Get a list of companies, retrieve all companies for the provided filters. This endpoint allows you to filter companies by various parameters including custom fields, tags, search terms, and more.",
    inputSchema: {
      type: 'object',
      properties: {
        searchTerm: {
          type: 'string',
          description: 'Filter by company name and description'
        },
        page: {
          type: 'integer',
          description: 'Page number for pagination'
        },
        pageSize: {
          type: 'integer',
          description: 'Number of items per page'
        },
        orderBy: {
          type: 'string',
          description: 'Field to order results by (e.g., name, dateadded, etc.)'
        },
        orderMode: {
          type: 'string',
          description: 'Sort order (asc or desc)',
          enum: ['asc', 'desc']
        },
        tagIds: {
          type: 'array',
          items: {
            type: 'string'
          },
          description: 'Filter by tag IDs'
        },
        includeCustomFields: {
          type: 'boolean',
          description: 'Include custom fields in the response'
        },
        fullProfile: {
          type: 'boolean',
          description: 'Include full profile information'
        },
        getStats: {
          type: 'boolean',
          description: 'Include stats of company tasks and projects'
        }
      }
    },
    annotations: {
      title: "Get Companies",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

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

  Registration of the 'getCompanies' tool in the toolPairs array, which is used to generate toolDefinitions and toolHandlersMap for MCP tool exposure.

  { definition: getCompanies, handler: handleGetCompanies },

• src/services/companies/getCompanies.ts:9-22 (helper)

  Helper service function that performs the actual API call to Teamwork to fetch companies based on params, used by the tool handler.

  export const getCompanies = async (params: any = {}) => {
    try {
      logger.info('Fetching all companies from Teamwork API');
      
      const api = ensureApiClient();
      const response = await api.get('companies.json', { params });
      
      logger.info(`Successfully retrieved companies. Count: ${response.data?.companies?.length || 0}`);
      return response.data;
    } catch (error: any) {
      logger.error(`Error fetching companies: ${error.message}`);
      throw new Error(`Failed to fetch companies: ${error.message}`);
    }
  };

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

  Import statement for the getCompanies tool definition and handler in the central tools index.

  import { getCompaniesDefinition as getCompanies, handleGetCompanies } from './companies/getCompanies.js';