使用说明

MCP浏览器世界

A. 模型上下文协议（MCP） 将LLM代理连接到基于浏览器的框架 3D引擎。它将场景对象（相机、灯光、网格、传感器等）暴露为MCP资源工具，让客户喜欢 克劳德代码 或 MCP检查员 检查和通过标准JSON-RPC接口操纵实时3D场景。

该框架的核心是与引擎无关的，并附带了适配器 Babylon.js 和 铯JS.

空间视图 --该项目是《空间视图书，其中包括空间MCP工具背后的愿景、概念和路线图。

快速启动

# 1. Clone & install
git clone https://github.com/pandaGaume/mcp-browser-world.git
cd mcp-browser-world
npm install

# 2. Build everything (TypeScript → UMD bundles → deploy)
npm run build:all:dev

# 3. Start the tunnel server (opens browser automatically)
npm run server:start

开发线束在以下位置打开 http://localhost:3000/。单击开始连接将浏览器端MCP服务器连接到隧道，然后将MCP客户端指向显示端点。

建筑

┌──────────────────────────────────────────────────────────────────────┐
│                        MCP Clients                                   │
│   Claude Code  ·  MCP Inspector  ·  any MCP-compatible agent         │
└──────────┬───────────────────────────────────────────────────────────┘
           │  POST /mcp   (Streamable HTTP, MCP 2025-03-26)
           │  GET  /sse   (SSE stream,      MCP 2024-11-05)
           ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     WsTunnel  (Node.js)                 @dev/tunnel  │
│            HTTP / HTTPS relay  ←→  WebSocket bridge                  │
└──────────┬───────────────────────────────────────────────────────────┘
           │  ws://localhost:3000/provider  (wss:// with TLS)
           ▼
┌──────────────────────────────────────────────────────────────────────┐
│                  McpServer  (browser page)                           │
│                                                                      │
│  ┌──────────┐  ┌───────────┐  ┌───────────┐                          │
│  │  Camera  │  │   Light   │  │   Mesh    │   ← Behaviors            │
│  │ Behavior │  │ Behavior  │  │ Behavior  │     (@dev/behaviors)     │
│  └────┬─────┘  └─────┬─────┘  └─────┬─────┘                          │
│       │              │              │                                │
│  ┌────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐  ┌───────────┐          │
│  │ Babylon  │  │  Babylon  │  │  Babylon  │  │  Filters  │ optional │
│  │ Adapter  │  │  Adapter  │  │  Adapter  │  │ Pipeline  │ @dev/    │
│  └──────────┘  └───────────┘  └───────────┘  │ (Workers) │ filters  │
│       │              │              │         └─────┬─────┘          │
│       └──────────────┴──────────────┴───────────────┘                │
│                      │                                               │
│              ┌───────┴────────┐                                      │
│              │  Babylon.js /  │   ← 3D Engine                        │
│              │   CesiumJS     │                                      │
│              └────────────────┘                                      │
└──────────────────────────────────────────────────────────────────────┘

分层设计

层	包	角色
核心	`@dev/core`	与传输无关的MCP服务器SDK：接口、基类、， `McpServer`, `McpServerBuilder`, `McpGrammar`
大地测量学	`@dev/geodesy`	坐标系（WGS84、ECEF、ENU）、椭球体、地理↔ 笛卡尔转换。自给自足，不依赖MCP
行为	`@dev/behaviors`	与引擎无关的场景行为： `McpCameraBehavior`, `McpLightBehavior`, `McpMeshBehavior` 具有工具/资源定义
巴比伦适配器	`@dev/babylon`	Babylon.js特定的适配器将行为映射到 `@babylonjs/core` 场景对象
铯适配器	`@dev/cesium`	CesiumJS特定适配器将行为映射到Cesium查看器（ECEF坐标， `flyTo` 动画）
过滤器	`@dev/filters`	快照的捕获后图像过滤器（灰度、视网膜等）。符合Worker条件的筛选器会自动在线程外运行
隧道	`@dev/tunnel`	Node.js WebSocket/HTTP中继将MCP客户端桥接到基于浏览器的客户端 `McpServer`

关键概念

术语	描述
行为 (`IMcpBehavior`)	对象类型（相机、灯光、网格）的能力模板。定义工具、资源和URI模板。每种类型注册一次
适配器 (`IMcpBehaviorAdapter`)	读取场景状态并分派工具调用的特定于引擎的实现
语法	每个会话解析可串行化的工具描述。看 docs/gramm.md
命名空间	短标识符（例如。 `"camera"`)按行为类型分组工具和URI模板
URI模板	RFC 6570模式（例如。 `babylon://camera/{cameraId}`)通过广告 `resources/templates/list`

