使用说明

Hello3DMCP服务器-用于3D模型控制的MCP服务器

MCP服务器，提供模型上下文协议（MCP）工具，用于通过WebSocket控制3D模型可视化应用程序。该服务器将MCP客户端（如ChatGPT、Claude Desktop、Cursor）与前端3D应用程序连接起来。

特性

MCP协议支持：适用于任何兼容MCP的客户端（ChatGPT、Claude Desktop、Cursor等）
双重运输模式：支持STDIO（子进程）和HTTP/SSE（远程）模式
WebSocket网桥：与前端应用程序进行实时双向通信
会话管理：独立会话的多用户支持
状态管理：查询和缓存应用程序状态，以进行准确的相对操作

快速开始

先决条件

Node.js（v18或更高版本）
npm
前端应用程序正在运行（请参阅 hello3dmcp前端)

安装

安装依赖项：
```
npm install
```

配置环境（可选）：

cp .env.example .env
# Edit .env with your settings

启动服务器：
```
npm start
```
或者：
```
node server.js
```

服务器启动时间：

MCP端点: http://localhost:3000/mcp （HTTP模式）
WebSocket服务器: ws://localhost:3001

配置

环境变量

创建一个 .env 文件（或使用环境变量）：

# MCP server port (default: 3000)
MCP_PORT=3000

# WebSocket server port (default: 3001)
WS_PORT=3001

# Browser URL for the 3D app frontend
# Used when generating connection URLs for MCP clients
# Default: http://localhost:5173
BROWSER_URL=http://localhost:5173

命令行参数

您可以通过命令行覆盖环境变量：

# Set browser URL
node server.js --browser-url https://your-app.netlify.app

# Or using short form
node server.js -u https://your-app.netlify.app

# Show help
node server.js --help

配置优先级：

命令行参数(--browser-url 或 -u)-最高优先级
环境变量(BROWSER_URL)
.env 文件(BROWSER_URL)
默认值(http://localhost:5173)-最低优先级

连接MCP客户端

快速比较：MCP客户端选项

客户端	成本	与本地主机兼容	需要公共URL	最适合
MCP检查员	免费	✅ 是	❌ 否	测试和调试工具
光标	免费	✅ 是	❌ 否	带AI助手的完整IDE
VS代码+MCP	免费	✅ 是	❌ 无	VS代码用户
克劳德代码	免费	✅ 是	❌ 否	基于CLI的测试
Continue.dev	免费	✅ 是	❌ 无	VS代码扩展用户
克劳德桌面版	免费	✅ 是	❌ 否	带Claude的桌面应用程序
ChatGPT	付费（加）	❌ 否	✅ 是（需要隧道）	OpenAI集成

Claude桌面安装

安装MCP包(.mcpb)文件：

构建包：
```
npm run build
```
这创造了 hello3dmcp-server.mcpb 在您的项目根目录中。
在Claude Desktop中安装：
- 打开克劳德桌面→ 设置→ 扩展→ 高级设置
- 点击“安装扩展”
- 选择 hello3dmcp-server.mcpb 文件
- 重新启动克劳德桌面
获取连接URL:
- 问克劳德：“我如何连接到3D应用程序？”或“获取浏览器URL”
- Claude将提供一个带有您唯一会话ID的URL
- 在浏览器中打开该URL

优点： 无需手动配置，独立的软件包，易于更新。

ChatGPT设置

ChatGPT需要一个可公开访问的服务器。

启动服务器：

node server.js --browser-url https://your-frontend.netlify.app

创建隧道：

ngrok http 3000
# or
lt --port 3000 --subdomain hello3dmcp-server

配置ChatGPT：
- 打开ChatGPT→ 设置→ 个性化→ 模型上下文协议
- 添加服务器：
  - 名字: hello3dmcp-server
  - 统一资源定位符: https://your-tunnel-url/mcp ⚠️ 包含 /mcp 最后！
  - 运输：HTTP或流式HTTP

光标

选项1:深度链接（macOS）

open 'cursor://anysphere.cursor-deeplink/mcp/install?name=hello3dmcp-server&config=eyJ1cmwiOiJodHRwOi8vbG9jYWxob3N0OjMwMDAvbWNwIn0='

选项2：手动配置

打开光标设置→ 特性→ 模型上下文协议

添加服务器：

{
  "mcpServers": {
    "hello3dmcp-server": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP检查员

MCP Inspector是用于测试和调试MCP服务器的开发人员工具。它提供了一个交互式web界面，用于探索服务器功能、测试工具和查看资源。

示例：MCP检查器连接到服务器，显示正在测试的工具。

测试选项：

您可以测试源代码（开发）或捆绑版本（生产）：

选项1：测试源代码（开发）

从源启动服务器：
```
npm start
# or
node server.js
```
服务器应在上运行 http://localhost:3000/mcp

启动MCP检查器：

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

选项2：测试捆绑版本（生产）

构建捆绑包：
```
npm run build:bundle
```
这创造了 dist/hello3dmcp-server.js
启动捆绑服务器：
```
npm run start:prod
# or
node dist/hello3dmcp-server.js
```
服务器应在上运行 http://localhost:3000/mcp

启动MCP检查器：

npx @modelcontextprotocol/inspector http://localhost:3000/mcp

使用检查器：

打开检查器UI：
- 检查员将启动一个web界面（通常在 http://localhost:5173)
- 打开浏览器并导航到终端中显示的URL
配置连接：
- 运输类型： 选择“流式HTTP”（这与服务器的传输相匹配）
- 网址： 进入 http://localhost:3000/mcp （注：端口3000，而不是3001）
- 连接类型： 选择“直接”
- 点击 “连接” 按钮
- 成功后，您应该看到一个绿点和“已连接”状态
浏览和测试工具：
- 点击 “工具” 顶部导航栏中的选项卡
- 您将在中间窗格中看到所有可用工具的列表：
  - change_model_color -更改三维模型的颜色
  - change_model_size -更改模型的统一大小
  - scale_model -在每个维度上独立缩放模型
  - change_background_color -更改场景的背景颜色
  - set_key_light_intensity -设置按键灯的强度
  - set_key_light_position -设置按键灯的位置
  - 还有更多。..
调用工具：
- 单击工具列表中的任何工具名称以将其选中
- 右侧窗格将显示工具的描述和参数
- 在输入字段中输入所需的参数值：
  - 对于 change_background_color：输入颜色名称（例如。， "tin")或十六进制代码（例如。， "#878687")
  - 对于 change_model_size：输入一个数字（例如。， 2.5)
  - 对于 scale_model：输入x、y、z轴的值
