TaskNote Bridge - Swift MCP Server with Things 3 & Apple Notes ✅

TaskNote Bridge - 支持 Things 3 和 Apple Notes 的 Swift MCP 服务 ✅

一款原生 macOS Swift 应用，为 Things 3 和 Apple Notes 集成实现了完整的 Model Context Protocol (MCP) 服务。

状态：✅ 已可用于生产环境 - 完整的 MCP 服务，带 GUI 监控功能

🚀 快速安装

📥 下载并安装

1. 下载最新版本
2. 打开 DMG，将 TaskNote Bridge 拖到 Applications
3. 启动应用 - MCP 服务会自动启动
4. 按照下方设置配置 VS Code

⚙️ Claude Desktop 配置

将以下内容添加到 Claude Desktop MCP 服务配置中：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 注意：将 /path/to/tasknote-bridge/ 替换为实际的安装目录。例如：

• 如果下载了发行版：/Users/[username]/Downloads/tasknote-bridge/
• 如果克隆了仓库：/Users/[username]/Projects/tasknote-bridge/
• 如果将其移到了 Applications：/Applications/TaskNote Bridge/

⚙️ VS Code 配置

将以下内容添加到 VS Code settings.json：

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh",
                "args": []
            }
        }
    }
}

就是这样！ 🎉 现在可以通过 AI 助手创建任务和笔记了。

📋 要求

• macOS：12.0+（Monterey 或更高版本）
• Things 3：从 Mac App Store 安装
• Apple Notes：macOS 内置
• VS Code：需安装 MCP 扩展

🎯 当前可用功能

# Test the stdio server (creates task in Things 3!)
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Hello from VS Code!", "tags": ["test"]}}}' | ./launch_swift_mcp_stdio.sh

# Expected output:
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ Task 'Hello from VS Code!' created in Things 3","type":"text"}],"isError":false}}

# ✅ Check Things 3 - your task will be there!

GUI 监控

# Build and run the macOS app
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# Server auto-starts with monitoring interface

🛠 完整功能集

原生 macOS MCP 服务应用

• 完整 MCP 服务：完整实现 MCP 协议的 Swift 服务，包含 Things 3 和 Apple Notes 工具
• 实时监控：服务状态面板，实时跟踪活动
• TCP 传输：基于网络的传输协议，兼容各种 MCP 客户端
• 日志流：实时服务日志，支持筛选和搜索
• 连接管理：监控活跃的客户端连接及请求/响应活动
• SwiftUI 界面：用于服务监控和控制的现代 macOS 界面

Things 3 集成

• 访问所有主要 Things 列表（收件箱、今天、即将到来等）
• 项目和领域管理
• 标签操作
• 高级搜索功能
• 最近项目跟踪
• 查看详细条目信息，包括检查清单
• 支持嵌套数据（领域中的项目、项目中的待办事项）
• 直接在 Things 3 应用中打开特定任务

Apple Notes 集成

• 创建包含标题、内容和标签的新笔记
• 按标题搜索笔记
• 获取笔记内容
• 列出所有笔记
• 直接在 Apple Notes 应用中打开笔记
• 删除笔记
• 完整集成 AppleScript，带来无缝的 macOS 使用体验

安装

选项 1：下载应用（推荐）

从 Releases 页面下载最新的 TaskNote Bridge.app

选项 2：从源代码构建

如果你希望从源代码构建，需要：

• Xcode 14.0 或更新版本
• macOS 13.0 或更新版本

克隆仓库并构建：

# Clone the repository
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# Open in Xcode and build
open "TaskNote Bridge.xcodeproj"

配置

前置条件

• 任何兼容 MCP 的 AI 助手或工具（Claude Desktop、带 MCP 扩展的 VS Code、Cursor、Continue、Zed 等）
• Things 3（必须在“设置”->“通用”中开启“Enable Things URLs”）
• Apple Notes（用于笔记管理功能）
• macOS 13.0 或更新版本（SwiftUI 和 AppleScript 集成所需）

🏗️ 项目架构

本项目提供了两种 MCP 服务实现，适用于不同的使用场景：

📱 TaskNote Bridge.app（GUI 应用）

• 用途：带有可视化监控界面的 macOS 应用
• 传输方式：TCP 服务（端口 8000），用于基于网络的连接
• 功能：实时仪表板、连接监控、日志查看器
• 适用场景：需要直观监控服务活动时
• 启动方式：从“应用程序”文件夹打开应用

📟 swift_mcp_stdio.swift（命令行服务）

