Things MCP Server

Instructions

Implementation Reference

• src/index.js:487-499 (handler)

  The handler function that implements the core logic of the 'add_project' tool. It builds a Things URL scheme using the provided arguments and opens it to trigger project creation in the Things app.

  async handleAddProject(args) {
    const url = buildThingsUrl('add-project', args);
    await this.openThingsUrl(url);
  
    return {
      content: [
        {
          type: 'text',
          text: `✅ 项目创建命令已发送${args.title ? `: ${args.title}` : ''}`,
        },
      ],
    };
  }

• src/index.js:120-169 (schema)

  Input schema defining the parameters accepted by the 'add_project' tool, including title, notes, scheduling, tags, area, subtasks, and flags.

  inputSchema: {
    type: 'object',
    properties: {
      title: {
        type: 'string',
        description: '项目标题',
      },
      notes: {
        type: 'string',
        description: '备注内容',
      },
      when: {
        type: 'string',
        description: '时间安排: today, tomorrow, evening, anytime, someday, 日期或日期时间',
      },
      deadline: {
        type: 'string',
        description: '截止日期(yyyy-mm-dd)',
      },
      tags: {
        type: 'string',
        description: '标签，逗号分隔',
      },
      areaId: {
        type: 'string',
        description: '区域ID',
      },
      area: {
        type: 'string',
        description: '区域标题',
      },
      todos: {
        type: 'array',
        items: { type: 'string' },
        description: '子待办事项列表',
      },
      completed: {
        type: 'boolean',
        description: '是否标记为完成',
      },
      canceled: {
        type: 'boolean',
        description: '是否标记为取消',
      },
      reveal: {
        type: 'boolean',
        description: '是否导航进入项目',
      },
    },
  },

• src/index.js:117-170 (registration)

  Registers the 'add_project' tool in the ListToolsRequestSchema handler, providing name, description, and input schema.

  {
    name: 'add_project',
    description: '创建新的项目。支持标题、备注、区域、标签、子任务等。',
    inputSchema: {
      type: 'object',
      properties: {
        title: {
          type: 'string',
          description: '项目标题',
        },
        notes: {
          type: 'string',
          description: '备注内容',
        },
        when: {
          type: 'string',
          description: '时间安排: today, tomorrow, evening, anytime, someday, 日期或日期时间',
        },
        deadline: {
          type: 'string',
          description: '截止日期(yyyy-mm-dd)',
        },
        tags: {
          type: 'string',
          description: '标签，逗号分隔',
        },
        areaId: {
          type: 'string',
          description: '区域ID',
        },
        area: {
          type: 'string',
          description: '区域标题',
        },
        todos: {
          type: 'array',
          items: { type: 'string' },
          description: '子待办事项列表',
        },
        completed: {
          type: 'boolean',
          description: '是否标记为完成',
        },
        canceled: {
          type: 'boolean',
          description: '是否标记为取消',
        },
        reveal: {
          type: 'boolean',
          description: '是否导航进入项目',
        },
      },
    },
  },

• src/index.js:429-430 (registration)

  Dispatches 'add_project' tool calls to the handleAddProject method in the CallToolRequestSchema handler.

  case 'add_project':
    return await this.handleAddProject(args);

• src/utils.js:84-93 (helper)

  Helper function used by the handler to construct the Things URL scheme for the 'add-project' command, including parameter mapping and encoding.

  export function buildThingsUrl(command, params = {}) {
    const baseUrl = `things:///${command}`;
    const queryString = buildQueryString(params);
  
    if (!queryString) {
      return baseUrl;
    }
  
    return `${baseUrl}?${queryString}`;
  }