Tinderbox MCP Server

Tinderbox MCP 服务

一个模型上下文协议（MCP）服务，可让 Claude 等 AI 助手与 macOS 上功能强大的知识管理应用 Tinderbox 交互。这样，你就可以用自然语言控制 Tinderbox，并将其连接到助手有权访问的其他服务。它在后台使用 Tinderbox 的 AppleScript 集成来创建和更新便笺，以及浏览文档层级结构。

🔄 迁移通知：版本 0.2.0

0.2.0 及更高版本已使用 Python 重写，并采用 HTTP 传输方式实现远程访问。

为什么使用 Python？

Python 重写版本支持基于 HTTP 的远程访问，让你能够：

• 使用 Connectors 从 Claude 移动应用连接
• 通过 Tailscale 或 Ngrok 随时随地访问 Tinderbox 服务
• 安全地与团队成员共享 Tinderbox 服务
• 使用现代 OAuth 身份验证（GitHub）确保安全访问

现有用户须知

• TypeScript 版本 0.1.x 仍可在 typescript 分支中使用
• 工具功能没有破坏性变更——所有工具的工作方式都相同
• AppleScript 文件保持不变——.scpt 文件未作修改
• 迁移指南请参阅 UPGRADE.md

---

包含的 Tinderbox 操作

该服务包含用于执行以下 Tinderbox 操作的工具：

• create_note - 在文档中创建新便笺
• link_notes - 在现有便笺之间创建链接，可指定链接类型
• update_attributes - 更改指定便笺的属性值
• read_note - 获取便笺内容（目前仅包括便笺标题和文本）
• get_siblings - 查找同一层级的便笺（此工具及后续工具会返回便笺路径及其 ChildCount，让助手知道还可以继续探索哪些内容）
• get_children - 获取指定父便笺的所有子便笺
• get_links - 查找便笺的所有外出链接

所有这些操作都需要模型知道要使用哪个文档。可以配置默认文档（请参阅下文的配置部分）。

前提条件

• Tinderbox
• macOS（用于 Tinderbox AppleScript 集成）
• Python 3.10 或更高版本
• GitHub 账户（用于 OAuth 身份验证）
• 兼容 MCP 的客户端（已使用 Claude Desktop 和 Claude Mobile 测试）

安装

1. 克隆此仓库：

git clone https://github.com/phkus/tinderbox-mcp.git
cd tinderbox-mcp

2. 创建虚拟环境：

python3 -m venv venv
source venv/bin/activate

3. 安装依赖项：

pip install -r requirements.txt

4. 设置 GitHub OAuth App：

   • 前往 https://github.com/settings/developers
   • 点击“New OAuth App”
   • 填写以下信息：
     • 应用名称：Tinderbox MCP
     • 主页 URL：http://localhost:8000
     • 授权回调 URL：http://localhost:8000/oauth/callback
   • 保存 Client ID 和 Client Secret

5. 配置服务（选择一种方式）：

   方式 A：使用 .env 文件（推荐大多数用户使用）

   cp .env.example .env
   # Edit .env with your credentials
   

   方式 B：导出环境变量（适合测试）

   export GITHUB_CLIENT_ID="your_client_id"
   export GITHUB_CLIENT_SECRET="your_client_secret"
   export DEFAULT_DOCUMENT="YourDocument"  # Without .tbx extension
   

   方式 C：启动时内联设置（适合快速单次测试）

   GITHUB_CLIENT_ID="your_id" GITHUB_CLIENT_SECRET="your_secret" DEFAULT_DOCUMENT="YourDocument" python src/server.py
   

配置

必需设置

• GITHUB_CLIENT_ID：GitHub OAuth App 的客户端 ID
• GITHUB_CLIENT_SECRET：GitHub OAuth App 的客户端密钥

可选设置

• DEFAULT_DOCUMENT：Tinderbox 文档名称，不含 .tbx 扩展名
  • 示例：如果文件名为 Research.tbx，则设置 DEFAULT_DOCUMENT=Research
  • 留空即可在每次请求中指定文档
• APPLESCRIPT_DIR：AppleScript 文件路径（默认值：./applescripts）
• SERVER_PORT：服务端口（默认值：8000）
• SERVER_HOST：服务主机（默认值：localhost）

注意：可以通过三种方式设置环境变量（请参阅上文安装步骤 5）。.env 文件是最方便的永久配置方式。

运行服务

在终端中启动服务：

source venv/bin/activate  # If not already activated
python src/server.py

你应该会看到类似以下的输出：

Starting Tinderbox MCP Server on http://localhost:8000
MCP endpoint: http://localhost:8000/mcp
AppleScript directory: /path/to/applescripts
Default document: YourDocument

Add this URL as a Connector in Claude settings:
  http://localhost:8000/mcp

请保持此终端窗口开启——服务需要持续运行才能处理请求。

与 Claude 配合使用

Claude Desktop

1. 打开 Claude Desktop 设置
2. 前往“连接器”部分
3. 点击“添加连接器”
4. 输入 URL：http://localhost:8000/mcp
5. 按提示使用 GitHub 进行身份验证
6. 现在即可使用 Tinderbox 工具

