getPeople
Retrieve and filter people data from Teamwork projects, including users, collaborators, and contacts, based on user type, date, search terms, or specific IDs within Teamwork MCP.
Instructions
Get all people from Teamwork
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| companyIds | No | Filter by company IDs | |
| includeClients | No | Include client users | |
| includeCollaborators | No | Include collaborator users | |
| lastLoginAfter | No | Filter by users who logged in after this date-time | |
| orderBy | No | Order by field | |
| orderMode | No | Order mode | |
| page | No | Page number | |
| pageSize | No | Number of items per page | |
| projectIds | No | Filter by project IDs | |
| searchTerm | No | Filter by name or email | |
| teamIds | No | Filter by team IDs | |
| updatedAfter | No | Filter by users updated after this date-time (format: ISO 8601) | |
| userType | No | Filter by user type |
Implementation Reference
- src/tools/people/getPeople.ts:91-140 (handler)The handler function that implements the core logic of the 'getPeople' MCP tool. It logs the input, calls the teamworkService.getPeople service, handles the response by stringifying it to JSON, and returns it as text content or appropriate error messages.export async function handleGetPeople(input: any) { logger.info('=== getPeople tool called ==='); logger.info(`Query parameters: ${JSON.stringify(input || {})}`); try { logger.info('Calling teamworkService.getPeople()'); const people = await teamworkService.getPeople(input); // Debug the response logger.info(`People response type: ${typeof people}`); if (people === null || people === undefined) { logger.warn('People response is null or undefined'); return { content: [{ type: "text", text: "No people found or API returned empty response." }] }; } try { const jsonString = JSON.stringify(people, null, 2); logger.info(`Successfully stringified people response`); logger.info('=== getPeople tool completed successfully ==='); return { content: [{ type: "text", text: jsonString }] }; } catch (jsonError: any) { logger.error(`JSON stringify error: ${jsonError.message}`); return { content: [{ type: "text", text: `Error formatting response: ${jsonError.message}` }] }; } } catch (error: any) { logger.error(`Error in getPeople tool: ${error.message}`); return { content: [{ type: "text", text: `Error: ${error.message}` }] }; } }
- src/tools/people/getPeople.ts:10-88 (schema)The schema definition for the 'getPeople' tool, including name, description, inputSchema with all query parameters, and annotations used for MCP tool registration.export const getPeopleDefinition = { name: "getPeople", description: "Get all people from Teamwork", inputSchema: { type: "object", properties: { userType: { type: "string", enum: ["account", "collaborator", "contact"], description: "Filter by user type" }, updatedAfter: { type: "string", description: "Filter by users updated after this date-time (format: ISO 8601)" }, searchTerm: { type: "string", description: "Filter by name or email" }, orderMode: { type: "string", enum: ["asc", "desc"], description: "Order mode" }, orderBy: { type: "string", enum: ["name", "namecaseinsensitive", "company"], description: "Order by field" }, lastLoginAfter: { type: "string", description: "Filter by users who logged in after this date-time" }, pageSize: { type: "integer", description: "Number of items per page" }, page: { type: "integer", description: "Page number" }, includeCollaborators: { type: "boolean", description: "Include collaborator users" }, includeClients: { type: "boolean", description: "Include client users" }, teamIds: { type: "array", items: { type: "integer" }, description: "Filter by team IDs" }, projectIds: { type: "array", items: { type: "integer" }, description: "Filter by project IDs" }, companyIds: { type: "array", items: { type: "integer" }, description: "Filter by company IDs" } } }, annotations: { title: "Get People", readOnlyHint: false, destructiveHint: false, openWorldHint: false } };
- src/tools/index.ts:83-83 (registration)Registration entry in the toolPairs array that associates the getPeople tool definition with its handler function for MCP tool system.{ definition: getPeople, handler: handleGetPeople },
- Supporting service function that performs the actual API call to Teamwork to retrieve people data, invoked by the tool handler.export const getPeople = async (params?: PeopleQueryParams) => { try { logger.info('Fetching people from Teamwork API'); const api = ensureApiClient(); const response = await api.get('/people.json', { params }); logger.info('Successfully fetched people'); return response.data; } catch (error: any) { logger.error(`Teamwork API error: ${error.message}`); throw new Error('Failed to fetch people from Teamwork API'); } };