Xojo IDE Control

xojo-mcp

一个 MCP（Model Context Protocol）服务，可让 AI 助手直接控制 Xojo IDE。它通过 stdin/stdout 使用 JSON-RPC 通信，并通过 Unix 域套接字将 IDE 命令转发给正在运行的 Xojo IDE 进程。

关于名称的说明。 此 crate 之前以 xmcp 发布。为避免与 X 的（前身为 Twitter）无关框架 xmcp 混淆，它更名为 xojo-mcp。安装后的 二进制文件仍然名为 xmcp，因此现有配置可以继续使用。

仅支持 macOS。 xojo-mcp 通过 Unix 域套接字与 Xojo IDE 通信（/tmp/XojoIDE 或 /tmp/$XOJO_IPCPATH——请参阅选择要通信的 IDE）。不支持 Windows，也没有添加支持的计划。原因并不是 IDE 在 Windows 上缺少 IPC 机制：Xojo 的 IPCSocket 是框架抽象，在 Windows 上是一个本地主机 TCP 套接字，其端口由路径字符串推导，而非来自文件系统条目。原版 XMCP 本身是一个 Xojo 应用，因此框架免费提供了这种传输方式；此移植版直接使用线路协议，所以要支持 Windows 就意味着需要逆向工程未公开的路径到端口推导方式。Linux 尚未测试，并非明确排除——它和 macOS 一样使用 Unix 套接字，但调试和系统日志工具读取的是 macOS 专有来源。

致谢

这是 XMCP 的 Rust 移植版，原作者为 Øjvind Søgaard Andersen，最初使用 Xojo 编写。原项目采用 MIT 许可证。

快速开始

1. 安装

选项 A：预编译二进制文件（Apple Silicon）

每个版本都附带一个 aarch64-apple-darwin tarball，该文件使用 Developer ID 证书签名，经 Apple 公证，并附有独立的 minisign 签名。从 Releases 获取最新版本，进行验证，然后将二进制文件放到 PATH 中：

minisign -Vm xmcp-*-aarch64-apple-darwin.tar.gz \
    -P RWR7Jy43Mphvu+jrP2FynfYpR7WdP0PvQaSFKfXub7q9Sh7fjtyAX9GU
tar xzf xmcp-*-aarch64-apple-darwin.tar.gz
install -m 755 xmcp-*/xmcp ~/.cargo/bin/xmcp

.minisig 才是值得进行的验证，也是旁边的 .sha256 无法做到的：与它所验证的文件托管在一起的校验和文件，只能证明下载文件未损坏，因为任何有能力替换一个资源的人，也能替换另一个。签名由从未接触过发布服务器的密钥生成——上面命令中的密钥保存在此仓库的 minisign.pub 文件中。

minisign 可通过 MacPorts 安装（port install minisign）。验证成功后会显示可信注释，其中包含版本和签名日期。仍然会发布 .sha256，供有需要的人使用：

shasum -a 256 -c xmcp-*-aarch64-apple-darwin.tar.gz.sha256

该二进制文件使用 Developer ID 证书签名并经 Apple 公证，因此 Gatekeeper 会允许它直接运行。你也可以自行检查：

codesign -dvv ~/.cargo/bin/xmcp   # Authority: Developer ID Application …
codesign -vvv -R="notarized" --check-notarization ~/.cargo/bin/xmcp

（spctl 看起来是显而易见的选择，但其实并不适用：对于任何普通命令行二进制文件，无论是否经过公证，它都会回答 does not seem to be an app。）

公证票据无法装订到独立可执行文件上——stapler 只支持 .app、.dmg 和 .pkg——因此，首次运行时需要连接到 Apple 来验证票据。如果首次运行时必须处于离线状态，请手动清除隔离标记：

xattr -d com.apple.quarantine ~/.cargo/bin/xmcp

Intel Mac 不在支持范围内，请改为从源代码构建。

选项 B：从 crates.io 安装

cargo install xojo-mcp

crate 名称为 xojo-mcp；它安装的二进制文件名为 xmcp。

选项 C：从源代码构建

git clone https://codeberg.org/brechanbech/xojo-mcp.git
cd xojo-mcp
cargo install --path .

这会将 xmcp 二进制文件安装到 ~/.cargo/bin/xmcp。如果 ~/.cargo/bin 已在 PATH 中（Rust 安装程序默认会将它添加到其中），就完成了。运行以下命令进行验证：

xmcp --help

可选： usage-guide.md 会在编译时嵌入二进制文件中，因此 MCP 资源开箱即用。如果想修改指南而不重新构建，可以将副本放在二进制文件旁边——xmcp 会优先使用磁盘上的文件，而非嵌入的备用版本：

