getCompanies
Retrieve and filter companies from Teamwork using parameters like search terms, tags, and custom fields to manage business relationships.
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 |
|---|---|---|---|
| searchTerm | No | Filter by company name and description | |
| page | No | Page number for pagination | |
| pageSize | No | Number of items per page | |
| orderBy | No | Field to order results by (e.g., name, dateadded, etc.) | |
| orderMode | No | Sort order (asc or desc) | |
| tagIds | No | Filter by tag IDs | |
| includeCustomFields | No | Include custom fields in the response | |
| fullProfile | No | Include full profile information | |
| getStats | No | Include stats of company tasks and projects |
Implementation Reference
- 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'); } }
- 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 },
- 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';