MoCo MCP Server

Instructions

Implementation Reference

• src/tools/activitiesTools.ts:31-67 (handler)

  The main handler for the get_activities tool. Validates input dates, fetches activities from Moco API, aggregates them by date/project/task, formats the summary, and returns a formatted string response.
  export const getActivitiesTool = { name: 'get_activities', description: 'Get all activities within a date range with automatic summation by date, project, and task. Optionally filter by project ID.', inputSchema: zodToJsonSchema(GetActivitiesSchema), handler: async (params: z.infer<typeof GetActivitiesSchema>): Promise<string> => { const { startDate, endDate, projectId } = params; // Validate date format and range if (!validateDateRange(startDate, endDate)) { return createValidationErrorMessage({ field: 'dateRange', value: `${startDate} to ${endDate}`, reason: 'invalid_date_range' }); } try { const apiService = new MocoApiService(); const activities = await apiService.getActivities(startDate, endDate, projectId); if (activities.length === 0) { return createEmptyResultMessage({ type: 'activities', startDate, endDate, projectId }); } const summary = aggregateActivities(activities, startDate, endDate); return formatActivitiesSummary(summary, projectId); } catch (error) { return `Error retrieving activities: ${error instanceof Error ? error.message : 'Unknown error'}`; } } };
• src/tools/activitiesTools.ts:21-25 (schema)

  Zod schema defining the input parameters for the get_activities tool: required startDate and endDate strings, optional positive projectId number.
  const GetActivitiesSchema = z.object({ startDate: z.string().describe('Start date in ISO 8601 format (YYYY-MM-DD)'), endDate: z.string().describe('End date in ISO 8601 format (YYYY-MM-DD)'), projectId: z.number().positive().optional().describe('Optional project ID to filter activities for a specific project') });
• src/index.ts:34-42 (registration)

  The getActivitiesTool is imported and included in the AVAILABLE_TOOLS array, which is used by the MCP server to list and dispatch tool calls.
  const AVAILABLE_TOOLS = [ getActivitiesTool, getUserProjectsTool, getUserProjectTasksTool, getUserHolidaysTool, getUserPresencesTool, getUserSickDaysTool, getPublicHolidaysTool ];
• src/services/mocoApi.ts:143-154 (helper)

  MocoApiService method that fetches activities from the MoCo API endpoint '/activities' with date range and optional project filter, handling pagination automatically.
  async getActivities(startDate: string, endDate: string, projectId?: number): Promise<Activity[]> { const params: Record<string, string | number> = { from: startDate, to: endDate }; if (projectId) { params.project_id = projectId; } return this.fetchAllPages<Activity>('/activities', params); }
• src/tools/activitiesTools.ts:73-147 (helper)

  Helper function that aggregates raw activities into structured summaries: daily breakdowns, project totals across days, task breakdowns, and grand total.
  function aggregateActivities(activities: Activity[], startDate: string, endDate: string): ActivityRangeSummary { // Group activities by date const activitiesByDate = new Map<string, Activity[]>(); activities.forEach(activity => { if (!activitiesByDate.has(activity.date)) { activitiesByDate.set(activity.date, []); } activitiesByDate.get(activity.date)!.push(activity); }); // Create daily summaries const dailySummaries: DailyActivitySummary[] = []; const projectTotalsMap = new Map<number, { projectName: string; totalHours: number; tasks: Map<number, { taskName: string; totalHours: number }>; }>(); // Sort dates for consistent output const sortedDates = Array.from(activitiesByDate.keys()).sort(); sortedDates.forEach(date => { const dayActivities = activitiesByDate.get(date)!; const dailySummary = createDailySummary(date, dayActivities); dailySummaries.push(dailySummary); // Accumulate project totals across all days dailySummary.projects.forEach(project => { if (!projectTotalsMap.has(project.projectId)) { projectTotalsMap.set(project.projectId, { projectName: project.projectName, totalHours: 0, tasks: new Map() }); } const projectTotal = projectTotalsMap.get(project.projectId)!; projectTotal.totalHours += project.projectTotal.hours; project.tasks.forEach(task => { if (!projectTotal.tasks.has(task.taskId)) { projectTotal.tasks.set(task.taskId, { taskName: task.taskName, totalHours: 0 }); } projectTotal.tasks.get(task.taskId)!.totalHours += task.hours; }); }); }); // Convert project totals map to array format const projectTotals = Array.from(projectTotalsMap.entries()).map(([projectId, data]) => ({ projectId, projectName: data.projectName, total: createTimeFormat(data.totalHours), tasks: Array.from(data.tasks.entries()).map(([taskId, taskData]) => ({ taskId, taskName: taskData.taskName, total: createTimeFormat(taskData.totalHours) })) })); // Calculate grand total const grandTotalHours = sumHours(dailySummaries.map(day => day.dailyTotal.hours)); return { startDate, endDate, dailySummaries, projectTotals, grandTotal: createTimeFormat(grandTotalHours) }; }