Things MCP Server

Instructions

Implementation Reference

• src/tools/add-project.ts:54-90 (handler)

  Async handler that maps input params to Things.app URL parameters, builds the 'add-project' URL, opens it via openThingsUrl, logs activity, and returns success content.
  async (params) => { try { logger.info('Adding new project', { 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.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.initialTodos) urlParams['to-dos'] = params.initialTodos.join('\n'); 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-project', urlParams); logger.debug('Generated URL', { url }); await openThingsUrl(url); return { content: [{ type: "text", text: `Successfully created project: ${params.title}` }] }; } catch (error) { logger.error('Failed to add project', { error: error instanceof Error ? error.message : error }); throw error; } }
• src/tools/add-project.ts:6-47 (schema)

  Zod schema defining all input parameters and validations for the add_project tool, including descriptions for MCP tool discovery.
  const addProjectSchema = z.object({ title: z.string().min(1).describe('Project title (required). Clear name describing the project goal, outcome, or deliverable'), notes: z.string().max(10000).optional().describe('Project description, objectives, scope, or additional context (max 10,000 characters). Supports markdown formatting for rich text documentation'), when: z.enum(['today', 'tomorrow', 'evening', 'anytime', 'someday']) .or(z.string().regex(/^\d{4}-\d{2}-\d{2}$/)) .optional() .describe('Schedule 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('Set a deadline for project completion in ISO date format (YYYY-MM-DD). Creates deadline tracking and reminders in Things.app'), tags: z.array(z.string().min(1)) .max(20) .optional() .describe('Array of tag names for categorizing and organizing the project (max 20 tags). Tags help with filtering and project management'), areaId: z.string() .optional() .describe('ID of the area of responsibility to assign this project to. Use this when you know the specific area ID'), areaName: z.string() .optional() .describe('Name of the area of responsibility to assign this project to (e.g., "Work", "Personal", "Health", "Finance"). Areas help organize projects by life domain'), initialTodos: z.array(z.string().min(1)) .max(50) .optional() .describe('Array of initial to-do item descriptions to create within the project (max 50 items). Each string becomes a separate task within the project'), completed: z.boolean() .optional() .default(false) .describe('Mark the project as completed immediately upon creation (default: false). Useful for logging already completed projects'), canceled: z.boolean() .optional() .default(false) .describe('Mark the project as canceled immediately upon creation (default: false). Useful for recording projects that are no longer viable'), 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 project 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-project.ts:49-92 (registration)

  Registration function that calls server.tool() to register the 'add_project' tool with its name, description, schema shape, and handler on the MCP server.
  export function registerAddProjectTool(server: McpServer): void { server.tool( 'add_project', 'Create a new project in Things.app. Add notes, tags, assign to areas, and pre-populate with initial to-dos.', addProjectSchema.shape, async (params) => { try { logger.info('Adding new project', { 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.areaId) urlParams['area-id'] = params.areaId; if (params.areaName) urlParams.area = params.areaName; if (params.initialTodos) urlParams['to-dos'] = params.initialTodos.join('\n'); 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-project', urlParams); logger.debug('Generated URL', { url }); await openThingsUrl(url); return { content: [{ type: "text", text: `Successfully created project: ${params.title}` }] }; } catch (error) { logger.error('Failed to add project', { error: error instanceof Error ? error.message : error }); throw error; } } ); }
• src/index.ts:22-22 (registration)

  Invocation of the registerAddProjectTool function during server initialization in the main entry point.
  registerAddProjectTool(server);
• src/types/things.ts:30-40 (schema)

  TypeScript interface defining the AddProjectParams type used in Things integration types, matching the tool schema.
  export interface AddProjectParams { title: string; notes?: string; when?: WhenValue; deadline?: string; tags?: string; area?: string; 'to-dos'?: string; completed?: boolean; canceled?: boolean; }