@mindstone-engineering/mcp-server-runway 0.1.0

package/dist/tools/voices.js

@@ -0,0 +1,85 @@
+import { z } from 'zod';
+import { runwayFetch, runwayRawFetch } from '../client.js';
+import { RunwayError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerVoiceTools(server) {
+    // ── List Custom Voices ────────────────────────────────────────────────
+    server.registerTool('list_custom_voices', {
+        description: 'List all custom voices you\'ve created. Returns voice IDs, names, descriptions, and status. ' +
+            'Use the voice ID with generate_speech.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const result = await runwayFetch('/voices');
+        const voices = result.data.map(v => ({
+            id: v.id, name: v.name, description: v.description || '', status: v.status, created: v.createdAt,
+        }));
+        return JSON.stringify({
+            ok: true, voices, count: voices.length, has_more: result.hasMore,
+            message: voices.length === 0
+                ? 'No custom voices yet. Create one with create_custom_voice.'
+                : `Found ${voices.length} custom voice(s).`,
+        });
+    }));
+    // ── Create Custom Voice ───────────────────────────────────────────────
+    server.registerTool('create_custom_voice', {
+        description: 'Create a custom voice from a text description of desired voice characteristics. ' +
+            'MODELS: eleven_multilingual_ttv_v2 (default), eleven_ttv_v3 (newer). ' +
+            'Check status with list_custom_voices. Once READY, use its ID with generate_speech.',
+        inputSchema: z.object({
+            name: z.string().describe('Name for the voice. Max 100 characters.'),
+            prompt: z.string().describe('Text description of desired voice. Min 20, max 1000 characters.'),
+            model: z.enum(['eleven_multilingual_ttv_v2', 'eleven_ttv_v3']).optional().describe('Voice design model. Default: eleven_multilingual_ttv_v2.'),
+            description: z.string().optional().describe('Optional description for your reference. Max 512 characters.'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const model = args.model || 'eleven_multilingual_ttv_v2';
+        const body = {
+            name: args.name,
+            from: { type: 'text', prompt: args.prompt, model },
+        };
+        if (args.description)
+            body.description = args.description;
+        const result = await runwayFetch('/voices', { method: 'POST', body: JSON.stringify(body) });
+        return JSON.stringify({
+            ok: true, voice_id: result.id,
+            message: `Custom voice "${args.name}" created (ID: ${result.id}). It may take a few seconds to process. Check status with list_custom_voices.`,
+        });
+    }));
+    // ── Preview Voice ─────────────────────────────────────────────────────
+    server.registerTool('preview_voice', {
+        description: 'Generate a short audio preview of a voice from a text description, without creating it. ' +
+            'Use to audition voice characteristics before committing with create_custom_voice.',
+        inputSchema: z.object({
+            prompt: z.string().describe('Text description of desired voice. Min 20, max 1000 characters.'),
+            model: z.enum(['eleven_multilingual_ttv_v2', 'eleven_ttv_v3']).optional().describe('Voice design model. Default: eleven_multilingual_ttv_v2.'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const model = args.model || 'eleven_multilingual_ttv_v2';
+        const result = await runwayFetch('/voices/preview', {
+            method: 'POST',
+            body: JSON.stringify({ prompt: args.prompt, model }),
+        });
+        return JSON.stringify({
+            ok: true, preview_url: result.url, duration_seconds: result.durationSecs,
+            message: `Voice preview generated (${result.durationSecs}s). Listen at: ${result.url}`,
+        });
+    }));
+    // ── Delete Custom Voice ───────────────────────────────────────────────
+    server.registerTool('delete_custom_voice', {
+        description: 'Delete a custom voice by ID. This is permanent and cannot be undone.',
+        inputSchema: z.object({
+            voice_id: z.string().describe('UUID of the voice to delete (from list_custom_voices).'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, withErrorHandling(async (args) => {
+        const delRes = await runwayRawFetch(`/voices/${args.voice_id}`, { method: 'DELETE' });
+        if (!delRes.ok && delRes.status !== 204) {
+            throw new RunwayError(`Failed to delete voice (HTTP ${delRes.status})`, `HTTP_${delRes.status}`, 'Check the voice ID and try again.');
+        }
+        return JSON.stringify({ ok: true, message: `Voice ${args.voice_id} deleted.` });
+    }));
+}
+//# sourceMappingURL=voices.js.map

package/dist/types.d.ts

@@ -0,0 +1,81 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const RUNWAY_API_BASE = "https://api.dev.runwayml.com/v1";
+export declare const RUNWAY_API_VERSION = "2024-11-06";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class RunwayError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface TaskResponse {
+    id: string;
+}
+export interface TaskDetail {
+    id: string;
+    status: 'PENDING' | 'THROTTLED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED';
+    createdAt: string;
+    output?: string[];
+    failure?: string;
+    failureCode?: string;
+}
+export interface OrgResponse {
+    tier: {
+        maxMonthlyCreditSpend: number;
+        models: Record<string, {
+            maxConcurrentGenerations: number;
+            maxDailyGenerations: number;
+        }>;
+    };
+    creditBalance: number;
+    usage: {
+        models: Record<string, {
+            dailyGenerations: number;
+        }>;
+    };
+}
+export interface UsageResponse {
+    results: Array<{
+        date: string;
+        usedCredits: Array<{
+            model: string;
+            amount: number;
+        }>;
+    }>;
+    models: string[];
+}
+export interface VoiceItem {
+    id: string;
+    name: string;
+    description?: string;
+    createdAt: string;
+    status: string;
+}
+export interface VoiceListResponse {
+    data: VoiceItem[];
+    hasMore: boolean;
+    nextCursor?: string;
+}
+export interface VoicePreviewResponse {
+    url: string;
+    durationSecs: number;
+}
+export interface UploadResponse {
+    uploadUrl: string;
+    fields: Record<string, string>;
+    runwayUri: string;
+}
+export declare const MIME_MAP: Record<string, string>;
+/** Data URI size limits (binary, before base64 expansion) */
+export declare const DATA_URI_BINARY_LIMITS: Record<string, number>;
+export declare const MAX_UPLOAD_BYTES: number;
+export declare const MIN_UPLOAD_BYTES = 512;
+export declare const VOICE_PRESETS: readonly ["Maya", "Arjun", "Serene", "Bernard", "Billy", "Mark", "Clint", "Mabel", "Chad", "Leslie", "Eleanor", "Elias", "Elliot", "Grungle", "Brodie", "Sandra", "Kirk", "Kylie", "Lara", "Lisa", "Malachi", "Marlene", "Martin", "Miriam", "Monster", "Paula", "Pip", "Rusty", "Ragnar", "Xylar", "Maggie", "Jack", "Katie", "Noah", "James", "Rina", "Ella", "Mariah", "Frank", "Claudia", "Niki", "Vincent", "Kendrick", "Myrna", "Tom", "Wanda", "Benjamin", "Kiana", "Rachel"];
+export declare const DUBBING_LANGUAGES: readonly ["en", "hi", "pt", "zh", "es", "fr", "de", "ja", "ar", "ru", "ko", "id", "it", "nl", "tr", "pl", "sv", "fil", "ms", "ro", "uk", "el", "cs", "da", "fi", "bg", "hr", "sk", "ta"];
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export declare function getErrorResolution(status: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,68 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const RUNWAY_API_BASE = 'https://api.dev.runwayml.com/v1';
+export const RUNWAY_API_VERSION = '2024-11-06';
+export class RunwayError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'RunwayError';
+    }
+}
+// ---------------------------------------------------------------------------
+// MIME & size limits
+// ---------------------------------------------------------------------------
+export const MIME_MAP = {
+    png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif',
+    webp: 'image/webp', bmp: 'image/bmp',
+    mp4: 'video/mp4', mov: 'video/quicktime', webm: 'video/webm', avi: 'video/x-msvideo',
+    mkv: 'video/x-matroska', '3gp': 'video/3gpp',
+    mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg', m4a: 'audio/mp4',
+    aac: 'audio/aac', flac: 'audio/flac',
+};
+/** Data URI size limits (binary, before base64 expansion) */
+export const DATA_URI_BINARY_LIMITS = {
+    image: 3_300_000,
+    video: 12_000_000,
+    audio: 12_000_000,
+};
+export const MAX_UPLOAD_BYTES = 200 * 1_048_576;
+export const MIN_UPLOAD_BYTES = 512;
+// ---------------------------------------------------------------------------
+// Voice presets and language constants
+// ---------------------------------------------------------------------------
+export const VOICE_PRESETS = [
+    'Maya', 'Arjun', 'Serene', 'Bernard', 'Billy', 'Mark', 'Clint', 'Mabel',
+    'Chad', 'Leslie', 'Eleanor', 'Elias', 'Elliot', 'Grungle', 'Brodie',
+    'Sandra', 'Kirk', 'Kylie', 'Lara', 'Lisa', 'Malachi', 'Marlene', 'Martin',
+    'Miriam', 'Monster', 'Paula', 'Pip', 'Rusty', 'Ragnar', 'Xylar', 'Maggie',
+    'Jack', 'Katie', 'Noah', 'James', 'Rina', 'Ella', 'Mariah', 'Frank',
+    'Claudia', 'Niki', 'Vincent', 'Kendrick', 'Myrna', 'Tom', 'Wanda',
+    'Benjamin', 'Kiana', 'Rachel',
+];
+export const DUBBING_LANGUAGES = [
+    'en', 'hi', 'pt', 'zh', 'es', 'fr', 'de', 'ja', 'ar', 'ru', 'ko', 'id',
+    'it', 'nl', 'tr', 'pl', 'sv', 'fil', 'ms', 'ro', 'uk', 'el', 'cs', 'da',
+    'fi', 'bg', 'hr', 'sk', 'ta',
+];
+/**
+ * Resolve an error status code to an actionable resolution string.
+ */
+export function getErrorResolution(status) {
+    if (status === 401) {
+        return 'Authentication failed. Check your Runway API key. Get one at https://dev.runwayml.com/';
+    }
+    if (status === 403) {
+        return 'Access forbidden. Check your Runway API key and account permissions.';
+    }
+    if (status === 404) {
+        return 'The resource does not exist or was deleted.';
+    }
+    if (status === 429) {
+        return 'Rate limited. Wait a moment and try again.';
+    }
+    return 'Try again or check https://dev.runwayml.com/';
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On RunwayError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { RunwayError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On RunwayError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof RunwayError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-runway",
+  "version": "0.1.0",
+  "description": "Runway ML MCP server for Model Context Protocol hosts — AI video, image, audio generation, custom voices, task management",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-runway": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/runway"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/runway",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}