- 点击 “运行工具” 按钮（纸飞机图标）
- 结果将显示在下面，显示“成功”和响应消息
- 如果您的3D应用程序正在运行并已连接，您将立即看到所做的更改
查看历史记录：
- 左下角的“历史记录”窗格显示了您之前的所有工具调用
- 点击任何历史条目查看其详细信息
- 使用“清除”删除历史记录条目

例子： 要将背景颜色更改为锡：

选择 change_background_color 从工具列表中
进入 tin 在“颜色”参数字段中
点击“运行工具”
您将看到： "Background color changed to tin (#878687)"
3D应用程序中的背景将更新为新颜色

注：检查器直接连接到您的MCP HTTP端点。启动检查器之前，请确保您的服务器正在运行。如果您使用的是隧道服务器（用于远程访问），您还可以连接到隧道URL：

npx @modelcontextprotocol/inspector https://your-tunnel-url.ngrok-free.app/mcp

可用的MCP工具

服务器提供了广泛的工具来控制3D模型：

模型对照组

change_model_color -更改模型颜色（十六进制或苹果蜡笔颜色名称）
change_model_size -更改统一模型大小
scale_model -在x、y、z维度上独立缩放模型
set_model_rotation -设置模型旋转（欧拉角）
rotate_model_clockwise -顺时针（相对）旋转模型
rotate_model_counterclockwise -逆时针旋转模型（相对）
nudge_model_pitch_up -调整模型俯仰（相对）
nudge_model_pitch_down -向下调整模型倾斜度（相对）
nudge_model_roll -调整模型滚动（相对）
get_model_color -获取当前模型颜色
get_model_scale -获取当前模型比例
get_model_rotation -获取当前模型旋转

灯光控制

set_key_light_intensity -设置关键光强度
set_key_light_color -设置按键灯颜色
set_key_light_position_spherical -设置关键灯光位置（球坐标）
set_key_light_distance -设置按键灯光距离
swing_key_light_up/down/left/right -按方向摆动按键灯
walk_key_light_in/out -将按键灯移近/移远
rotate_key_light_clockwise/counterclockwise -旋转键指示灯
nudge_key_light_elevation_up/down -调整按键灯高度
move_key_light_toward_direction -将关键灯移向方向
用于补光灯的类似工具
get_key_light_* / get_fill_light_* -查询灯光属性

相机控制

dolly_camera -设置相机距离
dolly_camera_in/out -将相机移近/移远
set_camera_fov -设置摄像头视野
increase_camera_fov / decrease_camera_fov -调整视场
get_camera_distance -获取相机距离
get_camera_fov -获取相机视场

