STARWARCLOUD STARWAR.AI
返回市场
熔炉箱-MCP

熔炉箱-MCP

作者：phkus5 星标更新：2025-11-07
安装使用来源：spider==github.com

项目介绍

Tinderbox MCP Server

这是一个模型上下文协议（MCP）服务器，使像Claude这样的AI助手能够与Tinderbox进行交互，Tinderbox是一款强大的macOS知识管理应用程序。这使得你可以使用自然语言控制Tinderbox，并将其连接到助手可以访问的其他服务。在后台，它使用Tinderbox的AppleScript集成来创建和更新笔记并导航文档层次结构。

🔄 迁移通知：版本 0.2.0

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

为什么选择Python？

Python重写实现了基于HTTP的远程访问，允许你：

  • 使用连接器从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-m
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
      • 主页URL：http://localhost:8000
      • 授权回调URL：http://localhost:8000/oauth/callback
    • 保存你的Client ID和Client Secret

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

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

    cp .env.example .env
# 编辑.env文件，填入你的凭证

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

    export GITHUB_CLIENT_ID="your_client_id"
export GITHUB_CLIENT_SECRET="your_client_secret"
export DEFAULT_DOCUMENT="YourDocument"  # 不带.tbx扩展名

    方法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，则设置DEFAULT_DOCUMENT=Research
    • 留空则每次请求时指定文档
  • APPLESCRIPT_DIR：AppleScript文件路径（默认：./applescripts）
  • SERVER_PORT：服务器端口（默认：8000）
  • SERVER_HOST：服务器主机（默认：localhost）

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

运行服务器

在终端中启动服务器：

source venv/bin/activate  # 如果尚未激活
python src/server.py

你应该看到如下输出：

正在 http://localhost:8000 上启动Tinderbox MCP Server
MCP端点：http://localhost:8000/mcp
AppleScript目录：/path/to/applescripts
默认文档：YourDocument

在Claude设置中添加此URL作为连接器：
  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工具

远程访问（高级）

要从任何地方（而不仅仅是本地主机）访问你的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认证进行远程访问。不要在超出本地主机的情况下禁用认证。

示例用法

一旦配置好，你可以要求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以获取详细的开发说明。

发展路线图

  • 迁移到Python并使用HTTP传输
  • 添加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的applescript-mcp服务器的启发。这两个服务器之间的主要区别在于，applescript-mcp将完整的AppleScript内容传递给终端，而这里的实现调用了独立的脚本文件，解决了参数中特殊字符如引号的问题。

感谢Tinderbox开发者Mark Bernstein，他使这款应用具备了可编程性。

许可

MIT

贡献

欢迎在此处贡献或通过Tinderbox论坛（用户名：pkus）向我提供反馈。

这基本上只是一个执行AppleScript的服务器。因此，它可以被改编成在MacOS上做任何其他可编程的事情。

注：对于TypeScript版本的文档，请参阅typescript分支。