@mindstone-engineering/mcp-server-runway 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Runway authentication module.
+ *
+ * API key management — stored via env var (RUNWAYML_API_SECRET)
+ * or configured at runtime via the configure_runway_api_key tool.
+ *
+ * Auth: Authorization: Bearer {key} + X-Runway-Version header on all API requests.
+ */
+/**
+ * Get the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export declare function setApiKey(key: string): void;
+/**
+ * Check if an API key is configured.
+ */
+export declare function hasApiKey(): boolean;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,29 @@
+/**
+ * Runway authentication module.
+ *
+ * API key management — stored via env var (RUNWAYML_API_SECRET)
+ * or configured at runtime via the configure_runway_api_key tool.
+ *
+ * Auth: Authorization: Bearer {key} + X-Runway-Version header on all API requests.
+ */
+/** Runtime API key — starts from env, can be updated via configure tool. */
+let apiKey = process.env.RUNWAYML_API_SECRET ?? '';
+/**
+ * Get the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Set the API key at runtime (from configure tool).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+/**
+ * Check if an API key is configured.
+ */
+export function hasApiKey() {
+    return apiKey.trim().length > 0;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Runway API HTTP client.
+ *
+ * Centralises Bearer auth + X-Runway-Version header injection,
+ * error handling, rate-limit messaging, and timeout handling.
+ *
+ * Auth: Authorization: Bearer {key}, X-Runway-Version: 2024-11-06
+ * Base URL: https://api.dev.runwayml.com/v1
+ */
+/**
+ * Make an authenticated JSON request to the Runway API.
+ */
+export declare function runwayFetch<T>(urlPath: string, options?: RequestInit): Promise<T>;
+/**
+ * Make a raw authenticated fetch (for DELETE endpoints that return 204 with no body).
+ */
+export declare function runwayRawFetch(urlPath: string, options?: RequestInit): Promise<Response>;
+/**
+ * Upload a local file to Runway's ephemeral storage.
+ * Returns a runway:// URI valid for 24 hours.
+ */
+export declare function uploadEphemeral(filePath: string): Promise<string>;
+/**
+ * Resolve a media input to a usable URI.
+ * - HTTPS/data/runway URIs are passed through.
+ * - Local files under the size limit are converted to data URIs.
+ * - Large local files are uploaded via ephemeral upload.
+ */
+export declare function resolveMediaInput(input: string, category: 'image' | 'video' | 'audio'): Promise<string>;
+/**
+ * Validate a download URL for SSRF safety.
+ * Returns an error message if the URL is unsafe, or null if OK.
+ */
+export declare function validateDownloadUrl(url: string): string | null;
+export declare function costEstimate(model: string, duration: number, audio?: boolean): {
+    credits: number;
+    usd: string;
+};
+/**
+ * Add content moderation to a request body if specified.
+ */
+export declare function addContentModeration(body: Record<string, unknown>, contentMod?: string): void;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,261 @@
+/**
+ * Runway API HTTP client.
+ *
+ * Centralises Bearer auth + X-Runway-Version header injection,
+ * error handling, rate-limit messaging, and timeout handling.
+ *
+ * Auth: Authorization: Bearer {key}, X-Runway-Version: 2024-11-06
+ * Base URL: https://api.dev.runwayml.com/v1
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { RunwayError, REQUEST_TIMEOUT_MS, RUNWAY_API_BASE, RUNWAY_API_VERSION, MIME_MAP, DATA_URI_BINARY_LIMITS, MAX_UPLOAD_BYTES, MIN_UPLOAD_BYTES, } from './types.js';
+import { getApiKey } from './auth.js';
+/**
+ * Make an authenticated JSON request to the Runway API.
+ */
+export async function runwayFetch(urlPath, options = {}) {
+    const apiKey = getApiKey();
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new RunwayError('Runway API key not configured', 'AUTH_REQUIRED', 'Configure your Runway API key in Settings. Get one at https://dev.runwayml.com/');
+    }
+    const url = `${RUNWAY_API_BASE}${urlPath}`;
+    console.error(`[Runway API] ${options.method || 'GET'} ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${apiKey}`,
+                'X-Runway-Version': RUNWAY_API_VERSION,
+                ...(options.headers || {}),
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new RunwayError('Request to Runway API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Runway API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 429) {
+        throw new RunwayError('Rate limited.', 'RATE_LIMITED', 'Wait a moment and try again.');
+    }
+    if (response.status === 401) {
+        throw new RunwayError('Authentication failed.', 'AUTH_FAILED', 'Check your Runway API key.');
+    }
+    if (response.status === 403) {
+        throw new RunwayError('Access forbidden.', 'AUTH_FAILED', 'Check your Runway API key and account permissions.');
+    }
+    if (response.status === 404) {
+        throw new RunwayError('Resource not found.', 'NOT_FOUND', 'The resource does not exist or was deleted.');
+    }
+    if (!response.ok) {
+        let detail = '';
+        try {
+            detail = (await response.json())?.error || '';
+        }
+        catch { /* empty */ }
+        throw new RunwayError(`Runway API error (HTTP ${response.status}): ${detail}`, `HTTP_${response.status}`, 'Try again or check https://dev.runwayml.com/');
+    }
+    return (await response.json());
+}
+/**
+ * Make a raw authenticated fetch (for DELETE endpoints that return 204 with no body).
+ */
+export async function runwayRawFetch(urlPath, options = {}) {
+    const apiKey = getApiKey();
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new RunwayError('Runway API key not configured', 'AUTH_REQUIRED', 'Configure your Runway API key in Settings. Get one at https://dev.runwayml.com/');
+    }
+    const url = `${RUNWAY_API_BASE}${urlPath}`;
+    console.error(`[Runway API] ${options.method || 'GET'} ${url}`);
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                'Authorization': `Bearer ${apiKey}`,
+                'X-Runway-Version': RUNWAY_API_VERSION,
+                ...(options.headers || {}),
+            },
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new RunwayError('Request to Runway API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Runway API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 429) {
+        throw new RunwayError('Rate limited.', 'RATE_LIMITED', 'Wait a moment and try again.');
+    }
+    if (response.status === 401) {
+        throw new RunwayError('Authentication failed.', 'AUTH_FAILED', 'Check your Runway API key.');
+    }
+    if (response.status === 403) {
+        throw new RunwayError('Access forbidden.', 'AUTH_FAILED', 'Check your Runway API key and account permissions.');
+    }
+    return response;
+}
+// ============================================================================
+// File resolution & ephemeral upload helpers
+// ============================================================================
+/**
+ * Upload a local file to Runway's ephemeral storage.
+ * Returns a runway:// URI valid for 24 hours.
+ */
+export async function uploadEphemeral(filePath) {
+    if (!fs.existsSync(filePath)) {
+        throw new RunwayError(`File not found: ${filePath}`, 'FILE_NOT_FOUND', 'Provide an accessible local file path.');
+    }
+    const stats = fs.statSync(filePath);
+    if (!stats.isFile()) {
+        throw new RunwayError(`Not a file: ${filePath}`, 'INVALID_INPUT', 'Provide a file path, not a directory.');
+    }
+    if (stats.size > MAX_UPLOAD_BYTES) {
+        throw new RunwayError('File exceeds 200MB upload limit.', 'FILE_TOO_LARGE', 'Reduce the file size or use a URL instead.');
+    }
+    if (stats.size < MIN_UPLOAD_BYTES) {
+        throw new RunwayError('File must be at least 512 bytes.', 'FILE_TOO_SMALL', 'Provide a valid media file.');
+    }
+    const filename = path.basename(filePath);
+    const uploadInfo = await runwayFetch('/uploads', {
+        method: 'POST',
+        body: JSON.stringify({ filename, type: 'ephemeral' }),
+    });
+    const fileBuffer = fs.readFileSync(filePath);
+    const formData = new FormData();
+    for (const [key, value] of Object.entries(uploadInfo.fields)) {
+        formData.append(key, value);
+    }
+    formData.append('file', new Blob([fileBuffer]), filename);
+    const uploadRes = await fetch(uploadInfo.uploadUrl, { method: 'POST', body: formData });
+    if (!uploadRes.ok && uploadRes.status !== 204) {
+        throw new RunwayError(`Upload failed (HTTP ${uploadRes.status})`, 'UPLOAD_FAILED', 'Try again. If the file is too large (max 200MB), reduce its size.');
+    }
+    return uploadInfo.runwayUri;
+}
+/**
+ * Resolve a media input to a usable URI.
+ * - HTTPS/data/runway URIs are passed through.
+ * - Local files under the size limit are converted to data URIs.
+ * - Large local files are uploaded via ephemeral upload.
+ */
+export async function resolveMediaInput(input, category) {
+    if (input.startsWith('https://') || input.startsWith('data:') || input.startsWith('runway://')) {
+        return input;
+    }
+    try {
+        const stats = fs.statSync(input);
+        if (!stats.isFile()) {
+            throw new RunwayError(`Not a file: ${input}`, 'INVALID_INPUT', 'Provide a file path, not a directory.');
+        }
+        const limit = DATA_URI_BINARY_LIMITS[category];
+        if (stats.size > limit) {
+            return await uploadEphemeral(input);
+        }
+        const buffer = fs.readFileSync(input);
+        const ext = input.split('.').pop()?.toLowerCase() || 'bin';
+        const fallback = category === 'image' ? 'image/png' : category === 'video' ? 'video/mp4' : 'audio/mpeg';
+        const mime = MIME_MAP[ext] || fallback;
+        return `data:${mime};base64,${buffer.toString('base64')}`;
+    }
+    catch (err) {
+        if (err instanceof RunwayError)
+            throw err;
+        throw new RunwayError(`Could not read file: ${input}`, 'FILE_NOT_FOUND', 'Provide a valid HTTPS URL, Runway URI, or accessible local file path.');
+    }
+}
+// ============================================================================
+// SSRF / Host validation for download URLs
+// ============================================================================
+/**
+ * Check whether a hostname is private, localhost, or otherwise reserved.
+ * Matches the same patterns as Workday's SSRF prevention.
+ */
+function isPrivateOrReservedHost(hostname) {
+    const lower = hostname.toLowerCase();
+    // Localhost names
+    if (lower === 'localhost' || lower === '[::1]' || lower === '::1') {
+        return true;
+    }
+    // .local domains
+    if (lower.endsWith('.local')) {
+        return true;
+    }
+    // IPv4 private/reserved ranges
+    const ipMatch = hostname.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (ipMatch) {
+        const [, a, b] = ipMatch.map(Number);
+        if (a === 127)
+            return true; // 127.0.0.0/8 loopback
+        if (a === 10)
+            return true; // 10.0.0.0/8 private
+        if (a === 172 && b >= 16 && b <= 31)
+            return true; // 172.16.0.0/12 private
+        if (a === 192 && b === 168)
+            return true; // 192.168.0.0/16 private
+        if (a === 169 && b === 254)
+            return true; // 169.254.0.0/16 link-local
+        if (a === 0)
+            return true; // 0.0.0.0/8
+    }
+    // IPv6 private/loopback (bracket-wrapped from URL parsing)
+    if (lower.startsWith('[') && lower.endsWith(']')) {
+        const inner = lower.slice(1, -1);
+        if (inner === '::1' || inner === '::' || inner.startsWith('fe80:') || inner.startsWith('fc') || inner.startsWith('fd')) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Validate a download URL for SSRF safety.
+ * Returns an error message if the URL is unsafe, or null if OK.
+ */
+export function validateDownloadUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return 'Invalid URL.';
+    }
+    if (parsed.protocol !== 'https:') {
+        return 'Only HTTPS URLs are supported for download.';
+    }
+    if (isPrivateOrReservedHost(parsed.hostname)) {
+        return 'Cannot download from local/private network addresses.';
+    }
+    return null;
+}
+// ============================================================================
+// Cost estimation helper
+// ============================================================================
+export function costEstimate(model, duration, audio) {
+    const rates = {
+        'gen4.5': 12,
+        gen4_turbo: 5,
+        gen3a_turbo: 5,
+        gen4_aleph: 15,
+        act_two: 5,
+        veo3: 40,
+        'veo3.1': audio === false ? 20 : 40,
+        'veo3.1_fast': audio === false ? 10 : 15,
+    };
+    const credits = (rates[model] || 5) * duration;
+    return { credits, usd: `$${(credits * 0.01).toFixed(2)}` };
+}
+/**
+ * Add content moderation to a request body if specified.
+ */
+export function addContentModeration(body, contentMod) {
+    if (contentMod === 'low') {
+        body.contentModeration = { publicFigureThreshold: 'low' };
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * Runway ML MCP Server
+ *
+ * Comprehensive AI media generation via Runway's API:
+ * - Video generation (text-to-video, image-to-video, video-to-video, character performance)
+ * - Image generation (text+reference-to-image)
+ * - Audio (TTS, sound effects, voice swap, dubbing, voice isolation)
+ * - Custom voices (list, create, preview, delete)
+ * - Task management (check, wait, cancel, download)
+ * - Account (balance, usage analytics, API key configuration)
+ *
+ * Environment variables:
+ * - RUNWAYML_API_SECRET: Runway API key (required)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+/**
+ * Runway ML MCP Server
+ *
+ * Comprehensive AI media generation via Runway's API:
+ * - Video generation (text-to-video, image-to-video, video-to-video, character performance)
+ * - Image generation (text+reference-to-image)
+ * - Audio (TTS, sound effects, voice swap, dubbing, voice isolation)
+ * - Custom voices (list, create, preview, delete)
+ * - Task management (check, wait, cancel, download)
+ * - Account (balance, usage analytics, API key configuration)
+ *
+ * Environment variables:
+ * - RUNWAYML_API_SECRET: Runway API key (required)
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Runway MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerVideoTools, registerImageTools, registerAudioTools, registerVoiceTools, registerTaskTools, registerAccountTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'runway-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerVideoTools(server);
+    registerImageTools(server);
+    registerAudioTools(server);
+    registerVoiceTools(server);
+    registerTaskTools(server);
+    registerAccountTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAccountTools(server: McpServer): void;
+//# sourceMappingURL=account.d.ts.map

package/dist/tools/account.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { runwayFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+export function registerAccountTools(server) {
+    // ── Balance ───────────────────────────────────────────────────────────
+    server.registerTool('get_runway_balance', {
+        description: 'Check your Runway credit balance, usage tier limits, and today\'s usage by model. 1 credit = $0.01.',
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        const org = await runwayFetch('/organization');
+        const bal = org.creditBalance;
+        const activeModels = Object.entries(org.usage.models).filter(([, v]) => v.dailyGenerations > 0);
+        const summary = [
+            `Credit Balance: ${bal} credits ($${(bal * 0.01).toFixed(2)})`,
+            `Monthly Limit: ${org.tier.maxMonthlyCreditSpend} credits`,
+            '',
+            'Model Limits:',
+            ...Object.entries(org.tier.models).map(([m, l]) => `  ${m}: ${l.maxConcurrentGenerations} concurrent, ${l.maxDailyGenerations}/day`),
+            ...(activeModels.length
+                ? ['', "Today's Usage:", ...activeModels.map(([m, v]) => `  ${m}: ${v.dailyGenerations} generations`)]
+                : []),
+            ...(bal === 0 ? ['', 'WARNING: No credits. Add at https://dev.runwayml.com/ (Billing tab, min $10).'] : []),
+        ];
+        return JSON.stringify({
+            ok: true, balance: bal, balance_usd: `$${(bal * 0.01).toFixed(2)}`,
+            summary: summary.join('\n'),
+        });
+    }));
+    // ── Credit Usage Analytics ────────────────────────────────────────────
+    server.registerTool('query_credit_usage', {
+        description: 'Query detailed credit usage broken down by model and day. Supports date ranges up to 90 days.',
+        inputSchema: z.object({
+            start_date: z.string().optional().describe('Start date (YYYY-MM-DD). Default: 30 days ago.'),
+            before_date: z.string().optional().describe('End date, not inclusive (YYYY-MM-DD). Default: 30 days after start.'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        const body = {};
+        if (args.start_date)
+            body.startDate = args.start_date;
+        if (args.before_date)
+            body.beforeDate = args.before_date;
+        const result = await runwayFetch('/organization/usage', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        let totalCredits = 0;
+        const byModel = {};
+        for (const day of result.results) {
+            for (const entry of day.usedCredits) {
+                totalCredits += entry.amount;
+                byModel[entry.model] = (byModel[entry.model] || 0) + entry.amount;
+            }
+        }
+        const lines = [
+            `Total credits used: ${totalCredits} ($${(totalCredits * 0.01).toFixed(2)})`,
+            `Period: ${result.results.length} days`,
+            '',
+            'By model:',
+            ...Object.entries(byModel).sort(([, a], [, b]) => b - a)
+                .map(([m, c]) => `  ${m}: ${c} credits ($${(c * 0.01).toFixed(2)})`),
+        ];
+        return JSON.stringify({
+            ok: true, total_credits: totalCredits,
+            days: result.results.length, by_model: byModel,
+            summary: lines.join('\n'),
+        });
+    }));
+}
+//# sourceMappingURL=account.js.map

package/dist/tools/audio.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerAudioTools(server: McpServer): void;
+//# sourceMappingURL=audio.d.ts.map