unreal-engine-mcp-server 0.4.0 → 0.4.3

package/.env.production

@@ -19,7 +19,7 @@ LOG_LEVEL=info
 
 # Server Settings
 SERVER_NAME=unreal-engine-mcp
-SERVER_VERSION=0.4.0
+SERVER_VERSION=0.4.3
 
 # Connection Settings
 MAX_RETRY_ATTEMPTS=3

package/.github/copilot-instructions.md

@@ -0,0 +1,45 @@
+# Unreal MCP – AI Agent Guide
+
+## Architecture essentials
+- `src/index.ts` boots the Model Context Protocol server, registers output schemas, and connects to Unreal only when a tool/resource call requires it via `ensureConnectedOnDemand`.
+- Consolidated tool routing lives in `src/tools/consolidated-tool-definitions.ts` and `src/tools/consolidated-tool-handlers.ts`, shrinking the surface to 13 multi-action tools that wrap the specialized classes in `src/tools/*`.
+- The Unreal bridge (`src/unreal-bridge.ts`) owns HTTP/WS transport, command throttling, health checks, and graceful fallbacks so callers never talk to Remote Control directly.
+- Health/metrics (connection status, latency, recent errors) are tracked in `index.ts` and exposed through the `ue://health` resource for quick diagnostics.
+
+## Key directories
+- `src/tools/` – domain-specific helpers (actors, landscapes, audio, niagara, etc.) that emit Python scripts or console commands.
+- `src/resources/` – read-only listings (assets, actors, levels) with caching and path normalization utilities.
+- `src/utils/` – shared helpers: validation/coercion, `escapePythonString`, result interpretation, AJV-powered response validation, stdout redirection.
+- `docs/unreal-tool-test-cases.md` + `tests/run-unreal-tool-tests.mjs` – declarative test matrix consumed by the automated harness; reports land in `tests/reports/` with time-stamped JSON.
+
+## Tool workflow expectations
+- New tool actions must be declared in the consolidated definitions (input/output schema) and wired in the handler switch before delegating to the relevant class in `src/tools/*`.
+- Always return plain JS objects with `success`, `message`, `error`, and optional `warnings` arrays; let `responseValidator.wrapResponse` handle MCP formatting.
+- Shared helpers like `interpretStandardResult` and `cleanObject` keep payloads JSON-safe—use them instead of ad-hoc parsing.
+- When validating inputs, reuse `ensureVector3`, `ensureRotation`, and other utilities from `src/utils/validation.ts` to keep error messaging consistent.
+
+## Unreal bridge & Python usage
+- Prefer `bridge.executePythonWithResult` for multi-line scripts; it captures stdout, parses the last `RESULT:` block, and falls back to the console `py` command when plugins are missing.
+- Python snippets should print a single `RESULT:` JSON payload and sanitize inputs with `escapePythonString` or typed coercion helpers.
+- `UnrealBridge.httpCall` enforces timeouts, queues commands, and blocks dangerous console strings (`buildpaths`, `rebuildnavigation`, etc.); avoid bypassing it with raw HTTP.
+- Auto-reconnect is disabled by default—tool handlers should call `ensureConnectedOnDemand()` instead of assuming a live session.
+
+## Response & validation conventions
+- Every consolidated tool has an AJV schema; mismatches surface as `_validation` warnings in responses and appear in stderr logs.
+- For Python-driven tools, use the `interpretResult`/`interpretStandardResult` helpers to turn raw bridge output into the normalized `{ success, message, error, warnings }` shape.
+- Keep warning text short and user-facing—the test harness searches response strings for keywords to grade scenarios.
+
+## Build & test workflow
+- `npm run build` compiles TypeScript to `dist/`; `npm run lint` enforces the ESLint rules shipped in `.eslintrc.json`.
+- `npm run test:tools` launches the compiled server via stdio, iterates the Markdown-defined cases, and writes a JSON run summary under `tests/reports/`.
+- Override harness behavior with env vars like `UNREAL_MCP_SERVER_CMD`, `UNREAL_MCP_SERVER_ARGS`, `UNREAL_MCP_TEST_DOC`, or `UNREAL_MCP_FBX_FILE` when Unreal lives elsewhere.
+
+## Unreal environment & configuration
+- Ensure the project enables: Remote Control API, Remote Control Web Interface, Python Editor Script Plugin, Editor Scripting Utilities, Sequencer, and Level Sequence Editor before invoking automation.
+- Default connection settings come from `UE_HOST`, `UE_RC_HTTP_PORT`, and `UE_RC_WS_PORT` (see README for the `DefaultEngine.ini` snippet that unlocks remote execution).
+- Tools defensively return `UE_NOT_CONNECTED` or asset-not-found errors; keep that contract when extending behavior so clients can retry intelligently.
+
+## Debugging & monitoring
+- Logs are routed to stderr via `routeStdoutLogsToStderr()` to keep MCP stdout JSON-only—check the terminal for detailed stack traces or validation warnings.
+- Use the `ue://health` and `ue://version` resources to confirm bridge connectivity, last health-check timestamp, and detected engine version.
+- The command queue in `UnrealBridge` spaces out console/Python traffic; heavy operations may need explicit `__callTimeoutMs` in the payload to extend HTTP timeouts.