坐标系

坐标使用隐式检测-- {x,y,z} 是笛卡尔坐标系， {lat,lon} 是地理上的。相机工具通过以下方式接受这两种格式 coordinateSchema （从 @dev/geodesy). 铯适配器通过以下方式将地理输入转换为ECEF resolveToCartesian3().

先决条件

工具	版本
Node.js	>=20.11.0<23.0.0
npm	>=8.0.0
浏览器	任何现代浏览器（Chrome、Edge、Firefox）

构建

编译TypeScript

npm run build:dev        # one-shot
npm run build:watch      # watch mode

UMD浏览器捆绑包

为以下对象生成webpack捆绑包 @dev/core, @dev/babylon，以及 @dev/cesium:

npm run bundle           # production (minified)
npm run bundle:dev       # development (source maps)
npm run bundle:watch     # watch mode (core only)

输出：

packages/dev/core/bundle/mcp-server.js
packages/dev/babylon/bundle/mcp-babylon.js
packages/dev/cesium/bundle/mcp-cesium.js

将捆绑包部署到开发工具

npm run deploy:bundles   # copies bundles → packages/host/www/bundle/

一次性构建所有内容

npm run build:all:dev    # development (recommended)
npm run build:all        # production (minified)

小贴士 --更改TypeScript源代码后，始终重新运行 npm run build:all:dev 所以浏览器会接收你的更改。

运行开发服务器

npm run server:start

输出：

⚙️  MCP Browser World — tunnel started
────────────────────────────────────────────────────────
📡  Provider     ws://localhost:3000/provider
🔌  MCP HTTP     http://localhost:3000/mcp   ← MCP Inspector
📺  MCP SSE      http://localhost:3000/sse   ← Claude Code
🖥️   Dev harness  http://localhost:3000/
────────────────────────────────────────────────────────

集 MCP_TUNNEL_NO_OPEN=1 以抑制浏览器的自动启动。

连接MCP客户端

浏览器开发工具

打开 http://localhost:3000/
将默认值保留在连接面板
点击开始 --状态更改为连接

MCP检查员

npx @modelcontextprotocol/inspector

选择 流式HTTP 传输，URL: http://localhost:3000/<serverName>/mcp.

克劳德代码

添加 ~/.claude/settings.json:

{
    "mcpServers": {
        "babylon": {
            "url": "http://localhost:3000/<serverName>/sse"
        }
    }
}

替换 <serverName> 名字传给 McpServerBuilder.withName().

然后尝试：

“列出巴比伦场景中可用的所有资源。” 将BoxMesh移动到位置（3，0，-2） “平滑地设置摄影机动画，使其在2秒内观察球体。”

HTTPS/TLS

# Generate a self-signed certificate
npm run gen-cert

# Start with TLS (bash)
MCP_TUNNEL_TLS_CERT=certs/cert.pem MCP_TUNNEL_TLS_KEY=certs/key.pem npm run server:start

# Or use the shortcut
npm run server:start:https

替换 http:// 随着 https:// 在所有客户端URL中。请参阅 docs/guides/howto.md 了解更多TLS详细信息。

样品

即用型示例页面已上线 packages/host/www/samples/:

示例	引擎	文件
相机控制	Babylon.js	`babylon-camera.html`
灯光管理	Babylon.js	`babylon-light.html`
网格操作	Babylon.js	`babylon-mesh.html`
多路复用（4个视口）	Babylon.js	`babylon-multiplex.html`
环回客户端	Babylon.js	`babylon-client.html`
相机+3D瓷砖	CesiumJS	`cesium-camera.html`

每个示例都包括一个连接面板、画布和控制台输出。

语法系统

工具描述与工具模式分开，因此可以替换它们，每个客户端都可以在不接触代码的情况下进行本地化或调优。语法很简单 JSON序列化对象，在会话期间按会话解析 initialize 握手。

完整文档： docs/gramm.md

快照筛选器

这 @dev/filters 软件包提供应用于以下内容的捕获后图像过滤器 camera_snapshot PNG编码前的结果。过滤器实施 ISnapshotFilter 并通过以下方式在相机适配器上注册 IHasImageFiltering 界面。

这 camera_snapshot 工具接受可选 filters 参数：

价值观	行为
（省略）	原始捕获，未应用过滤器
`[]`	跳过所有过滤器（与省略的相同）
`["retinex", ...]`	按顺序仅应用指定的筛选器

