getProjects
Fetch and filter Teamwork projects by date, type, status, or custom criteria. Generate detailed reports in multiple formats and organize projects by various fields for streamlined project management.
Instructions
Get all projects from Teamwork
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| includeArchivedProjects | No | Include archived projects | |
| includeCompletedProjects | No | Include completed projects | |
| includeProjectBillingMethod | No | Include project billing method | |
| includeProjectBudget | No | Include project budget | |
| includeProjectCategory | No | Include project category | |
| includeProjectCompany | No | Include project company | |
| includeProjectCreator | No | Include project creator | |
| includeProjectCustomFields | No | Include project custom fields | |
| includeProjectHealth | No | Include project health | |
| includeProjectOwner | No | Include project owner | |
| includeProjectProfitability | No | Include project profitability | |
| includeProjectRateCardCurrencies | No | Include project rate card currencies | |
| includeProjectRateCardRates | No | Include project rate card rates | |
| includeProjectRateCardTaskCurrencies | No | Include project rate card task currencies | |
| includeProjectRateCardTaskRates | No | Include project rate card task rates | |
| includeProjectRateCardTasks | No | Include project rate card tasks | |
| includeProjectRateCardUserCurrencies | No | Include project rate card user currencies | |
| includeProjectRateCardUserRates | No | Include project rate card user rates | |
| includeProjectRateCardUsers | No | Include project rate card users | |
| includeProjectRateCards | No | Include project rate cards | |
| includeProjectStatus | No | Include project status | |
| includeProjectTags | No | Include project tags | |
| maxBudgetCapacityUsedPercent | No | Filter by maximum budget capacity used | |
| maxLastActivityDate | No | Filter by max last activity date (format: YYYY-MM-DD) | |
| minBudgetCapacityUsedPercent | No | Filter by minimum budget capacity used | |
| minLastActivityDate | No | Filter by min last activity date (format: YYYY-MM-DD) | |
| notCompletedBefore | No | Filter by projects that have not been completed before the given date (format: YYYY-MM-DD) | |
| orderBy | No | Order by field | |
| orderByCustomFieldId | No | Order by custom field id when orderBy is equal to customfield | |
| orderMode | No | Order mode | |
| page | No | Page number (not used when generating reports) | |
| pageSize | No | Number of items in a page (not used when generating reports) | |
| projectType | No | Filter by project type | |
| reportFormat | No | Define the format of the report | |
| reportTimezone | No | Configure the report dates displayed in a timezone | |
| reportType | No | Define the type of the report | |
| searchTerm | No | Filter by project name | |
| timeMode | No | Profitability time mode | |
| updatedAfter | No | Filter projects updated after this date-time (format: ISO 8601) | |
| userId | No | Filter by user id |
Implementation Reference
- src/tools/index.ts:65-102 (registration)Registration of the getProjects MCP tool: pairs the imported getProjectsDefinition and handleGetProjects in the toolPairs array, which populates toolDefinitions and toolHandlersMap for the MCP server.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 }, { definition: getCompanyById, handler: handleGetCompanyById }, { definition: getProjectsPeopleMetricsPerformance, handler: handleGetProjectsPeopleMetricsPerformance }, { definition: getProjectsPeopleUtilization, handler: handleGetProjectsPeopleUtilization }, { definition: getAllocationTime, handler: handleGetProjectsAllocationsTime }, { definition: getTime, handler: handleGetTime }, { definition: getProjectPerson, handler: handleGetProjectPerson }, { definition: getProjectsReportingUserTaskCompletion, handler: handleGetProjectsReportingUserTaskCompletion }, { definition: getProjectsReportingUtilization, handler: handleGetProjectsReportingUtilization }, { definition: getTimezones, handler: handleGetTimezones } ];
- Core implementation of getProjects: fetches list of projects from Teamwork API using v3 with fallback to v1, handles errors. This service function is imported and used by the MCP tool handler.export const getProjects = async (params?: ProjectQueryParams) => { try { logger.info('Fetching projects from Teamwork API'); try { // Try with v3 API first const api = ensureApiClient(); const response = await api.get('/projects.json', { params }); logger.info('Successfully fetched projects using v3 API'); return response.data; } catch (error: any) { logger.warn(`V3 API request failed: ${error.message}`); // Try the v1 API format as fallback logger.info('Trying v1 API format as fallback'); try { const v1Api = getApiClientForVersion('v1'); const v1Response = await v1Api.get('/projects.json', { params }); logger.info('Successfully fetched projects using v1 API'); return v1Response.data; } catch (v1Error: any) { logger.error(`V1 API request also failed: ${v1Error.message}`); throw error; // Throw the original error } } } catch (error: any) { logger.error(`Teamwork API error: ${error.message}`); throw new Error('Failed to fetch projects from Teamwork API'); } }; export default getProjects;
- src/tools/index.ts:7-7 (registration)Import of the getProjects tool definition (schema) and handler from the dedicated tool file.import { getProjectsDefinition as getProjects, handleGetProjects } from './projects/getProjects.js';
- src/services/index.ts:6-6 (helper)Central export of the getProjects service for use across the app, including tools.import getProjects from './projects/getProjects.js';