Things MCP Server

Instructions

Implementation Reference

• src/tools/add-todo.ts:66-106 (handler)

  The asynchronous handler function that maps input parameters to Things.app URL scheme parameters, constructs the URL, opens it to create the todo, handles errors, and returns a success response.
  async (params) => { try { logger.info('Adding new to-do', { title: params.title }); const urlParams: Record<string, any> = { title: params.title }; // Map schema parameters to Things URL scheme parameters if (params.notes) urlParams.notes = params.notes; if (params.when) urlParams.when = params.when; if (params.deadline) urlParams.deadline = params.deadline; if (params.tags) urlParams.tags = params.tags.join(','); if (params.checklistItems) urlParams['checklist-items'] = params.checklistItems.join(','); if (params.projectId) urlParams['list-id'] = params.projectId; if (params.projectName) urlParams.list = params.projectName; if (params.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.headingId) urlParams['heading-id'] = params.headingId; if (params.headingName) urlParams.heading = params.headingName; if (params.completed) urlParams.completed = params.completed; if (params.canceled) urlParams.canceled = params.canceled; if (params.creationDate) urlParams['creation-date'] = params.creationDate; if (params.completionDate) urlParams['completion-date'] = params.completionDate; const url = buildThingsUrl('add', urlParams); logger.debug('Generated URL', { url }); await openThingsUrl(url); return { content: [{ type: "text", text: `Successfully created to-do: ${params.title}` }] }; } catch (error) { logger.error('Failed to add to-do', { error: error instanceof Error ? error.message : error }); throw error; } }
• src/tools/add-todo.ts:6-59 (schema)

  Zod schema defining the structure, validation rules, and descriptions for all input parameters of the 'add_todo' tool.
  const addTodoSchema = z.object({ title: z.string().min(1).describe('To-do title (required). Clear, actionable description of the task'), notes: z.string().max(10000).optional().describe('Additional notes or details for the to-do (max 10,000 characters). Supports markdown formatting for rich text'), when: z.enum(['today', 'tomorrow', 'evening', 'anytime', 'someday']) .or(z.string().regex(/^\d{4}-\d{2}-\d{2}$/)) .optional() .describe('Schedule the to-do for a specific time. Use "today" for immediate action, "tomorrow" for next day, "evening" for later today, "anytime" for no specific time, "someday" for future consideration, or ISO date format (YYYY-MM-DD) for specific date'), deadline: z.string() .regex(/^\d{4}-\d{2}-\d{2}$/) .optional() .describe('Set a deadline for the to-do in ISO date format (YYYY-MM-DD). Creates a deadline reminder in Things.app'), tags: z.array(z.string().min(1)) .max(20) .optional() .describe('Array of tag names for organizing and categorizing the to-do (max 20 tags). Tags help with filtering and organization'), checklistItems: z.array(z.string().min(1)) .max(100) .optional() .describe('Array of checklist item descriptions to add as sub-tasks (max 100 items). Each item becomes a checkable sub-task within the to-do'), projectId: z.string() .optional() .describe('ID of the project to add this to-do to. Use this when you know the specific project ID'), projectName: z.string() .optional() .describe('Name of the project to add this to-do to. Things.app will find the project by name and add the to-do there'), areaId: z.string() .optional() .describe('ID of the area of responsibility to assign this to-do to. Use this when you know the specific area ID'), areaName: z.string() .optional() .describe('Name of the area of responsibility to assign this to-do to (e.g., "Work", "Personal", "Health")'), headingId: z.string() .optional() .describe('ID of a specific heading within the target project to organize the to-do under'), headingName: z.string() .optional() .describe('Name of a heading within the target project to organize the to-do under (e.g., "Phase 1", "Research")'), completed: z.boolean() .optional() .default(false) .describe('Mark the to-do as completed immediately upon creation (default: false). Useful for logging already completed tasks'), canceled: z.boolean() .optional() .default(false) .describe('Mark the to-do as canceled immediately upon creation (default: false). Useful for recording tasks that are no longer needed'), creationDate: z.string() .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/) .optional() .describe('Override the creation date with a specific ISO8601 datetime (YYYY-MM-DDTHH:MM:SS). Useful for importing historical data'), completionDate: z.string() .regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/) .optional() .describe('Set a specific completion date using ISO8601 datetime (YYYY-MM-DDTHH:MM:SS). Only used when completed is true') });
• src/tools/add-todo.ts:61-108 (registration)

  Registration function that calls server.tool() to register the 'add_todo' tool with the MCP server, providing the tool name, description, input schema, and handler function.
  export function registerAddTodoTool(server: McpServer): void { server.tool( 'add_todo', 'Create a new to-do item in Things.app. Add notes, tags, checklist items, and assign to projects or areas.', addTodoSchema.shape, async (params) => { try { logger.info('Adding new to-do', { title: params.title }); const urlParams: Record<string, any> = { title: params.title }; // Map schema parameters to Things URL scheme parameters if (params.notes) urlParams.notes = params.notes; if (params.when) urlParams.when = params.when; if (params.deadline) urlParams.deadline = params.deadline; if (params.tags) urlParams.tags = params.tags.join(','); if (params.checklistItems) urlParams['checklist-items'] = params.checklistItems.join(','); if (params.projectId) urlParams['list-id'] = params.projectId; if (params.projectName) urlParams.list = params.projectName; if (params.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.headingId) urlParams['heading-id'] = params.headingId; if (params.headingName) urlParams.heading = params.headingName; if (params.completed) urlParams.completed = params.completed; if (params.canceled) urlParams.canceled = params.canceled; if (params.creationDate) urlParams['creation-date'] = params.creationDate; if (params.completionDate) urlParams['completion-date'] = params.completionDate; const url = buildThingsUrl('add', urlParams); logger.debug('Generated URL', { url }); await openThingsUrl(url); return { content: [{ type: "text", text: `Successfully created to-do: ${params.title}` }] }; } catch (error) { logger.error('Failed to add to-do', { error: error instanceof Error ? error.message : error }); throw error; } } ); }
• src/index.ts:21-21 (registration)

  Main application entry point where registerAddTodoTool is invoked to register the tool with the MCP server instance.
  registerAddTodoTool(server);
• src/types/things.ts:17-28 (schema)

  TypeScript interface defining parameters for adding a todo item, matching the Things.app URL scheme keys used in URL construction.
  export interface AddTodoParams { title: string; notes?: string; when?: WhenValue; deadline?: string; tags?: string; 'checklist-items'?: string; list?: string; heading?: string; completed?: boolean; canceled?: boolean; }