Tinderbox MCP Server

Tinderbox MCP服务器

一个模型上下文协议（MCP）服务器，使像克劳德这样的人工智能助手能够与 火药桶，适用于macOS的强大知识管理应用程序。这允许您使用自然语言控制Tinderbox，并将其连接到助手可以访问的其他服务。在后台，它使用Tinderbox的AppleScript集成来创建和更新笔记，并浏览文档的层次结构。

🔄 迁移通知：版本0.2.0

0.2.0+版本已经用Python重写，使用HTTP传输进行远程访问。

为什么是Python？

Python重写使 基于HTTP的远程访问，允许您：

• 使用连接器从Claude Mobile应用程序连接
• 通过Tailscale或Ngrok从任何地方访问您的Tinderbox服务器
• 与团队成员安全共享您的Tinderbox服务器
• 使用现代OAuth身份验证（GitHub）进行安全访问

对于现有用户

• TypeScript版本0.1.x 仍然可以在 typescript 分支
• 没有突破性的变化 工具功能-所有工具的工作方式相同
• 相同的AppleScript文件 -the .scpt 文件未更改
• 看 升级.md 迁移指南

______________________________________________________________________

包括Tinderbox操作

服务器包括用于这些Tinderbox操作的工具：

• create_note -在文档中创建新注释
• link_notes -在现有笔记之间创建链接，可以选择链接类型
• update_attributes -更改指定注释的属性值
• read_note -检索笔记的内容（目前仅检索笔记的标题和文本）
• get_siblings -查找同一层次级别的笔记（此工具和以下工具返回笔记的路径及其ChildCount，让助手知道可以在哪里进一步探索）
• get_children -获取指定父注释的所有子注释
• get_links -查找笔记中的所有传出链接

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

先决条件

• 火药桶
• 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

1. 创建虚拟环境：

python3 -m venv venv
source venv/bin/activate

1. 安装依赖项：

pip install -r requirements.txt

1. 设置GitHub OAuth应用程序：

- 首选https://github.com/settings/developers - 点击“新建OAuth应用程序” - 填写： - 应用程序名称： Tinderbox MCP - 主页网址： http://localhost:8000 - 授权回调URL: http://localhost:8000/oauth/callback - 保存您的客户端ID和客户端密码

1. 配置服务器（选择一种方法）：

方法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应用程序客户端ID
• GITHUB_CLIENT_SECRET：您的GitHub OAuth应用程序客户端密钥

可选设置

• DEFAULT_DOCUMENT：Tinderbox文档的名称 没有.tbx扩展名

- 示例：如果您的文件是 Research.tbx，set 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

保持此终端窗口打开 -服务器需要保持运行以处理请求。

与克劳德一起使用

克劳德桌面

1. 打开克劳德桌面设置
2. 转到“连接器”部分
3. 点击“添加连接器”
4. 输入URL： http://localhost:8000/mcp
5. 在提示时使用GitHub进行身份验证
6. Tinderbox工具现在将可用

克劳德·莫比尔

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

远程访问（高级）

要从任何地方（而不仅仅是本地主机）访问您的Tinderbox服务器：

选项1：尾秤 （出于安全考虑建议）

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

选项2:Ngrok （临时公共访问）

• 安装 哔哔
• 运行： ngrok http 8000
• 在Claude连接器中使用ngrok URL
• 例子： https://abc123.ngrok.io/mcp
• 注意：重新启动时免费的ngrok URL会更改

安全说明：始终使用OAuth身份验证进行远程访问。在本地主机之外暴露服务器时，切勿禁用身份验证。

示例用法

配置后，您可以让Claude处理您的Tinderbox文档：

• “在Tinderbox文档‘研究项目’中，根据我们谈话的要点创建笔记。”
• “在Tinderbox文档‘研究项目’中，探索笔记‘path/to/note’的子项，并建议连接。在创建链接之前，请与我确认链接。”
• “在Tinderbox文档‘研究项目’中，创建一个图表来再现我上传的图像。你可以使用‘Xpos’和‘Ypos’属性在Tinderbbox地图上设置笔记的位置。X从左到右，Y从上到下。两者都可以有负数，地图也没有真正的边界，但作为一般准则，你可以假设左上角为0和0，右下角约为40和40。注释可以通过更改十六进制代码中的“Color”属性来着色。"

警告

这 update_attribute 该工具允许助手覆盖现有笔记的属性，包括“名称”和“文本”属性。提供给模型的工具描述要求它对此保持谨慎，但这仍然可能导致内容丢失。保留Tinderbox文档的备份。

这是唯一可以更改现有笔记内容的工具，因为 create_note 将在同一容器中创建一个同名的新笔记。为了增加安全性，您可以删除 update_attribute 通过删除配置或脚本文件中的条目，可以使用该工具。或者，可以将AppleScript更改为只允许编辑没有任何值的属性。

扩展服务器

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

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

看 CLAUDE.md 详细的开发说明。

路线图

• \[x\] 使用HTTP传输迁移到Python
• \[x\] 添加GitHub OAuth身份验证
• \[\]将当前作为主代码一部分的工具配置移动到单独的文件中
• \[\]一个工具，为助手提供文档部分或全部的概述，类似于导出->作为大纲
• \[\]为DEVONthink添加一个类似的服务器
• \[\]为Bookends添加类似的服务器

故障排除

服务器无法启动

“需要GitHub OAuth凭据”

• 确保您已创建GitHub OAuth应用程序
• 集 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET 环境变量
• 检查你的 .env 文件具有正确的值

“AppleScript目录不存在”

• 验证 applescripts/ 文件夹存在于项目根目录中
• 检查 APPLESCRIPT_DIR 移动脚本时的环境变量

工具不工作

“找不到文档”

• 确保Tinderbox文档已在Tinderbox中打开
• 验证 DEFAULT_DOCUMENT 与文档名称完全匹配（不带.tbx）
• 文档名称区分大小写

“找不到脚本”

• 全部验证 .scpt 文件存在于 applescripts/ 目录
• 检查文件权限是否允许读取

连接问题

无法从Claude连接

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

致谢

这个项目的灵感来自Josh Rutkowski的 应用程序描述mcp 服务器。这两个服务器之间的主要区别在于，applescript-mcp将applescript的全部内容传递给终端，而此实现调用单独的脚本文件，这解决了参数中引号等特殊字符的一些问题。

感谢Tinderbox的开发者Mark Bernstein使该应用程序可脚本化。

许可证

麻省理工学院

贡献

欢迎在此处或通过在Tinderbox论坛上向我发送反馈来做出贡献（用户名：pkus）。

这基本上只是一个执行AppleScript的服务器。因此，它可以适应在MacOS上编写脚本的任何其他操作。

______________________________________________________________________

备注：有关TypeScript版本文档，请参阅 typescript 分支.