@vib3code/sdk 2.0.1 → 2.0.3-canary.91a95f3

package/src/agent/mcp/stdio-server.js

@@ -0,0 +1,264 @@
+#!/usr/bin/env node
+/**
+ * VIB3+ MCP Server — JSON-RPC 2.0 over stdio
+ *
+ * Implements the Model Context Protocol so any MCP client (Claude Desktop,
+ * Cursor, custom agents) can control VIB3+ programmatically.
+ *
+ * Usage:
+ *   node src/agent/mcp/stdio-server.js
+ *
+ * Or via package.json bin:
+ *   vib3-mcp
+ */
+
+import { createInterface } from 'readline';
+import { MCPServer } from './MCPServer.js';
+import { getToolList } from './tools.js';
+
+const SERVER_INFO = {
+    name: 'vib3-mcp',
+    version: '2.0.3',
+    description: 'VIB3+ 4D Visualization MCP Server — 3 systems, 24 geometries, 6D rotation'
+};
+
+// ── JSON-RPC helpers ──
+
+function jsonrpc(id, result) {
+    return JSON.stringify({ jsonrpc: '2.0', id, result });
+}
+
+function jsonrpcError(id, code, message, data) {
+    const err = { jsonrpc: '2.0', id, error: { code, message } };
+    if (data !== undefined) err.error.data = data;
+    return JSON.stringify(err);
+}
+
+function jsonrpcNotification(method, params) {
+    return JSON.stringify({ jsonrpc: '2.0', method, params });
+}
+
+// ── MCP Protocol implementation ──
+
+class VIB3StdioMCP {
+    constructor() {
+        this.server = new MCPServer();
+        this.initialized = false;
+    }
+
+    async handleMessage(raw) {
+        let msg;
+        try {
+            msg = JSON.parse(raw);
+        } catch {
+            return jsonrpcError(null, -32700, 'Parse error');
+        }
+
+        if (msg.jsonrpc !== '2.0') {
+            return jsonrpcError(msg.id ?? null, -32600, 'Invalid Request: missing jsonrpc 2.0');
+        }
+
+        const { id, method, params } = msg;
+
+        switch (method) {
+            case 'initialize':
+                return this.handleInitialize(id, params);
+            case 'initialized':
+                return null; // Notification, no response
+            case 'tools/list':
+                return this.handleToolsList(id);
+            case 'tools/call':
+                return await this.handleToolsCall(id, params);
+            case 'resources/list':
+                return this.handleResourcesList(id);
+            case 'resources/read':
+                return await this.handleResourcesRead(id, params);
+            case 'ping':
+                return jsonrpc(id, {});
+            default:
+                return jsonrpcError(id, -32601, `Method not found: ${method}`);
+        }
+    }
+
+    handleInitialize(id, params) {
+        this.initialized = true;
+
+        return jsonrpc(id, {
+            protocolVersion: '2024-11-05',
+            capabilities: {
+                tools: {},
+                resources: { subscribe: false, listChanged: false }
+            },
+            serverInfo: SERVER_INFO
+        });
+    }
+
+    handleToolsList(id) {
+        const tools = getToolList().map(t => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema
+        }));
+
+        return jsonrpc(id, { tools });
+    }
+
+    async handleToolsCall(id, params) {
+        if (!params?.name) {
+            return jsonrpcError(id, -32602, 'Invalid params: missing tool name');
+        }
+
+        const { name, arguments: args = {} } = params;
+
+        try {
+            const result = await this.server.handleToolCall(name, args);
+
+            return jsonrpc(id, {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify(result, null, 2)
+                    }
+                ],
+                isError: !result.success
+            });
+        } catch (error) {
+            return jsonrpc(id, {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: false,
+                            error: error.message
+                        })
+                    }
+                ],
+                isError: true
+            });
+        }
+    }
+
+    handleResourcesList(id) {
+        return jsonrpc(id, {
+            resources: [
+                {
+                    uri: 'vib3://docs/claude-md',
+                    name: 'CLAUDE.md',
+                    description: 'Full VIB3+ SDK technical reference for AI agents',
+                    mimeType: 'text/markdown'
+                },
+                {
+                    uri: 'vib3://docs/geometry-summary',
+                    name: '24 Geometry + 6D Rotation Summary',
+                    description: 'Complete geometry encoding and rotation plane reference',
+                    mimeType: 'text/markdown'
+                },
+                {
+                    uri: 'vib3://docs/control-reference',
+                    name: 'Control Reference',
+                    description: 'Parameter ranges, keyboard shortcuts, API reference',
+                    mimeType: 'text/markdown'
+                },
+                {
+                    uri: 'vib3://state/current',
+                    name: 'Current Engine State',
+                    description: 'Live engine state (system, geometry, parameters, rotation)',
+                    mimeType: 'application/json'
+                }
+            ]
+        });
+    }
+
+    async handleResourcesRead(id, params) {
+        if (!params?.uri) {
+            return jsonrpcError(id, -32602, 'Invalid params: missing uri');
+        }
+
+        const { uri } = params;
+
+        try {
+            let content;
+            let mimeType = 'text/markdown';
+
+            switch (uri) {
+                case 'vib3://docs/claude-md':
+                    content = await this._readFile('CLAUDE.md');
+                    break;
+                case 'vib3://docs/geometry-summary':
+                    content = await this._readFile('24-GEOMETRY-6D-ROTATION-SUMMARY.md');
+                    break;
+                case 'vib3://docs/control-reference':
+                    content = await this._readFile('DOCS/CONTROL_REFERENCE.md');
+                    break;
+                case 'vib3://state/current':
+                    content = JSON.stringify(this.server.getState(), null, 2);
+                    mimeType = 'application/json';
+                    break;
+                default:
+                    return jsonrpcError(id, -32602, `Unknown resource: ${uri}`);
+            }
+
+            return jsonrpc(id, {
+                contents: [{ uri, mimeType, text: content }]
+            });
+        } catch (error) {
+            return jsonrpcError(id, -32603, `Resource read failed: ${error.message}`);
+        }
+    }
+
+    async _readFile(relativePath) {
+        const { readFile } = await import('fs/promises');
+        const { resolve, dirname } = await import('path');
+        const { fileURLToPath } = await import('url');
+
+        // Resolve relative to project root (3 levels up from src/agent/mcp/)
+        const __dirname = dirname(fileURLToPath(import.meta.url));
+        const projectRoot = resolve(__dirname, '..', '..', '..');
+        const filePath = resolve(projectRoot, relativePath);
+
+        return readFile(filePath, 'utf-8');
+    }
+}
+
+// ── Main: stdio transport ──
+
+async function main() {
+    const mcp = new VIB3StdioMCP();
+
+    const rl = createInterface({
+        input: process.stdin,
+        terminal: false
+    });
+
+    // Log to stderr so stdout stays clean for JSON-RPC
+    const log = (msg) => process.stderr.write(`[vib3-mcp] ${msg}\n`);
+
+    log(`VIB3+ MCP Server v${SERVER_INFO.version} starting on stdio`);
+
+    rl.on('line', async (line) => {
+        const trimmed = line.trim();
+        if (!trimmed) return;
+
+        try {
+            const response = await mcp.handleMessage(trimmed);
+            if (response !== null) {
+                process.stdout.write(response + '\n');
+            }
+        } catch (error) {
+            log(`Error: ${error.message}`);
+            process.stdout.write(
+                jsonrpcError(null, -32603, `Internal error: ${error.message}`) + '\n'
+            );
+        }
+    });
+
+    rl.on('close', () => {
+        log('stdin closed, shutting down');
+        process.exit(0);
+    });
+}
+
+main().catch((err) => {
+    process.stderr.write(`[vib3-mcp] Fatal: ${err.message}\n`);
+    process.exit(1);
+});

