@visionengine/remotion-file-bridge 1.0.0

package/README-zh.md

@@ -0,0 +1,31 @@
+# VE Remotion 文件桥接 MCP
+
+用于通过 `ve-backend` 查询、读取、下载、保存 Remotion 项目文件的 MCP 服务。
+
+## 环境变量
+
+参考 `.env.example`。
+
+必填：
+
+- `BASE_URL`
+- `API_KEY`
+- `WORKDIR`
+
+其中 `WORKDIR` 表示本地工作目录：`download_file` 下载文件到本地时，以及 `save_file` 读取相对本地路径时，都会以它为基准。
+
+## 工具
+
+- `list_files`：按 `children` / `tree` / `file` 模式浏览当前用户工作区。
+- `read_file`：直接读取文本文件，或返回二进制资源的预览/下载地址。
+- `download_file`：把远端工作区文件下载到本地 `WORKDIR`。
+- `save_file`：把本地文件、文本、base64 内容或远端 URL 保存到工作区。
+
+## 后端依赖
+
+该 MCP 依赖以下后端接口：
+
+- `GET /api/v1/auth/me`
+- `GET /api/v1/files/list`
+- `GET /shared/{userId}/{path}`
+- `POST /save`

package/README.md

@@ -0,0 +1,31 @@
+# VE Remotion File Bridge
+
+MCP server for listing, reading, downloading, and saving Remotion project files through `ve-backend`.
+
+## Environment
+
+See `.env.example`.
+
+Required:
+
+- `BASE_URL`
+- `API_KEY`
+- `WORKDIR`
+
+`WORKDIR` is the local base directory used when `download_file` writes files locally or when `save_file` reads a relative local path.
+
+## Tools
+
+- `list_files`: browse the current user's Remotion workspace with `children` / `tree` / `file` modes.
+- `read_file`: read text files directly, or return preview/download URLs for binary assets.
+- `download_file`: download a remote workspace file into local `WORKDIR`.
+- `save_file`: save local files, text, base64 content, or remote URLs into the workspace.
+
+## Backend requirements
+
+This MCP package depends on these backend endpoints:
+
+- `GET /api/v1/auth/me`
+- `GET /api/v1/files/list`
+- `GET /shared/{userId}/{path}`
+- `POST /save`

