3dstreet

3dstreet-mcp

一种 Model Context Protocol 中继，可让 Claude Desktop 或 Claude Code 操控浏览器中运行的 3DStreet 场景。

这是合适的工具吗？ 对于无法使用 WebMCP 的 MCP 客户端，此中继是备用方案。如果你的 Agent 在浏览器内运行（ChatGPT 桌面浏览器、Chrome 中的 Gemini、启用了 WebMCP 源试用功能或 chrome://flags/#enable-webmcp-testing 的 Chrome 149+），则不需要此软件包：打开 https://3dstreet.app，页面会通过 document.modelContext 向浏览器注册相同的工具——无需安装，也无需配对。请参阅 3DStreet WebMCP 文档。仅当客户端没有自己的浏览器或不支持 WebMCP 时，才使用此中继（Claude Desktop、Claude Code、Cursor、无头脚本）。这些客户端原生支持 WebMCP 后，此中继将停用。

已在 MCP Registry 中以 app.3dstreet/3dstreet 登记。

状态：alpha — 协议可能会变更。跟进 3DStreet#1582（设计）和 3DStreet#1600（浏览器端）。在任意 3dstreet.app 标签页中均可创建场景；保存和地理空间功能需要免费的 3DStreet 帐户。

工作原理

Claude Desktop  ── stdio MCP ──▶  3dstreet-mcp  ── ws://127.0.0.1:51735 ──▶  3DStreet tab
or Claude Code                    (this package)                              (your browser)

中继通过标准输入/输出与 MCP 通信，并通过 localhost WebSocket 将每个 tools/list 和 tools/call 请求转发到 3DStreet 标签页。实际工作由标签页完成——它已登录、已加载目录，并负责云端保存流程。中继只是一个简单的管道。

WebSocket 不会传递任何身份验证令牌。中继端口仅绑定到 127.0.0.1，并拒绝来自 3DStreet 允许列表之外源的 WebSocket 升级请求（https://3dstreet.app、https://dev-3dstreet.web.app、http://localhost:3333、http://127.0.0.1:3333）。

设置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "3dstreet": {
      "command": "npx",
      "args": ["-y", "3dstreet-mcp"]
    }
  }
}

重启 Claude Desktop。

Claude Code

claude mcp add 3dstreet -- npx -y 3dstreet-mcp

配对浏览器标签页

启动时，中继会在日志中打印自动配对 URL，例如：

open this URL to pair a 3DStreet tab: https://3dstreet.app/#mcp

在已登录的浏览器中打开该 URL，编辑器便会检测到 #mcp 片段，打开 AI Assistant 窗格，并自动与中继配对——无需使用控制台命令。（如果你在非默认端口上运行中继，URL 格式为 https://3dstreet.app/#mcp=PORT。）

如果你更愿意手动配对：打开 https://3dstreet.app，点击右侧面板中的 AI Assistant，输入 /mcp，然后点击 Reconnect。

现在你可以向 Claude 提出如下请求：

• “当前场景里有什么？”
• “在街道左侧添加一条自行车道。”
• “将环境预设更改为夜晚。”

在状态栏中切换 Read-only，即可阻止场景修改 （如果你只是想让 Claude 讲解场景，这会很有用）。

命令行界面

3dstreet-mcp [options]

Options:
  -p, --port <number>    WebSocket port (default 51735)
  -o, --origin <url>     Origin used in the printed auto-pair URL and
                         the MCP `instructions` hint (default
                         https://3dstreet.app — set to
                         http://localhost:3333 when running 3DStreet
                         from a local dev server)
  -h, --help             Show this help
  -v, --version          Print version and exit

如果需要使用不同端口（例如，让两个 Claude 客户端分别连接两个不同的标签页），请传入 --port，并打开中继打印的自动配对 URL——https://3dstreet.app/#mcp=PORT——该 URL 会选择相应端口并触发自动配对。

在本地开发 3DStreet 时，将 --origin 指向开发服务器，使打印出的 URL 和大模型的 instructions 提示都能指向正确的标签页：

node src/cli.js --origin http://localhost:3333
# → open this URL to pair a 3DStreet tab: http://localhost:3333/#mcp

告知大模型如何配对

中继会在每次 initialize 时返回一个 instructions 字符串（这是可选的 MCP 字段，客户端可以将其合并到大模型的系统提示词中）。该字符串会说明场景工具会转发到已配对的标签页，提供自动配对 URL，并告知模型在没有标签页连接时将此 URL 显示给用户——这样，大模型会主动引导用户完成配对，而不是等待一个不明原因的工具调用超时。

如果此中继会话中从未配对过任何标签页，tools/call 也会在错误消息中返回自动配对 URL 并立即失败，而不是排队等待 30 秒。标签页配对后，短暂断连时会恢复排队重试行为，以便重新连接的对等端处理完正在执行的调用。

暴露的工具

工具列表会从配对的浏览器标签页获取，因此始终与编辑器命令注册表所提供的内容一致。截至 #1600，包括：

• 读取： getScene、getEntity、getSelectedEntity、 getManagedStreet、listMixins、getSessionInfo
• 选择 / 摄像机： selectEntity、focusCamera
• 修改： entityCreate、entityUpdate、entityRemove、 entityClone、entityReparent、componentAdd、componentRemove、 segmentAdd、segmentUpdate、segmentRemove、replaceManagedStreet、 ……以及注册表中的其余工具
• 历史记录： undo、redo

在 MCP 客户端中运行 tools/list，查看当前可用的工具。

线协议（面向贡献者）

Stdio 端：以换行符分隔的 JSON-RPC 2.0，MCP 2024-11-05。

WebSocket 端：使用相同的 JSON-RPC 封装，由中继在本地处理 initialize / ping / 通知，并仅将 tools/list 和 tools/call 转发给对端。对端会为收到的帧分配自己的 ID；响应按 ID 匹配。

单对端策略：第一个连接的浏览器标签页占用连接槽位。 第二个连接会收到 WebSocket 关闭代码 4001，原因是 paired-elsewhere。

开发

git clone https://github.com/3DStreet/3dstreet-mcp.git
cd 3dstreet-mcp
npm install
npm test

针对真实的 3DStreet 构建进行冒烟测试：

# Terminal 1 — the relay, REPL-free, just stdio
node src/cli.js

# Terminal 2 — exercise it with the MCP inspector
npx @modelcontextprotocol/inspector node src/cli.js

许可证

AGPL-3.0-or-later，与 3DStreet 本身相同。