MCP Server for Things3

一个强大的MCP（模型上下文协议）服务器，提供与Things3的全面集成，允许您通过MCP协议创建、管理和搜索任务和项目。功能包括改进的错误处理、安全的URL编码以及增强的AppleScript集成。

功能

• ✅ 创建项目：在Things3中创建新项目，并支持完整的元数据
• ✅ 创建待办事项：创建新的待办事项，包含详细的属性，如检查列表、标签和日期
• ✅ 查看任务：列出收件箱、今日清单或所有项目的任务
• ✅ 完成任务：通过搜索标题标记待办事项为已完成
• ✅ 搜索功能：通过标题或内容搜索所有待办事项
• ✅ 强大的错误处理：全面的验证和错误恢复
• ✅ 安全的URL编码：正确处理特殊字符和Unicode
• ✅ AppleScript集成：安全的非JSON字符串连接方法

安装

先决条件

• 已安装Things3的macOS系统
• Python 3.8+
• 运行中的Things3（用于实时操作）

安装服务器

1. 克隆此仓库：

   git clone <repository-url>
   cd mcp-things3
   

2. 使用pip安装：

   pip install -e .
   

3. 服务器将以mcp-server-things3的形式可用

可用工具

查看操作

view-inbox

查看Things3收件箱中的所有待办事项。

• 参数：无
• 返回：带有截止日期和调度信息的收件箱待办事项列表

view-projects

查看Things3中的所有项目。

• 参数：无
• 返回：带有标题的所有项目列表

view-todos

查看今日清单中的所有待办事项。

• 参数：无
• 返回：带有元数据的今日待办事项列表

创建操作

create-things3-project

在Things3中创建新项目。

• 必需：title（字符串）
• 可选：
  • notes（字符串）
  • area（字符串）
  • when（字符串）- 开始日期/时间
  • deadline（字符串）- 截止日期
  • tags（字符串数组）

示例：

{
  "title": "网站重新设计",
  "notes": "公司网站的整体翻新",
  "area": "工作",
  "deadline": "2024-03-15",
  "tags": ["紧急", "web-dev"]
}

create-things3-todo

在Things3中创建新的待办事项。

• 必需：title（字符串）
• 可选：
  • notes（字符串）
  • when（字符串）- 开始日期/时间
  • deadline（字符串）- 截止日期
  • checklist（字符串数组）
  • tags（字符串数组）
  • list（字符串）- 分配到的项目或区域
  • heading（字符串）- 归属于此标题

示例：

{
  "title": "审查设计草图",
  "notes": "检查新的首页设计",
  "list": "网站重新设计",
  "deadline": "2024-02-20",
  "tags": ["审查"],
  "checklist": ["检查移动响应性", "验证品牌指南", "测试无障碍性"]
}

管理操作

complete-things3-todo

通过搜索标题标记待办事项为已完成。

• 必需：title（字符串）- 搜索的标题或部分标题
• 返回：成功/失败消息

示例：

{
  "title": "审查设计"
}

search-things3-todos

通过标题或内容搜索待办事项。

• 必需：query（字符串）- 搜索词
• 返回：匹配的待办事项列表及其状态和元数据

示例：

{
  "query": "网站"
}

与Claude的集成

此MCP服务器旨在无缝地与Claude AI配合使用。配置后，您可以使用自然语言来管理您的Things3任务：

• “创建一个名为‘第一季度规划’的项目，截止日期为3月31日”
• “添加一个待办事项以审查预算，并附带任务检查列表”
• “显示我今天的所有任务”
• “标记‘致电客户’任务为已完成”
• “搜索所有与网站项目相关的待办事项”

配置

MCP客户端配置

添加到您的MCP客户端配置（例如，Claude Desktop配置）：

{
  "mcpServers": {
    "things3": {
      "command": "mcp-server-things3",
      "args": []
    }
  }
}

Things3设置

1. 确保已安装并运行Things3
2. 在提示时授予AppleScript访问所需的权限
3. 服务器将在操作前验证Things3的可用性

架构

组件

• server.py：主要的MCP服务器实现，包含工具定义和处理器
• applescript_handler.py：强大的AppleScript集成，具有安全的数据解析
• URL编码：正确处理x-callback-url参数中的特殊字符
• 错误处理：全面的验证和优雅的错误恢复

安全特性

• 输入净化：所有用户输入都针对AppleScript进行了适当的转义
• URL编码：在URL中正确处理特殊字符和Unicode
• 验证：在操作前检查Things3的可用性
• 错误恢复：优雅地处理AppleScript和系统错误

开发

运行测试

python test_things3.py

调试

服务器包含全面的日志记录。设置调试级别：

export PYTHONPATH="."
python -c "
import logging
logging.basicConfig(level=logging.DEBUG)
from src.mcp_server_things3.server import main
import asyncio
asyncio.run(main())
"

贡献

1. 分叉仓库
2. 创建功能分支
3. 为新功能添加测试
4. 确保所有测试通过
5. 提交拉取请求

故障排除

常见问题

“Things3不可用”

• 确保已安装并运行Things3
• 在提示时授予AppleScript权限
• 检查Things3是否未处于权限受限模式

“执行AppleScript失败”

• 验证macOS安全设置允许AppleScript
• 确保Things3具有必要的辅助功能权限
• 尝试重启Things3

特殊字符的URL编码问题

• 服务器现在正确处理Unicode和特殊字符
• 如果问题持续，请检查日志以获取特定的URL构造错误

性能说明

• AppleScript操作可能有轻微延迟
• 大量待办事项列表（1000+项）可能需要更长时间进行搜索
• 考虑使用具体的搜索而不是广泛的查询以获得更好的性能

许可

MIT许可 - 详情参见LICENSE文件。

更新日志

v0.1.0

• 初始发布，包含基本的CRUD操作
• 全面的错误处理和验证
• 安全的URL编码和AppleScript集成
• 搜索和完成功能
• 强大的数据解析，不使用JSON字符串连接