cp usage-guide.md ~/.cargo/bin/

2. 添加到 Claude Code

在任意终端中运行：

claude mcp add xmcp -- xmcp

或者手动将其添加到 Claude Code 设置中。打开 MCP 配置文件 （macOS 上为 ~/.claude/settings.json 或项目级的 .claude/settings.json），并添加：

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": []
    }
  }
}

要启用详细日志记录（写入 stderr，可在 Claude Code MCP 日志中查看）：

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": ["-v"]
    }
  }
}

3. 使用

1. 启动 Xojo IDE 并打开项目
2. 在项目目录中启动 Claude Code 会话
3. Claude 会自动发现 29 个 xmcp 工具和使用指南

4. 下载 Xojo 文档（推荐）

文档工具（search_docs、lookup_class、list_doc_topics）需要 本地 Xojo 文档副本。我们提供了一个脚本，可从 docs.xojo.com 下载文档：

scripts/update-xojo-docs.sh

此脚本会从 docs.xojo.com 下载 llms.txt 和 llms-full.txt，并将 完整文档拆分为 _sources/ 下的独立类文件。所有文件都会存放在 ~/Library/Application Support/Xojo/Xojo/<version>/Documentation/ 中， xmcp 会在启动时自动检测该目录。请定期重新运行脚本以获取文档更新—— Xojo 发布新版本时会刷新这些文件。

默认情况下，lookup_class 会返回经过整理的摘要：类描述及其成员表格， 并将 Sphinx 交叉引用标记解析为纯文本。摘要只有几千个字符，而原始页面 则有数万字符——单是 String 就超过 70,000 个字符。可通过 member 请求单个成员，或通过 full: true 请求未经处理的页面：

lookup_class(class_name: "String")                     # description + member tables
lookup_class(class_name: "String", member: "Middle")   # that member's entry alone
lookup_class(class_name: "String", full: true)         # the raw .rst.txt page

要改用自定义位置：

scripts/update-xojo-docs.sh /path/to/docs
xmcp --docs-path /path/to/docs

只读模式

默认情况下，连接到 xmcp 的助手可以更改你的项目：重写代码、创建新项目项、 保存和还原。这正是此工具的用途——但并非总是你想要的。如果你只想让助手 查看 项目——阅读代码、构建项目、运行项目、分析项目、回答问题、 查阅文档——而不允许它修改或覆盖源文件，请以只读模式启动服务。

只读模式由服务本身强制执行，而不是靠请求助手遵守。它是 xmcp 中最重要的 安全控制，因此值得了解其具体工作方式。

启用方式

最简单的方法是在启动命令中使用 --read-only 标志。在 Claude Code 中：

claude mcp add xmcp -- xmcp --read-only

或者，在 Claude Code 设置文件中（~/.claude/settings.json 或项目级的 .claude/settings.json）：

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": ["--read-only"]
    }
  }
}

如果你的 MCP 客户端更倾向于使用环境变量而非命令行参数， XMCP_READ_ONLY=1 的作用完全相同。接受的真值包括 1、true、yes 和 on （不区分大小写）：

{
  "mcpServers": {
    "xmcp": {
      "command": "xmcp",
      "args": [],
      "env": { "XMCP_READ_ONLY": "1" }
    }
  }
}

如果标志和环境变量同时存在，只要其中任意一个启用只读模式，就会生效—— 无法通过另一个将其禁用。

在启动时设置，而非在对话中设置

这是新手最容易弄错的地方。不要通过在聊天中告诉助手“只读”来 让它进入只读模式。 提示词只是对模型的请求，模型可能会忘记、误解， 或被说服而不再遵守——如果模型直接调用写入工具，它就完全不起作用。 只读模式正是为了消除这一弱点而存在的。

只读模式是服务启动方式的一项属性。你需要在会话开始前，在 MCP 客户端的 配置中设置一次。从那时起，在整个服务进程的生命周期内，此限制都会持续生效， 不受对话中输入内容的影响。你和助手都无法在会话中途切换此模式；要更改模式， 需要修改配置并重新连接服务。（必须重启服务，更改才能生效——已经运行的服务 不会读取新的标志或环境变量。）

它实际会阻止什么

只读模式会禁用十个可修改项目的工具：

工具	原本会执行的操作
set_code	覆盖方法、属性或其他项目项的代码
edit_code	替换项目项代码中的精确子字符串
set_selected_text	替换代码编辑器中的当前文本选区
set_declaration	重命名方法或属性，或更改其类型
create_project_item	添加新的类、模块、窗口或其他项目项
property_value	更改框架属性，例如 App.OptimizationLevel
constant_value	更改项目常量的值
get_item_description	更改项目项的描述
revert_project	放弃未保存的更改，恢复到上次保存的状态
save_project	将项目当前的内存状态写入磁盘

