Things MCP Server

Instructions

Implementation Reference

• src/tools/update-project.ts:57-122 (handler)

  The asynchronous handler function that executes the update_project tool. It handles updates via Things.app URL schemes for most fields and JSON operations for completion/cancellation status changes. Logs actions, requires authentication, builds URLs, and returns success message.
  async (params) => { try { logger.info('Updating project', { id: params.id }); const authToken = requireAuthToken(); // Check if we're doing a completion/cancellation operation (use JSON) if (params.completed !== undefined || params.canceled !== undefined) { const attributes: Record<string, any> = {}; if (params.completed !== undefined) { attributes.completed = params.completed; if (params.completionDate) { attributes['completion-date'] = params.completionDate; } } if (params.canceled !== undefined) { attributes.canceled = params.canceled; } const operation: JsonOperation = { type: 'project', operation: 'update', id: params.id, attributes }; await executeJsonOperation(operation, authToken); } else { // Use URL scheme for other updates const urlParams: Record<string, any> = { id: params.id, 'auth-token': authToken }; // Map schema parameters to Things URL scheme parameters if (params.title) urlParams.title = params.title; if (params.notes) urlParams.notes = params.notes; if (params.prependNotes) urlParams['prepend-notes'] = params.prependNotes; if (params.appendNotes) urlParams['append-notes'] = params.appendNotes; if (params.when) urlParams.when = params.when; if (params.deadline) urlParams.deadline = params.deadline; if (params.tags) urlParams.tags = params.tags.join(','); if (params.addTags) urlParams['add-tags'] = params.addTags.join(','); if (params.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.creationDate) urlParams['creation-date'] = params.creationDate; const url = buildThingsUrl('update-project', urlParams); logger.debug('Generated URL', { url: url.replace(authToken, '***') }); await openThingsUrl(url); } return { content: [{ type: "text", text: `Successfully updated project: ${params.id}` }] }; } catch (error) { logger.error('Failed to update project', { error: error instanceof Error ? error.message : error }); throw error; } }
• src/tools/update-project.ts:8-50 (schema)

  Zod schema defining and validating all input parameters for the update_project tool, including descriptions for MCP tool schema.
  const updateProjectSchema = z.object({ id: z.string().min(1).describe('The unique ID of the project to update. This ID can be obtained from the list_projects tool'), title: z.string().min(1).optional().describe('Update the project title with a new clear name describing the project goal, outcome, or deliverable'), notes: z.string().max(10000).optional().describe('Replace existing notes with new project description, objectives, or context (max 10,000 characters). Supports markdown formatting. This completely replaces existing notes'), prependNotes: z.string().optional().describe('Add text to the beginning of existing notes without replacing them. Useful for adding project updates or new objectives'), appendNotes: z.string().optional().describe('Add text to the end of existing notes without replacing them. Useful for adding progress updates or new requirements'), when: z.enum(['today', 'tomorrow', 'evening', 'anytime', 'someday']) .or(z.string().regex(/^\d{4}-\d{2}-\d{2}$/)) .optional() .describe('Reschedule when to start working on this project. Use "today" to start immediately, "tomorrow" to start next day, "evening" to start later today, "anytime" for flexible timing, "someday" for future consideration, or ISO date format (YYYY-MM-DD) for specific start date'), deadline: z.string() .regex(/^\d{4}-\d{2}-\d{2}$/) .optional() .describe('Update the project deadline in ISO date format (YYYY-MM-DD). Creates or updates deadline tracking and reminders in Things.app'), tags: z.array(z.string().min(1)) .max(20) .optional() .describe('Replace all current tags with this new set of tag names (max 20 tags). This completely replaces existing tags for the project'), addTags: z.array(z.string().min(1)) .max(20) .optional() .describe('Add these tag names to existing tags without removing current ones (max 20 total tags). Preserves existing project tags'), areaId: z.string() .optional() .describe('Move the project to a different area of responsibility by specifying the area ID'), areaName: z.string() .optional() .describe('Move the project to a different area of responsibility by specifying the area name (e.g., "Work", "Personal", "Health", "Finance")'), completed: z.boolean() .optional() .describe('Mark the project as completed (true) or reopen it (false). Completed projects are moved to the Logbook along with all their to-dos'), canceled: z.boolean() .optional() .describe('Mark the project as canceled (true) or restore it (false). Canceled projects are moved to the Trash along with all their to-dos'), 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 data migration or historical project tracking'), 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 marking the project as completed') });
• src/tools/update-project.ts:52-124 (registration)

  The registration function that registers the 'update_project' tool on the MCP server, providing name, description, schema, and handler.
  export function registerUpdateProjectTool(server: McpServer): void { server.tool( 'update_project', 'Update an existing project in Things.app. Modify title, notes, scheduling, tags, area assignment, and completion status.', updateProjectSchema.shape, async (params) => { try { logger.info('Updating project', { id: params.id }); const authToken = requireAuthToken(); // Check if we're doing a completion/cancellation operation (use JSON) if (params.completed !== undefined || params.canceled !== undefined) { const attributes: Record<string, any> = {}; if (params.completed !== undefined) { attributes.completed = params.completed; if (params.completionDate) { attributes['completion-date'] = params.completionDate; } } if (params.canceled !== undefined) { attributes.canceled = params.canceled; } const operation: JsonOperation = { type: 'project', operation: 'update', id: params.id, attributes }; await executeJsonOperation(operation, authToken); } else { // Use URL scheme for other updates const urlParams: Record<string, any> = { id: params.id, 'auth-token': authToken }; // Map schema parameters to Things URL scheme parameters if (params.title) urlParams.title = params.title; if (params.notes) urlParams.notes = params.notes; if (params.prependNotes) urlParams['prepend-notes'] = params.prependNotes; if (params.appendNotes) urlParams['append-notes'] = params.appendNotes; if (params.when) urlParams.when = params.when; if (params.deadline) urlParams.deadline = params.deadline; if (params.tags) urlParams.tags = params.tags.join(','); if (params.addTags) urlParams['add-tags'] = params.addTags.join(','); if (params.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.creationDate) urlParams['creation-date'] = params.creationDate; const url = buildThingsUrl('update-project', urlParams); logger.debug('Generated URL', { url: url.replace(authToken, '***') }); await openThingsUrl(url); } return { content: [{ type: "text", text: `Successfully updated project: ${params.id}` }] }; } catch (error) { logger.error('Failed to update project', { error: error instanceof Error ? error.message : error }); throw error; } } ); }
• src/index.ts:24-24 (registration)

  Top-level call to register the update_project tool during server initialization.
  registerUpdateProjectTool(server);
• src/types/things.ts:61-75 (schema)

  TypeScript type definition for UpdateProjectParams, mirroring the tool parameters for type safety in URL building and other utilities.
  export interface UpdateProjectParams { id: string; 'auth-token': string; title?: string; notes?: string; when?: WhenValue; deadline?: string; tags?: string; area?: string; completed?: boolean; canceled?: boolean; 'prepend-notes'?: string; 'append-notes'?: string; 'add-tags'?: string; }