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": ""
}发送命令
服务器向前端发送命令：
{
"type": "changeColor",
"color": "#ff0000"
}状态查询
服务器可以请求当前状态：
{
"type": "requestState",
"requestId": "",
"forceRefresh": false
}前端响应：
{
"type": "stateResponse",
"requestId": "",
"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.jsWebsocket消息处理程序
- 更新文档 在README.md中
故障排除
端口已在使用中
# Check what's using the ports
lsof -i :3000 -i :3001
# Kill processes
lsof -ti :3000 -ti :3001 | xargs kill -9WebSocket连接问题
- 验证WebSocket服务器是否在端口3001上运行
- 检查防火墙/安全组是否允许WebSocket连接
- 确保前端使用正确的会话ID连接
MCP客户端无法连接
- 验证MCP端点是否可访问：
http://localhost:3000/mcp - 检查CORS设置（默认情况下服务器允许所有来源）
- 对于远程客户端，确保隧道正在运行并且URL正确
工具未出现
- 服务器更改后重新启动MCP客户端
- 检查服务器日志是否有错误
- 验证服务器是否已成功启动
相关项目
- hello3dmcp前端 -3D可视化前端应用程序
许可证
麻省理工学院
贡献
欢迎投稿！请随时提交拉取请求。