package/dist/client.js

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { buildSharedDownloadUrl, buildSharedPreviewUrl, ensureDir, getBaseUrl, getWorkDir, normalizeWorkspacePath, requireApiKey, resolveUserId, toRelativePath } from './shared.js';
+import { inferTargetPath } from './path-mapping.js';
+const TEXT_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.json', '.md', '.txt', '.css', '.html', '.srt', '.ass', '.vtt', '.yml', '.yaml', '.csv']);
+function isTextPath(filePath) {
+    return TEXT_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+function buildAuthHeaders() {
+    return {
+        Authorization: `Bearer ${requireApiKey()}`,
+    };
+}
+export async function listProjectFiles(args) {
+    const userId = await resolveUserId(args.userId);
+    const workspacePath = normalizeWorkspacePath(args.path || '.', userId);
+    const mode = args.mode || (args.recursive ? 'tree' : 'children');
+    const query = new URLSearchParams({
+        path: workspacePath,
+        mode,
+        max_depth: String(args.maxDepth ?? 2),
+        limit: String(args.limit ?? 200),
+        include_content: String(Boolean(args.includeContent)),
+    });
+    const response = await fetch(`${getBaseUrl()}/api/v1/files/list?${query.toString()}`, {
+        headers: buildAuthHeaders(),
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to list files: ${response.status} ${await response.text()}`);
+    }
+    const payload = await response.json();
+    return {
+        success: payload.success,
+        userId,
+        workspacePath: payload.path,
+        metadata: {
+            mode: payload.mode,
+            pagination: payload.pagination,
+            entries: payload.entries,
+        },
+    };
+}
+export async function readProjectFile(args) {
+    const userId = await resolveUserId(args.userId);
+    const workspacePath = normalizeWorkspacePath(args.path, userId);
+    const previewUrl = buildSharedPreviewUrl(userId, workspacePath);
+    const downloadUrl = buildSharedDownloadUrl(userId, workspacePath);
+    const shouldReadText = args.asText !== false && isTextPath(workspacePath);
+    if (!shouldReadText) {
+        return {
+            success: true,
+            userId,
+            workspacePath,
+            previewUrl,
+            downloadUrl,
+            metadata: {
+                mode: args.download ? 'download' : 'preview',
+                contentKind: 'binary',
+            },
+        };
+    }
+    const response = await fetch(args.download ? downloadUrl : previewUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to read file: ${response.status} ${await response.text()}`);
+    }
+    const content = await response.text();
+    return {
+        success: true,
+        userId,
+        workspacePath,
+        previewUrl,
+        downloadUrl,
+        metadata: {
+            contentKind: 'text',
+            content,
+        },
+    };
+}
+export async function downloadProjectFile(args) {
+    const userId = await resolveUserId(args.userId);
+    const workspacePath = normalizeWorkspacePath(args.remotePath, userId);
+    const downloadUrl = buildSharedDownloadUrl(userId, workspacePath);
+    const previewUrl = buildSharedPreviewUrl(userId, workspacePath);
+    const relativeOutput = args.localPath?.trim()
+        ? args.localPath.trim().replaceAll('\\', '/')
+        : `${inferTargetPath(path.basename(workspacePath), undefined, undefined)}/${path.basename(workspacePath)}`;
+    const absoluteOutput = path.isAbsolute(relativeOutput)
+        ? relativeOutput
+        : path.join(getWorkDir(), relativeOutput);
+    ensureDir(path.dirname(absoluteOutput));
+    const response = await fetch(downloadUrl);
+    if (!response.ok) {
+        throw new Error(`Failed to download file: ${response.status} ${await response.text()}`);
+    }
+    const arrayBuffer = await response.arrayBuffer();
+    await fs.promises.writeFile(absoluteOutput, Buffer.from(arrayBuffer));
+    return {
+        success: true,
+        userId,
+        workspacePath,
+        previewUrl,
+        downloadUrl,
+        localPath: toRelativePath(absoluteOutput),
+        metadata: {
+            size: Buffer.byteLength(Buffer.from(arrayBuffer)),
+        },
+    };
+}
+export async function saveProjectFile(args) {
+    const userId = await resolveUserId(args.userId);
+    const targetPath = inferTargetPath(args.fileName, args.contentType, args.targetPath);
+    const saveUrl = `${getBaseUrl()}/save`;
+    let response;
+    if (args.sourceType === 'local_path') {
+        if (!args.localPath) {
+            throw new Error('localPath is required when sourceType=local_path');
+        }
+        const absolutePath = path.isAbsolute(args.localPath) ? args.localPath : path.join(getWorkDir(), args.localPath);
+        const fileBuffer = await fs.promises.readFile(absolutePath);
+        const form = new FormData();
+        form.append('file', new Blob([fileBuffer], { type: args.contentType || 'application/octet-stream' }), args.fileName);
+        form.append('file_name', args.fileName);
+        form.append('path', targetPath);
+        response = await fetch(saveUrl, {
+            method: 'POST',
+            headers: buildAuthHeaders(),
+            body: form,
+        });
+    }
+    else if (args.sourceType === 'remote_url') {
+        if (!args.content) {
+            throw new Error('content must be the remote URL when sourceType=remote_url');
+        }
+        const upstream = await fetch(args.content);
+        if (!upstream.ok) {
+            throw new Error(`Failed to fetch remote_url source: ${upstream.status} ${await upstream.text()}`);
+        }
+        const buffer = Buffer.from(await upstream.arrayBuffer());
+        const form = new FormData();
+        form.append('file', new Blob([buffer], { type: args.contentType || upstream.headers.get('content-type') || 'application/octet-stream' }), args.fileName);
+        form.append('file_name', args.fileName);
+        form.append('path', targetPath);
+        response = await fetch(saveUrl, {
+            method: 'POST',
+            headers: buildAuthHeaders(),
+            body: form,
+        });
+    }
+    else {
+        if (typeof args.content !== 'string') {
+            throw new Error('content is required for text/base64 source types');
+        }
+        response = await fetch(saveUrl, {
+            method: 'POST',
+            headers: {
+                ...buildAuthHeaders(),
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify({
+                file_name: args.fileName,
+                content: args.content,
+                path: targetPath,
+                encoding: args.sourceType === 'text' ? 'text' : 'base64',
+            }),
+        });
+    }
+    if (!response.ok) {
+        throw new Error(`Failed to save file: ${response.status} ${await response.text()}`);
+    }
+    const payload = await response.json();
+    const returnedPath = payload.file.path.replaceAll('\\', '/');
+    if (!returnedPath.startsWith(`${userId}/`)) {
+        throw new Error(`Saved file belongs to another user workspace: ${returnedPath}`);
+    }
+    const workspacePath = normalizeWorkspacePath(returnedPath, userId);
+    return {
+        success: payload.success,
+        userId,
+        workspacePath,
+        previewUrl: buildSharedPreviewUrl(userId, workspacePath),
+        downloadUrl: buildSharedDownloadUrl(userId, workspacePath),
+        metadata: {
+            file: payload.file,
+            overwriteRequested: Boolean(args.overwrite),
+        },
+    };
+}

package/dist/index.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { server } from './server.js';
+server.start({ transportType: 'stdio' });

package/dist/path-mapping.js

@@ -0,0 +1,33 @@
+import * as path from 'path';
+const VIDEO_EXTENSIONS = new Set(['.mp4', '.mov', '.avi', '.mkv', '.webm']);
+const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp', '.gif', '.svg']);
+const AUDIO_EXTENSIONS = new Set(['.mp3', '.wav', '.aac', '.m4a', '.flac', '.ogg']);
+const FONT_EXTENSIONS = new Set(['.ttf', '.otf', '.woff', '.woff2']);
+const DATA_EXTENSIONS = new Set(['.json', '.csv', '.srt', '.ass', '.vtt']);
+const DOC_EXTENSIONS = new Set(['.md', '.txt', '.pdf', '.doc', '.docx']);
+const SOURCE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.css', '.html']);
+function normalizeDir(value) {
+    return value.replaceAll('\\', '/').replace(/^\/+/, '').replace(/\/+/g, '/');
+}
+export function inferTargetPath(fileName, contentType, explicitPath) {
+    if (explicitPath?.trim()) {
+        return normalizeDir(explicitPath.trim());
+    }
+    const normalizedType = (contentType || '').toLowerCase();
+    const ext = path.extname(fileName).toLowerCase();
+    if (normalizedType.startsWith('video/') || VIDEO_EXTENSIONS.has(ext))
+        return 'public/videos';
+    if (normalizedType.startsWith('image/') || IMAGE_EXTENSIONS.has(ext))
+        return 'public/images';
+    if (normalizedType.startsWith('audio/') || AUDIO_EXTENSIONS.has(ext))
+        return 'public/audio';
+    if (normalizedType.includes('font') || FONT_EXTENSIONS.has(ext))
+        return 'public/fonts';
+    if (DATA_EXTENSIONS.has(ext))
+        return 'public/data';
+    if (DOC_EXTENSIONS.has(ext))
+        return 'public/documents';
+    if (SOURCE_EXTENSIONS.has(ext))
+        return 'src';
+    return 'public/documents';
+}

package/dist/server.js

@@ -0,0 +1,62 @@
+import { FastMCP } from 'fastmcp';
+import { z } from 'zod';
+import { downloadProjectFile, listProjectFiles, readProjectFile, saveProjectFile } from './client.js';
+const server = new FastMCP({
+    name: 'VE Remotion File Bridge',
+    version: '1.0.0',
+});
+server.addTool({
+    name: 'list_files',
+    description: 'List files in the current Remotion project workspace via the backend file bridge API.',
+    annotations: { title: 'List Remotion Project Files', readOnlyHint: true, openWorldHint: false },
+    parameters: z.object({
+        userId: z.string().optional().describe('Optional user id override. Normally resolved automatically from API key.'),
+        path: z.string().optional().describe('Workspace-relative path, default is root.'),
+        recursive: z.boolean().optional().describe('Whether to recursively browse files. If true, defaults mode to tree.'),
+        mode: z.enum(['children', 'tree', 'file']).optional(),
+        includeContent: z.boolean().optional(),
+        maxDepth: z.number().int().min(1).max(10).optional(),
+        limit: z.number().int().min(1).max(1000).optional(),
+    }),
+    execute: async (args) => JSON.stringify(await listProjectFiles(args), null, 2),
+});
+server.addTool({
+    name: 'read_file',
+    description: 'Read a project file as text when suitable, or return preview/download URLs for binary files.',
+    annotations: { title: 'Read Remotion Project File', readOnlyHint: true, openWorldHint: false },
+    parameters: z.object({
+        userId: z.string().optional(),
+        path: z.string().describe('Workspace-relative file path.'),
+        asText: z.boolean().optional().describe('Whether to fetch text content for text-like files. Defaults to true.'),
+        download: z.boolean().optional().describe('Whether to prefer download mode when requesting remote content.'),
+    }),
+    execute: async (args) => JSON.stringify(await readProjectFile(args), null, 2),
+});
+server.addTool({
+    name: 'download_file',
+    description: 'Download a remote workspace file into the local WORKDIR.',
+    annotations: { title: 'Download Remotion Project File', readOnlyHint: false, openWorldHint: false },
+    parameters: z.object({
+        userId: z.string().optional(),
+        remotePath: z.string().describe('Workspace-relative remote file path.'),
+        localPath: z.string().optional().describe('Optional local output path, relative to WORKDIR or absolute.'),
+    }),
+    execute: async (args) => JSON.stringify(await downloadProjectFile(args), null, 2),
+});
+server.addTool({
+    name: 'save_file',
+    description: 'Save local files, text, base64 payloads, or remote URLs into the current user Remotion workspace.',
+    annotations: { title: 'Save Remotion Project File', readOnlyHint: false, openWorldHint: true },
+    parameters: z.object({
+        userId: z.string().optional(),
+        sourceType: z.enum(['local_path', 'text', 'base64', 'remote_url']),
+        localPath: z.string().optional(),
+        content: z.string().optional(),
+        fileName: z.string().min(1),
+        targetPath: z.string().optional(),
+        contentType: z.string().optional(),
+        overwrite: z.boolean().optional(),
+    }),
+    execute: async (args) => JSON.stringify(await saveProjectFile(args), null, 2),
+});
+export { server };

package/dist/shared.js

@@ -0,0 +1,82 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const BASE_URL = (process.env.BASE_URL || 'https://api.visionengine-tech.com').replace(/\/$/, '');
+const WORKDIR = process.env.WORKDIR || './';
+let cachedUserId = null;
+export function getBaseUrl() {
+    return BASE_URL;
+}
+export function getWorkDir() {
+    return path.isAbsolute(WORKDIR) ? WORKDIR : path.resolve(process.cwd(), WORKDIR);
+}
+export function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+    return dirPath;
+}
+export function toRelativePath(absolutePath) {
+    const workDir = getWorkDir();
+    if (absolutePath.startsWith(workDir)) {
+        return path.relative(workDir, absolutePath).replaceAll('\\', '/') || '.';
+    }
+    return absolutePath.replaceAll('\\', '/');
+}
+export function normalizeWorkspacePath(value, userId) {
+    let normalized = value.trim().replaceAll('\\', '/').replace(/^\/+/, '');
+    if (!normalized || normalized === '.') {
+        return '.';
+    }
+    if (/^[a-zA-Z]:/.test(normalized) || normalized.startsWith('//')) {
+        throw new Error('Path must be workspace-relative');
+    }
+    const prefix = userId ? `${userId}/` : '';
+    if (prefix && normalized.startsWith(prefix)) {
+        normalized = normalized.slice(prefix.length);
+    }
+    const parts = normalized.split('/').filter(Boolean);
+    if (parts.some((part) => part === '..')) {
+        throw new Error('Path traversal is not allowed');
+    }
+    return parts.join('/');
+}
+export function buildSharedPreviewUrl(userId, workspacePath) {
+    const normalized = normalizeWorkspacePath(workspacePath, userId);
+    return `${BASE_URL}/shared/${userId}/${normalized}`;
+}
+export function buildSharedDownloadUrl(userId, workspacePath) {
+    return `${buildSharedPreviewUrl(userId, workspacePath)}?download=true`;
+}
+export function requireApiKey() {
+    const apiKey = process.env.API_KEY || '';
+    if (!apiKey) {
+        throw new Error('API_KEY environment variable is required');
+    }
+    return apiKey;
+}
+export async function fetchCurrentUserIdByApiKey() {
+    const apiKey = requireApiKey();
+    const response = await fetch(`${BASE_URL}/api/v1/auth/me`, {
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+        },
+    });
+    if (!response.ok) {
+        throw new Error(`Failed to resolve user id: ${response.status} ${await response.text()}`);
+    }
+    const payload = await response.json();
+    if (!payload.success || !payload.user_id) {
+        throw new Error('Backend did not return a valid user_id');
+    }
+    cachedUserId = payload.user_id;
+    return payload.user_id;
+}
+export async function resolveUserId(inputUserId) {
+    if (inputUserId?.trim()) {
+        return inputUserId.trim();
+    }
+    if (cachedUserId) {
+        return cachedUserId;
+    }
+    return fetchCurrentUserIdByApiKey();
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@visionengine/remotion-file-bridge",
+  "version": "1.0.0",
+  "description": "VisionEngine Remotion File Bridge MCP Server",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "ve-remotion-file-bridge": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "README-zh.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clear": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "remotion",
+    "files",
+    "visionengine"
+  ],
+  "author": "team@visionengine-tech.com",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/crazyyanchao/ve-mcp.git",
+    "directory": "packages/remotion-file-bridge"
+  },
+  "homepage": "https://visionengine-tech.com/mcp",
+  "dependencies": {
+    "fastmcp": "^3.26.8",
+    "zod": "^4.1.12"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "typescript": "^5.8.3",
+    "vitest": "^3.1.3"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}