Things MCP Server

Instructions

Implementation Reference

• src/index.js:583-611 (handler)

  The main handler function for the 'json_import' tool. It processes the input arguments, checks for updates requiring auth, builds a Things URL scheme command using buildThingsUrl('json', params), opens it, and returns a success message.

  async handleJsonImport(args) {
    const authToken = args.authToken || DEFAULT_AUTH_TOKEN;
    const params = {
      data: JSON.stringify(args.data),
      reveal: args.reveal,
    };
  
    // 如果数据中包含更新操作，需要授权令牌
    const hasUpdate = args.data.some(item => item.operation === 'update');
    if (hasUpdate && !authToken) {
      throw new Error('JSON数据包含更新操作，需要授权令牌');
    }
  
    if (authToken) {
      params.authToken = authToken;
    }
  
    const url = buildThingsUrl('json', params);
    await this.openThingsUrl(url);
  
    return {
      content: [
        {
          type: 'text',
          text: `✅ JSON导入命令已发送 (${args.data.length}个项目)`,
        },
      ],
    };
  }

• src/index.js:363-380 (schema)

  Input schema definition for the json_import tool, specifying the expected JSON data array, optional authToken, and reveal flag.

  inputSchema: {
    type: 'object',
    properties: {
      data: {
        type: 'array',
        description: 'JSON数据数组，包含to-do和project对象',
      },
      authToken: {
        type: 'string',
        description: '授权令牌（如包含更新操作则必需）',
      },
      reveal: {
        type: 'boolean',
        description: '是否显示第一个创建的项',
      },
    },
    required: ['data'],
  },

• src/index.js:445-446 (registration)

  Dispatch case in the CallToolRequestSchema handler that routes calls to the json_import handler function.

  case 'json_import':
    return await this.handleJsonImport(args);

• src/index.js:360-381 (registration)

  Tool descriptor registration in the ListToolsRequestSchema response, defining name, description, and schema.

  {
    name: 'json_import',
    description: 'JSON批量导入待办事项和项目。支持复杂的嵌套结构。',
    inputSchema: {
      type: 'object',
      properties: {
        data: {
          type: 'array',
          description: 'JSON数据数组，包含to-do和project对象',
        },
        authToken: {
          type: 'string',
          description: '授权令牌（如包含更新操作则必需）',
        },
        reveal: {
          type: 'boolean',
          description: '是否显示第一个创建的项',
        },
      },
      required: ['data'],
    },
  },

• src/utils.js:167-177 (helper)

  Helper function specifically for building Things URLs for JSON imports, handling JSON serialization. Used indirectly via the general buildThingsUrl in the handler.

  export function buildJsonUrl(data, options = {}) {
    // JSON需要先序列化再编码
    const jsonString = JSON.stringify(data);
  
    const params = {
      data: jsonString,
      ...options,
    };
  
    return buildThingsUrl('json', params);
  }