getCompanies
Find and filter companies by name, tags, custom fields, or search terms using this Teamwork MCP tool. Retrieve detailed profiles, stats, and paginated results for efficient company management.
Instructions
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.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| fullProfile | No | Include full profile information | |
| getStats | No | Include stats of company tasks and projects | |
| includeCustomFields | No | Include custom fields in the response | |
| orderBy | No | Field to order results by (e.g., name, dateadded, etc.) | |
| orderMode | No | Sort order (asc or desc) | |
| page | No | Page number for pagination | |
| pageSize | No | Number of items per page | |
| searchTerm | No | Filter by company name and description | |
| tagIds | No | Filter by tag IDs |
Implementation Reference
- The handleGetCompanies function is the main tool handler. It processes input parameters, calls the teamworkService.getCompanies service, and returns the result as formatted JSON or an error message.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) { logger.error(`Error in getCompanies handler: ${error.message}`); return { content: [{ type: "text", text: `Error retrieving companies: ${error.message}` }] }; } }
- The getCompaniesDefinition object defines the tool's name, description, input schema with various filter parameters, 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:41-92 (registration)The tool is imported and registered in the toolPairs array, which is used to create toolDefinitions and toolHandlersMap for MCP tool exposure.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 },
- The getCompanies service function performs the actual API call to Teamwork's companies endpoint and is invoked 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}`); } };