Tasknote Bridge MCP

TaskNote Bridge-带Things 3和Apple Notes的Swift MCP服务器✅

一个本机macOS Swift应用程序，实现了完整的 模型上下文协议（MCP） 用于Things 3和Apple Notes集成的服务器。

状态: ✅ 生产就绪 -配备GUI监控的完整MCP服务器

🚀 快速安装

📥 下载并安装

1. 下载最新版本
2. 打开DMG 并将TaskNote Bridge拖动到应用程序中
3. 启动应用程序 -MCP服务器自动启动
4. 配置VS代码 使用以下设置

⚙️ Claude桌面配置

将此添加到您的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/ - 如果你克隆了repo： /Users/[username]/Projects/tasknote-bridge/ - 如果将其移动到应用程序： /Applications/TaskNote Bridge/

⚙️ VS代码配置

将此添加到您的VS代码中 settings.json:

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

就是这样！ 🎉 您已准备好通过AI助手创建任务和笔记。

📋 需求

• macOS12.0+（蒙特利或更高）
• 事情3：从Mac应用商店安装
• 苹果笔记：内置于macOS
• VS代码：带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服务器：使用Things 3和Apple Notes工具全面实现MCP协议的Swift
• 实时监控：带有实时活动跟踪的服务器状态仪表板
• TCP传输：用于通用MCP客户端兼容性的基于网络的传输协议
• 日志流：具有过滤和搜索功能的实时服务器日志
• 连接管理：监视活动客户端连接和请求/响应活动
• SwiftUI界面：用于服务器监控和控制的现代macOS界面

事物3整合

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

Apple Notes集成

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

安装

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

下载最新 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等）
• 事情3（必须在设置->常规中打开“启用事情URL”）
• Apple Notes（用于笔记管理功能）
• macOS 13.0或更高版本（SwiftUI和AppleScript集成所需）

🏗️ 项目架构

该项目提供 两种MCP服务器实现 对于不同的用例：

📱 TaskNote Bridge.app （GUI应用程序）

• 目的：带有可视化监控界面的macOS应用程序
• 运输：用于基于网络的连接的TCP服务器（端口8000）
• 特性：实时仪表板、连接监控、日志查看器
• 用例：当您想要对服务器活动进行可视化监控时
• 发射：从“应用程序”文件夹打开应用程序

📟 swift_mcp_sdio.swift （命令行服务器）

• 目的：基于stdio的轻量级MCP服务器
• 运输：标准输入/输出通信
• 特性：直接JSON-RPC消息处理，开销最小
• 用例: 建议用于Claude Desktop 以及大多数MCP客户端
• 发射：通过 launch_swift_mcp_stdio.sh 脚本

🔧 使用哪一个？

💡 关键点：大多数MCP客户端（包括Claude Desktop）都期望基于stdio的通信，而不是TCP连接。

🔗 MCP客户端连接指南

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

🎯 克劳德桌面

配置Claude桌面 要使用基于stdio的MCP服务器：

