AI导哈

3D场景实时操作服务

Threlte MCP是一个基于Model Context Protocol的服务，使AI代理能够实时检查和操作Three.js/Threlte场景。

  • by SerifeusStudio
  • TypeScript
  • 本地部署
  • 8 星标
  • 更新于
在 GitHub 查看 SerifeusStudio/threlte-mcp

使用说明

Threlte MCP

MCP（模型上下文协议）服务器，使AI代理能够实时检查和操纵Three.js/Serlte场景。

✅ 兼容

  • 克劳德桌面版 -Anthropic的桌面应用程序
  • 反重力 -谷歌的人工智能集成开发环境
  • 克劳德代码 -Claude的CLI工具
  • 光标 -AI驱动的代码编辑器
  • 帆板运动 -Codeium的人工智能集成开发环境
  • 继续 -VS代码AI扩展
  • 任何兼容MCP的客户端

请参阅详细的兼容性指南→

特性

  • 🔍 现场检查 -查看完整的3D场景层次结构，按名称/类型查找对象
  • 🎯 对象操纵 -移动、旋转、缩放、显示/隐藏对象
  • 🎨 材料和资产 -应用材料、加载GLTF模型、更改环境
  • 🧪 资产分析 -检查GLTF结构并验证性能
  • dYZ+ 资产优化 -简化网格、压缩纹理、修剪未使用的数据
  • dY”？ Svelte出口 -从GLTF生成Threlte/Svelte组件
  • dYZ？ 相机预设 -保存、加载和设置摄影机视图的动画
  • ⚡ 物理控制 -添加物理体，施加脉冲，设置重力
  • 🎭 Vibe预设 -应用情绪预设（舒适、怪异、霓虹灯等）

安装

npm install threlte-mcp

快速开始

1.安装包装

npm install threlte-mcp

2.配置IDE（一次性设置）

npx threlte-mcp setup

此功能会自动检测您的IDE（Antigravity、Cursor、Claude Desktop）并创建MCP配置。

3.将组件添加到您的Threlte应用程序中

MCPBridge组件需要Svelte 5。

<script>
  import { MCPBridgeComponent } from 'threlte-mcp/client';
</script>

<!-- Add inside your <Canvas> -->
<MCPBridgeComponent />

就是这样！ AI现在可以检查和操纵您的场景。

📋 Manual Configuration (Alternative)

如果 npx threlte-mcp setup 不适用于您的IDE，请手动添加到您的配置中：

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

配置文件位置：

  • 反重力: ~/.gemini/antigravity/mcp_config.json
  • 光标: ~/.cursor/mcp.json
  • 克劳德桌面版: ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）
🔧 Advanced: TypeScript API 
import { MCPBridge } from 'threlte-mcp/client';
import { useThrelte } from '@threlte/core';

const { scene } = useThrelte();

// Create bridge (auto-connects in dev mode)
const bridge = new MCPBridge(scene, {
  url: 'ws://127.0.0.1:8082',  // default
  autoConnect: true,           // default in dev
  reconnectDelay: 60000,       // 1 minute
});

// In render loop
bridge.update();

// Get scene state
bridge.getSceneState();

// Find objects
bridge.findObjects({ nameContains: 'player' });

选项B：按场景（简单用于原型制作）

<script lang="ts">
  import { onMount, onDestroy } from 'svelte';
  import { useThrelte } from '@threlte/core';

  const { scene } = useThrelte();
  let ws: WebSocket | null = null;
  
  onMount(() => {
    ws = new WebSocket('ws://localhost:8082');
    
    ws.onopen = () => {
      console.log('[MCPBridge] Connected');
      // Send initial scene state
      ws?.send(JSON.stringify({
        type: 'sceneState',
        data: serializeScene(scene)
      }));
    };
    
    ws.onmessage = (event) => {
      const command = JSON.parse(event.data);
      handleCommand(command);
    };
  });
  
  onDestroy(() => {
    ws?.close();
  });
  
  function serializeScene(obj: THREE.Object3D, depth = 0, maxDepth = 3) {
    if (depth > maxDepth) return null;
    return {
      name: obj.name,
      type: obj.type,
      position: obj.position.toArray(),
      rotation: obj.rotation.toArray().slice(0, 3),
      scale: obj.scale.toArray(),
      visible: obj.visible,
      children: obj.children.map(c => serializeScene(c, depth + 1, maxDepth)).filter(Boolean)
    };
  }
  
  function handleCommand(cmd: any) {
    const { action, requestId, ...params } = cmd;
    let result;
    
    switch (action) {
      case 'getFullSceneState':
        result = { data: serializeScene(scene, 0, params.maxDepth || 3) };
        break;
      case 'moveSceneObject':
        const obj = scene.getObjectByName(params.name || params.path);
        if (obj && params.position) {
          obj.position.set(...params.position);
          result = { success: true };
        }
        break;
      // Add more handlers as needed
    }
    
    if (requestId) {
      ws?.send(JSON.stringify({ ...result, requestId }));
    }
  }
</script>

3.运行您的应用程序并开始使用MCP工具

一旦MCP服务器和Threlte应用程序都运行，AI代理就可以：

"Get the scene state"
"Find all objects named 'Player'"  
"Move the 'Camera' to position [0, 5, 10]"
"Apply the 'neon' vibe to the scene"

可用工具

现场检查

工具 说明
get_scene_state 获取完整的场景层次结构
find_objects 按名称、类型或用户数据搜索
get_object_position 获取特定对象的位置
log_positions 导出代码位置

相机

工具 说明
set_camera_position 设置相机位置、视角和镜头设置
save_camera_preset 将当前相机视图另存为预设
load_camera_preset 加载已保存的相机视图
list_camera_presets 列出所有已保存的摄像头预设
delete_camera_preset 删除已保存的相机预设
animate_camera_presets 通过一系列预设进行动画制作

层级管理

工具 说明
spawn_entity 创建基本体（长方体、球体等）
destroy_entity 从场景中删除对象
move_object 设置对象位置
set_transform 设置位置、旋转、比例
set_visibility 显示/隐藏对象
rename_entity 重命名对象
duplicate_entity 克隆对象

物理学

工具 说明
make_physical 添加物理体
remove_physics 移除物理体
apply_impulse 用力
set_gravity 设置全局重力

资产处理

工具 说明
analyze_gltf 检查GLTF/GLB结构
validate_asset 验证GLTF/GLB是否存在问题
optimize_gltf 优化GLTF/GLB资产
export_to_svelte 生成Threlte/Svelte组件

材料和资产

工具 说明
load_asset 加载GLTF/GLB模型
apply_material 设置材料
set_environment 设置天空盒/环境

大气

工具 说明
apply_vibe 应用情绪预设
get_bridge_status 检查连接状态

配置

WebSocket连接

默认情况下，服务器使用端口8082进行WebSocket通信。

环境变量

MCPBridge在开发模式下自动连接。对于生产，您可以通过环境变量启用它：

# Add to .env file:
VITE_MCP_ENABLED=true

这有助于：

  • 生产构建中的测试
  • 演示环境
  • 调试生产问题

注： 在开发模式下自动启用(npm run dev)，无需配置。

发展

# Clone the repo
git clone https://github.com/RaulContreras123/threlte-mcp.git
cd threlte-mcp

# Install dependencies
npm install

# Run in development
npm run dev

# Build for production
npm run build

贡献

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

  1. 分叉存储库
  2. 创建功能分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

麻省理工学院© 劳尔 Contreras

链接

建于 克劳德 🤖

相关 MCP