property_value、constant_value 和 get_item_description 也能读取，但每个都是一个工具，因此只读模式会连读取操作一起阻止。

工具注解

每个工具还会在 tools/list 中携带 MCP 行为提示，包括 title 和 readOnlyHint、destructiveHint、idempotentHint 及 openWorldHint，以便客户端决定调用前需要确认什么。这些只是提示，并非强制限制；它们描述的是工具对整台机器的影响，而非仅对项目的影响，因此限制比只读模式更严格：build_project、 run_project 和 agentic_run 不会改动源代码，在只读模式下仍可使用，但它们会写入构建输出或启动应用，因此不会被标记为只读。除了 run_ide_script 外，所有工具的 openWorldHint 均为 false；run_ide_script 中的 DoShellCommand 可以访问任何内容。

其他功能都仍可正常使用——浏览和列出项目项、读取代码（get_code）、构建（build_project）、运行（run_project）、停止、编译检查（analyze_project）、检查描述和常量、使用调试日志工具，以及使用全部三种文档工具。简而言之：浏览、构建、运行和分析——只是不能写入。

请注意，构建和运行操作有意不受阻止。它们不会更改源代码，只会对其进行测试。build_project 会在构建文件夹中写入已编译的应用，run_project 会启动调试会话，但两者都不会触及项目本身，因此都被视为在只读模式下安全。

强制执行方式

限制通过两个相互独立的层面实施，因此即使客户端或模型行为异常，也能生效：

1. 被阻止的工具会从工具列表中移除。 当助手向服务查询可用工具（tools/list）时，六个修改类工具会被筛除。模型看不到它们，因此无法选择调用自己不知道存在的工具。这使该模式在实际使用中真正有效，而不只是提供防护。
2. 任何对被阻止工具的调用都会遭到拒绝。 如果仍有对六个工具之一的请求到达——例如工具列表已过期、调用是手工构造的，或客户端有缺陷——服务会在请求到达 IDE 之前将其拒绝，并返回清晰的错误，说明该工具在只读模式下已禁用。

嵌入式使用指南也会告知助手：如果看到工具集缩减，就表示项目有意设为只读；它应使用可用工具完成工作，而不是试图绕过限制。

同时运行两种模式

由于模式按服务固定，你可以用不同名称注册两次 xmcp，并根据任务选择要交给助手使用的实例——例如，用普通的 xmcp 进行编辑会话，再用单独的 xmcp-ro 进行只读审查会话：

claude mcp add xmcp    -- xmcp
claude mcp add xmcp-ro -- xmcp --read-only

选择要连接的 IDE

IDE 会监听一个套接字，其路径由临时目录和名称 XojoIDE 组成；如果 IDE 环境中设置了 XOJO_IPCPATH，则使用该变量的值。将其设置为每个实例各不相同的名称，是 Xojo 支持的运行多个 IDE（例如，同时运行两个版本）并分别连接到每个实例的方式：

env XOJO_IPCPATH=Xojo2026r2_1 "/Applications/Xojo 2026 Release 2.1/Xojo.app/Contents/MacOS/Xojo" &

必须为 xmcp 指定相同的值，否则它会连接到占用默认 XojoIDE 套接字的实例：

{
  "mcpServers": {
    "xmcp-2026r2-1": {
      "command": "xmcp",
      "args": [],
      "env": { "XOJO_IPCPATH": "Xojo2026r2_1" }
    }
  }
}

名称只能包含 a-z、A-Z、0-9 和 _；如果值包含其他字符，xmcp 会忽略该值（并在 stderr 上显示警告），然后回退到 XojoIDE。候选目录依次为 /tmp（IDE 本身优先使用该目录）和 $TMPDIR（当 /tmp 不可写时，IDE 会回退到此目录）。

如果你一次只运行一个 IDE，可以忽略这些内容：默认设置即可正常工作。

要求

• macOS（Xojo IDE IPC 套接字仅适用于 macOS）
• Rust 工具链（rustup — https://rustup.rs）
• 使用任何工具前，必须先启动 Xojo IDE 并打开一个项目

选项

xmcp [OPTIONS]

• --read-only — 只读模式：隐藏并拒绝所有会修改项目的工具。也可以通过 XMCP_READ_ONLY=1 启用。完整说明请参阅只读模式。
• -v、--verbose — 启用详细日志并输出到 stderr
• -d、--docs-path <PATH> — Xojo 文档目录的路径（如果省略则自动检测）
• -V、--version — 打印版本
• -h、--help — 打印帮助

