Spline MCP Server

Implementation Reference

• src/tools/runtime-tools.js:125-476 (handler)

  Core handler implementation for generateSceneInteractionCode tool. Registers the tool and provides the execution logic that dynamically generates complete Spline runtime JavaScript code with interaction features based on the interactionType parameter.
  server.tool( 'generateSceneInteractionCode', { sceneId: z.string().min(1).describe('Scene ID'), interactionType: z.enum([ 'explore', 'eventListeners', 'variables', 'camera', 'physics', 'custom' ]).describe('Type of interaction'), options: z.record(z.any()).optional().describe('Interaction-specific options'), }, async ({ sceneId, interactionType, options }) => { try { let code = ''; const sceneUrl = `https://prod.spline.design/${sceneId}/scene.splinecode`; const baseCode = ` import { Application } from '@splinetool/runtime'; // Create a new Application instance const canvas = document.getElementById('canvas3d'); const spline = new Application(canvas); // Load the scene spline.load('${sceneUrl}').then(() => { console.log('Scene loaded successfully'); `; const endCode = ` }); `; let interactionCode = ''; switch (interactionType) { case 'explore': interactionCode = ` // Scene exploration const allObjects = spline.getObjects(); console.log('Total objects:', allObjects.length); // Log object hierarchy function logObjectHierarchy(objects, indent = '') { objects.forEach(obj => { console.log(\`\${indent}\${obj.name} (\${obj.type})\`); if (obj.children && obj.children.length > 0) { logObjectHierarchy(obj.children, indent + ' '); } }); } logObjectHierarchy(allObjects); // Find objects by type const cubes = allObjects.filter(obj => obj.type === 'cube'); const lights = allObjects.filter(obj => obj.type === 'light'); const cameras = allObjects.filter(obj => obj.type === 'camera'); console.log('Cubes:', cubes.length); console.log('Lights:', lights.length); console.log('Cameras:', cameras.length); `; break; case 'eventListeners': interactionCode = ` // Set up event listeners spline.addEventListener('mouseDown', (e) => { console.log('Mouse down on:', e.target.name); // Highlight clicked object if (e.target.material) { e.target.userData.originalColor = e.target.material.color.clone(); e.target.material.color.set('#ff0000'); } }); spline.addEventListener('mouseUp', (e) => { console.log('Mouse up on:', e.target.name); // Restore original color if (e.target.material && e.target.userData.originalColor) { e.target.material.color.copy(e.target.userData.originalColor); } }); spline.addEventListener('mouseHover', (e) => { console.log('Mouse hover on:', e.target.name); document.body.style.cursor = 'pointer'; }); spline.addEventListener('mouseOut', (e) => { console.log('Mouse out from:', e.target.name); document.body.style.cursor = 'default'; }); // Key events document.addEventListener('keydown', (e) => { console.log('Key down:', e.key); // Example: Move objects with arrow keys const selectedObject = spline.findObjectByName('${options?.objectName || 'Cube'}'); if (selectedObject) { const moveDistance = 0.1; switch (e.key) { case 'ArrowUp': selectedObject.position.z -= moveDistance; break; case 'ArrowDown': selectedObject.position.z += moveDistance; break; case 'ArrowLeft': selectedObject.position.x -= moveDistance; break; case 'ArrowRight': selectedObject.position.x += moveDistance; break; } } }); `; break; case 'variables': interactionCode = ` // Get all variables const variables = spline.getVariables(); console.log('Variables:', variables); // Set variables spline.setVariable('counter', 0); spline.setVariable('isActive', true); spline.setVariable('userName', 'Visitor'); // Listen for variable changes spline.addEventListener('variableChanged', (e) => { console.log('Variable changed:', e.variableName, e.value); // React to specific variable changes if (e.variableName === 'counter') { // Example: Update UI based on counter document.getElementById('counter-display').textContent = e.value; // Example: Rotate object based on counter const cube = spline.findObjectByName('${options?.objectName || 'Cube'}'); if (cube) { cube.rotation.y = e.value * 0.1; } } }); // Example: Increment counter every second setInterval(() => { const currentCount = spline.getVariable('counter') || 0; spline.setVariable('counter', currentCount + 1); }, 1000); `; break; case 'camera': interactionCode = ` // Get all cameras const cameras = spline.getObjects().filter(obj => obj.type === 'camera'); console.log('Available cameras:', cameras.map(c => c.name)); // Get the active camera const activeCamera = spline.getActiveCamera(); console.log('Active camera:', activeCamera.name); // Create UI for camera switching const cameraControls = document.createElement('div'); cameraControls.style.position = 'absolute'; cameraControls.style.top = '20px'; cameraControls.style.right = '20px'; cameraControls.style.zIndex = '100'; document.body.appendChild(cameraControls); // Add camera buttons cameras.forEach(camera => { const button = document.createElement('button'); button.textContent = camera.name; button.addEventListener('click', () => { // Switch to this camera spline.setActiveCamera(camera); }); cameraControls.appendChild(button); }); // Camera animation function function animateCameraTo(targetPosition, duration = 1000) { const camera = spline.getActiveCamera(); const startPosition = { ...camera.position }; let startTime = null; function animate(timestamp) { if (!startTime) startTime = timestamp; const elapsed = timestamp - startTime; const progress = Math.min(elapsed / duration, 1); // Ease in-out const easeInOut = progress < 0.5 ? 2 * progress * progress : 1 - Math.pow(-2 * progress + 2, 2) / 2; camera.position.x = startPosition.x + (targetPosition.x - startPosition.x) * easeInOut; camera.position.y = startPosition.y + (targetPosition.y - startPosition.y) * easeInOut; camera.position.z = startPosition.z + (targetPosition.z - startPosition.z) * easeInOut; if (progress < 1) { requestAnimationFrame(animate); } } requestAnimationFrame(animate); } // Example: Add position buttons const positions = [ { name: 'Front', position: { x: 0, y: 0, z: 5 } }, { name: 'Top', position: { x: 0, y: 5, z: 0 } }, { name: 'Side', position: { x: 5, y: 0, z: 0 } } ]; positions.forEach(pos => { const button = document.createElement('button'); button.textContent = pos.name; button.addEventListener('click', () => { animateCameraTo(pos.position); }); cameraControls.appendChild(button); }); `; break; case 'physics': interactionCode = ` // Set up physics (if the scene has physics enabled) // Note: This requires physics to be set up in the Spline scene // Get physics objects const physicsObjects = spline.getObjects().filter(obj => obj.physics); console.log('Physics objects:', physicsObjects.map(obj => obj.name)); // Apply force to an object function applyForce(objectName, force) { const obj = spline.findObjectByName(objectName); if (obj && obj.physics) { obj.physics.applyForce(force); } } // Example: Apply force on click spline.addEventListener('mouseDown', (e) => { if (e.target.physics) { // Apply upward force applyForce(e.target.name, { x: 0, y: 10, z: 0 }); } }); // Create physics controls const physicsControls = document.createElement('div'); physicsControls.style.position = 'absolute'; physicsControls.style.bottom = '20px'; physicsControls.style.left = '20px'; physicsControls.style.zIndex = '100'; document.body.appendChild(physicsControls); // Reset physics button const resetButton = document.createElement('button'); resetButton.textContent = 'Reset Physics'; resetButton.addEventListener('click', () => { // Reset all physics objects physicsObjects.forEach(obj => { obj.physics.reset(); }); }); physicsControls.appendChild(resetButton); // Gravity controls const gravityControls = document.createElement('div'); gravityControls.innerHTML = '<label>Gravity: </label>'; const gravitySlider = document.createElement('input'); gravitySlider.type = 'range'; gravitySlider.min = '0'; gravitySlider.max = '20'; gravitySlider.value = '9.8'; gravitySlider.addEventListener('input', (e) => { // Update gravity const gravity = parseFloat(e.target.value); spline.setPhysicsGravity({ x: 0, y: -gravity, z: 0 }); }); gravityControls.appendChild(gravitySlider); physicsControls.appendChild(gravityControls); `; break; case 'custom': // For custom interaction, use the provided options interactionCode = options?.code || ` // Custom interaction code console.log('Custom interaction code goes here'); // Example: Set up a custom animation loop let time = 0; function animate() { time += 0.01; // Animate all objects spline.getObjects().forEach(obj => { if (obj.type === 'mesh') { // Create wave effect obj.position.y = Math.sin(time + obj.position.x) * 0.2; } }); requestAnimationFrame(animate); } // Start animation loop animate(); `; break; default: interactionCode = ` // Default interaction code console.log('Scene loaded and ready for interaction'); `; } code = baseCode + interactionCode + endCode; return { content: [ { type: 'text', text: code } ] }; } catch (error) { return { content: [ { type: 'text', text: `Error generating scene interaction code: ${error.message}` } ], isError: true }; } } );
• src/tools/runtime-tools.js:127-133 (schema)

  Zod schema defining input parameters: sceneId (string), interactionType (enum of interaction modes), options (optional record).
  { sceneId: z.string().min(1).describe('Scene ID'), interactionType: z.enum([ 'explore', 'eventListeners', 'variables', 'camera', 'physics', 'custom' ]).describe('Type of interaction'), options: z.record(z.any()).optional().describe('Interaction-specific options'), },
• src/index.js:104-104 (registration)

  Top-level registration call that invokes registerRuntimeTools(server), which in turn registers the generateSceneInteractionCode tool among others.
  registerRuntimeTools(server);