任务笔记-桥接器-MCP

Name: 任务笔记-桥接器-MCP
Author: ragdollKB

作者：ragdollKB3 星标更新：2025-06-01

安装使用来源：spider==github.com

项目介绍

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

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

状态: ✅ 生产就绪 - 完整的MCP服务器带图形界面监控

🚀 快速安装

📥 下载与安装

下载最新版本
打开DMG文件并将TaskNote Bridge拖到“应用程序”中
启动应用程序 - MCP服务器会自动启动
使用以下设置配置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: 12.0+ (Monterey或更高版本)
Things 3: 从Mac App Store安装
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": "来自VS Code的问候！", "tags": ["测试"]}}}' | ./launch_swift_mcp_stdio.sh

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

# ✅ 检查Things 3 - 你的任务会在那里！

对于图形界面监控

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

🛠 完整特性集

原生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，VS Code带MCP扩展，Cursor，Continue，Zed等）
Things 3（必须在设置->常规中启用Things URL）
Apple Notes（用于笔记管理功能）
macOS 13.0或更新版本（需要SwiftUI和AppleScript集成）

🏗️ 项目架构

此项目提供了两种不同的MCP服务器实现，以适应不同的使用场景：

📱 TaskNote Bridge.app（GUI应用）

目的: 带有视觉监控界面的macOS应用
传输: TCP服务器（端口8000），用于网络连接
特性: 实时仪表板，连接监控，日志查看器
使用场景: 当你需要监控服务器活动的可视化界面时
启动: 从“应用程序”文件夹打开应用

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

目的: 基于标准输入输出的轻量级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服务器：

打开Claude Desktop
点击左下角的设置齿轮（⚙️）
选择“开发者”
在“MCP服务器”部分，点击“编辑配置”
添加以下配置：

{
    "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

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

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

🔧 VS Code带MCP扩展

在VS Code中安装MCP扩展：
- 打开VS Code扩展（Cmd+Shift+X）
- 搜索“Model Context Protocol”并安装
配置VS Code设置（settings.json）：

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

重启VS Code以加载MCP服务器

🖱️ Cursor IDE

打开Cursor设置（Cmd+,）
导航到扩展→ Model Context Protocol
添加服务器配置：

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

⚡ Continue（VS Code扩展）

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

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

🚀 Zed Editor

打开Zed设置（Cmd+,）
添加到你的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应用中配置）
协议: TCP带JSON-RPC 2.0

Stdio连接

命令: /Applications/TaskNote Bridge.app/Contents/Resources/launch_mcp_server.sh
传输: 标准输入输出带JSON-RPC 2.0

📋 验证步骤

配置任何客户端后：

测试连接：

# 对于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

检查可用工具 - 你应该看到如下的工具：
- bb7_add-todo
- bb7_add-project
- bb7_get-today
- bb7_notes-create
- 以及更多...

测试任务创建：

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

验证在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 URL是否在Things 3 -> 设置 -> 通用中启用

对于VS Code（带MCP扩展）

首先确保你已经安装并运行了TaskNote Bridge应用。
在VS Code中安装MCP扩展：
- 打开VS Code
- 转到扩展（Cmd+Shift+X）
- 搜索"MCP"并安装官方MCP扩展
配置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

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

使用

在TaskNote Bridge应用中

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

在Claude Desktop中

一旦连接，你可以使用自然语言与TaskNote Bridge进行交互：

Things 3示例：

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

Apple Notes示例：

"创建一个关于今天站会会议纪要的笔记"
"在我的笔记中搜索有关季度审查的内容"
"创建一个关于我想尝试的新餐厅的笔记"
"显示我所有带有旅行信息的笔记"

在VS Code中

安装并配置MCP扩展后：

打开命令面板（Cmd+Shift+P）
输入"MCP"以查看可用的MCP命令
使用"MCP: Call Tool"与Things工具交互
或者使用支持MCP的任何AI助手来访问你的Things数据

对于任何兼容MCP的工具

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

兼容的应用程序包括：

Claude Desktop
VS Code带MCP扩展
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   #