场景控制

change_background_color -更改场景背景颜色
get_background_color -获取背景颜色

连接

get_browser_connection_url -获取将浏览器连接到3D应用程序的URL

建筑

服务器支持 两种运输方式:

STDIO模式（子进程-克劳德桌面）

┌─────────────────┐         ┌──────────────┐         ┌─────────────┐
│ Claude Desktop  │──stdin▶│  MCP Server   │────────▶│  WebSocket  │
│  (Subprocess)   │◀─stdout│  (server.js)  │         │   Server    │
└─────────────────┘         └──────────────┘         └─────────────┘
                                      │                       │
                                      │              ┌────────▼────────┐
                                      └──────────────▶│  Frontend App   │
                                                     │  (WebSocket)     │
                                                     └─────────────────┘

HTTP/SSE模式（ChatGPT，手动）

┌─────────────────┐         ┌──────────────┐         ┌─────────────┐
│   MCP Client    │──HTTP──▶│  MCP Server   │────────▶│  WebSocket  │
│  (AI Assistant) │──SSE───▶│  (server.js)  │         │   Server    │
└─────────────────┘         └──────────────┘         └─────────────┘
                                      │                       │
                                      │              ┌────────▼────────┐
                                      └──────────────▶│  Frontend App   │
                                                     │  (WebSocket)     │
                                                     └─────────────────┘

它是如何工作的：

MCP客户端 向MCP服务器发送工具调用请求（通过STDIO或HTTP/SSE）
MCP服务器 自动检测传输模式并相应地处理请求
MCP服务器 通过WebSocket将命令路由到连接的浏览器客户端（按会话ID）
前端应用程序 接收WebSocket消息并更新3D模型
更改在浏览器中立即可见

运输检测：

STDIO模式：在以下情况下自动检测 stdin 不是TTY（子流程）
HTTP模式：在以下情况下自动检测 stdin 是TTY（手动执行）

WebSocket协议

服务器通过WebSocket与前端应用程序通信：

会话注册

前端在连接时发送：

{
  "type": "registerSession",
  "sessionId": "<session-id>"
}

发送命令

服务器向前端发送命令：

{
  "type": "changeColor",
  "color": "#ff0000"
}

状态查询

服务器可以请求当前状态：

{
  "type": "requestState",
  "requestId": "<unique-id>",
  "forceRefresh": false
}

前端响应：

{
  "type": "stateResponse",
  "requestId": "<unique-id>",
  "state": { /* current state object */ }
}

部署

铁路

连接存储库 铁路
设置环境变量：
- MCP_PORT：3000（或铁路指定的港口）
- WS_PORT：3001（或使用与MCP_port相同的端口）
- BROWSER_URL：您的前端URL
部署

渲染

创建新的Web服务
设置环境变量：
- MCP_PORT: 3000
- WS_PORT: 3001
- BROWSER_URL：您的前端URL
部署

Fly.io

创建 fly.toml 配置
设置环境变量 通过 fly secrets
部署: fly deploy

重要说明

WebSocket支持：确保您的托管平台支持WebSocket连接
端口配置：某些平台分配单个端口-您可能需要为MCP和WebSocket使用相同的端口
HTTPS/WSS：使用 wss:// （安全WebSocket）用于生产部署

发展

添加新工具

在中注册工具 server.js:

mcpServer.registerTool(
  'your_tool_name',
  {
    title: 'Your Tool Title',
    description: 'Description',
    inputSchema: {
      param: z.string().describe('Parameter')
    }
  },
  async ({ param }) => {
    routeToCurrentSession({
      type: 'yourCommandType',
      param: param
    });
    return {
      content: [{ type: 'text', text: 'Success' }]
    };
  }
);

前端处理命令 在 Application.js Websocket消息处理程序
更新文档 在README.md中

故障排除

端口已在使用中

# Check what's using the ports
lsof -i :3000 -i :3001

# Kill processes
lsof -ti :3000 -ti :3001 | xargs kill -9

WebSocket连接问题

验证WebSocket服务器是否在端口3001上运行
检查防火墙/安全组是否允许WebSocket连接
确保前端使用正确的会话ID连接

MCP客户端无法连接

验证MCP端点是否可访问： http://localhost:3000/mcp
检查CORS设置（默认情况下服务器允许所有来源）
对于远程客户端，确保隧道正在运行并且URL正确

工具未出现

服务器更改后重新启动MCP客户端
检查服务器日志是否有错误
验证服务器是否已成功启动

许可证

麻省理工学院

贡献

欢迎投稿！请随时提交拉取请求。