Tasknote Bridge MCP

🚀 TaskNote Bridge - Swift MCP Server 與 Things 3 和 Apple Notes 的集成 ✅

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）
• VS Code（帶有 MCP 擴展）

💻 使用示例

基礎用法

# 測試 stdio 服務器（在 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

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

# ✅ 檢查 Things 3 - 你的任務將出現在那裡！

高級用法

GUI 監控

# 構建並運行 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. 導航到擴展 → 模型上下文協議
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": "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

使用方法

在 TaskNote Bridge 應用程序中

1. 從“應用程序”文件夾中啟動 TaskNote Bridge 應用程序。
2. 該應用程序提供了一個原生 macOS 界面，用於：
   • 查看你的 Things 3 任務、項目和區域
   • 管理你的 Apple 筆記
   • 監控 MCP 服務器連接
   • 實時查看活動日誌

在 Claude Desktop 中

連接成功後，你可以使用自然語言與 TaskNote Bridge 進行交互： Things 3 示例：

• “我今天的待辦事項清單上有什麼？”
• “創建一個待辦事項，為我下週的海灘度假打包”
• “為陣亡將士紀念日燒烤創建一個項目，幷包含規劃任務”
• “顯示我所有與工作相關的任務”
• “將購物任務標記為已完成”
• “添加一個明天給媽媽打電話的任務”

Apple Notes 示例：

• “創建一個包含今天站立會議會議記錄的筆記”
• “在我的筆記中搜索有關季度審查的任何內容”
• “記錄我想嘗試的新餐廳”
• “顯示我所有包含旅行信息的筆記”

在 VS Code 中

安裝並配置 MCP 擴展後：

1. 打開命令面板（Cmd + Shift + P）
2. 輸入“MCP”以查看可用的 MCP 命令
3. 使用“MCP: 調用工具”與 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
• 檢查日誌：查看 ~/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 → 設置 → 通用中啟用了“啟用 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":{}}}}