• 用途：轻量级的 stdio MCP 服务
• 传输方式：标准输入/输出通信
• 功能：直接处理 JSON-RPC 消息，开销极低
• 适用场景：推荐用于 Claude Desktop 和大多数 MCP 客户端
• 启动方式：通过 launch_swift_mcp_stdio.sh 脚本启动

🔧 该使用哪一个？

MCP 客户端	推荐的服务	配置
Claude Desktop	✅ stdio 脚本	command: "/path/to/launch_swift_mcp_stdio.sh"
VS Code MCP	✅ stdio 脚本	与 Claude Desktop 相同
自定义 TCP 客户端	📱 GUI 应用	连接到 localhost:8000
开发/测试	📱 GUI 应用	可视化监控 + TCP 访问

💡 要点：大多数 MCP 客户端（包括 Claude Desktop）都使用基于 stdio 的通信，而非 TCP 连接。

🔗 MCP 客户端连接指南

TaskNote Bridge 支持多种连接方式，可与各种 MCP 客户端配合使用。请选择最适合你的客户端的方式：

🎯 Claude Desktop

配置 Claude Desktop，以使用基于 stdio 的 MCP 服务：

1. 打开 Claude Desktop
2. 点击左下角的设置齿轮（⚙️）
3. 选择“Developer”
4. 在“MCP Servers”部分，点击“Edit Config”
5. 添加以下配置：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

📝 注意：将 /path/to/tasknote-bridge/ 替换为实际的安装目录。常见路径：