1. 打开克劳德桌面
2. 点击设置齿轮(⚙️) 在左下角
3. 选择“开发人员”
4. 在“MCP服务器”部分，单击“编辑配置”
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 \\\`

1. 保存配置
2. 重新启动克劳德桌面 应用更改

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

🔧 带有MCP扩展的VS代码

1. 安装MCP扩展 对于VS代码：

- 打开VS代码扩展名（Cmd+Shift+X） - 搜索“模型上下文协议”并安装

1. 配置VS代码 设置(settings.json):

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

1. 重新启动VS代码 加载MCP服务器

🖱️ 光标IDE

1. 打开光标设置 （Cmd+，）
2. 导航到扩展 → 模型上下文协议
3. 添加服务器配置:

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

⚡ 继续（VS代码扩展）

1. 安装继续扩展 VS代码
2. 打开继续配置 （通常 ~/.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. 添加到您的设置.json:

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

🛠️ 自定义MCP客户端

对于任何自定义MCP客户端或应用程序：

tcp连接

• 主机: localhost
• 端口: 8000 （默认设置，可在TaskNote Bridge应用程序中配置）
• 协议：TCP与JSON-RPC 2.0

标准连接

• 命令: /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

1. 检查可用工具 -您应该看到以下工具：

- bb7_add-todo - bb7_add-project - bb7_get-today - bb7_notes-create - 还有更多。..

1. 测试任务创建:

   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

1. 在事物3中验证 -测试任务应出现在您的收件箱中

🔍 连接问题疑难解答

克劳德桌面未连接

• 检查配置文件是否为有效的JSON
• 验证文件路径是否存在： /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
• 完全重新启动克劳德桌面
• 检查克劳德日志： ~/Library/Logs/Claude/mcp*.log

TCP连接问题

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

标准连接问题

• 验证脚本权限： ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 直接在终端中测试脚本
• 检查Things 3中是否启用了Things 3 URL→ 设置→ 将军

用于VS代码（带MCP扩展名）

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

1. 安装VS代码的MCP扩展：

- 打开VS代码 - 转到扩展（Cmd+Shift+X） - 搜索“MCP”并安装官方MCP扩展

1. 配置VS代码设置：

- 打开设置（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

1. 重新启动VS Code以加载MCP服务器。

用法

用法

在TaskNote Bridge应用程序中

1. 从“应用程序”文件夹启动TaskNote Bridge应用程序。
2. 该应用程序提供了一个原生macOS界面，用于：

- 查看你的Things 3任务、项目和领域 - 管理您的Apple Notes - 监控MCP服务器连接 - 实时查看活动日志

在克劳德桌面

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

三个例子：

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

Apple Notes示例：

• “根据今天的站立会议记录创建一个笔记”
• “在我的笔记中搜索有关季度回顾的任何信息”
• “记下我想尝试的新餐厅”
• “显示我所有包含旅行信息的笔记”

在VS代码中

安装并配置MCP扩展后：

1. 打开命令面板（Cmd+Shift+P）
2. 键入“MCP”查看可用的MCP命令
3. 使用“MCP：调用工具”与Things工具进行交互
4. 或者使用任何支持MCP的AI助手来访问您的Things数据

适用于任何MCP兼容工具

该服务器遵循标准的MCP协议，可以与任何兼容MCP的应用程序或AI助手一起工作。只需配置您的工具，使用上述方法之一连接到Swift MCP服务器。

兼容的应用程序包括：

• 克劳德桌面
• 带有MCP扩展的VS代码
• 光标
• 继续
• 泽德
• 源代码图科迪
• 任何自定义MCP客户端实现

💡 更好集成的专业提示

克劳德桌面优化

• 创建自定义项目 在Claude中，提供有关如何使用Things 3和组织区域、项目、标签等的说明。
• 告诉克劳德要包括哪些信息 创建任务时（例如，任务描述中的相关细节）
• 与日历MCP服务器结合使用 让Claude为任务分配时间，并根据日历事件创建待办事项

多客户端使用

• 使用TCP模式 同时连接多个客户端
• 保持TaskNote Bridge应用程序打开 实时监控所有MCP活动
• 检查应用程序日志 如果您在工具调用中遇到任何问题

高级工作流

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

项目结构

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 -从某一天列表中获取待办事项
• get-logbook -完成待办事项
• get-trash -收到垃圾待办事项

基本操作

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

标签操作

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

搜索操作

• search-todos -按标题/注释进行简单搜索
• search-advanced -具有多个过滤器的高级搜索
• open-todo -按标题搜索待办事项，并在Things应用程序中打开它

基于时间的操作

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

刀具参数

所有人

• project_uuid （可选）-按项目筛选待办事项
• include_items （可选，默认值：true）-包括检查表项目

获取项目/获取区域/获取标签

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

搜索高级

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

获取最新信息

• period -时间段（例如，“3d”、“1w”、“2m”、“1年”）

全部开放

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

笔记打开

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

故障排除

连接问题

克劳德桌面

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

TCP连接问题

• 应用程序正在运行：确保TaskNote Bridge应用程序在TCP服务器启动的情况下运行
• 端口可用性：检查端口8000是否可用 lsof -i :8000
• 防火墙设置：验证macOS防火墙是否允许本地连接
• 尝试其他端口：如果需要，请更改TaskNote Bridge应用程序设置中的端口

标准连接问题

• 脚本权限：验证脚本是否可执行： ls -la /Applications/TaskNote\ Bridge.app/Contents/Resources/launch_mcp_server.sh
• 直接测试：在终端中测试脚本以确保其正常工作
• 事情3 URL：确保在Things 3中打开“启用Things URL”→ 设置→ 将军

工具执行问题

该服务器包括全面的错误处理功能，用于：

• 无效的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

常见错误解决方案

“权限被拒绝”错误

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

“事情3没有响应”错误

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

“拒绝访问Apple Notes”错误

• 授予TaskNote Bridge权限以在“系统首选项”中控制Apple Notes→ 安全与隐私→ 自动化
• 确保Apple Notes应用程序不受任何安全软件的限制

🚨 故障排除

Claude桌面连接问题

“请求超时”/服务器没有响应

如果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. 重新启动克劳德桌面
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":{}}}}