Claude Mobile

1. 打开 Claude 应用设置
2. 前往“连接器”
3. 添加新的连接器，URL 为：http://localhost:8000/mcp
4. 在浏览器中完成 GitHub OAuth
5. 开始在对话中使用 Tinderbox 工具

远程访问（高级）

如需从任何位置（而不只是 localhost）访问你的 Tinderbox 服务：

选项 1：Tailscale（推荐，安全性更高）

• 在 Mac 和移动设备上安装 Tailscale
• 两台设备将共享一个专用网络
• 在连接器 URL 中使用 Tailscale IP 代替 localhost
• 示例：http://100.x.x.x:8000/mcp

选项 2：Ngrok（临时公开访问）

• 安装 Ngrok
• 运行：ngrok http 8000
• 在 Claude 连接器中使用 ngrok URL
• 示例：https://abc123.ngrok.io/mcp
• 注意：免费 ngrok URL 在重启后会变化

安全提示：远程访问时务必使用 OAuth 身份验证。将服务暴露到 localhost 以外时，切勿禁用身份验证。

使用示例

配置完成后，你可以让 Claude 处理 Tinderbox 文档：

• “在 Tinderbox 文档‘Research project’中，根据我们对话的要点创建笔记。”
• “在 Tinderbox 文档‘Research project’中，查看笔记‘path/to/note’的子笔记并建议建立关联。创建链接前请先向我确认。”
• “在 Tinderbox 文档‘Research project’中，创建一张复现我上传图片的图表。你可以使用‘Xpos’和‘Ypos’属性设置 Tinderbox 地图上笔记的位置。X 从左到右递增，Y 从上到下递增。两者都可以为负数，而且地图没有实际边界，但通常可以将左上角设为 0 和 0，右下角设为约 40 和 40。可以通过将‘Color’属性改为十六进制代码来为笔记着色。”

警告

update_attribute 工具允许助手覆盖现有笔记的属性，包括 Name 和 Text 属性。提供给模型的工具说明要求谨慎使用此工具，但仍可能导致内容丢失。请备份 Tinderbox 文档。

这是唯一能够更改现有笔记内容的工具，因为 create_note 只会在同一容器中创建一个同名的新笔记。为提高安全性，你可以删除配置中的对应条目或脚本文件，以移除 update_attribute 工具。也可以修改 AppleScript，使其只允许编辑没有值的属性。

扩展服务

即使服务正在运行，也可以随时编辑 applescripts 文件夹中的现有脚本文件。要添加自定义 Tinderbox 操作，必须重启服务：

1. 在与其他文件相同的位置创建一个新的 AppleScript（.scpt）文件
2. 在 src/server.py 中使用 @mcp.tool() 装饰器添加工具定义
3. 重启服务

详细的开发说明请参阅 CLAUDE.md。

路线图

• 迁移到使用 HTTP 传输的 Python
• 添加 GitHub OAuth 身份验证
• 将目前属于主代码一部分的工具配置移至单独的文件
• 添加一个工具，让助手能够概览文档的部分内容或全文，类似于“导出 -> 作为大纲”
• 为 DEVONthink 添加类似的服务
• 为 Bookends 添加类似的服务

故障排除

服务无法启动

“GitHub OAuth 凭据必需”

• 确保你已创建 GitHub OAuth 应用
• 设置 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET 环境变量
• 检查 .env 文件中的值是否正确

“AppleScript 目录不存在”

• 确认项目根目录中存在 applescripts/ 文件夹
• 如果你移动了脚本，请检查 APPLESCRIPT_DIR 环境变量

工具无法正常工作

“找不到文稿”

• 确保 Tinderbox 文稿已在 Tinderbox 中打开
• 确认 DEFAULT_DOCUMENT 与文稿名称完全一致（不含 .tbx）
• 文稿名称区分大小写

“找不到脚本”

• 确认 applescripts/ 目录中存在所有 .scpt 文件
• 检查文件权限是否允许读取

连接问题

无法从 Claude 连接

• 确认服务正在运行（检查终端窗口）
• 在浏览器中测试 URL：http://localhost:8000/mcp
• 检查防火墙是否阻止了端口 8000
• 如需远程访问，请确认已正确配置 Tailscale/Ngrok

致谢

本项目的灵感来自 Josh Rutkowski 的 applescript-mcp 服务。两个服务的主要区别在于，applescript-mcp 会将 AppleScript 的完整内容传递给终端，而本实现会调用单独的脚本文件，从而解决了参数中引号等特殊字符引发的一些问题。

感谢 Tinderbox 的开发者 Mark Bernstein，感谢他让这款应用支持脚本化操作。

许可证

MIT

贡献

欢迎在此处贡献，或在 Tinderbox 论坛上向我反馈（用户名：pkus）。

这基本上只是一个执行 AppleScript 的服务。因此，它也可以调整为执行 MacOS 上任何其他可脚本化的操作。

---

注意：TypeScript 版本的文档请参阅 typescript branch。