Teamwork MCP

Instructions

Implementation Reference

• src/tools/reporting/getUserTaskCompletion.ts:188-200 (handler)

  The tool handler function that executes the core logic: calls the reporting service with input and returns formatted JSON response or error.

  export async function handleGetProjectsReportingUserTaskCompletion(input: any) {
    try {
      const response = await getUserTaskCompletion(input);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(response, null, 2)
        }]
      };
    } catch (error: any) {
      return createErrorResponse(error, 'Retrieving user task completion');
    }
  } 

• src/tools/reporting/getUserTaskCompletion.ts:4-186 (schema)

  The complete tool schema definition, including input parameters, descriptions, enums, and annotations for the MCP tool.

  export const getProjectsReportingUserTaskCompletionDefinition = {
    name: "getProjectsReportingUserTaskCompletion",
    description: "Returns task completions for a given user. Retrieve a person record and its task completion stats.",
    inputSchema: {
      type: 'object',
      properties: {
        userId: {
          type: 'integer',
          description: 'Path parameter: userId'
        },
        userType: {
          type: 'string',
          description: 'user type',
          enum: ['account', 'collaborator', 'contact']
        },
        updatedAfter: {
          type: 'string',
          description: 'date time'
        },
        startDate: {
          type: 'string',
          description: 'start date for task completion report'
        },
        endDate: {
          type: 'string',
          description: 'end date for task completion report'
        },
        searchTerm: {
          type: 'string',
          description: 'filter by comment content'
        },
        reportFormat: {
          type: 'string',
          description: 'define the format of the report'
        },
        orderMode: {
          type: 'string',
          description: 'order mode',
          enum: ['asc', 'desc']
        },
        orderBy: {
          type: 'string',
          description: 'order by',
          enum: ['id', 'name', 'namecaseinsensitive', 'overduetasks', 'assignedtasks', 'completedtasks', 'projects', 'activeprojects']
        },
        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.'
        },
        isReportDownload: {
          type: 'boolean',
          description: 'generate a report document'
        },
        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'
        },
        includeArchivedProjects: {
          type: 'boolean',
          description: 'include archived projects in the report'
        },
        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',
          description: 'team ids'
        },
        selectedColumns: {
          type: 'array',
          description: 'customise the report by selecting columns'
        },
        projectIds: {
          type: 'array',
          description: 'filter by project ids'
        },
        jobRoleIds: {
          type: 'array',
          description: 'filter by job role ids'
        },
        include: {
          type: 'array',
          description: 'include (not used when generating reports)'
        },
        ids: {
          type: 'array',
          description: 'filter by user ids'
        },
        fieldsTeams: {
          type: 'array',
          description: 'Query parameter: fields[teams]'
        },
        fieldsPerson: {
          type: 'array',
          description: 'Query parameter: fields[person]'
        },
        fieldsPeople: {
          type: 'array',
          description: 'Query parameter: fields[people]'
        },
        fieldsCompanies: {
          type: 'array',
          description: 'Query parameter: fields[companies]'
        },
        fieldsProjectPermissions: {
          type: 'array',
          description: 'Query parameter: fields[ProjectPermissions]'
        },
        excludeProjectIds: {
          type: 'array',
          description: 'exclude people assigned to certain project id'
        },
        excludeIds: {
          type: 'array',
          description: 'exclude certain user ids'
        },
        companyIds: {
          type: 'array',
          description: 'company ids'
        }
      },
      required: ['userId']
    },
    annotations: {
      title: "Get the Tasks Completed by a User",
      readOnlyHint: false,
      destructiveHint: false,
      openWorldHint: false
    }
  };

• src/tools/index.ts:99-99 (registration)

  Registration of the tool in the central toolPairs array used to create toolDefinitions and toolHandlersMap.

  { definition: getProjectsReportingUserTaskCompletion, handler: handleGetProjectsReportingUserTaskCompletion },

• src/tools/index.ts:48-48 (registration)

  Import of the tool definition and handler from the specific reporting module.

  import { getProjectsReportingUserTaskCompletionDefinition as getProjectsReportingUserTaskCompletion, handleGetProjectsReportingUserTaskCompletion } from './reporting/getUserTaskCompletion.js';

• src/utils/config.ts:253-253 (helper)

  Tool grouping configuration used for allow/deny filtering of tools.

  'Reporting': ['getProjectsReportingUserTaskCompletion', 'getProjectsReportingUtilization'],