使用 camera_list_filters 在运行时发现已注册的过滤器。

符合工人资格的过滤器（实施 IWorkerSnapshotFilter)都是自动批处理并在主线程之外执行，以获得更好的性能。

内置过滤器：灰度, 视网膜 （具有颜色恢复功能的多尺度视网膜）。

完整文档： docs/filters/architecture.md

MCP传输

传输	端点	规格
流式HTTP	`POST /<serverName>/mcp`	MCP 2025-03-26
SSE流	`GET /<serverName>/sse`	MCP 2024-11-05
SSE消息	`POST /<serverName>/messages?sessionId=…`	MCP 2024-11-05
原始websocket	`ws://localhost:3000/<serverName>`	内部/测试

配置TLS时，通过HTTPS/WSS可用的所有传输。

行为

该框架附带了三种行为，每种行为都有详细的记录：

行为	工具	文档
相机	20种工具——定位、投影、动画、快照过滤、场景查询	docs/behaviors/camera.md
光	17个工具——创建、属性、环境光	docs/behaviors/light.md
网格	13个工具——可见性、变换、材质、标签	文档/行为/网格.md

相机工具（摘要）

类别	工具
运动	`camera_set_target`, `camera_set_position`, `camera_look_at`, `camera_orbit`, `camera_dolly`, `camera_pan`
光学	`camera_set_fov`, `camera_zoom`, `camera_set_projection`
控制	`camera_lock`, `camera_unlock`
捕获	`camera_snapshot` （接受可选 `filters` 阵列）， `camera_list_filters`
动画	`camera_animate_to`, `camera_animate_orbit`, `camera_follow_path`, `camera_shake`, `camera_stop_animation`
场景查询	`scene_visible_objects`, `scene_pick_from_center`

轻型工具（概述）

类别	工具
生命周期	`light_create`, `light_remove`
物业	`light_set_enabled`, `light_set_intensity`, `light_set_diffuse_color`, `light_set_specular_color`
空间	`light_set_position`, `light_set_direction`, `light_set_target`, `light_set_range`
特定类型	`light_spot_set_angle`, `light_spot_set_exponent`, `light_hemi_set_ground_color`
批次	`light_update`
环境温度	`scene_get_ambient`, `scene_set_ambient_color`, `scene_set_ambient_enabled`

网格工具（摘要）

类别	工具
可见性	`mesh_set_enabled`, `mesh_set_visible`, `mesh_set_visibility`
转换	`mesh_set_position`, `mesh_set_rotation`, `mesh_set_scaling`, `mesh_animate_to`
材料	`mesh_set_color`, `mesh_set_material_alpha`
标签	`mesh_tag_add`, `mesh_tag_remove`, `mesh_tag_set`, `mesh_find_by_tag`

项目结构

mcp-browser-world/
├── packages/
│   ├── dev/
│   │   ├── core/           @dev/core — MCP server SDK
│   │   │   ├── src/
│   │   │   │   ├── interfaces/       Public TypeScript interfaces
│   │   │   │   └── server/           McpServer, McpServerBuilder, McpGrammar
│   │   │   └── bundle/               mcp-server.js (UMD)
│   │   ├── geodesy/        @dev/geodesy — coordinate systems & ellipsoids
│   │   │   └── src/
│   │   │       ├── geodesy.ellipsoid.ts      Ellipsoid (WGS84, GRS80, …)
│   │   │       ├── geodesy.system.ts         GeodeticSystem (ECEF ↔ geodetic)
│   │   │       ├── geodesy.schemas.ts        JSON schemas + resolveToCartesian3
│   │   │       └── calculators/              Spherical & flat-earth calculators
│   │   ├── behaviors/      @dev/behaviors — engine-agnostic scene behaviors
│   │   │   └── src/
│   │   │       ├── behaviours/       McpCameraBehavior, McpLightBehavior, McpMeshBehavior
│   │   │       └── states/           State interfaces (camera, light, mesh, math)
│   │   ├── babylon/        @dev/babylon — Babylon.js adapters
│   │   │   ├── src/adapters/         Camera, Light, Mesh adapters
│   │   │   └── bundle/               mcp-babylon.js (UMD)
│   │   ├── cesium/         @dev/cesium — CesiumJS adapters
│   │   │   ├── src/adapters/         Camera, Light, Mesh adapters (ECEF)
│   │   │   └── bundle/               mcp-cesium.js (UMD)
│   │   ├── filters/        @dev/filters — snapshot image filters
│   │   │   └── src/
│   │   │       ├── interfaces/       ISnapshotFilter, IImageFilterSet, IHasImageFiltering
│   │   │       ├── imageFilterSet.ts Default implementation (worker batching)
│   │   │       ├── grayscale.filter.ts   Built-in: grayscale (worker-eligible)
│   │   │       └── retinex.filter.ts     Built-in: retinex  (worker-eligible)
│   │   ├── tunnel/         @dev/tunnel — WebSocket/HTTP relay
│   │   │   └── src/                  WsTunnel, WsTunnelBuilder, CLI entry
│   │   └── tools/          @dev/tools — shared build utilities (placeholder)
│   └── host/
│       └── www/            Dev harness & samples
│           ├── bundle/     Deployed UMD bundles
│           ├── samples/    babylon-camera, babylon-light, babylon-mesh, cesium-camera
│           └── index.html  Browser MCP provider
├── scripts/
│   ├── deploy-bundles.mjs  Copy bundles → www/bundle/
│   └── gen-cert.mjs        Generate self-signed TLS certificate
├── docs/
│   ├── behaviors/
│   │   ├── camera.md       Camera behavior — full tool reference
│   │   ├── light.md        Light behavior — full tool reference
│   │   └── mesh.md         Mesh behavior — full tool reference
│   ├── filters/
│   │   └── architecture.md Filter pipeline architecture & custom filters
│   ├── guides/
│   │   └── howto.md        Tips, recipes & common tasks
│   └── grammar.md          Grammar system documentation
└── package.json            Monorepo root (npm workspaces)