package/.github/workflows/publish-mcp.yml

@@ -49,7 +49,7 @@ jobs:
       - name: Update server.json version
         run: |
           VERSION=${{ steps.version.outputs.version }}
-          jq --arg v "$VERSION" '.version = $v | .packages[] |= if .registry_type == "npm" then .version = $v else . end' server.json > tmp && mv tmp server.json
+          jq --arg v "$VERSION" '.version = $v | .packages[] |= if .registryType == "npm" then .version = $v else . end' server.json > tmp && mv tmp server.json
           echo "Updated server.json:"
           cat server.json
 

package/README.md

@@ -4,6 +4,7 @@
 [![NPM Package](https://img.shields.io/npm/v/unreal-engine-mcp-server)](https://www.npmjs.com/package/unreal-engine-mcp-server)
 [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-TypeScript-blue)](https://github.com/modelcontextprotocol/sdk)
 [![Unreal Engine](https://img.shields.io/badge/Unreal%20Engine-5.0--5.6-orange)](https://www.unrealengine.com/)
+[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-Published-green)](https://registry.modelcontextprotocol.io/)
 
 A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal Engine via Remote Control API. Built with TypeScript and designed for game development automation.
 
@@ -24,11 +25,26 @@ A comprehensive Model Context Protocol (MCP) server that enables AI assistants t
 ### Prerequisites
 - Node.js 18+
 - Unreal Engine 5.0-5.6
-- Required UE Plugins:
-  - Remote Control
-  - Web Remote Control
-  - Python Script Plugin
-  - Editor Scripting Utilities
+- Required UE Plugins (enable via **Edit ▸ Plugins**):
+  - **Remote Control API** – core Remote Control HTTP/WS endpoints
+  - **Remote Control Web Interface** – enables WebSocket bridge used by this server
+  - **Python Editor Script Plugin** – exposes Python runtime for automation
+  - **Editor Scripting Utilities** – unlocks Editor Actor/Asset subsystems used throughout the tools
+  - **Sequencer** *(built-in)* – keep enabled for cinematic tools
+  - **Level Sequence Editor** – required for `manage_sequence` operations
+
+> 💡 After toggling any plugin, restart the editor to finalize activation. Keep `Editor Scripting Utilities` and `Python Editor Script Plugin` enabled prior to connecting, otherwise many subsystem-based tools (actor spawning, audio, foliage, UI widgets) will refuse to run for safety.
+
+### Plugin feature map
+
+| Plugin | Location | Used By | Notes |
+|--------|----------|---------|-------|
+| Remote Control API | Developer Tools ▸ Remote Control | All tools | Provides HTTP/WS endpoints consumed by the MCP bridge |
+| Remote Control Web Interface | Developer Tools ▸ Remote Control | All tools | Enables persistent WebSocket session |
+| Python Editor Script Plugin | Scripting | Landscapes, lighting, audio, physics, sequences, UI | Required for every Python execution path |
+| Editor Scripting Utilities | Scripting | Actors, foliage, assets, landscapes, UI | Supplies Editor Actor/Asset subsystems in UE5.6 |
+| Sequencer | Built-in | Sequencer tools | Ensure not disabled in project settings |
+| Level Sequence Editor | Animation | Sequencer tools | Activate before calling `manage_sequence` operations |
 
 ### Installation
 

package/dist/index.js

@@ -36,6 +36,7 @@ import { responseValidator } from './utils/response-validator.js';
 import { ErrorHandler } from './utils/error-handler.js';
 import { routeStdoutLogsToStderr } from './utils/stdio-redirect.js';
 import { cleanObject } from './utils/safe-json.js';
+import { createElicitationHelper } from './utils/elicitation.js';
 const log = new Logger('UE-MCP');
 // Ensure stdout remains JSON-only for MCP by routing logs to stderr unless opted out.
 routeStdoutLogsToStderr();
@@ -61,7 +62,7 @@ const CONFIG = {
     RETRY_DELAY_MS: 2000,
     // Server info
     SERVER_NAME: 'unreal-engine-mcp',
-    SERVER_VERSION: '0.4.0',
+    SERVER_VERSION: '0.4.3',
     // Monitoring
     HEALTH_CHECK_INTERVAL_MS: 30000 // 30 seconds
 };
@@ -211,10 +212,34 @@ export async function createServer() {
         capabilities: {
             resources: {},
             tools: {},
-            prompts: {},
-            logging: {}
+            prompts: {
+                listChanged: false
+            },
+            logging: {},
+            elicitation: {}
         }
     });
+    // Optional elicitation helper – used only if client supports it.
+    const elicitation = createElicitationHelper(server, log);
+    const defaultElicitationTimeoutMs = elicitation.getDefaultTimeoutMs();
+    const createNotConnectedResponse = (toolName) => {
+        const payload = {
+            success: false,
+            error: 'UE_NOT_CONNECTED',
+            message: 'Unreal Engine is not connected (after 3 attempts). Please open UE and try again.',
+            retriable: false,
+            scope: `tool-call/${toolName}`
+        };
+        return responseValidator.wrapResponse(toolName, {
+            ...payload,
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(payload, null, 2)
+                }
+            ]
+        });
+    };
     // Handle resource listing
     server.setRequestHandler(ListResourcesRequestSchema, async () => {
         return {
@@ -402,20 +427,14 @@ export async function createServer() {
     });
     // Handle tool calls - consolidated tools only (13)
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
-        const { name, arguments: args } = request.params;
+        const { name } = request.params;
+        let args = request.params.arguments || {};
         const startTime = Date.now();
         // Ensure connection only when needed, with 3 attempts
         const connected = await ensureConnectedOnDemand();
         if (!connected) {
-            const notConnected = {
-                content: [{ type: 'text', text: 'Unreal Engine is not connected (after 3 attempts). Please open UE and try again.' }],
-                success: false,
-                error: 'UE_NOT_CONNECTED',
-                retriable: false,
-                scope: `tool-call/${name}`
-            };
             trackPerformance(startTime, false);
-            return notConnected;
+            return createNotConnectedResponse(name);
         }
         // Create tools object for handler
         const tools = {
@@ -441,6 +460,10 @@ export async function createServer() {
             introspectionTools,
             visualTools,
             engineTools,
+            // Elicitation (client-optional)
+            elicit: elicitation.elicit,
+            supportsElicitation: elicitation.supports,
+            elicitationTimeoutMs: defaultElicitationTimeoutMs,
             // Resources for listing and info
             assetResources,
             actorResources,
@@ -450,6 +473,62 @@ export async function createServer() {
         // Execute consolidated tool handler
         try {
             log.debug(`Executing tool: ${name}`);
+            // Opportunistic generic elicitation for missing primitive required fields
+            try {
+                const toolDef = consolidatedToolDefinitions.find(t => t.name === name);
+                const inputSchema = toolDef?.inputSchema;
+                const elicitFn = tools.elicit;
+                if (inputSchema && typeof elicitFn === 'function') {
+                    const props = inputSchema.properties || {};
+                    const required = Array.isArray(inputSchema.required) ? inputSchema.required : [];
+                    const missing = required.filter((k) => {
+                        const v = args[k];
+                        if (v === undefined || v === null)
+                            return true;
+                        if (typeof v === 'string' && v.trim() === '')
+                            return true;
+                        return false;
+                    });
+                    // Build a flat primitive-only schema subset per MCP Elicitation rules
+                    const primitiveProps = {};
+                    for (const k of missing) {
+                        const p = props[k];
+                        if (!p || typeof p !== 'object')
+                            continue;
+                        const t = (p.type || '').toString();
+                        const isEnum = Array.isArray(p.enum);
+                        if (t === 'string' || t === 'number' || t === 'integer' || t === 'boolean' || isEnum) {
+                            primitiveProps[k] = {
+                                type: t || (isEnum ? 'string' : undefined),
+                                title: p.title,
+                                description: p.description,
+                                enum: p.enum,
+                                enumNames: p.enumNames,
+                                minimum: p.minimum,
+                                maximum: p.maximum,
+                                minLength: p.minLength,
+                                maxLength: p.maxLength,
+                                pattern: p.pattern,
+                                format: p.format,
+                                default: p.default
+                            };
+                        }
+                    }
+                    if (Object.keys(primitiveProps).length > 0) {
+                        const elicitOptions = { fallback: async () => ({ ok: false, error: 'missing-params' }) };
+                        if (typeof tools.elicitationTimeoutMs === 'number' && Number.isFinite(tools.elicitationTimeoutMs)) {
+                            elicitOptions.timeoutMs = tools.elicitationTimeoutMs;
+                        }
+                        const elicitRes = await elicitFn(`Provide missing parameters for ${name}`, { type: 'object', properties: primitiveProps, required: Object.keys(primitiveProps) }, elicitOptions);
+                        if (elicitRes && elicitRes.ok && elicitRes.value) {
+                            args = { ...args, ...elicitRes.value };
+                        }
+                    }
+                }
+            }
+            catch (e) {
+                log.debug('Generic elicitation prefill skipped', { err: e?.message || String(e) });
+            }
             let result = await handleConsolidatedToolCall(name, args, tools);
             log.debug(`Tool ${name} returned result`);
             // Clean the result to remove circular references
@@ -481,13 +560,23 @@ export async function createServer() {
                     metrics.recentErrors.splice(0, metrics.recentErrors.length - 20);
             }
             catch { }
-            return {
+            const sanitizedError = cleanObject(errorResponse);
+            let errorText = '';
+            try {
+                errorText = JSON.stringify(sanitizedError, null, 2);
+            }
+            catch {
+                errorText = sanitizedError.message || errorResponse.message || `Failed to execute ${name}`;
+            }
+            const wrappedError = {
+                ...sanitizedError,
+                isError: true,
                 content: [{
                         type: 'text',
-                        text: errorResponse.message || `Failed to execute ${name}`
-                    }],
-                ...errorResponse
+                        text: errorText
+                    }]
             };
+            return responseValidator.wrapResponse(name, wrappedError);
         }
     });
     // Handle prompt listing
@@ -496,11 +585,21 @@ export async function createServer() {
             prompts: prompts.map(p => ({
                 name: p.name,
                 description: p.description,
-                arguments: Object.entries(p.arguments || {}).map(([name, schema]) => ({
-                    name,
-                    description: schema.description,
-                    required: schema.required || false
-                }))
+                arguments: Object.entries(p.arguments || {}).map(([name, schema]) => {
+                    const meta = {};
+                    if (schema.type)
+                        meta.type = schema.type;
+                    if (schema.enum)
+                        meta.enum = schema.enum;
+                    if (schema.default !== undefined)
+                        meta.default = schema.default;
+                    return {
+                        name,
+                        description: schema.description,
+                        required: schema.required ?? false,
+                        ...(Object.keys(meta).length ? { _meta: meta } : {})
+                    };
+                })
             }))
         };
     });
@@ -510,17 +609,11 @@ export async function createServer() {
         if (!prompt) {
             throw new Error(`Unknown prompt: ${request.params.name}`);
         }
-        // Return a template for the lighting setup
+        const args = (request.params.arguments || {});
+        const messages = prompt.build(args);
         return {
-            messages: [
-                {
-                    role: 'user',
-                    content: {
-                        type: 'text',
-                        text: `Set up three-point lighting with ${request.params.arguments?.intensity || 'medium'} intensity`
-                    }
-                }
-            ]
+            description: prompt.description,
+            messages
         };
     });
     return { server, bridge };

