getProjectPerson
Read-onlyIdempotent
Retrieve people records from a Teamwork project, enabling filtering by user type, company, team, and activity status to manage project members effectively.
Instructions
Returns one or more people on a project. Retrieve a person(s) record.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes | Path parameter: projectId | |
| personId | Yes | Path parameter: personId | |
| userType | No | user type | |
| updatedAfter | No | date time | |
| searchTerm | No | filter by comment content | |
| orderMode | No | order mode | |
| orderBy | No | order by | |
| lastLoginAfter | No | Query parameter: lastLoginAfter | |
| pageSize | No | number of items in a page (not used when generating reports) | |
| page | No | page number (not used when generating reports) | |
| skipCounts | No | SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons. | |
| showDeleted | No | include deleted items | |
| searchUserJobRole | No | Include user job role in search | |
| orderPrioritiseCurrentUser | No | Force to have the current/session user in the response | |
| onlySiteOwner | No | Query parameter: onlySiteOwner | |
| onlyOwnerCompany | No | return people only from the owner company. This will replace any provided company ID. | |
| inclusiveFilter | No | make the filter inclusive for user ids, teamIds, companyIds | |
| includeServiceAccounts | No | include service accounts | |
| includePlaceholders | No | include placeholder users | |
| includeCollaborators | No | exclude collaborators types, returning only account and contact. | |
| includeClients | No | include clients | |
| filterByNoCostRate | No | Returns users who are missing cost rates(OCA only) | |
| excludeContacts | No | exclude contact types, returning only account and collaborator. | |
| teamIds | No | team ids | |
| projectIds | No | filter by project ids | |
| include | No | include (not used when generating reports) | |
| ids | No | filter by user ids | |
| fieldsTeams | No | Query parameter: fields[teams] | |
| fieldsPerson | No | Query parameter: fields[person] | |
| fieldsPeople | No | Query parameter: fields[people] | |
| fieldsCompanies | No | Query parameter: fields[companies] | |
| fieldsProjectPermissions | No | Query parameter: fields[ProjectPermissions] | |
| excludeProjectIds | No | exclude people assigned to certain project id | |
| excludeIds | No | exclude certain user ids | |
| companyIds | No | company ids |
Implementation Reference
- The handler function that executes the tool logic. It processes input parameters, maps fields for the API, calls the underlying service, and returns the response as JSON text or an error.
export async function handleGetProjectPerson(input: any) { logger.info("Calling getProjectPersonService()"); const apiInput: Record<string, any> = { ...input }; const fieldMappings: Record<string, string> = { fieldsTeams: "fields[teams]", fieldsPerson: "fields[person]", fieldsPeople: "fields[people]", fieldsCompanies: "fields[companies]", fieldsProjectPermissions: "fields[ProjectPermissions]", }; for (const [camelCaseKey, apiKey] of Object.entries(fieldMappings)) { if (apiInput[camelCaseKey] !== undefined) { apiInput[apiKey] = apiInput[camelCaseKey]; delete apiInput[camelCaseKey]; } } try { const response = await getProjectPersonService({ projectId: apiInput.projectId, personId: apiInput.personId, ...apiInput }); logger.info("getProjectPersonService response received"); return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] }; } catch (error: any) { return createErrorResponse(error, 'Retrieving project person'); } } - The tool schema definition including inputSchema with all parameters, required fields (projectId, personId), description, and annotations.
export const getProjectPersonDefinition = { name: "getProjectPerson", description: "Returns one or more people on a project. Retrieve a person(s) record.", inputSchema: { type: 'object', properties: { projectId: { type: 'integer', description: 'Path parameter: projectId' }, personId: { type: 'integer', description: 'Path parameter: personId' }, userType: { type: 'string', description: 'user type', enum: [ 'account', 'collaborator', 'contact' ] }, updatedAfter: { type: 'string', description: 'date time' }, searchTerm: { type: 'string', description: 'filter by comment content' }, orderMode: { type: 'string', description: 'order mode', enum: [ 'asc', 'desc' ] }, orderBy: { type: 'string', description: 'order by', enum: [ 'name', 'namecaseinsensitive', 'company' ] }, lastLoginAfter: { type: 'string', description: 'Query parameter: lastLoginAfter' }, pageSize: { type: 'integer', description: 'number of items in a page (not used when generating reports)' }, page: { type: 'integer', description: 'page number (not used when generating reports)' }, skipCounts: { type: 'boolean', description: 'SkipCounts allows you to skip doing counts on a list API endpoint for performance reasons.' }, showDeleted: { type: 'boolean', description: 'include deleted items' }, searchUserJobRole: { type: 'boolean', description: 'Include user job role in search' }, orderPrioritiseCurrentUser: { type: 'boolean', description: 'Force to have the current/session user in the response' }, onlySiteOwner: { type: 'boolean', description: 'Query parameter: onlySiteOwner' }, onlyOwnerCompany: { type: 'boolean', description: 'return people only from the owner company. This will replace any provided company ID.' }, inclusiveFilter: { type: 'boolean', description: 'make the filter inclusive for user ids, teamIds, companyIds' }, includeServiceAccounts: { type: 'boolean', description: 'include service accounts' }, includePlaceholders: { type: 'boolean', description: 'include placeholder users' }, includeCollaborators: { type: 'boolean', description: 'exclude collaborators types, returning only account and contact.' }, includeClients: { type: 'boolean', description: 'include clients' }, filterByNoCostRate: { type: 'boolean', description: 'Returns users who are missing cost rates(OCA only)' }, excludeContacts: { type: 'boolean', description: 'exclude contact types, returning only account and collaborator.' }, teamIds: { type: 'array', items: { type: 'integer' }, description: 'team ids' }, projectIds: { type: 'array', items: { type: 'integer' }, description: 'filter by project ids' }, include: { type: 'array', items: { type: 'string' }, description: 'include (not used when generating reports)' }, ids: { type: 'array', items: { type: 'integer' }, description: 'filter by user ids' }, fieldsTeams: { type: 'array', description: 'Query parameter: fields[teams]', items: { type: 'string', enum: [ "id", "name", "teamLogo", "teamLogoIcon", "teamLogoColor" ] } }, fieldsPerson: { type: 'array', description: 'Query parameter: fields[person]', items: { type: 'string', enum: [ "id", "firstName", "lastName", "title", "email", "companyId", "company", "isAdmin", "isClientUser", "isServiceAccount", "type", "deleted", "avatarUrl", "lengthOfDay", "workingHoursId", "workingHour", "userRate", "userCost", "canAddProjects" ] } }, fieldsPeople: { type: 'array', description: 'Query parameter: fields[people]', items: { type: 'string', enum: [ "id", "firstName", "lastName", "title", "email", "companyId", "company", "isAdmin", "isClientUser", "isServiceAccount", "type", "deleted", "avatarUrl", "lengthOfDay", "workingHoursId", "workingHour", "userRate", "userCost", "canAddProjects" ] } }, fieldsCompanies: { type: 'array', description: 'Query parameter: fields[companies]', items: { type: 'string', enum: [ "id", "name", "logoUploadedToServer", "logoImage" ] } }, fieldsProjectPermissions: { type: 'array', description: 'Query parameter: fields[ProjectPermissions]', items: { type: 'string', enum: [ "viewMessagesAndFiles", "viewTasksAndMilestones", "viewTime", "viewNotebooks", "viewRiskRegister", "viewEstimatedTime", "viewInvoices", "addTasks", "addRisks", "manageCustomFields", "addExpenses", "editAllTasks", "addMilestones", "addTaskLists", "addMessages", "addFiles", "addTime", "addNotebooks", "viewLinks", "addLinks", "canViewForms", "addForms", "viewAllTimeLogs", "setPrivacy", "projectAdministrator", "viewProjectUpdate", "addProjectUpdate", "canViewProjectMembers", "canViewProjectBudget", "canManageProjectBudget", "canViewRates", "canManageRates", "canViewSchedule", "canManageSchedule", "receiveEmailNotifications", "isObserving", "isArchived", "active", "canAccess", "inOwnerCompany", "canManagePeople", "canViewProjectTemplates", "canManageProjectTemplates" ] } }, excludeProjectIds: { type: 'array', items: { type: 'integer' }, description: 'exclude people assigned to certain project id' }, excludeIds: { type: 'array', items: { type: 'integer' }, description: 'exclude certain user ids' }, companyIds: { type: 'array', items: { type: 'integer' }, description: 'company ids' } }, required: [ 'projectId', 'personId' ] }, annotations: { title: "Get a Person(s) on a Project", readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false } }; - src/tools/index.ts:98-98 (registration)Registration of the getProjectPerson tool in the toolPairs array, pairing the definition and handler for use in the tools system.
{ definition: getProjectPerson, handler: handleGetProjectPerson }, - The service function called by the tool handler, which makes the actual API call to retrieve project person data from Teamwork API.
export async function getProjectPerson(params: GetProjectPersonPathParams & QueryParams) { const api = getApiClientForVersion('v3'); const { projectId, personId, ...queryParams } = params; logger.debug(`Making GET request to /projects/${projectId}/people/${personId}.json with params: ${JSON.stringify(queryParams)}`); try { const response = await api.get(`/projects/${projectId}/people/${personId}.json`, { params: queryParams }); return response.data; } catch (error: any) { if (error.response) { logger.error(`Error fetching project person: Status ${error.response.status} - ${JSON.stringify(error.response.data)}`); } else if (error.request) { logger.error(`Error fetching project person: No response received - ${error.request}`); } else { logger.error(`Error fetching project person: ${error.message}`); } throw new Error(`Failed to fetch project person from Teamwork API: ${error.message}`); } } export default getProjectPerson;