环境变量

变量	默认值	描述
`MCP_TUNNEL_PORT`	`3000`	TCP端口
`MCP_TUNNEL_HOST`	`0.0.0.0`	绑定地址
`MCP_TUNNEL_PROVIDER_PATH`	`/provider`	浏览器提供程序的WebSocket路径
`MCP_TUNNEL_CLIENT_PATH`	`/`	原始WS客户端的WebSocket路径
`MCP_TUNNEL_MCP_PATH`	`/mcp`	可流式传输的HTTP端点
`MCP_TUNNEL_WWW_DIR`	`packages/host/www`	开发工具目录
`MCP_TUNNEL_BUNDLE_DIR`	`packages/dev/core/bundle`	捆绑目录服务于 `/bundle/`
`MCP_TUNNEL_NO_OPEN`	（未设置）	跳过自动打开浏览器
`MCP_TUNNEL_TLS_CERT`	（未设置）	PEM证书文件路径
`MCP_TUNNEL_TLS_KEY`	（未设置）	PEM私钥文件路径
`MCP_TUNNEL_PROTOCOL`	（自动）	武力 `"http"` 或 `"https"`

npm脚本

脚本	描述
`npm run build:dev`	编译TypeScript
`npm run build:watch`	在监视模式下编译
`npm run bundle` / `bundle:dev`	Webpack捆绑包（生产/开发）
`npm run deploy:bundles`	将捆绑包复制到开发工具
`npm run build:all` / `build:all:dev`	完整构建管道
`npm run server:start`	建造+启动隧道
`npm run server:start:http`	强制HTTP
`npm run server:start:https`	使用本地证书强制HTTPS
`npm run gen-cert`	生成自签名TLS证书

3D场景协议框架

使用说明

MCP浏览器世界

快速启动

建筑

分层设计

关键概念

坐标系

先决条件

构建

编译TypeScript

UMD浏览器捆绑包

将捆绑包部署到开发工具

一次性构建所有内容

运行开发服务器

连接MCP客户端

浏览器开发工具

MCP检查员

克劳德代码

HTTPS/TLS

样品

语法系统

快照筛选器

MCP传输

行为

相机工具（摘要）

轻型工具（概述）

网格工具（摘要）

项目结构

环境变量

npm脚本

延伸阅读

使用说明

MCP浏览器世界

快速启动

建筑

分层设计

关键概念

坐标系

先决条件

构建

编译TypeScript

UMD浏览器捆绑包

将捆绑包部署到开发工具

一次性构建所有内容

运行开发服务器

连接MCP客户端

浏览器开发工具

MCP检查员

克劳德代码

HTTPS/TLS

样品

语法系统

快照筛选器

MCP传输

行为

相机工具（摘要）

轻型工具（概述）

网格工具（摘要）

项目结构

环境变量

npm脚本

延伸阅读

相关 MCP

JSON-RPC服务

以太坊RPC MPC服务器

WinDbg调试服务器

PHP MCP服务器SDK

CSV文件管理服务器

模型上下文协议服务器