package/dist/prompts/index.d.ts

@@ -2,13 +2,20 @@ export interface PromptArgument {
     type: string;
     description?: string;
     enum?: string[];
-    default?: any;
+    default?: unknown;
     required?: boolean;
 }
-export interface Prompt {
+export interface PromptTemplate {
     name: string;
     description: string;
     arguments?: Record<string, PromptArgument>;
+    build: (args: Record<string, unknown>) => Array<{
+        role: 'user' | 'assistant';
+        content: {
+            type: 'text';
+            text: string;
+        };
+    }>;
 }
-export declare const prompts: Prompt[];
+export declare const prompts: PromptTemplate[];
 //# sourceMappingURL=index.d.ts.map

package/dist/prompts/index.js

@@ -1,37 +1,216 @@
+function clampChoice(value, choices, fallback) {
+    if (typeof value === 'string') {
+        const normalized = value.toLowerCase();
+        if (choices.includes(normalized)) {
+            return normalized;
+        }
+    }
+    return fallback;
+}
+function coerceNumber(value, fallback, min, max) {
+    const num = typeof value === 'number' ? value : Number(value);
+    if (!Number.isFinite(num)) {
+        return fallback;
+    }
+    if (min !== undefined && num < min) {
+        return min;
+    }
+    if (max !== undefined && num > max) {
+        return max;
+    }
+    return num;
+}
+function formatVector(value) {
+    if (!value || typeof value !== 'object') {
+        return null;
+    }
+    const vector = value;
+    const x = typeof vector.x === 'number' ? vector.x : Number(vector.x);
+    const y = typeof vector.y === 'number' ? vector.y : Number(vector.y);
+    const z = typeof vector.z === 'number' ? vector.z : Number(vector.z);
+    if ([x, y, z].some((component) => !Number.isFinite(component))) {
+        return null;
+    }
+    return `${x.toFixed(2)}, ${y.toFixed(2)}, ${z.toFixed(2)}`;
+}
 export const prompts = [
     {
         name: 'setup_three_point_lighting',
-        description: 'Set up a basic three-point lighting rig around the current camera focus',
+        description: 'Author a cinematic three-point lighting rig aligned to the active camera focus.',
         arguments: {
             intensity: {
                 type: 'string',
                 enum: ['low', 'medium', 'high'],
                 default: 'medium',
-                description: 'Light intensity level'
+                description: 'Overall lighting mood. Low = dramatic contrast, high = bright key light.'
             }
+        },
+        build: (args) => {
+            const intensity = clampChoice(args.intensity, ['low', 'medium', 'high'], 'medium');
+            const moodHints = {
+                low: 'gentle key with strong contrast and subtle rim highlights',
+                medium: 'balanced key/fill ratio for natural coverage',
+                high: 'bright key with energetic fill and crisp rim separation'
+            };
+            const text = `Configure a three-point lighting rig around the current cinematic focus.
+
+Tasks:
+- Position a key light roughly 45° off-axis at eye level. Target the subject center and tune intensity for ${intensity} output (${moodHints[intensity]}).
+- Add a fill light on the opposite side with wider spread and softened shadows to control contrast.
+- Place a rim/back light to outline silhouettes and separate the subject from the background.
+- Ensure all lights use physically plausible color temperature, enable shadow casting where helpful, and adjust attenuation to avoid spill.
+- Once balanced, report the final intensity values, color temperatures, and any blockers encountered.`;
+            return [{
+                    role: 'user',
+                    content: { type: 'text', text }
+                }];
         }
     },
     {
         name: 'create_fps_controller',
-        description: 'Create a first-person shooter character controller',
+        description: 'Spin up a first-person controller blueprint with input mappings, collision, and starter movement.',
         arguments: {
             spawnLocation: {
-                type: 'object',
-                description: 'Location to spawn the controller',
+                type: 'vector',
+                description: 'Optional XYZ spawn position for the player pawn.',
                 required: false
             }
+        },
+        build: (args) => {
+            const spawnVector = formatVector(args.spawnLocation);
+            const spawnLine = spawnVector ? `Spawn the pawn at world coordinates (${spawnVector}).` : 'Spawn the pawn at a safe default player start or the origin.';
+            const text = `Build a First Person Character blueprint with:
+- Camera + arms mesh, basic WASD input, jump, crouch, and sprint bindings using Enhanced Input.
+- Proper collision capsule sizing for a 180cm tall human.
+- Momentum-preserving air control with configurable acceleration and friction.
+- A configurable base turn rate with mouse sensitivity scaling.
+- Serialized defaults for walking speed (600 uu/s) and sprint speed (900 uu/s).
+- Expose key movement settings as editable defaults.
+- ${spawnLine}
+
+Finish by compiling, saving, and summarizing the created blueprint path plus the mapped input actions.`;
+            return [{
+                    role: 'user',
+                    content: { type: 'text', text }
+                }];
         }
     },
     {
         name: 'setup_post_processing',
-        description: 'Configure post-processing volume with cinematic settings',
+        description: 'Author a post-process volume tuned to a named cinematic grade.',
         arguments: {
             style: {
                 type: 'string',
                 enum: ['cinematic', 'realistic', 'stylized', 'noir'],
                 default: 'cinematic',
-                description: 'Visual style preset'
+                description: 'Look preset to emphasize color grading and tone-mapping style.'
+            }
+        },
+        build: (args) => {
+            const style = clampChoice(args.style, ['cinematic', 'realistic', 'stylized', 'noir'], 'cinematic');
+            const styleNotes = {
+                cinematic: 'filmic tonemapper, gentle bloom, warm highlights, cool shadows, slight vignette',
+                realistic: 'minimal grading, accurate white balance, restrained bloom, detail-preserving sharpening',
+                stylized: 'bold saturation shifts, custom color LUT, exaggerated contrast, selective bloom',
+                noir: 'monochrome conversion, strong contrast curve, subtle film grain, heavy vignette'
+            };
+            const text = `Create a global post-process volume with priority over level defaults.
+- Apply the "${style}" look: ${styleNotes[style]}.
+- Configure tone mapping, exposure, bloom, chromatic aberration, and LUTs as required.
+- Ensure the volume is unbound unless level-specific constraints apply.
+- Provide sanity checks for HDR output and keep auto-exposure transitions smooth.
+- Summarize all modified settings with their final numeric values or asset references.`;
+            return [{
+                    role: 'user',
+                    content: { type: 'text', text }
+                }];
+        }
+    },
+    {
+        name: 'setup_dynamic_day_night_cycle',
+        description: 'Create or update a Blueprint to drive a dynamic day/night cycle with optional weather hooks.',
+        arguments: {
+            startTime: {
+                type: 'string',
+                enum: ['dawn', 'noon', 'dusk', 'midnight'],
+                default: 'dawn',
+                description: 'Initial lighting state for the cycle.'
+            },
+            transitionMinutes: {
+                type: 'number',
+                default: 5,
+                description: 'Game-time minutes to blend between major lighting states.'
+            },
+            enableWeather: {
+                type: 'boolean',
+                default: false,
+                description: 'Whether to expose hooks for weather-driven sky adjustments.'
+            }
+        },
+        build: (args) => {
+            const startTime = clampChoice(args.startTime, ['dawn', 'noon', 'dusk', 'midnight'], 'dawn');
+            const transitionMinutes = coerceNumber(args.transitionMinutes, 5, 1, 60);
+            const enableWeather = Boolean(args.enableWeather);
+            const weatherLine = enableWeather
+                ? '- Expose interfaces for cloud opacity, precipitation-driven skylight updates, and lightning flashes.'
+                : '- Weather hooks are disabled; keep the blueprint lean';
+            const text = `Implement a Blueprint-based day/night cycle manager.
+- Start the sequence at ${startTime} lighting.
+- Advance sun rotation, skylight captures, fog, and sky atmosphere continuously with ${transitionMinutes} minute blends between key states.
+- Sync directional light intensity/color with real-world sun elevation and inject moonlight at night.
+- ${weatherLine}.
+- Provide editor controls for time-of-day multiplier and manual overrides.
+- Document the generated blueprint path and exposed parameters.`;
+            return [{
+                    role: 'user',
+                    content: { type: 'text', text }
+                }];
+        }
+    },
+    {
+        name: 'design_cinematic_camera_move',
+        description: 'Author a sequencer shot with a polished camera move and easing markers.',
+        arguments: {
+            durationSeconds: {
+                type: 'number',
+                default: 6,
+                description: 'Shot duration in seconds.'
+            },
+            moveStyle: {
+                type: 'string',
+                enum: ['push_in', 'orbit', 'tracking', 'crane'],
+                default: 'push_in',
+                description: 'Camera move archetype to emphasize.'
+            },
+            focusTarget: {
+                type: 'string',
+                description: 'Optional actor or component name to keep in focus.',
+                required: false
             }
+        },
+        build: (args) => {
+            const duration = coerceNumber(args.durationSeconds, 6, 2, 30);
+            const moveStyle = clampChoice(args.moveStyle, ['push_in', 'orbit', 'tracking', 'crane'], 'push_in');
+            const focusLine = typeof args.focusTarget === 'string' && args.focusTarget.trim().length > 0
+                ? `Lock focus distance on "${args.focusTarget}" and animate depth of field pulls if necessary.`
+                : 'Pick the most prominent subject in frame and maintain crisp focus throughout the move.';
+            const moveHints = {
+                push_in: 'Ease-in push toward the subject with gentle camera roll stabilization.',
+                orbit: '360° orbit with consistent parallax and a tracked look-at target.',
+                tracking: 'Match the subject velocity along a spline with smoothed acceleration.',
+                crane: 'Combine vertical rise with lateral drift for a reveal shot.'
+            };
+            const text = `In Sequencer, author a ${duration.toFixed(1)} second cinematic shot.
+- Movement style: ${moveStyle} (${moveHints[moveStyle]}).
+- Key auto-exposure, camera focal length, and focal distance for a premium look.
+- Add ease-in/ease-out tangents at shot boundaries to avoid abrupt starts/stops.
+- ${focusLine}
+- Annotate the timeline with intent markers (intro beat, climax, resolve).
+- Render a preview range and summarize the created assets.`;
+            return [{
+                    role: 'user',
+                    content: { type: 'text', text }
+                }];
         }
     }
 ];

package/dist/resources/actors.d.ts

@@ -7,7 +7,25 @@ export declare class ActorResources {
     private getFromCache;
     private setCache;
     listActors(): Promise<any>;
-    getActorByName(actorName: string): Promise<any>;
+    getActorByName(actorName: string): Promise<{
+        success: true;
+        name: string;
+        path: string | undefined;
+        class: string | undefined;
+        error?: undefined;
+    } | {
+        success: false;
+        error: string;
+        name?: undefined;
+        path?: undefined;
+        class?: undefined;
+    } | {
+        error: string;
+        success?: undefined;
+        name?: undefined;
+        path?: undefined;
+        class?: undefined;
+    }>;
     getActorTransform(actorPath: string): Promise<any>;
 }
 //# sourceMappingURL=actors.d.ts.map