Things MCP Server

# Things URL Scheme 接口文档 ## 概述 Things应用通过特殊URL链接来执行命令，格式如下： ``` things:///commandName?parameter1=value1&parameter2=value2&... ``` 打开这些链接会启动应用并执行对应的命令。 **例子：创建一个待办事项** ``` things:///add?title=Buy%20milk&notes=High%20fat ``` ## 核心特性 ### x-callback-url 支持 所有命令都支持 x-callback-url 约定： | 回调类型 | 说明 | |---------|------| | `x-success` | 命令执行成功时触发 | | `x-error` | 命令执行失败时触发 | | `x-cancel` | 命令被取消时触发 | 许多命令会向x-success回调返回参数。 ### 授权机制 需要修改Things数据的命令需要授权令牌来运行，这能防止恶意链接修改你的数据。 **获取授权令牌：** - **Mac**: Things → Settings → General → Enable Things URLs → Manage - **iOS**: Settings → General → Things URLs 需要在命令中传递参数：`auth-token` ### 获取IDs 某些命令需要提供待办事项或列表的ID。 **获取待办事项ID：** - **Mac**: 右键点击待办事项 → Share → Copy Link - **iOS**: 打开待办事项，工具栏 → Share → Copy Link **获取列表ID：** - **Mac**: 右键点击侧边栏的列表 → Share → Copy Link - **iOS**: 进入列表，右上角 → Share → Copy Link ## 数据类型 | 类型 | 说明 | 示例 | |-----|------|------| | **string** | 百分号编码，最大长度4000字符（除特殊说明外） | `Buy%20milk` | | **date string** | today、tomorrow或yyyy-mm-dd格式，支持自然语言（英文） | `today`, `2017-09-29`, `next tuesday` | | **time string** | 本地时区的时间格式 | `9:30PM`, `21:30` | | **date time string** | 日期@时间格式 | `2018-02-25@14:00` | | **ISO8601 date time string** | ISO8601标准格式 | `2018-03-10T14:30:00Z` | | **boolean** | 真/假值 | `true`, `false` | | **JSON string** | JSON格式字符串 | `[{"key":"value"}]` | ## 启用URL Scheme 首次执行URL命令时，Things会询问是否启用此功能，点击"Enable"即可。 可以后续在设置中修改： - **Mac**: Things → Settings → General - **iOS**: Settings → General → Things URLs **版本：** 当前URL Scheme版本为 2 --- ## 命令列表 ### 1. add - 添加待办事项 创建新的待办事项。 #### 基础示例 创建简单待办事项到收件箱： ``` things:///add?title=Book%20flights ``` 添加待办事项并设置标签和备注： ``` things:///add? title=Buy%20milk& notes=Low%20fat.& when=evening& tags=Errand ``` 批量创建待办事项到某个项目： ``` things:///add? titles=Milk%0aBeer%0aCheese& list=Shopping ``` 添加待办事项到指定区域（使用ID）： ``` things:///add? title=Call%20doctor& when=next%20monday& list-id=3052219D-8039-43D0-8654-AE1E20BE4F56 ``` 添加待办事项并设置提醒时间： ``` things:///add? title=Collect%20dry%20cleaning& when=evening@6pm ``` **限制：** 每10秒内最多添加250个待办事项 #### 参数 所有参数可选。若既未指定 `when` 也未指定 `list-id`，待办事项将添加到收件箱。 | 参数 | 类型 | 说明 | |-----|------|------| | `title` | string | 待办事项的标题。如果指定了titles，此参数被忽略 | | `titles` | string | 新行分隔（%0a）的标题列表，用于批量创建。优先于title和show-quick-entry | | `notes` | string | 备注文本，最大长度10000字符 | | `when` | string | 时间安排：today、tomorrow、evening、anytime、someday、日期字符串或日期时间字符串。日期时间格式会添加提醒 | | `deadline` | date string | 截止日期 | | `tags` | string | 逗号分隔的标签标题。如果标签不存在，不会应用 | | `checklist-items` | string | 新行分隔（%0a）的清单项，最多100项 | | `use-clipboard` | string | 剪贴板模式：replace-title、replace-notes、replace-checklist-items。优先于对应的参数 | | `list-id` | string | 项目或区域的ID，优先于list | | `list` | string | 项目或区域的标题，被list-id忽略 | | `heading-id` | string | 项目内的标题ID，优先于heading。如果项目或标题不存在则忽略 | | `heading` | string | 项目内的标题名称，被heading-id忽略 | | `completed` | boolean | 是否标记为完成。默认：false。若canceled为true则忽略 | | `canceled` | boolean | 是否标记为已取消。默认：false。优先于completed | | `show-quick-entry` | boolean | 是否显示快速输入对话框。titles指定时被忽略。默认：false | | `reveal` | boolean | 是否导航并显示新建的待办事项。多个时显示首个。show-quick-entry为true时忽略。默认：false | | `creation-date` | ISO8601 date time string | 数据库中的创建日期。未来日期会被忽略 | | `completion-date` | ISO8601 date time string | 数据库中的完成日期。未完成/取消或未来日期会被忽略 | #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-id` | 逗号分隔的新建待办事项ID列表 | --- ### 2. add-project - 添加项目 创建新的项目。 #### 基础示例 创建项目并设置开始时间： ``` things:///add-project? title=Build%20treehouse& when=today ``` 在指定区域内创建项目： ``` things:///add-project? title=Plan%20Birthday%20Party& area=Family ``` 在指定区域创建项目并设置截止日期： ``` things:///add-project? title=Submit%20Tax& deadline=December%2031& area-id=F00A4075-0CA6-4A7F-88C6-CC8B4F1712FC ``` #### 参数 所有参数可选。 | 参数 | 类型 | 说明 | |-----|------|------| | `title` | string | 项目标题 | | `notes` | string | 备注文本，最大长度10000字符 | | `when` | string | 时间安排：today、tomorrow、evening、anytime、someday、日期字符串或日期时间字符串 | | `deadline` | date string | 截止日期 | | `tags` | string | 逗号分隔的标签标题 | | `area-id` | string | 区域ID，优先于area | | `area` | string | 区域标题，被area-id忽略 | | `to-dos` | string | 新行分隔（%0a）的待办事项标题，将创建到项目内 | | `completed` | boolean | 是否标记为完成。默认：false。若canceled为true则忽略。设为true会将所有子待办事项标记为完成 | | `canceled` | boolean | 是否标记为已取消。默认：false。优先于completed。设为true会将所有子待办事项标记为取消 | | `reveal` | boolean | 是否导航进入新建的项目。默认：false | | `creation-date` | ISO8601 date time string | 数据库中的创建日期。如果to-dos指定，此日期也适用于它们。未来日期会被忽略 | | `completion-date` | ISO8601 date time string | 数据库中的完成日期。如果to-dos指定，此日期也适用于它们。未完成/取消或未来日期会被忽略 | #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-id` | 新建项目的ID | --- ### 3. update - 更新待办事项 更新现有的待办事项。 #### 基础示例 设置待办事项开始时间： ``` things:///update? id=4BE64FEA-8FEF-4F4F-B8B2-4E74605D5FA5& when=today ``` 修改待办事项标题： ``` things:///update? id=4BE64FEA-8FEF-4F4F-B8B2-4E74605D5FA5& title=Buy%20bread ``` 追加备注： ``` things:///update? id=4BE64FEA-8FEF-4F4F-B8B2-4E74605D5FA5& append-notes=Wholemeal%20bread ``` 添加清单项： ``` things:///update? id=4BE64FEA-8FEF-4F4F-B8B2-4E74605D5FA5& append-checklist-items=Cheese%0aBread%0aEggplant ``` 清除截止日期（参数值为空）： ``` things:///update? id=4BE64FEA-8FEF-4F4F-B8B2-4E74605D5FA5& deadline= ``` #### 参数 `id` 和 `auth-token` 必须指定。其他参数可选。参数使用 `=` 但无值时表示清除该值。 | 参数 | 类型 | 说明 | |-----|------|------| | `auth-token` | string | **必需**。Things URL Scheme授权令牌 | | `id` | string | **必需**。待办事项的ID | | `title` | string | 新标题，替换现有标题 | | `notes` | string | 新备注，替换现有备注。最大长度10000字符 | | `prepend-notes` | string | 在现有备注前添加文本。最大长度10000字符 | | `append-notes` | string | 在现有备注后添加文本。最大长度10000字符 | | `when` | string | 设置时间安排。重复待办事项无法修改此字段 | | `deadline` | date string | 设置截止日期。重复待办事项无法修改此字段 | | `tags` | string | 逗号分隔的标签标题，替换所有现有标签 | | `add-tags` | string | 逗号分隔的标签标题，添加到现有标签 | | `checklist-items` | string | 新行分隔（%0a）的清单项。替换所有现有清单项，最多100项 | | `prepend-checklist-items` | string | 新行分隔（%0a）的清单项，添加到前面。最多100项 | | `append-checklist-items` | string | 新行分隔（%0a）的清单项，添加到后面。最多100项 | | `list-id` | string | 项目或区域ID，优先于list | | `list` | string | 项目或区域标题，被list-id忽略 | | `heading-id` | string | 项目内的标题ID，优先于heading。如果标题不存在则忽略 | | `heading` | string | 项目内的标题名称，被heading-id忽略 | | `completed` | boolean | 标记为完成或未完成。若canceled为true则忽略。对已取消的待办事项设为false会标记为未完成。重复待办事项无法修改此字段 | | `canceled` | boolean | 标记为已取消或未完成。优先于completed。对已完成的待办事项设为false会标记为未完成。重复待办事项无法修改此字段 | | `reveal` | boolean | 是否导航并显示更新后的待办事项。默认：false | | `duplicate` | boolean | 设为true时先复制待办事项再更新。重复待办事项无法复制。默认：false | | `creation-date` | ISO8601 date time string | 设置数据库中的创建日期。未来日期会被忽略 | | `completion-date` | ISO8601 date time string | 设置数据库中的完成日期。未完成/取消或未来日期会被忽略。重复待办事项无法修改此字段 | #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-id` | 更新的待办事项ID | --- ### 4. update-project - 更新项目 更新现有的项目。 #### 基础示例 设置项目开始时间： ``` things:///update-project? id=852763FD-5954-4DF9-A88A-2ADD808BD279& when=tomorrow ``` 添加标签： ``` things:///update-project? id=852763FD-5954-4DF9-A88A-2ADD808BD279& add-tags=Important ``` 前置备注： ``` things:///update-project? id=852763FD-5954-4DF9-A88A-2ADD808BD279& prepend-notes=SFO%20to%20JFK. ``` 清除截止日期： ``` things:///update-project? id=852763FD-5954-4DF9-A88A-2ADD808BD279& deadline= ``` #### 参数 `id` 和 `auth-token` 必须指定。其他参数可选。参数使用 `=` 但无值时表示清除该值。 | 参数 | 类型 | 说明 | |-----|------|------| | `auth-token` | string | **必需**。Things URL Scheme授权令牌 | | `id` | string | **必需**。项目的ID | | `title` | string | 新标题，替换现有标题 | | `notes` | string | 新备注，替换现有备注。最大长度10000字符 | | `prepend-notes` | string | 在现有备注前添加文本。最大长度10000字符 | | `append-notes` | string | 在现有备注后添加文本。最大长度10000字符 | | `when` | string | 设置时间安排。重复项目无法修改此字段 | | `deadline` | date string | 设置截止日期。重复项目无法修改此字段 | | `tags` | string | 逗号分隔的标签标题，替换所有现有标签 | | `add-tags` | string | 逗号分隔的标签标题，添加到现有标签 | | `area-id` | string | 区域ID，优先于area | | `area` | string | 区域标题，被area-id忽略 | | `completed` | boolean | 标记为完成或未完成。若canceled为true则忽略。设为true仅当所有子待办事项已完成/取消且所有子标题已存档时有效。对已取消的项目设为false会标记为未完成。重复项目无法修改此字段 | | `canceled` | boolean | 标记为已取消或未完成。优先于completed。设为true仅当所有子待办事项已完成/取消且所有子标题已存档时有效。对已完成的项目设为false会标记为未完成。重复项目无法修改此字段 | | `reveal` | boolean | 是否导航并显示更新后的项目。默认：false | | `duplicate` | boolean | 设为true时先复制项目再更新。重复项目无法复制。默认：false | | `creation-date` | ISO8601 date time string | 设置数据库中的创建日期。未来日期会被忽略 | | `completion-date` | ISO8601 date time string | 设置数据库中的完成日期。未完成/取消或未来日期会被忽略。重复项目无法修改此字段 | #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-id` | 更新的项目ID | --- ### 5. show - 显示和导航 导航到并显示区域、项目、标签或待办事项，或内置列表，可选按标签筛选。 #### 基础示例 导航到"今天"列表： ``` things:///show?id=today ``` 显示特定待办事项： ``` things:///show?id=8796CC16E-92FA-4809-9A26-36194985E87B ``` 导航进入项目： ``` things:///show?id=9096CC16E-92FA-4809-9A26-36194985E44A ``` 按标题查询项目： ``` things:///show?query=vacation ``` 按标题查询项目并按标签筛选： ``` things:///show? query=vacation& filter=errand ``` #### 参数 `id` 和 `query` 至少指定一个；`filter` 可选。 | 参数 | 类型 | 说明 | |-----|------|------| | `id` | string | 区域、项目、标签或待办事项的ID；或内置列表ID：inbox、today、anytime、upcoming、someday、logbook、tomorrow、deadlines、repeating、all-projects、logged-projects。优先于query | | `query` | string | 区域、项目、标签或内置列表的名称。等同于使用快速查找功能并选择第一个结果。被id忽略。**注意**：待办事项无法通过query显示，请使用id或search命令 | | `filter` | string | 逗号分隔的标签标题，用于筛选列表 | #### 返回参数 (x-success) 无 --- ### 6. search - 搜索 调用并显示搜索屏幕。 #### 基础示例 搜索特定文本： ``` things:///search?query=vacation ``` 显示搜索屏幕但不搜索： ``` things:///search ``` #### 参数 所有参数可选。 | 参数 | 类型 | 说明 | |-----|------|------| | `query` | string | 搜索查询文本 | #### 返回参数 (x-success) 无 --- ### 7. version - 获取版本信息 获取Things应用和URL Scheme的版本。 #### 基础示例 ``` things:///version ``` #### 参数 无 #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-scheme-version` | Things URL Scheme的版本 | | `x-things-client-version` | 应用的构建号 | --- ### 8. json - JSON数据导入（开发者用） 高级JSON命令，允许对导入的项目和待办事项进行更多控制。此命令专为应用开发者或熟悉脚本/编程的人员使用。 我们提供了Swift辅助类来帮助生成JSON。获取代码：[Things JSON Coder GitHub仓库](https://github.com/culturedcode/ThingsJSONCoder) #### 基础示例 ``` things:///json?data= [ { "type": "project", "attributes": { "title": "Go Shopping", "items": [ { "type": "to-do", "attributes": { "title": "Bread" } }, { "type": "to-do", "attributes": { "title": "Milk" } } ] } } ] ``` #### 参数 | 参数 | 类型 | 说明 | |-----|------|------| | `auth-token` | string | 当JSON数据包含更新操作时需要。Things URL Scheme授权令牌 | | `data` | JSON string | **必需**。JSON应为包含待办事项和项目对象的数组 | | `reveal` | boolean | 是否导航并显示新建的待办事项或项目。多个时显示首个。默认：false | #### 返回参数 (x-success) | 参数 | 说明 | |-----|------| | `x-things-ids` | JSON字符串，包含创建的待办事项和项目IDs数组 | #### JSON对象结构 每个操作包含以下字段： | 字段 | 必需 | 说明 | |-----|------|------| | `type` | ✓ | 对象类型：to-do、project、heading、checklist-item。详见下方 | | `operation` | | 操作类型：create（创建）或update（更新）。默认：create。仅待办事项和项目支持更新 | | `id` | *有条件* | 更新操作时必需，为要更新的对象ID | | `attributes` | ✓ | 对象属性字典，所有属性可选 | #### 对象类型详解 ##### To-Do（待办事项） ```json { "type": "to-do", "attributes": { "title": "Milk" } } ``` **属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `title` | string | 标题 | | `notes` | string | 备注，最大10000字符 | | `when` | string | 时间安排：today、tomorrow、evening、anytime、someday、日期字符串或日期时间字符串 | | `deadline` | date string | 截止日期 | | `tags` | array | 标签标题数组 | | `checklist-items` | array | checklist-item对象数组，最多100项 | | `list-id` | string | 项目或区域ID，优先于list。如在项目items内指定则忽略 | | `list` | string | 项目或区域标题。被list-id忽略或在项目items内则忽略 | | `heading-id` | string | 项目内标题ID，优先于heading | | `heading` | string | 项目内标题名称，被heading-id忽略 | | `completed` | boolean | 是否完成。默认：false。若canceled为true则忽略 | | `canceled` | boolean | 是否取消。默认：false。优先于completed | | `creation-date` | ISO8601 | 创建日期 | | `completion-date` | ISO8601 | 完成日期 | **仅用于更新操作的属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `prepend-notes` | string | 在备注前添加文本。最大10000字符 | | `append-notes` | string | 在备注后添加文本。最大10000字符 | | `add-tags` | array | 添加标签数组 | | `prepend-checklist-items` | array | 在清单前添加项 | | `append-checklist-items` | array | 在清单后添加项 | ##### Project（项目） ```json { "type": "project", "attributes": { "title": "Go Shopping", "items": [ { "type": "to-do", "attributes": { "title": "Bread" } } ] } } ``` **属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `title` | string | 标题 | | `notes` | string | 备注，最大10000字符 | | `when` | string | 时间安排 | | `deadline` | date string | 截止日期 | | `tags` | array | 标签标题数组 | | `area-id` | string | 区域ID，优先于area | | `area` | string | 区域标题，被area-id忽略 | | `completed` | boolean | 是否完成。默认：false。仅当所有子项完成/取消时有效 | | `canceled` | boolean | 是否取消。默认：false。仅当所有子项完成/取消时有效 | | `creation-date` | ISO8601 | 创建日期 | | `completion-date` | ISO8601 | 完成日期 | **仅用于创建操作的属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `items` | array | to-do或heading对象数组 | **仅用于更新操作的属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `prepend-notes` | string | 在备注前添加文本。最大10000字符 | | `append-notes` | string | 在备注后添加文本。最大10000字符 | | `add-tags` | array | 添加标签数组 | ##### Heading（标题/分组） ```json { "type": "heading", "attributes": { "title": "Sights" } } ``` **属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `title` | string | 标题 | | `archived` | boolean | 是否存档。默认：false。仅当所有下属待办事项完成/取消时有效 | ##### Checklist Item（清单项） ```json { "type": "checklist-item", "attributes": { "title": "Hotels", "completed": true } } ``` **属性：** | 属性 | 类型 | 说明 | |-----|------|------| | `title` | string | 标题 | | `completed` | boolean | 是否完成。默认：false。若canceled为true则忽略 | | `canceled` | boolean | 是否取消。默认：false。优先于completed | #### JSON示例（未编码） ```json [ { "type": "project", "attributes": { "title": "Go Shopping", "items": [ { "type": "to-do", "attributes": { "title": "Bread" } }, { "type": "to-do", "attributes": { "title": "Milk" } } ] } }, { "type": "project", "attributes": { "title": "Vacation in Rome", "notes": "Some time in August.", "area": "Family", "items": [ { "type": "to-do", "attributes": { "title": "Ask Sarah for travel guide" } }, { "type": "to-do", "attributes": { "title": "Add dates to calendar" } }, { "type": "heading", "attributes": { "title": "Sights" } }, { "type": "to-do", "attributes": { "title": "Vatican City" } }, { "type": "to-do", "attributes": { "title": "The Colosseum", "notes": "12€" } }, { "type": "heading", "attributes": { "title": "Planning" } }, { "type": "to-do", "attributes": { "title": "Call Paolo", "completed": true } }, { "type": "to-do", "attributes": { "title": "Book flights", "when": "today" } }, { "type": "to-do", "attributes": { "title": "Research", "checklist-items": [ { "type": "checklist-item", "attributes": { "title": "Hotels", "completed": true } }, { "type": "checklist-item", "attributes": { "title": "Transport from airport" } } ] } } ] } }, { "type": "to-do", "attributes": { "title": "Pick up dry cleaning", "when": "evening", "tags": ["Errand"] } }, { "type": "to-do", "attributes": { "title": "Submit report", "deadline": "2018-02-01", "list": "Work" } } ] ``` #### URL编码说明 上述JSON示例必须删除空格并进行URL编码才能使用。 **删除空格后：** ``` [{"type":"to-do","attributes":{"title":"Buy milk"}}] ``` **URL编码后：** ``` %5B%7B%22type%22:%22to-do%22,%22attributes%22:%7B%22title%22:%22Buy%20milk%22%7D%7D%5B ``` --- ### 9. add-json - 已废弃 **已废弃。请使用json命令来添加项。** --- ## 快速参考 ### 内置列表ID | ID | 说明 | |----|------| | `inbox` | 收件箱 | | `today` | 今天 | | `anytime` | 任何时间 | | `upcoming` | 即将进行 | | `someday` | 某天 | | `logbook` | 日志 | | `tomorrow` | 明天 | | `deadlines` | 截止日期 | | `repeating` | 重复 | | `all-projects` | 所有项目 | | `logged-projects` | 已记录的项目 | ### 时间值 | 值 | 说明 | |----|------| | `today` | 今天 | | `tomorrow` | 明天 | | `evening` | 今晚 | | `anytime` | 任何时间 | | `someday` | 某天 | | 自然语言 | `next tuesday`、`in 3 days` 等（英文） | | 日期格式 | `yyyy-mm-dd`（如 `2017-09-29`） | | 日期时间 | `yyyy-mm-dd@HH:mm`（如 `2018-02-25@14:00`） | --- ## 常见用途示例 ### 批量导入待办事项到项目 使用 `add` 命令的 `titles` 参数： ``` things:///add? titles=牛奶%0a啤酒%0a奶酪& list=购物清单 ``` ### 创建包含检查清单的待办事项 ``` things:///add? title=度假计划& checklist-items=预订机票%0a安排酒店%0a准备行李 ``` ### 为现有待办事项添加提醒 ``` things:///update? id=YOUR_TODO_ID& auth-token=YOUR_AUTH_TOKEN& when=2025-11-10@18:30 ``` ### 搜索功能集成 ``` things:///search?query=紧急任务 ``` --- ## 开发建议 1. **参数编码**：所有字符串参数需进行百分号编码，特殊字符如空格编码为 `%20` 2. **新行处理**：列表参数使用 `%0a` 表示新行 3. **时间格式**：优先使用 `yyyy-mm-dd` 格式以避免地区差异 4. **错误处理**：利用 x-callback-url 的 x-error 和 x-cancel 回调处理异常 5. **ID验证**：频繁使用ID前，建议验证ID的有效性 6. **JSON数据**：使用官方Swift辅助类生成JSON以减少错误 --- 最后更新：2025-11-03 文档版本：Things URL Scheme v2