lemolabs-spotter-mcp 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+# SPOTTER MCP Server
+
+AI sound design spotting as an MCP tool for Claude Code.
+
+Analyzes any video → generates a complete cue sheet → optionally generates or searches SFX audio → exports DAW-synchronized WAV stems.
+
+## Install
+
+```bash
+git clone <repo>
+cd spotter/mcp-server
+npm install
+npm run build
+```
+
+## Add to Claude Code
+
+Edit `~/.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "spotter": {
+      "command": "node",
+      "args": ["/absolute/path/to/spotter/mcp-server/dist/index.js"]
+    }
+  }
+}
+```
+
+Restart Claude Code. Verify with `/mcp` — you should see `spotter` listed.
+
+## Configure providers
+
+### ElevenLabs (SFX generation)
+
+```
+configure_provider({ provider: "elevenlabs", api_key: "YOUR_KEY" })
+```
+
+### Freesound (SFX search)
+
+Get a free API key at freesound.org/apiv2:
+
+```
+configure_provider({ provider: "freesound", api_key: "YOUR_KEY" })
+```
+
+### Custom REST provider
+
+Any API that accepts `POST { prompt, duration_seconds }` and returns audio:
+
+```
+configure_provider({
+  provider: "my_sfx_api",
+  api_key: "YOUR_KEY",
+  endpoint: "https://api.example.com/v1/generate"
+})
+```
+
+Config stored in `~/.spotter/config.json`.
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `analyze_video` | Extract frames → AI analysis → cue sheet (analysis.json) |
+| `generate_sfx` | Generate audio from text prompt via ElevenLabs or custom provider |
+| `search_sfx` | Search Freesound for existing recordings |
+| `export_stems` | Export DAW-ready WAV stems + CSV cue sheet |
+| `list_providers` | Show configured providers and their status |
+| `configure_provider` | Add/update API keys and endpoints |
+
+## Typical workflow
+
+```
+# 1. Analyze a video
+analyze_video({ video_path: "/path/to/scene.mp4", criterio: "dark thriller, minimal music, emphasis on environment" })
+
+# 2. Generate SFX for specific cues (returns audio files in project/media/)
+generate_sfx({ prompt: "heavy rain on metal roof, distant thunder", duration_seconds: 8, output_dir: "/path/to/project/media" })
+
+# 3. Export DAW stems (pads each clip to full video length with silence before/after)
+export_stems({ project_dir: "/path/to/project", video_duration: 120.5 })
+```
+
+The exported WAVs drop directly into any DAW (Reaper, Logic, Pro Tools, etc.) at the correct timecode — no manual alignment needed.
+
+## Project structure
+
+```
+~/Documents/Proyectos SPOTTER/<timestamp>_<name>/
+├── analysis.json       # Full cue sheet (cues array + narrative)
+├── criterio.txt        # Director's intent (if provided)
+├── frames/             # Extracted JPGs used for analysis
+├── media/              # Generated/downloaded audio files
+└── export/
+    ├── cue_sheet.csv   # Human-readable cue sheet
+    └── AMB_cue_001_*.wav  # DAW-synchronized stems
+```
+
+## Use without the Electron app
+
+SPOTTER MCP works standalone — you don't need the Electron app. The Electron app is for step-by-step manual control; the MCP server is for fully automated pipeline use from Claude Code.

package/dist/config.d.ts

@@ -0,0 +1,14 @@
+export interface ProviderConfig {
+    apiKey?: string;
+    endpoint?: string;
+    enabled: boolean;
+    type?: 'sfx-generate' | 'sfx-search' | 'both';
+}
+export interface SpotterConfig {
+    claudePath: string;
+    providers: Record<string, ProviderConfig>;
+}
+export declare function loadConfig(): SpotterConfig;
+export declare function saveConfig(config: SpotterConfig): void;
+export declare function getKey(name: string): string | null;
+export declare function setKey(name: string, apiKey: string): void;

package/dist/config.js