• 下载的发行版：/Users/[username]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh
• 克隆的仓库：/Users/[username]/Projects/tasknote-bridge/launch_swift_mcp_stdio.sh
• 应用包安装：/Applications/TaskNote Bridge.app/Contents/Resources/launch_swift_mcp_stdio.sh ```

6. 保存配置
7. 重启 Claude Desktop 以应用更改

✅ 成功：现在 Claude Desktop 将通过 stdio 传输方式连接，这是 MCP 通信推荐且最可靠的方式。

🔧 使用 MCP 扩展的 VS Code

1. 为 VS Code 安装 MCP 扩展：

   • 打开 VS Code 扩展（Cmd+Shift+X）
   • 搜索“Model Context Protocol”并安装

2. 配置 VS Code 设置（settings.json）：

{
    "mcp": {
        "servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

3. 重启 VS Code 以加载 MCP 服务

🖱️ Cursor IDE

1. 打开 Cursor 设置（Cmd+,）
2. 前往“扩展” → Model Context Protocol
3. 添加服务配置：

{
    "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
    "args": []
}

⚡ Continue（VS Code 扩展）

1. 在 VS Code 中安装 Continue 扩展
2. 打开 Continue 配置（通常为 ~/.continue/config.json）
3. 添加 MCP 服务：

{
    "mcpServers": [
        {
            "name": "tasknote-bridge",
            "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
            "args": []
        }
    ]
}

🚀 Zed 编辑器

1. 打开 Zed 设置（Cmd+,）
2. 添加到你的 settings.json：

{
    "assistant": {
        "mcp_servers": {
            "tasknote-bridge": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh"
            }
        }
    }
}

🛠️ 自定义 MCP 客户端

适用于任何自定义 MCP 客户端或应用：

TCP 连接

• 主机：localhost
• 端口：8000（默认值，可在 TaskNote Bridge 应用中配置）
• 协议：使用 JSON-RPC 2.0 的 TCP

Stdio 连接

• 命令：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• 传输方式：使用 JSON-RPC 2.0 的标准输入/输出

📋 验证步骤

配置任何客户端后：

1. 测试连接：

   # For stdio testing
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   
   # For TCP testing (if server is running)
   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | nc localhost 8000
   

2. 检查可用工具——你应该会看到如下工具：

   • bb7_add-todo
   • bb7_add-project
   • bb7_get-today
   • bb7_notes-create
   • 还有更多……

3. 测试任务创建：

   echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "Test from MCP!", "tags": ["test"]}}}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
   

4. 在 Things 3 中验证——测试任务应出现在收件箱中

🔍 连接问题排查

Claude Desktop 无法连接

• 检查配置文件是否为有效的 JSON
• 确认文件路径存在：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• 完全重启 Claude Desktop
• 查看 Claude 日志：~/Library/Logs/Claude/mcp*.log

TCP 连接问题

• 确保 TaskNote Bridge 应用正在运行
• 检查端口 8000 是否可用：lsof -i :8000
• 尝试在 TaskNote Bridge 设置中使用其他端口
• 确认防火墙设置允许本地连接

Stdio 连接问题

• 确认脚本权限：ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 在终端中直接测试脚本
• 检查 Things 3 中的 Things 3 URL 是否已启用：Things 3 → Settings → General

对于 VS Code（使用 MCP 扩展）

1. 首先，确保已安装并运行 TaskNote Bridge 应用。

2. 为 VS Code 安装 MCP 扩展：

   • 打开 VS Code
   • 前往扩展（Cmd+Shift+X）
   • 搜索 “MCP” 并安装官方 MCP 扩展

3. 配置 VS Code 设置：

   • 打开设置（Cmd+,）
   • 点击右上角的 “Open Settings (JSON)”
   • 添加以下配置：

{
    "mcp": {
        "inputs": [],
        "servers": {
            "things-swift": {
                "command": "/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh",
                "args": []
            }
        }
    }
}

注意：将路径替换为应用的实际安装位置。如果已将应用移至 Applications 文件夹，请使用：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh

4. 重启 VS Code 以加载 MCP 服务。

用法

用法

在 TaskNote Bridge 应用中

1. 从 Applications 文件夹启动 TaskNote Bridge 应用。
2. 应用提供 macOS 原生界面，可用于：
   • 查看 Things 3 任务、项目和领域
   • 管理 Apple Notes
   • 监控 MCP 服务连接
   • 实时查看活动日志

在 Claude Desktop 中

连接后，你可以使用自然语言与 TaskNote Bridge 交互：

Things 3 示例：

• “我今天的待办事项有哪些？”
• “创建一个待办事项：为下周的海滩假期打包”
• “创建一个 Memorial Day 烧烤项目，并添加计划任务”
• “显示我所有与工作相关的任务”
• “将杂货采购任务标记为已完成”
• “添加一项明天给妈妈打电话的任务”

Apple Notes 示例：

• “创建一条笔记，记录今天站会的会议纪要”
• “搜索我的笔记，查找有关季度回顾的内容”
• “创建一条关于我想尝试的新餐厅的笔记”
• “显示所有包含旅行信息的笔记”

在 VS Code 中

安装并配置 MCP 扩展后：

1. 打开命令面板（Cmd+Shift+P）
2. 输入 “MCP” 查看可用的 MCP 命令
3. 使用 “MCP: Call Tool” 与 Things 工具交互
4. 或使用任何支持 MCP 的 AI 助手访问你的 Things 数据

适用于任何兼容 MCP 的工具

此服务遵循标准 MCP 协议，可与任何兼容 MCP 的应用或 AI 助手配合使用。只需按照上述任一方式配置工具，以连接到 Swift MCP 服务。

兼容的应用包括：

• Claude Desktop
• 配备 MCP 扩展的 VS Code
• Cursor
• Continue
• Zed
• Sourcegraph Cody
• 任何自定义 MCP 客户端实现

💡 更好集成的专业建议

优化 Claude Desktop

• 在 Claude 中创建自定义项目，并说明你如何使用 Things 3，以及如何整理领域、项目、标签等。
• 告知 Claude 创建任务时应包含哪些信息（例如，任务描述中的相关细节）
• 结合日历 MCP 服务，让 Claude 为任务安排时间，并根据日历事件创建待办事项

多客户端使用

• 使用 TCP 模式同时连接多个客户端
• 保持 TaskNote Bridge 应用开启，以实时监控所有 MCP 活动
• 如果工具调用遇到问题，请查看应用日志

高级工作流

• “使用艾森豪威尔矩阵评估我当前的待办事项”
• “帮我使用 Things 进行 GTD 风格的每周回顾”
• “为 [project name] 创建项目计划，包含子任务和截止日期”
• “分析我的任务完成模式并提出改进建议”

项目结构

TaskNote Bridge.app/          # The macOS Swift application
├── Contents/
│   ├── MacOS/                # Native Swift executable containing MCP server
│   │   └── TaskNote Bridge   # Main app with embedded MCP server
│   ├── Resources/            # Application resources
│   └── Info.plist            # App bundle configuration
├── TaskNote Bridge.xcodeproj/ # Xcode project
├── SwiftMCPServer.swift      # Core MCP server implementation
├── ThingsIntegration.swift   # Things 3 integration layer
├── NotesIntegration.swift    # Apple Notes integration layer
└── README.md                 # This documentation

可用工具

列表视图

• get-inbox - 获取收件箱中的待办事项
• get-today - 获取今天到期的待办事项
• get-upcoming - 获取即将到期的待办事项
• get-anytime - 获取 Anytime 列表中的待办事项
• get-someday - 获取 Someday 列表中的待办事项
• get-logbook - 获取已完成的待办事项
• get-trash - 获取已移至废纸篓的待办事项

基本操作

• get-todos - 获取待办事项，可按项目筛选
• get-projects - 获取所有项目
• get-areas - 获取所有领域

标签操作

• get-tags - 获取所有标签
• get-tagged-items - 获取带有指定标签的项目

搜索操作

• search-todos - 按标题或备注进行简单搜索
• search-advanced - 使用多个筛选条件进行高级搜索
• open-todo - 按标题搜索待办事项，并在 Things 应用中打开

基于时间的操作

• get-recent - 获取最近创建的项目

工具参数

get-todos

• project_uuid（可选）- 按项目筛选待办事项
• include_items（可选，默认值：true）- 包含清单项目

get-projects / get-areas / get-tags

• include_items（可选，默认值：false）- 包含其中的项目

search-advanced

• status - 按状态筛选（未完成/已完成/已取消）
• start_date - 按开始日期筛选（YYYY-MM-DD）
• deadline - 按截止日期筛选（YYYY-MM-DD）
• tag - 按标签筛选
• area - 按领域 UUID 筛选
• type - 按项目类型筛选（待办事项/项目/标题）

get-recent

• period - 时间段（例如，'3d'、'1w'、'2m'、'1y'）

open-todo

• title - 要搜索并打开的待办事项的标题或部分标题

notes-open

• title - 要在 Apple Notes 中打开的笔记的准确标题

故障排除

连接问题

Claude Desktop

• 检查配置文件：确保 JSON 配置有效且格式正确
• 验证文件路径：确保 /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh 存在
• 重新启动 Claude：更改配置后，完全退出并重新启动 Claude Desktop
• 检查日志：查看 ~/Library/Logs/Claude/mcp*.log 中的 Claude 日志

TCP 连接问题

• 应用正在运行：确保 TaskNote Bridge 应用正在运行且已启动 TCP 服务
• 端口可用性：使用 lsof -i :8000 检查端口 8000 是否可用
• 防火墙设置：确认 macOS 防火墙允许本地连接
• 尝试其他端口：如有需要，在 TaskNote Bridge 应用设置中更改端口

Stdio 连接问题

• 脚本权限：确认脚本可执行：ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 直接测试：在终端中测试脚本，确保其正常运行
• Things 3 URL：确保已在 Things 3 → Settings → General 中启用“Enable Things URLs”

工具执行问题

服务包含全面的错误处理，涵盖：

• 无效 UUID 和格式错误的请求
• 缺少必需参数
• Things 3 数据库访问错误
• Apple Notes AppleScript 执行错误
• 数据格式化和序列化错误

所有错误都会记录描述性消息。查看 MCP 日志：

# Follow Claude Desktop logs in real-time
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# Check TaskNote Bridge app logs
# Open TaskNote Bridge app and view the built-in log viewer

# Test server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

常见错误的解决方法

“Permission denied”错误

• 运行：chmod +x /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 在“系统设置 → 安全性与隐私”中向 TaskNote Bridge 应用授予必要权限

“Things 3 not responding”错误

• 确保已安装 Things 3，且至少启动过一次
• 检查 Things 3 设置中是否已启用“Enable Things URLs”
• 尝试重新启动 Things 3

“Apple Notes 访问被拒绝”错误

• 在“系统偏好设置” →“安全性与隐私” →“自动化”中，授予 TaskNote Bridge 控制 Apple Notes 的权限
• 确保任何安全软件都未限制 Apple Notes 应用

🚨 故障排查

Claude Desktop 连接问题

“请求超时” / 服务未响应

如果 Claude Desktop 显示超时错误或未收到响应：

❌ 错误配置（会导致超时）：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "nc",
            "args": ["localhost", "8000"]
        }
    }
}

✅ 正确配置：

{
    "mcpServers": {
        "tasknote-bridge": {
            "command": "/path/to/tasknote-bridge/launch_swift_mcp_stdio.sh"
        }
    }
}

原因：

• Claude Desktop 需要基于 stdio 的通信（启动子进程）
• nc localhost 8000 的方式尝试通过 netcat 使用 TCP，但无法正确处理 MCP 协议初始化
• stdio 脚本提供了 Claude Desktop 所需的正确 JSON-RPC 消息处理

修复方法：

1. 更新 Claude Desktop 配置，使用 stdio 脚本
2. 重启 Claude Desktop
3. 现在连接应该可以正常工作，不再超时

验证服务是否正常

直接测试 stdio 服务：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | /path/to/tasknote-bridge/launch_swift_mcp_stdio.sh

你应该会立即看到类似这样的响应：

{"jsonrpc":"2.0","id":1,"result":{"serverInfo":{"name":"things-mcp-swift","version":"1.0.0"},"protocolVersion":"2024-11-05","capabilities":{"tools":{}}}}