tbx MCP

增强型Tinderbox MCP服务器

一个独立的MCP（模型上下文协议）服务器 火药桶 它提供了11个工具，用于通过AppleScript读取、创建和操作笔记、链接和属性。与Tinderbox捆绑的MCP服务器不同，tbx-MCP作为一个单独的进程运行，使其可用于容器、远程环境和任何兼容MCP的客户端。

需求

• 火药桶 已安装（11.6.0或更高版本）
• Ruby 3.1+与Bundler

安装Ruby

如果您没有安装Ruby（或需要更新版本），请通过以下方式安装 家酿:

brew install ruby

安装后，按照Homebrew打印的说明将Homebrew的Ruby添加到PATH中。通常：

echo 'export PATH="/opt/homebrew/opt/ruby/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

验证安装并安装Bundler Gem：

ruby --version
gem install bundler

安装

git clone  tbx-mcp
cd tbx-mcp
bundle install

设置

克劳德桌面

将以下内容添加到您的Claude Desktop配置文件中：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tinderbox": {
      "command": "ruby",
      "args": ["/full/path/to/tbx-mcp/server.rb"]
    }
  }
}

替换 /full/path/to/tbx-mcp 使用克隆存储库的实际路径。

保存配置后重新启动Claude Desktop。

克劳德代码

将服务器添加到Claude Code项目设置或全局设置中：

项目级别 （建议添加到 .claude/settings.json 在项目根目录中）：

{
  "mcpServers": {
    "tinderbox": {
      "command": "ruby",
      "args": ["/full/path/to/tbx-mcp/server.rb"]
    }
  }
}

全球 （适用于所有项目-添加到 ~/.claude/settings.json):

{
  "mcpServers": {
    "tinderbox": {
      "command": "ruby",
      "args": ["/full/path/to/tbx-mcp/server.rb"]
    }
  }
}

保存后，重新启动Claude Code或运行 /mcp 重新连接。

验证

一旦连接，服务器就会公开11个工具和6个参考资源。在Claude Code中，您可以通过以下方式进行验证 /mcp --你应该看看 tinderbox 列出了它的工具。

工具

所有操作文档的工具都需要 document 参数（文档名称）。使用 get_document 首先发现打开的文档名称。

这 get_reference 该工具提供对详细文档的按需访问。可用主题： action-attributes, action-functions, adornments, export-codes, expressions, system-containers.

资源

服务器将详细的Tinderbox参考文档作为MCP资源公开。仅当需要更深入的引用时，LLM才会按需加载这些内容。

情境感知设计

该服务器旨在通过两层架构最大限度地减少上下文窗口的消耗：

始终存在（约3400个代币，占20万代币的1.7%）

这些说明提供了一个精心策划的快速参考，涵盖了表达式语法、30多个关键属性、动作代码模式、日期格式代码和11个常见陷阱。

按需资源（约26000个代币，仅在需要时加载）

预算汇总表

即使在加载了所有资源的最坏情况下，服务器也会保持 15% 20万个上下文窗口——为对话留下17万多个令牌。

运行测试

测试套件要求Tinderbox在运行时至少打开一个文档。

bundle exec rake test

该套件包括59个测试，涵盖所有工具、AppleScript帮助程序和跨工具一致性检查。测试笔记前缀为 [MCP-TEST] 并自动清理。

建筑

.
|-- Gemfile
|-- Rakefile
|-- README.md
|-- server.rb
|-- lib
|   |-- apple_script_helper.rb
|   |-- tinderbox_mcp.rb
|   `-- tinderbox_mcp
|       |-- create_link.rb
|       |-- create_note.rb
|       |-- do_action.rb
|       |-- evaluate.rb
|       |-- get_document.rb
|       |-- get_notes.rb
|       |-- get_view.rb
|       |-- instructions.rb
|       |-- open_document.rb
|       `-- set_value.rb
|-- references
|   |-- action-attributes.md
|   |-- action-functions.md
|   |-- export-codes.md
|   |-- expressions.md
|   `-- system-containers.md
`-- test
    |-- apple_script_helper_test.rb
    |-- consistency_test.rb
    |-- create_link_test.rb
    |-- create_note_test.rb
    |-- do_action_test.rb
    |-- evaluate_test.rb
    |-- get_document_test.rb
    |-- get_notes_test.rb
    |-- get_view_test.rb
    |-- open_document_test.rb
    |-- set_value_test.rb
    `-- test_helper.rb

设计决策

• 版本无关的AppleScript：所有脚本都使用 tell application id "Cere" 而不是 tell application "Tinderbox 11"，因此该服务器适用于任何Tinderbox版本。
• 明确的文档定位：每个工具都需要一个 document 参数--否 front document 可能针对错误窗口的调用。
• set_value没有操作代码：值是通过AppleScript设置的 attribute of API绕过Tinderbox在操作字符串中缺少引号转义。
• 无状态：没有服务器端状态。每个工具调用都是自包含的。

许可证

麻省理工学院