package/src/agent/mcp/tools.js

@@ -395,6 +395,373 @@ export const toolDefinitions = {
             type: 'object',
             properties: {}
         }
+    },
+
+    // ===== AGENT-POWER TOOLS (Phase 7 — Agent Harness) =====
+
+    describe_visual_state: {
+        name: 'describe_visual_state',
+        description: 'Returns a structured natural-language description of the current visualization state. Useful for multimodal agents to understand what the visualization looks like without a screenshot. Includes system, geometry, color mood, motion character, and complexity assessment.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    batch_set_parameters: {
+        name: 'batch_set_parameters',
+        description: 'Atomically sets multiple parameters including rotation, visual, and system in one call. Prevents intermediate render states. More efficient than calling set_rotation + set_visual_parameters separately.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                system: {
+                    type: 'string',
+                    enum: ['quantum', 'faceted', 'holographic'],
+                    description: 'Optional: switch system first'
+                },
+                geometry: {
+                    type: 'integer',
+                    minimum: 0,
+                    maximum: 23,
+                    description: 'Geometry index'
+                },
+                rotation: {
+                    type: 'object',
+                    description: '6D rotation angles (all optional)',
+                    properties: {
+                        XY: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        XZ: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        YZ: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        XW: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        YW: { type: 'number', minimum: -6.28, maximum: 6.28 },
+                        ZW: { type: 'number', minimum: -6.28, maximum: 6.28 }
+                    }
+                },
+                visual: {
+                    type: 'object',
+                    description: 'Visual parameters (all optional)',
+                    properties: {
+                        hue: { type: 'integer', minimum: 0, maximum: 360 },
+                        saturation: { type: 'number', minimum: 0, maximum: 1 },
+                        intensity: { type: 'number', minimum: 0, maximum: 1 },
+                        speed: { type: 'number', minimum: 0.1, maximum: 3 },
+                        chaos: { type: 'number', minimum: 0, maximum: 1 },
+                        morphFactor: { type: 'number', minimum: 0, maximum: 2 },
+                        gridDensity: { type: 'number', minimum: 4, maximum: 100 },
+                        dimension: { type: 'number', minimum: 3.0, maximum: 4.5 }
+                    }
+                },
+                preset: {
+                    type: 'string',
+                    enum: ['ambient', 'reactive', 'immersive', 'energetic', 'calm', 'cinematic'],
+                    description: 'Optional: apply behavior preset after setting params'
+                }
+            }
+        }
+    },
+
+    create_timeline: {
+        name: 'create_timeline',
+        description: 'Creates a ParameterTimeline animation from a track specification. Supports multi-parameter keyframe animation with per-keyframe easing, BPM sync, and loop modes. Returns timeline ID for playback control.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Timeline name' },
+                duration_ms: { type: 'integer', minimum: 100, maximum: 600000, description: 'Total duration in milliseconds' },
+                bpm: { type: 'number', minimum: 20, maximum: 300, description: 'Optional BPM for beat-sync quantization' },
+                loop_mode: {
+                    type: 'string',
+                    enum: ['loop', 'bounce', 'once'],
+                    default: 'once',
+                    description: 'Playback loop mode'
+                },
+                tracks: {
+                    type: 'object',
+                    description: 'Parameter tracks. Each key is a parameter name, value is array of keyframes [{time, value, easing}]',
+                    additionalProperties: {
+                        type: 'array',
+                        items: {
+                            type: 'object',
+                            properties: {
+                                time: { type: 'number', description: 'Time in ms from start' },
+                                value: { type: 'number', description: 'Parameter value at this keyframe' },
+                                easing: {
+                                    type: 'string',
+                                    enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'quadIn', 'quadOut', 'cubicIn', 'cubicOut', 'elastic', 'bounce', 'spring', 'overshoot', 'sine', 'exponential'],
+                                    default: 'easeInOut',
+                                    description: 'Easing function for interpolation TO this keyframe'
+                                }
+                            },
+                            required: ['time', 'value']
+                        }
+                    }
+                }
+            },
+            required: ['duration_ms', 'tracks']
+        }
+    },
+
+    play_transition: {
+        name: 'play_transition',
+        description: 'Plays a smooth animated transition from current parameter values to target values, or a sequence of transitions. Uses the TransitionAnimator system with configurable easing.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                sequence: {
+                    type: 'array',
+                    description: 'Array of transition steps. Each step smoothly animates to target params.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            params: {
+                                type: 'object',
+                                description: 'Target parameter values (any VIB3+ parameter)',
+                                additionalProperties: { type: 'number' }
+                            },
+                            duration: { type: 'integer', minimum: 50, maximum: 30000, default: 1000, description: 'Step duration in ms' },
+                            easing: {
+                                type: 'string',
+                                enum: ['linear', 'easeIn', 'easeOut', 'easeInOut', 'quadIn', 'quadOut', 'cubicIn', 'cubicOut', 'elastic', 'bounce', 'spring', 'overshoot', 'sine', 'exponential'],
+                                default: 'easeInOut'
+                            },
+                            delay: { type: 'integer', minimum: 0, default: 0, description: 'Delay before this step starts (ms)' }
+                        },
+                        required: ['params']
+                    }
+                }
+            },
+            required: ['sequence']
+        }
+    },
+
+    apply_color_preset: {
+        name: 'apply_color_preset',
+        description: 'Applies one of 22 themed color presets that set hue, saturation, intensity, and optionally post-processing to create a cohesive visual theme.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                preset: {
+                    type: 'string',
+                    enum: ['Ocean', 'Lava', 'Neon', 'Monochrome', 'Sunset', 'Aurora', 'Cyberpunk', 'Forest', 'Desert', 'Galaxy', 'Ice', 'Fire', 'Toxic', 'Royal', 'Pastel', 'Retro', 'Midnight', 'Tropical', 'Ethereal', 'Volcanic', 'Holographic', 'Vaporwave'],
+                    description: 'Color preset name'
+                }
+            },
+            required: ['preset']
+        }
+    },
+
+    set_post_processing: {
+        name: 'set_post_processing',
+        description: 'Configures post-processing effects pipeline. Supports 14 composable effects and 7 preset chains. Effects are applied in order.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                effects: {
+                    type: 'array',
+                    description: 'Ordered list of effects to apply',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                enum: ['bloom', 'chromaticAberration', 'vignette', 'filmGrain', 'scanlines', 'pixelate', 'blur', 'sharpen', 'colorGrade', 'noise', 'distort', 'glitch', 'rgbShift', 'feedback'],
+                                description: 'Effect name'
+                            },
+                            intensity: { type: 'number', minimum: 0, maximum: 1, default: 0.5, description: 'Effect strength' },
+                            enabled: { type: 'boolean', default: true }
+                        },
+                        required: ['name']
+                    }
+                },
+                chain_preset: {
+                    type: 'string',
+                    description: 'Alternative: apply a named preset chain instead of individual effects'
+                },
+                clear_first: {
+                    type: 'boolean',
+                    default: true,
+                    description: 'Clear existing effects before applying new ones'
+                }
+            }
+        }
+    },
+
+    create_choreography: {
+        name: 'create_choreography',
+        description: 'Creates a multi-scene choreography specification with system transitions, timelines, audio config, and post-processing per scene. This is the most powerful agent tool — it allows designing complete synchronized visual performances that would be extremely difficult to create manually.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Choreography name' },
+                duration_ms: { type: 'integer', minimum: 1000, description: 'Total choreography duration' },
+                bpm: { type: 'number', minimum: 20, maximum: 300, description: 'Optional BPM for beat sync' },
+                scenes: {
+                    type: 'array',
+                    description: 'Ordered scene definitions. Each scene has a time range, system/geometry, and parameter timeline.',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            time_start: { type: 'integer', minimum: 0, description: 'Scene start time (ms)' },
+                            time_end: { type: 'integer', description: 'Scene end time (ms)' },
+                            system: { type: 'string', enum: ['quantum', 'faceted', 'holographic'] },
+                            geometry: { type: 'integer', minimum: 0, maximum: 23 },
+                            transition_in: {
+                                type: 'object',
+                                description: 'How this scene enters (crossfade, cut, etc.)',
+                                properties: {
+                                    type: { type: 'string', enum: ['cut', 'crossfade', 'wipe', 'dissolve', 'zoom'] },
+                                    duration: { type: 'integer', minimum: 0 }
+                                }
+                            },
+                            tracks: {
+                                type: 'object',
+                                description: 'Parameter timeline tracks for this scene (same format as create_timeline)',
+                                additionalProperties: {
+                                    type: 'array',
+                                    items: {
+                                        type: 'object',
+                                        properties: {
+                                            time: { type: 'number' },
+                                            value: { type: 'number' },
+                                            easing: { type: 'string' }
+                                        }
+                                    }
+                                }
+                            },
+                            color_preset: { type: 'string', description: 'Color preset for this scene' },
+                            post_processing: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Post-processing effects active during this scene'
+                            },
+                            audio: {
+                                type: 'object',
+                                description: 'Audio reactivity config for this scene'
+                            }
+                        },
+                        required: ['time_start', 'time_end', 'system']
+                    }
+                }
+            },
+            required: ['name', 'duration_ms', 'scenes']
+        }
+    },
+
+    // ===== VISUAL FEEDBACK TOOLS (Phase 7.1 — Agent Harness) =====
+
+    capture_screenshot: {
+        name: 'capture_screenshot',
+        description: 'Captures the current visualization as a base64-encoded PNG image by compositing all 5 canvas layers. Only works in browser context. Returns image data that multimodal agents can analyze for visual feedback.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                width: { type: 'integer', minimum: 64, maximum: 2048, default: 512, description: 'Output image width' },
+                height: { type: 'integer', minimum: 64, maximum: 2048, default: 512, description: 'Output image height' },
+                format: {
+                    type: 'string',
+                    enum: ['png', 'jpeg', 'webp'],
+                    default: 'png',
+                    description: 'Image format'
+                },
+                quality: { type: 'number', minimum: 0.1, maximum: 1.0, default: 0.92, description: 'JPEG/WebP quality' }
+            }
+        }
+    },
+
+    design_from_description: {
+        name: 'design_from_description',
+        description: 'Maps a natural-language aesthetic description to VIB3+ parameters. Understands emotions (serene, energetic, mysterious), styles (minimal, intricate, organic), colors (ocean, neon, cyberpunk), motion (flowing, pulsing, hypnotic), depth (deep, flat), and geometry (spherical, fractal, crystal). Combine multiple words for precise targeting.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                description: {
+                    type: 'string',
+                    description: 'Space-separated aesthetic descriptors. Examples: "serene ocean deep minimal", "energetic neon geometric", "mysterious galaxy intricate hypnotic"'
+                },
+                apply: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'If true, immediately apply the resolved parameters to the engine'
+                }
+            },
+            required: ['description']
+        }
+    },
+
+    get_aesthetic_vocabulary: {
+        name: 'get_aesthetic_vocabulary',
+        description: 'Returns the full vocabulary of aesthetic descriptor words organized by category (emotions, styles, colors, motion, depth, geometry). Use this to discover what descriptions the system understands.',
+        inputSchema: {
+            type: 'object',
+            properties: {}
+        }
+    },
+
+    play_choreography: {
+        name: 'play_choreography',
+        description: 'Loads and plays a choreography specification on the engine. Requires a choreography spec (from create_choreography) or a stored choreography ID. Controls: play, pause, stop, seek.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                choreography: {
+                    type: 'object',
+                    description: 'Full choreography spec (from create_choreography output). Provide this OR choreography_id.'
+                },
+                choreography_id: {
+                    type: 'string',
+                    description: 'ID of a previously created choreography (from create_choreography)'
+                },
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'stop', 'seek'],
+                    default: 'play',
+                    description: 'Playback action'
+                },
+                seek_percent: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: 'For seek action: position as 0-1 percentage'
+                },
+                loop: {
+                    type: 'boolean',
+                    default: false,
+                    description: 'Loop the choreography'
+                }
+            }
+        }
+    },
+
+    control_timeline: {
+        name: 'control_timeline',
+        description: 'Controls playback of a previously created timeline (from create_timeline). Actions: play, pause, stop, seek, set_speed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                timeline_id: {
+                    type: 'string',
+                    description: 'ID of the timeline to control'
+                },
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'stop', 'seek', 'set_speed'],
+                    description: 'Playback control action'
+                },
+                seek_percent: {
+                    type: 'number',
+                    minimum: 0,
+                    maximum: 1,
+                    description: 'For seek: position as 0-1 percentage'
+                },
+                speed: {
+                    type: 'number',
+                    minimum: 0.1,
+                    maximum: 10,
+                    description: 'For set_speed: playback speed multiplier'
+                }
+            },
+            required: ['timeline_id', 'action']
+        }
     }
 };