环境变量：XMCP_READ_ONLY（见上文）和 XOJO_IPCPATH，用于选择要连接的 IDE 实例 — 参阅选择要连接的 IDE。

与原版的区别

这是一个可直接替换的版本 — 它提供原版的全部 25 个工具，名称和参数均相同（最后移植的两个工具是 analyze_project 和 debug_control，现在已完全对齐），此外还新增了一个工具 edit_code，总计 26 个工具。它通过 Unix 域套接字使用相同的 IDE Communicator Protocol v2，并更新为 MCP 协议版本 2025-11-25。

显著区别：

• 二进制名称为 xmcp
• edit_code — 按目标执行 str_replace 风格的编辑 — 一次调用即可替换某个项目项代码中的精确子字符串（读取 → 替换 → 写入，全部在服务端完成），而不是通过 set_code 重新发送整个项目项。原版没有此工具，因此小幅编辑只能重写整个项目项，或使用基于 shell 的文本处理。
• 直接写入代码 — 无需通过 shell/base64 编组 — set_code 和 edit_code 会直接通过 IPC 发送源代码，所有 IDE 脚本字符串转义（引号、换行符、特殊字符）均由服务端处理。无需手动设法通过桥接传递代码 — 原版在编辑文件时强制使用的“Agent 端进行 base64 编码 / Mac 端解码 / 通过 shell 运行”工作流，在这里完全不存在。
• 强制执行只读模式 — --read-only / XMCP_READ_ONLY 会在服务端移除并拒绝可修改内容的工具。原版没有内置强制机制；只能通过提示词要求它不要写入。参阅只读模式。
• 无需 Xojo 许可证 — 使用标准 Rust 工具链即可构建
• 内置 usage-guide.md 的编译时备用副本 — 原版在二进制文件旁缺少该文件时会静默失败；Rust 版本会在编译时嵌入一份副本，因此 MCP 资源始终可用。磁盘上的文件仍优先使用，因此无需重新构建即可编辑该文件。
• CLI 解析使用 clap，而不是原版的自定义 OptionParser。标志相同。

工具

xmcp 提供 5 个类别的 29 个工具：

IDE 工具（22 个）： list_project_items, get_current_location, select_project_item, get_code, set_code, edit_code, get_selected_text, set_selected_text, build_project, run_project, stop_project, create_project_item, run_ide_script, get_project_info, revert_project, save_project, get_item_description, constant_value, property_value, set_declaration, analyze_project, debug_control

文档工具（3 个）： search_docs, lookup_class, list_doc_topics

调试工具（2 个）： get_debug_log, get_system_log

Agentic Mode（1 个）： agentic_run — 运行已启用 Xojo 2026r3 Agentic Mode 的项目，并返回带位置的编译错误。它通过项目文件夹中的文件运行，而不是通过 IDE 套接字，因此即使套接字不可用，也可以通过 project_dir 指定项目。

成本估算（1 个）： estimate_request_cost

许可证

MIT — 详情请参阅 LICENSE.md。

MCP 注册表

MCP 注册表 的所有权验证令牌（从 crates.io 上渲染的此 crate README 中读取）：

注册表所有权令牌：mcp-name: io.github.brechanbech/xojo-mcp

发布

版本发布后即不可更改——crates.io 可以撤回版本，但不会删除版本，版本号也永远不会重复使用——因此发布顺序很重要：

1. cargo test 和 cargo clippy --all-targets 均通过。

2. 更新 Cargo.toml 中的 version。

3. 更新 server.json 中的 version——包括两个字段：顶层字段和 packages[] 下的字段。没有任何机制会强制执行此操作：没有脚本、没有 CI，也没有测试会读取该文件。正因如此，该文件在 3.4.1 和 3.5.0 版本发布期间仍保持 3.4.0，导致注册表展示的版本比用户实际可安装的版本落后两个版本。

4. 提交并推送；发布前等待 CI 通过，而不是发布后再等。

5. 运行 cargo publish --dry-run，它会从打包后的副本进行编译，因此能发现 crate 依赖了未随包发布的文件。然后运行 cargo publish。

6. 发布到 MCP 注册表，必须在 crates.io 发布之后，不能提前——注册表会从此 crate 在 crates.io 上渲染后的 README 中读取 mcp-name 来验证命名空间，并且 server.json 指定的 cargo 版本必须已在 crates.io 上发布：

   mcp-publisher validate      # checks server.json against the live registry
   mcp-publisher login github  # interactive, for the io.github.brechanbech/* namespace
   mcp-publisher publish