Motion MCP Server

Instructions

Implementation Reference

• src/handlers/ScheduleHandler.ts:1-19 (handler)

  The ScheduleHandler class implements the tool logic. The handle method receives MotionSchedulesArgs (unused since only 'list' operation is supported) and calls handleList() which retrieves schedules from the Motion API service and formats them using formatScheduleList.
  import { BaseHandler } from './base/BaseHandler'; import { McpToolResponse } from '../types/mcp'; import { MotionSchedulesArgs } from '../types/mcp-tool-args'; import { formatScheduleList } from '../utils'; export class ScheduleHandler extends BaseHandler { async handle(_args: MotionSchedulesArgs): Promise<McpToolResponse> { try { return await this.handleList(); } catch (error: unknown) { return this.handleError(error); } } private async handleList(): Promise<McpToolResponse> { const schedules = await this.motionService.getSchedules(); return formatScheduleList(schedules); } }
• src/services/motionApi.ts:2354-2394 (handler)

  The getSchedules() method in MotionApiService fetches all schedules from the Motion API endpoint /schedules. It uses caching (scheduleCache), validates the response against SchedulesListResponseSchema, and handles both array and wrapped response formats.
  async getSchedules(): Promise<MotionSchedule[]> { const cacheKey = 'schedules:all'; return this.scheduleCache.withCache(cacheKey, async () => { try { mcpLog(LOG_LEVELS.DEBUG, 'Fetching schedules from Motion API', { method: 'getSchedules' }); const response: AxiosResponse<ListResponse<MotionSchedule>> = await this.requestWithRetry(() => this.client.get('/schedules')); // Validate response against schema const validatedResponse = this.validateResponse( response.data, SchedulesListResponseSchema, 'getSchedules' ); // Handle both wrapped and unwrapped responses const schedules = Array.isArray(validatedResponse) ? validatedResponse : validatedResponse.schedules || []; const schedulesArray = Array.isArray(schedules) ? schedules : []; mcpLog(LOG_LEVELS.INFO, 'Schedules fetched successfully', { method: 'getSchedules', count: schedulesArray.length }); return schedulesArray; } catch (error: unknown) { mcpLog(LOG_LEVELS.ERROR, 'Failed to fetch schedules', { method: 'getSchedules', error: getErrorMessage(error), apiStatus: isAxiosError(error) ? error.response?.status : undefined, apiMessage: isAxiosError(error) ? error.response?.data?.message : undefined }); throw this.formatApiError(error, 'fetch', 'schedule'); } }); }
• src/handlers/HandlerFactory.ts:27-38 (registration)

  The HandlerFactory.registerHandlers() method maps TOOL_NAMES.SCHEDULES (which is 'motion_schedules') to the ScheduleHandler class, enabling tool instantiation when requested.
  private registerHandlers(): void { this.handlers.set(TOOL_NAMES.TASKS, TaskHandler); this.handlers.set(TOOL_NAMES.PROJECTS, ProjectHandler); this.handlers.set(TOOL_NAMES.WORKSPACES, WorkspaceHandler); this.handlers.set(TOOL_NAMES.USERS, UserHandler); this.handlers.set(TOOL_NAMES.SEARCH, SearchHandler); this.handlers.set(TOOL_NAMES.COMMENTS, CommentHandler); this.handlers.set(TOOL_NAMES.CUSTOM_FIELDS, CustomFieldHandler); this.handlers.set(TOOL_NAMES.RECURRING_TASKS, RecurringTaskHandler); this.handlers.set(TOOL_NAMES.SCHEDULES, ScheduleHandler); this.handlers.set(TOOL_NAMES.STATUSES, StatusHandler); }
• src/tools/ToolDefinitions.ts:473-487 (schema)

  The schedulesToolDefinition defines the MCP tool interface with name 'motion_schedules', description, and input schema that accepts an 'operation' parameter (enum: ['list']).
  export const schedulesToolDefinition: McpToolDefinition = { name: TOOL_NAMES.SCHEDULES, description: "Get all schedules showing weekly working hours and time zones. The Motion API returns all schedules with no filtering options.", inputSchema: { type: "object", properties: { operation: { type: "string", enum: ["list"], description: "Operation to perform" } }, additionalProperties: false } };
• src/utils/responseFormatters.ts:438-472 (helper)

  The formatScheduleList() helper function formats the array of MotionSchedule objects into a user-readable MCP response, displaying schedule name, timezone, and working days count.
  export function formatScheduleList(schedules: MotionSchedule[]): CallToolResult { // Add null safety check for the array itself if (!schedules || !Array.isArray(schedules) || schedules.length === 0) { return formatMcpSuccess("No schedules found."); } const scheduleFormatter = (schedule: MotionSchedule) => { // Defensive programming for nested schedule object if (!schedule) { return '- Invalid schedule entry'; } const name = schedule.name || 'Unnamed'; const timezone = schedule.timezone || 'Unknown timezone'; // Count working days if schedule details are available let workingDays = ''; if (schedule.schedule && typeof schedule.schedule === 'object') { const days = ['monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday', 'sunday']; const activeDays = days.filter(day => Array.isArray(schedule.schedule[day as keyof MotionScheduleDetails]) && schedule.schedule[day as keyof MotionScheduleDetails]!.length > 0 ); workingDays = activeDays.length > 0 ? ` | Working days: ${activeDays.length}/7` : ' | No working hours defined'; } else { workingDays = ' | Schedule details unavailable'; } return `- ${name} (${timezone})${workingDays}`; }; return formatListResponse(schedules, `Found ${schedules.length} schedule${schedules.length === 1 ? '' : 's'}`, scheduleFormatter); }