@@ -0,0 +1,36 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+const CONFIG_DIR = path.join(os.homedir(), '.spotter');
+const CONFIG_PATH = path.join(CONFIG_DIR, 'config.json');
+const DEFAULTS = {
+    claudePath: 'claude',
+    providers: {
+        elevenlabs: { enabled: false, type: 'sfx-generate' },
+        freesound: { enabled: false, type: 'sfx-search' },
+    }
+};
+export function loadConfig() {
+    if (!fs.existsSync(CONFIG_PATH))
+        return DEFAULTS;
+    try {
+        const raw = JSON.parse(fs.readFileSync(CONFIG_PATH, 'utf-8'));
+        return { ...DEFAULTS, ...raw, providers: { ...DEFAULTS.providers, ...raw.providers } };
+    }
+    catch {
+        return DEFAULTS;
+    }
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2), 'utf-8');
+}
+export function getKey(name) {
+    const cfg = loadConfig();
+    return cfg.providers[name]?.apiKey ?? null;
+}
+export function setKey(name, apiKey) {
+    const cfg = loadConfig();
+    cfg.providers[name] = { ...(cfg.providers[name] ?? { enabled: true }), apiKey };
+    saveConfig(cfg);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,213 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { analyzeVideo } from './tools/analyze.js';
+import { exportStems } from './tools/export.js';
+import { getProvider, listProviders } from './providers/registry.js';
+import { loadConfig, setKey, saveConfig } from './config.js';
+import path from 'path';
+import fs from 'fs';
+const server = new Server({ name: 'spotter', version: '0.1.0' }, { capabilities: { tools: {} } });
+// ─── Tool definitions ────────────────────────────────────────────────────────
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: 'analyze_video',
+            description: 'Analyze a video file for sound design. Extracts frames, runs AI analysis, returns a complete cue sheet with sound descriptions and timecodes.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    video_path: { type: 'string', description: 'Absolute path to the video file (.mp4, .mov)' },
+                    project_dir: { type: 'string', description: 'Optional: directory to store project files. Defaults to ~/Documents/Proyectos SPOTTER/<timestamp>_<name>' },
+                    criterio: { type: 'string', description: "Optional: director's intent / sonic references (free text, passed to the AI)" },
+                },
+                required: ['video_path']
+            }
+        },
+        {
+            name: 'generate_sfx',
+            description: 'Generate a sound effect audio file from a text prompt using ElevenLabs or a configured provider.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    prompt: { type: 'string', description: 'Sound description in English (e.g. "heavy rain on metal roof, distant thunder rumble")' },
+                    duration_seconds: { type: 'number', description: 'Duration in seconds (0.5–22). Default: 5', default: 5 },
+                    output_dir: { type: 'string', description: 'Directory to save the generated audio file' },
+                    provider: { type: 'string', description: 'Provider name (elevenlabs, or any configured custom provider). Default: first enabled provider' },
+                },
+                required: ['prompt', 'output_dir']
+            }
+        },
+        {
+            name: 'search_sfx',
+            description: 'Search for sound effects on Freesound or a configured search provider.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'Search query in English' },
+                    max_results: { type: 'number', description: 'Maximum results to return (1–20). Default: 10', default: 10 },
+                    provider: { type: 'string', description: 'Search provider. Default: freesound' },
+                },
+                required: ['query']
+            }
+        },
+        {
+            name: 'export_stems',
+            description: 'Export DAW-synchronized WAV stems + CSV cue sheet from a SPOTTER project. Each WAV starts at the correct timecode position for direct import into any DAW.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    project_dir: { type: 'string', description: 'Path to the SPOTTER project directory (must contain analysis.json and media/ folder)' },
+                    video_duration: { type: 'number', description: 'Video duration in seconds (used to pad WAV files to full length)' },
+                    cues: { type: 'string', description: 'Optional: JSON array of cue objects with updated positions. If omitted, reads from project analysis.json' },
+                },
+                required: ['project_dir', 'video_duration']
+            }
+        },
+        {
+            name: 'list_providers',
+            description: 'List all configured SFX providers and their status.',
+            inputSchema: { type: 'object', properties: {} }
+        },
+        {
+            name: 'configure_provider',
+            description: 'Add or update an SFX provider API key or endpoint. Stored in ~/.spotter/config.json.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    provider: { type: 'string', description: 'Provider name (e.g. elevenlabs, freesound, or a custom name)' },
+                    api_key: { type: 'string', description: 'API key for the provider' },
+                    endpoint: { type: 'string', description: 'Optional: custom REST endpoint for generate (POST with {prompt, duration_seconds} body)' },
+                    enabled: { type: 'boolean', description: 'Enable or disable this provider', default: true },
+                },
+                required: ['provider']
+            }
+        },
+    ]
+}));
+// ─── Tool handlers ────────────────────────────────────────────────────────────
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    if (!args)
+        throw new McpError(ErrorCode.InvalidParams, 'Missing arguments');
+    try {
+        switch (name) {
+            case 'analyze_video': {
+                const result = await analyzeVideo({
+                    videoPath: args.video_path,
+                    projectDir: args.project_dir,
+                    criterio: args.criterio,
+                });
+                const analysis = result.analysis;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify({
+                                projectDir: result.projectDir,
+                                analysisPath: result.analysisPath,
+                                cueCount: (analysis.cues ?? []).length,
+                                narrative: analysis.narrative,
+                                cues: analysis.cues,
+                            }, null, 2)
+                        }]
+                };
+            }
+            case 'generate_sfx': {
+                const provider = getProvider(args.provider);
+                if (!provider.canGenerate || !provider.generate) {
+                    throw new McpError(ErrorCode.InvalidParams, `Provider "${provider.name}" does not support generation`);
+                }
+                const result = await provider.generate(args.prompt, args.duration_seconds ?? 5, args.output_dir);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            }
+            case 'search_sfx': {
+                const provider = getProvider(args.provider ?? 'freesound');
+                if (!provider.canSearch || !provider.search) {
+                    throw new McpError(ErrorCode.InvalidParams, `Provider "${provider.name}" does not support search`);
+                }
+                const results = await provider.search(args.query, args.max_results ?? 10);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(results, null, 2)
+                        }]
+                };
+            }
+            case 'export_stems': {
+                const projectDir = args.project_dir;
+                const videoDuration = args.video_duration;
+                let cues;
+                if (args.cues) {
+                    cues = JSON.parse(args.cues);
+                }
+                else {
+                    const analysisPath = path.join(projectDir, 'analysis.json');
+                    if (!fs.existsSync(analysisPath)) {
+                        throw new McpError(ErrorCode.InvalidParams, `No analysis.json found in ${projectDir}`);
+                    }
+                    const analysis = JSON.parse(fs.readFileSync(analysisPath, 'utf-8'));
+                    cues = analysis.cues ?? [];
+                }
+                const result = await exportStems(projectDir, cues, videoDuration);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            }
+            case 'list_providers': {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(listProviders(), null, 2)
+                        }]
+                };
+            }
+            case 'configure_provider': {
+                const providerName = args.provider;
+                const cfg = loadConfig();
+                cfg.providers[providerName] = {
+                    ...(cfg.providers[providerName] ?? {}),
+                    enabled: args.enabled ?? true,
+                    ...(args.api_key ? { apiKey: args.api_key } : {}),
+                    ...(args.endpoint ? { endpoint: args.endpoint, type: 'sfx-generate' } : {}),
+                };
+                saveConfig(cfg);
+                // Also mirror to setKey for convenience
+                if (args.api_key)
+                    setKey(providerName, args.api_key);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Provider "${providerName}" configured. Config saved to ~/.spotter/config.json`
+                        }]
+                };
+            }
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof McpError)
+            throw e;
+        throw new McpError(ErrorCode.InternalError, e instanceof Error ? e.message : String(e));
+    }
+});
+// ─── Start ────────────────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr is safe for logging (doesn't pollute MCP stdio)
+    process.stderr.write('SPOTTER MCP server running\n');
+}
+main().catch(err => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/providers/registry.d.ts

@@ -0,0 +1,30 @@
+export interface SfxGenerateResult {
+    filePath: string;
+    provider: string;
+    prompt: string;
+    durationSeconds: number;
+}
+export interface SfxSearchResult {
+    id: string;
+    name: string;
+    duration: number;
+    username: string;
+    license: string;
+    previewUrl: string;
+    sourceUrl: string;
+    provider: string;
+}
+export interface SfxProvider {
+    name: string;
+    canGenerate: boolean;
+    canSearch: boolean;
+    generate?(prompt: string, durationSeconds: number, outputDir: string): Promise<SfxGenerateResult>;
+    search?(query: string, maxResults?: number): Promise<SfxSearchResult[]>;
+}
+export declare function getProvider(name?: string): SfxProvider;
+export declare function listProviders(): Array<{
+    name: string;
+    enabled: boolean;
+    hasKey: boolean;
+    type: string;
+}>;

package/dist/providers/registry.js

@@ -0,0 +1,115 @@
+import { loadConfig } from '../config.js';
+// ─── ElevenLabs provider ─────────────────────────────────────────────────────
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+const elevenLabsProvider = {
+    name: 'elevenlabs',
+    canGenerate: true,
+    canSearch: false,
+    async generate(prompt, durationSeconds, outputDir) {
+        const cfg = loadConfig();
+        const key = cfg.providers['elevenlabs']?.apiKey;
+        if (!key)
+            throw new Error('ElevenLabs API key not configured. Run: spotter-mcp config set elevenlabs.apiKey YOUR_KEY');
+        const res = await fetch('https://api.elevenlabs.io/v1/sound-generation', {
+            method: 'POST',
+            headers: { 'xi-api-key': key, 'Content-Type': 'application/json' },
+            body: JSON.stringify({ text: prompt, duration_seconds: durationSeconds, prompt_influence: 0.6 })
+        });
+        if (!res.ok) {
+            const body = await res.text();
+            throw new Error(`ElevenLabs error ${res.status}: ${body.slice(0, 200)}`);
+        }
+        fs.mkdirSync(outputDir, { recursive: true });
+        const slug = prompt.slice(0, 32).replace(/[^a-zA-Z0-9]/g, '_');
+        const id = crypto.randomBytes(4).toString('hex');
+        const filename = `el_${slug}_${id}.mp3`;
+        const filePath = path.join(outputDir, filename);
+        fs.writeFileSync(filePath, Buffer.from(await res.arrayBuffer()));
+        return { filePath, provider: 'elevenlabs', prompt, durationSeconds };
+    }
+};
+// ─── Freesound provider ──────────────────────────────────────────────────────
+const freesoundProvider = {
+    name: 'freesound',
+    canGenerate: false,
+    canSearch: true,
+    async search(query, maxResults = 12) {
+        const cfg = loadConfig();
+        const key = cfg.providers['freesound']?.apiKey;
+        if (!key)
+            throw new Error('Freesound API key not configured. Run: spotter-mcp config set freesound.apiKey YOUR_KEY');
+        const params = new URLSearchParams({
+            query, token: key,
+            fields: 'id,name,duration,previews,license,username,url',
+            page_size: String(maxResults),
+            filter: 'duration:[1 TO 60]',
+            sort: 'score'
+        });
+        const res = await fetch(`https://freesound.org/apiv2/search/text/?${params}`);
+        if (!res.ok)
+            throw new Error(`Freesound error ${res.status}`);
+        const data = await res.json();
+        return (data.results ?? []).map(r => ({
+            id: String(r.id),
+            name: r.name,
+            duration: r.duration,
+            username: r.username,
+            license: r.license,
+            previewUrl: r.previews?.['preview-hq-mp3'] ?? '',
+            sourceUrl: r.url,
+            provider: 'freesound'
+        }));
+    }
+};
+// ─── Custom provider (generic REST) ─────────────────────────────────────────
+function buildCustomProvider(name) {
+    return {
+        name,
+        canGenerate: true,
+        canSearch: false,
+        async generate(prompt, durationSeconds, outputDir) {
+            const cfg = loadConfig();
+            const pc = cfg.providers[name];
+            if (!pc?.endpoint)
+                throw new Error(`Provider "${name}" has no endpoint configured`);
+            if (!pc.apiKey)
+                throw new Error(`Provider "${name}" has no apiKey configured`);
+            const res = await fetch(pc.endpoint, {
+                method: 'POST',
+                headers: { 'Authorization': `Bearer ${pc.apiKey}`, 'Content-Type': 'application/json' },
+                body: JSON.stringify({ prompt, duration_seconds: durationSeconds })
+            });
+            if (!res.ok)
+                throw new Error(`${name} error ${res.status}: ${(await res.text()).slice(0, 200)}`);
+            const contentType = res.headers.get('content-type') ?? '';
+            const ext = contentType.includes('wav') ? 'wav' : contentType.includes('ogg') ? 'ogg' : 'mp3';
+            fs.mkdirSync(outputDir, { recursive: true });
+            const slug = prompt.slice(0, 32).replace(/[^a-zA-Z0-9]/g, '_');
+            const id = crypto.randomBytes(4).toString('hex');
+            const filePath = path.join(outputDir, `${name}_${slug}_${id}.${ext}`);
+            fs.writeFileSync(filePath, Buffer.from(await res.arrayBuffer()));
+            return { filePath, provider: name, prompt, durationSeconds };
+        }
+    };
+}
+// ─── Registry ────────────────────────────────────────────────────────────────
+const BUILT_IN = {
+    elevenlabs: elevenLabsProvider,
+    freesound: freesoundProvider,
+};
+export function getProvider(name) {
+    const cfg = loadConfig();
+    const target = name ?? Object.keys(cfg.providers).find(k => cfg.providers[k].enabled) ?? 'elevenlabs';
+    return BUILT_IN[target] ?? buildCustomProvider(target);
+}
+export function listProviders() {
+    const cfg = loadConfig();
+    return Object.entries(cfg.providers).map(([name, pc]) => ({
+        name,
+        enabled: pc.enabled,
+        hasKey: !!pc.apiKey,
+        type: pc.type ?? (BUILT_IN[name]?.canGenerate ? 'sfx-generate' : 'sfx-search')
+    }));
+}

