Tasknote Bridge MCP

🚀 TaskNote Bridge - 支持Things 3与Apple Notes的Swift MCP服务器 ✅

TaskNote Bridge是一款原生macOS Swift应用程序，它实现了一个完整的模型上下文协议（MCP）服务器，用于集成Things 3和Apple Notes。借助该应用，用户可以通过AI助手在这两个工具中便捷地创建任务和笔记。

🚀 快速开始

📥 下载与安装

1. 下载最新版本
2. 打开DMG文件，将TaskNote Bridge拖移到“应用程序”文件夹
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/[用户名]/Downloads/tasknote-bridge/
• 若克隆仓库：/Users/[用户名]/Projects/tasknote-bridge/
• 若移至“应用程序”文件夹：/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 MCP服务器应用程序

• 完整的MCP服务器：用Swift完整实现MCP协议，集成Things 3和Apple Notes工具
• 实时监控：服务器状态仪表盘，实时跟踪活动
• TCP传输：基于网络的传输协议，与通用MCP客户端兼容
• 日志流：实时服务器日志，支持过滤和搜索
• 连接管理：监控活动客户端连接以及请求/响应活动
• SwiftUI界面：现代macOS界面，用于服务器监控和控制

Things 3集成

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

Apple Notes集成

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

📦 安装指南

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

从发布页面下载最新的TaskNote Bridge.app。

选项2：从源代码构建

若想从源代码构建，你需要：

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

克隆仓库并构建：

# 克隆仓库
git clone https://github.com/ragdollKB/taskNote-bridge-mcp.git
cd taskNote-bridge-mcp

# 在Xcode中打开并构建
open "TaskNote Bridge.xcodeproj"

配置

前提条件

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

💻 使用示例

基础用法

# 测试stdio服务器（在Things 3中创建任务！）
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "bb7_add-todo", "arguments": {"title": "来自VS Code的问候！", "tags": ["测试"]}}}' | ./launch_swift_mcp_stdio.sh

# 预期输出：
{"jsonrpc":"2.0","id":1,"result":{"content":[{"text":"✅ 任务'来自VS Code的问候！'已在Things 3中创建","type":"text"}],"isError":false}}

# ✅ 检查Things 3 - 你的任务将显示在那里！

高级用法

# 构建并运行macOS应用程序
xcodebuild -project "TaskNote Bridge.xcodeproj" -scheme "TaskNote Bridge" build
open "TaskNote Bridge.app"
# 服务器将自动启动并显示监控界面

📚 详细文档

项目架构

本项目提供两种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. 选择“开发者”
4. 在“MCP服务器”部分，点击“编辑配置”
5. 添加以下配置：

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

⚠️ 重要提示

请将/path/to/tasknote-bridge/替换为实际的安装目录。常见路径如下：

• 下载发布版本：/Users/[用户名]/Downloads/tasknote-bridge/launch_swift_mcp_stdio.sh
• 克隆仓库：/Users/[用户名]/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通信推荐且最可靠的方法。

🔧 VS Code与MCP扩展

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. 测试连接：

# 进行stdio测试
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

# 进行TCP测试（若服务器正在运行）
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": "来自MCP的测试！", "tags": ["测试"]}}}' | /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

对于VS Code（安装了MCP扩展）

1. 首先，确保已安装并运行TaskNote Bridge应用程序。
2. 为VS Code安装MCP扩展：
   • 打开VS Code
   • 转到扩展（Cmd+Shift+X）
   • 搜索“MCP”并安装官方MCP扩展
3. 配置VS Code设置：
   • 打开设置（Cmd+,）
   • 点击右上角的“打开设置（JSON）”
   • 添加以下配置：

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

⚠️ 重要提示

请将路径替换为实际安装应用程序的位置。若将其移至“应用程序”文件夹，请使用：/Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh

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

使用方法

在TaskNote Bridge应用程序中

1. 从“应用程序”文件夹启动TaskNote Bridge应用程序。
2. 该应用程序提供了一个原生macOS界面，用于：
   • 查看Things 3任务、项目和区域
   • 管理Apple Notes
   • 监控MCP服务器连接
   • 实时查看活动日志

在Claude Desktop中

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

• “我今天的待办事项列表有哪些？”
• “创建一个下周为海滩度假打包的待办事项”
• “创建一个阵亡将士纪念日烧烤项目，并包含规划任务”
• “显示我所有与工作相关的任务”
• “将购物任务标记为已完成”
• “添加一个明天给妈妈打电话的任务”

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风格的每周回顾”
• “为[项目名称]创建一个包含子任务和截止日期的项目计划”
• “分析我的任务完成模式并提出改进建议”

项目结构

TaskNote Bridge.app/          # macOS Swift应用程序
├── Contents/
│   ├── MacOS/                # 包含MCP服务器的原生Swift可执行文件
│   │   └── TaskNote Bridge   # 嵌入MCP服务器的主应用程序
│   ├── Resources/            # 应用程序资源
│   └── Info.plist            # 应用程序包配置
├── TaskNote Bridge.xcodeproj/ # Xcode项目
├── SwiftMCPServer.swift      # 核心MCP服务器实现
├── ThingsIntegration.swift   # Things 3集成层
├── NotesIntegration.swift    # Apple Notes集成层
└── README.md                 # 本文档

可用工具

列表视图

• get-inbox - 获取收件箱中的待办事项
• get-today - 获取今天到期的待办事项
• get-upcoming - 获取即将到来的待办事项
• get-anytime - 获取“任何时间”列表中的待办事项
• get-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
• 检查日志：查看Claude日志~/Library/Logs/Claude/mcp*.log

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 → “设置” → “通用”中启用了“启用Things URL”

工具执行问题

服务器包含全面的错误处理，用于处理以下情况：

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

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

# 实时跟踪Claude Desktop日志
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

# 检查TaskNote Bridge应用程序日志
# 打开TaskNote Bridge应用程序并查看内置的日志查看器

# 直接测试服务器
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh

常见错误解决方案

“权限被拒绝”错误

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

“Things 3无响应”错误

• 确保已安装Things 3并至少启动过一次
• 检查Things 3设置中是否启用了“启用Things URL”
• 尝试重启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":{}}}}