Things MCP Server

Instructions

Implementation Reference

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

  Handler function that logs the action, maps input parameters to Things.app URL parameters, builds the URL using buildThingsUrl, opens the URL to create the project, and returns a success message.

  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 the structure and validation rules for the input parameters of the add_project tool.

  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, 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 main server initialization to enable the tool.

  registerAddProjectTool(server);

• src/types/things.ts:30-40 (schema)

  TypeScript interface defining the parameters for add-project in Things.app URL scheme.

  export interface AddProjectParams {
    title: string;
    notes?: string;
    when?: WhenValue;
    deadline?: string;
    tags?: string;
    area?: string;
    'to-dos'?: string;
    completed?: boolean;
    canceled?: boolean;
  }