package/dist/tools/analyze.d.ts

@@ -0,0 +1,11 @@
+export interface AnalyzeOptions {
+    videoPath: string;
+    projectDir?: string;
+    criterio?: string;
+}
+export interface AnalysisResult {
+    projectDir: string;
+    analysisPath: string;
+    analysis: object;
+}
+export declare function analyzeVideo(opts: AnalyzeOptions): Promise<AnalysisResult>;

package/dist/tools/analyze.js

@@ -0,0 +1,142 @@
+import ffmpegPath from 'ffmpeg-static';
+import ffmpeg from 'fluent-ffmpeg';
+import { spawn } from 'child_process';
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { loadConfig } from '../config.js';
+ffmpeg.setFfmpegPath(ffmpegPath);
+function extractFrame(videoPath, tc, outputPath) {
+    return new Promise((resolve, reject) => {
+        ffmpeg(videoPath)
+            .seekInput(tc)
+            .frames(1)
+            .outputOptions(['-q:v 4', '-vf scale=960:-2'])
+            .output(outputPath)
+            .on('end', () => resolve())
+            .on('error', (err) => reject(err))
+            .run();
+    });
+}
+function getVideoDuration(videoPath) {
+    return new Promise((resolve, reject) => {
+        ffmpeg.ffprobe(videoPath, (err, data) => {
+            if (err)
+                reject(err);
+            else
+                resolve(data.format.duration ?? 0);
+        });
+    });
+}
+function buildPrompt(duration, criterio, frameFiles) {
+    const now = new Date().toISOString();
+    const frameList = frameFiles.map(f => {
+        const tcMatch = path.basename(f).match(/_(\d+)s\.jpg$/);
+        const tc = tcMatch ? parseInt(tcMatch[1]) : 0;
+        return `  - ${f}  (tc: ${tc}s)`;
+    }).join('\n');
+    return `You are a professional sound designer analyzing a video project for sound design spotting.
+
+VIDEO DURATION: ${duration.toFixed(1)} seconds
+${criterio ? `DIRECTOR'S INTENT: ${criterio}` : ''}
+
+FRAMES (${frameFiles.length} total — use the Read tool to view each image):
+${frameList}
+
+TASK:
+1. Use the Read tool to read and visually analyze EVERY frame listed above.
+2. Generate 15–30 sound design cues covering the full ${duration.toFixed(1)}s.
+3. Output ONLY a raw JSON object to stdout — no markdown fences, no prose, pure JSON.
+
+JSON SCHEMA (ALL text content in English):
+{
+  "narrative": {
+    "synopsis": "1–2 sentences: what happens visually and narratively",
+    "mood": "dominant emotional tone and subtext",
+    "pacing": "visual/narrative rhythm description",
+    "keyMoments": [{"tc": 12.5, "description": "moment description for sound"}],
+    "soundscapeNotes": "acoustic spaces, sound worlds, reference layers"
+  },
+  "cues": [
+    {
+      "id": "cue_001",
+      "tc_in": 0.0,
+      "tc_out": 15.0,
+      "track": "AMB",
+      "description": "Concrete sound description in English — feeds into Freesound search and ElevenLabs SFX generation",
+      "mood": "Emotional tone of this cue in English",
+      "priority": "A",
+      "notes": "Optional production notes in English",
+      "status": "pending"
+    }
+  ],
+  "analyzedAt": "${now}",
+  "modelUsed": "claude-sonnet-4-6"
+}
+
+TRACK RULES:
+- AMB: ambiences, atmospheres, room tone
+- FOLEY: physical presence (footsteps, cloth, contact, objects)
+- DISEÑO: non-naturalistic sound design (emotional hits, transitions, abstract elements)
+- PRÁCTICO: diegetic practical sources (cars, TV, phone, machinery)
+
+PRIORITY: A=essential / B=enriches / C=optional texture
+Cues from different tracks CAN overlap in time. status always "pending".
+tc_in/tc_out never exceed ${duration.toFixed(1)}.
+
+CRITICAL: your entire response must be ONLY the JSON object. Start with { end with }.`;
+}
+export async function analyzeVideo(opts) {
+    const { videoPath, criterio = '' } = opts;
+    if (!fs.existsSync(videoPath))
+        throw new Error(`Video not found: ${videoPath}`);
+    // Determine project directory
+    const projectDir = opts.projectDir ?? path.join(os.homedir(), 'Documents', 'Proyectos SPOTTER', `${Date.now()}_${path.basename(videoPath, path.extname(videoPath)).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 40)}`);
+    const framesDir = path.join(projectDir, 'frames');
+    fs.mkdirSync(framesDir, { recursive: true });
+    // Extract frames
+    const duration = await getVideoDuration(videoPath);
+    const targetCount = Math.min(20, Math.max(4, Math.ceil(duration / 8)));
+    const interval = duration / targetCount;
+    const frameFiles = [];
+    for (let i = 0; i < targetCount; i++) {
+        const tc = Math.min(i * interval, duration - 0.5);
+        const outPath = path.join(framesDir, `frame_${String(i).padStart(3, '0')}_${Math.round(tc)}s.jpg`);
+        if (!fs.existsSync(outPath))
+            await extractFrame(videoPath, tc, outPath);
+        frameFiles.push(outPath);
+    }
+    // Run claude CLI
+    const cfg = loadConfig();
+    const claudePath = cfg.claudePath || 'claude';
+    const prompt = buildPrompt(duration, criterio, frameFiles);
+    const result = await new Promise((resolve, reject) => {
+        const env = { ...process.env, PATH: `/usr/local/bin:/opt/homebrew/bin:${process.env.PATH || ''}` };
+        const proc = spawn(claudePath, ['-p', prompt, '--output-format', 'text', '--allowedTools', 'Read'], { env });
+        let stdout = '';
+        let stderr = '';
+        proc.stdout.on('data', (d) => { stdout += d.toString(); });
+        proc.stderr.on('data', (d) => { stderr += d.toString(); });
+        proc.on('close', code => {
+            if (code !== 0)
+                reject(new Error(`Claude exited ${code}\n${stderr.slice(-300)}`));
+            else
+                resolve(stdout);
+        });
+        proc.on('error', err => reject(new Error(`Claude not found at "${claudePath}": ${err.message}`)));
+    });
+    const jsonMatch = result.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        throw new Error(`Claude returned no JSON.\nOutput: ${result.slice(0, 300)}`);
+    const analysis = JSON.parse(jsonMatch[0]);
+    const analysisPath = path.join(projectDir, 'analysis.json');
+    fs.writeFileSync(analysisPath, JSON.stringify(analysis, null, 2), 'utf-8');
+    // Save criterio if provided
+    if (criterio)
+        fs.writeFileSync(path.join(projectDir, 'criterio.txt'), criterio, 'utf-8');
+    // Copy video reference
+    const destVideo = path.join(projectDir, path.basename(videoPath));
+    if (!fs.existsSync(destVideo))
+        fs.copyFileSync(videoPath, destVideo);
+    return { projectDir, analysisPath, analysis };
+}

package/dist/tools/export.d.ts

@@ -0,0 +1,19 @@
+export interface ExportCue {
+    id: string;
+    tc_in: number;
+    tc_out: number;
+    track: string;
+    description: string;
+    mood?: string;
+    priority: string;
+    audioFile?: string;
+    startTime?: number;
+    endTime?: number;
+}
+export interface ExportResult {
+    exportDir: string;
+    wavFiles: string[];
+    csvPath: string;
+    errors: string[];
+}
+export declare function exportStems(projectDir: string, cues: ExportCue[], videoDuration: number): Promise<ExportResult>;

package/dist/tools/export.js

@@ -0,0 +1,61 @@
+import { execFile } from 'child_process';
+import ffmpegPath from 'ffmpeg-static';
+import fs from 'fs';
+import path from 'path';
+function runFfmpeg(args) {
+    return new Promise((resolve, reject) => {
+        execFile(ffmpegPath, args, (err, _stdout, stderr) => {
+            if (err)
+                reject(new Error(stderr || err.message));
+            else
+                resolve();
+        });
+    });
+}
+export async function exportStems(projectDir, cues, videoDuration) {
+    const exportDir = path.join(projectDir, 'export');
+    const mediaDir = path.join(projectDir, 'media');
+    fs.mkdirSync(exportDir, { recursive: true });
+    const exported = [];
+    const errors = [];
+    for (const cue of cues) {
+        if (!cue.audioFile)
+            continue;
+        const src = path.join(mediaDir, cue.audioFile);
+        if (!fs.existsSync(src)) {
+            errors.push(`${cue.id}: audio file not found (${cue.audioFile})`);
+            continue;
+        }
+        const tcIn = cue.startTime ?? cue.tc_in;
+        const delayMs = Math.round(tcIn * 1000);
+        const safeName = cue.description.slice(0, 36).replace(/[^a-zA-Z0-9_\- ]/g, '').replace(/\s+/g, '_');
+        const outName = `${cue.track}_${cue.id}_${safeName}.wav`;
+        const outPath = path.join(exportDir, outName);
+        try {
+            await runFfmpeg([
+                '-y', '-i', src,
+                '-af', `adelay=${delayMs}|${delayMs},apad=whole_dur=${videoDuration}`,
+                '-t', String(videoDuration),
+                '-ar', '48000', '-ac', '2', '-c:a', 'pcm_s16le',
+                outPath
+            ]);
+            exported.push(outName);
+        }
+        catch (e) {
+            errors.push(`${cue.id}: ${e instanceof Error ? e.message.slice(0, 80) : 'error'}`);
+        }
+    }
+    // CSV cue sheet
+    const header = 'ID,TC_IN,TC_OUT,DURATION,TRACK,PRIORITY,DESCRIPTION,MOOD,AUDIO_FILE,WAV_EXPORT';
+    const rows = cues.map(c => {
+        const tcIn = (c.startTime ?? c.tc_in).toFixed(3);
+        const tcOut = (c.endTime ?? c.tc_out).toFixed(3);
+        const dur = (parseFloat(tcOut) - parseFloat(tcIn)).toFixed(3);
+        const esc = (s) => `"${(s ?? '').replace(/"/g, '""')}"`;
+        const wav = exported.find(f => f.includes(c.id)) ?? '';
+        return [c.id, tcIn, tcOut, dur, c.track, c.priority, esc(c.description), esc(c.mood ?? ''), esc(c.audioFile ?? ''), esc(wav)].join(',');
+    });
+    const csvPath = path.join(exportDir, 'cue_sheet.csv');
+    fs.writeFileSync(csvPath, [header, ...rows].join('\n'), 'utf-8');
+    return { exportDir, wavFiles: exported, csvPath, errors };
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "lemolabs-spotter-mcp",
+  "version": "0.1.0",
+  "description": "AI-assisted sound design spotting — MCP server for Claude Code",
+  "keywords": ["mcp", "sound-design", "spotting", "ai", "claude"],
+  "author": "Lemö Labs",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "spotter-mcp": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "node --loader ts-node/esm src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "ffmpeg-static": "^5.2.0",
+    "fluent-ffmpeg": "^2.1.2"
+  },
+  "devDependencies": {
+    "@types/fluent-ffmpeg": "^2.1.24",
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.0",
+    "typescript": "^5.3.0"
+  }
+}