update_project

Instructions

Implementation Reference

• src/tools/update-project.ts:52-124 (handler)

  The main handler function 'registerUpdateProjectTool' that registers and implements the 'update_project' tool. It handles both URL-scheme updates (title, notes, scheduling, tags, area) and JSON-based operations (completion, cancellation) via Things.app.

  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/tools/update-project.ts:8-50 (schema)

  Zod schema definition for the 'update_project' tool inputs, defining all parameters: id, title, notes, prependNotes, appendNotes, when, deadline, tags, addTags, areaId, areaName, completed, canceled, creationDate, completionDate.

  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/index.ts:11-26 (registration)

  Import and registration of the update_project tool in the main server entry point. The tool is registered via registerUpdateProjectTool(server) on line 24.

  import { registerUpdateProjectTool } from './tools/update-project.js';
  import { registerThingsSummaryTool } from './tools/things-summary.js';
  import { registerExportJsonTool } from './tools/export-json.js';
  
  const server = new McpServer({
    name: 'things-mcp',
    version: '1.0.0'
  });
  
  // Register all tools
  registerAddTodoTool(server);
  registerAddProjectTool(server);
  registerUpdateTodoTool(server);
  registerUpdateProjectTool(server);
  registerThingsSummaryTool(server);
  registerExportJsonTool(server);

• src/types/things.ts:61-75 (helper)

  TypeScript interface 'UpdateProjectParams' defining the URL-scheme parameters for updating a project (id, auth-token, title, notes, when, deadline, tags, area, completed, canceled, prepend-notes, append-notes, add-tags).

  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;
  }

• src/utils/url-builder.ts:8-31 (helper)

  The 'buildThingsUrl' helper that constructs the things:///update-project URL from the command name and parameters, with proper encoding. Also the 'openThingsUrl' helper that opens the URL on macOS.

  export function buildThingsUrl(command: ThingsCommand, params: Record<string, any>): string {
    const baseUrl = `things:///${command}`;
    const queryParts: string[] = [];
    
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined && value !== null && value !== '') {
        let encodedValue: string;
        
        if (key === 'data' && command === 'json') {
          // JSON data needs to be stringified and encoded
          encodedValue = encodeURIComponent(JSON.stringify(value));
        } else {
          // Encode all values using proper percent encoding
          const stringValue = Array.isArray(value) ? value.join(',') : String(value);
          encodedValue = encodeURIComponent(stringValue);
        }
        
        queryParts.push(`${encodeURIComponent(key)}=${encodedValue}`);
      }
    }
    
    const queryString = queryParts.join('&');
    return queryString ? `${baseUrl}?${queryString}` : baseUrl;
  }