Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.
TypeScript browser-shellcontrol-planefile-managerhomelabmobile-firstnextjsptyreactself-hostedserver-managementshadcn-uisysadmintailwindcssterminaltypescriptvpsweb-desktopweb-terminal
feat(mcp): import ChatGPT generated files
rahmanef63d212ae5fe89a
diff --git a/docs/PROGRESS.md b/docs/PROGRESS.mdindex 8c270577..bff1559d 100644--- a/docs/PROGRESS.md+++ b/docs/PROGRESS.md@@ -1515,3 +1515,7 @@ behaviorally verified on an isolated `:4011` dev server (prod never touched).*34 older entries (2026-05-29 → 2026-06-15) were trimmed on 2026-08-10 to keepthis file readable as the source of truth it claims to be. Nothing referenced themby line, and they are one command away: `git show 421ab7f:docs/PROGRESS.md`.*++## 2026-08-20 — ChatGPT generated-file → VPS bridge (DONE)++MCP now exposes `fs_upload_file` with `_meta["openai/fileParams"]`, so ChatGPT can generate or receive an image first and then transfer the exact file bytes into an existing bounded VPS directory. The server accepts only temporary HTTPS OpenAI file references, caps imports at 20 MiB, validates image MIME types, inherits the existing write-root and credential denylist through `uploadInto`, audits as `fs.upload`, and returns byte count plus SHA-256 without persisting the temporary download URL.diff --git a/lib/mcp/dispatch.test.ts b/lib/mcp/dispatch.test.tsindex 9ea51751..a67254ca 100644--- a/lib/mcp/dispatch.test.ts+++ b/lib/mcp/dispatch.test.ts@@ -44,11 +44,19 @@ describe("protocol", () => {it("publishes server and toolset metadata so action drift is visible", async () => {const r = await dispatch({ id: 1, method: "initialize" }, "exec");const result = r.result as { serverInfo: { version: string }; _meta: { toolset: { toolCount: number; hash: string } } };- expect(result.serverInfo.version).toBe("1.4.0");+ expect(result.serverInfo.version).toBe("1.4.1");expect(result._meta.toolset.toolCount).toBe(TOOLS.length);expect(result._meta.toolset.hash).toMatch(/^[a-f0-9]{16}$/);});++ it("publishes OpenAI file binding metadata on the upload bridge", async () => {+ const r = await dispatch({ id: 1, method: "tools/list" }, "write");+ const tools = (r.result as { tools: Array<{ name: string; _meta?: Record<string, unknown> }> }).tools;+ const upload = tools.find((tool) => tool.name === "fs_upload_file");+ expect(upload?._meta).toEqual({ "openai/fileParams": ["file"] });+ });+it("answers ping and initialized", async () => {expect(await dispatch({ id: 2, method: "ping" }, "read")).toMatchObject({ result: {} });expect(await dispatch({ id: 3, method: "notifications/initialized" }, "read")).toMatchObject({ result: {} });diff --git a/lib/mcp/dispatch.ts b/lib/mcp/dispatch.tsindex 7e530bf4..bcad8a86 100644--- a/lib/mcp/dispatch.ts+++ b/lib/mcp/dispatch.ts@@ -32,6 +32,7 @@ const toolList = (scope: Scope) => visibleTools(scope).map((tool) => ({description: tool.description,inputSchema: tool.inputSchema,...(tool.annotations ? { annotations: tool.annotations } : {}),+ ...(tool.meta ? { _meta: tool.meta } : {}),}));function instructions(scope: Scope): string {diff --git a/lib/mcp/openai-file-upload.ts b/lib/mcp/openai-file-upload.tsnew file mode 100644index 00000000..617d22dd--- /dev/null+++ b/lib/mcp/openai-file-upload.ts@@ -0,0 +1,90 @@+import { createHash } from "crypto";+import path from "path";+import { HostError, uploadInto } from "@/lib/host";++export interface OpenAiProvidedFile {+ download_url: string;+ file_id: string;+ mime_type?: string;+ file_name?: string;+ name?: string;+ size?: number;+}++const MAX_FILE_BYTES = 20 * 1024 * 1024;+const ALLOWED_MIME = new Set(["image/png", "image/webp", "image/jpeg", "application/octet-stream"]);++function providedFile(value: unknown): OpenAiProvidedFile {+ if (!value || typeof value !== "object") throw new HostError("file must be a ChatGPT-provided file object");+ const row = value as Partial<OpenAiProvidedFile>;+ if (typeof row.download_url !== "string" || !row.download_url) throw new HostError("file.download_url is missing");+ if (typeof row.file_id !== "string" || !row.file_id) throw new HostError("file.file_id is missing");+ return row as OpenAiProvidedFile;+}++function trustedDownloadUrl(raw: string): URL {+ let url: URL;+ try { url = new URL(raw); } catch { throw new HostError("file.download_url is invalid"); }+ if (url.protocol !== "https:") throw new HostError("file.download_url must use HTTPS");+ const host = url.hostname.toLowerCase();+ if (host !== "files.oaiusercontent.com" && !host.endsWith(".oaiusercontent.com")) {+ throw new HostError("file.download_url is not an OpenAI file host");+ }+ return url;+}++function safeFilename(input: string | undefined, fallback: string): string {+ const value = path.basename((input || fallback).trim());+ if (!value || value === "." || value === ".." || value.length > 200) throw new HostError("filename is invalid");+ if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(value)) throw new HostError("filename may contain only letters, digits, dot, dash and underscore");+ return value;+}++export async function importOpenAiProvidedFile(opts: {+ file: unknown;+ dest: string;+ filename?: string;+}): Promise<{+ ok: true;+ fileId: string;+ path: string;+ filename: string;+ mimeType: string;+ bytes: number;+ sha256: string;+}> {+ const file = providedFile(opts.file);+ const url = trustedDownloadUrl(file.download_url);+ const mimeType = (file.mime_type || "application/octet-stream").toLowerCase();+ if (!ALLOWED_MIME.has(mimeType)) throw new HostError(`unsupported file type: ${mimeType}`);+ if (typeof file.size === "number" && (!Number.isFinite(file.size) || file.size < 0 || file.size > MAX_FILE_BYTES)) {+ throw new HostError("file exceeds the 20 MiB MCP import limit");+ }++ const response = await fetch(url, {+ redirect: "follow",+ signal: AbortSignal.timeout(60_000),+ headers: { accept: "image/png,image/webp,image/jpeg,application/octet-stream" },+ });+ if (!response.ok) throw new HostError(`OpenAI file download failed (${response.status})`);+ const declared = Number(response.headers.get("content-length") || 0);+ if (declared > MAX_FILE_BYTES) throw new HostError("file exceeds the 20 MiB MCP import limit");+ const data = Buffer.from(await response.arrayBuffer());+ if (data.byteLength === 0) throw new HostError("OpenAI file download was empty");+ if (data.byteLength > MAX_FILE_BYTES) throw new HostError("file exceeds the 20 MiB MCP import limit");++ const fallback = file.file_name || file.name || `${file.file_id}.bin`;+ const filename = safeFilename(opts.filename, fallback);+ const result = await uploadInto(opts.dest, [{ relPath: filename, data }]);+ if (result.written !== 1 || result.failed.length) throw new HostError(`file import failed: ${result.failed.join(", ") || "not written"}`);++ return {+ ok: true,+ fileId: file.file_id,+ path: path.join(opts.dest, filename),+ filename,+ mimeType,+ bytes: data.byteLength,+ sha256: createHash("sha256").update(data).digest("hex"),+ };+}diff --git a/lib/mcp/parity.test.ts b/lib/mcp/parity.test.tsindex e60dd673..9eec35b2 100644--- a/lib/mcp/parity.test.ts+++ b/lib/mcp/parity.test.ts@@ -38,6 +38,7 @@ const MCP_ONLY: Record<string, string> = {"screen.capture": "external MCP clients need visual proof of the rendered OS; in-shell Alfa already runs inside that browser UI","image.generation.status": "provider readiness is exposed to external asset agents; Alfa currently has no image-generation output renderer","image.generate": "the external asset agent needs provider bytes, durable sandbox paths and provenance; Alfa currently cannot render or persist provider image output",+ "fs.upload.file": "external ChatGPT connectors need openai/fileParams to move conversation-generated files onto the VPS; in-shell Alfa already has direct host filesystem access","workflow.start": "the external connector needs an actor-scoped task boundary; Alfa already owns an in-app conversation/run boundary","workflow.cancel": "same actor-scoped boundary; external runs need explicit recovery from an interrupted task","workflow.finish": "same actor-scoped learning loop; Alfa recipes can use the session route later without weakening MCP scope semantics",@@ -94,7 +95,7 @@ describe("MCP rate limits mirror the routes", () => {// stricter, never laxer.const ROUTE_LIMITS: Record<string, number> = {"fs.write": 120, "fs.mkdir": 120, "fs.move": 120, "fs.copy": 60,- "fs.delete": 60, "exec": 60, "managed-app": 12, "camoufox": 12,+ "fs.delete": 60, "fs.upload": 20, "exec": 60, "managed-app": 12, "camoufox": 12,};const MCP_NATIVE_LIMITS: Record<string, number> = {// screen_capture has no HTTP route by design; it exists only for connecteddiff --git a/lib/mcp/tool-kit.ts b/lib/mcp/tool-kit.tsindex 96efbdba..40b64292 100644--- a/lib/mcp/tool-kit.ts+++ b/lib/mcp/tool-kit.ts@@ -39,6 +39,8 @@ export interface McpTool {scope: Scope;inputSchema: { type: "object"; properties: Record<string, unknown>; required?: string[] };annotations?: Record<string, boolean>;+ /** OpenAI Apps SDK metadata, including top-level file parameter binding. */+ meta?: Record<string, unknown>;run: (a: Record<string, unknown>, context: McpRunContext) => Promise<unknown>;/** Which audit action this writes, and which argument names the target. Reads* are deliberately unaudited (bounded + high-volume, same rule the /api/v1diff --git a/lib/mcp/tools.ts b/lib/mcp/tools.tsindex df1a57dc..3a560bde 100644--- a/lib/mcp/tools.ts+++ b/lib/mcp/tools.ts@@ -4,6 +4,7 @@ import { performManagedAppAction } from "@/lib/managed-apps/manager";import { isManagedAppId } from "@/lib/managed-apps/catalog";import { MANAGED_APP_ACTIONS, type ManagedAppAction } from "@/lib/managed-apps/types";import { type McpTool, str, opt, S, PATH_P, mcpDirect } from "./tool-kit";+import { importOpenAiProvidedFile } from "./openai-file-upload";import {generateOpenAiImage,OPENAI_IMAGE_BACKGROUNDS,@@ -44,6 +45,40 @@ const MUTATE_TOOLS: McpTool[] = [expectedSha256: opt(a, "expected_sha256"),})) }),},+ {+ name: "fs_upload_file",+ limit: { key: "fs.upload", max: 20, windowMs: 60_000 },+ audit: { action: "fs.upload" as const, targetArg: "dest" },+ description:+ "Import one ChatGPT conversation/generated file into an existing VPS directory. " ++ "ChatGPT binds the top-level file parameter through openai/fileParams, MSO downloads the temporary OpenAI URL immediately, validates the host/type/size, writes within OS_FS_WRITE_ROOTS, and returns byte count plus SHA-256. Existing same-name files may be replaced.",+ scope: "write",+ annotations: { destructiveHint: true, openWorldHint: true },+ meta: { "openai/fileParams": ["file"] },+ inputSchema: S({+ file: {+ type: "object",+ description: "ChatGPT-provided file reference. Select or attach exactly one generated/uploaded image.",+ properties: {+ download_url: { type: "string" },+ file_id: { type: "string" },+ mime_type: { type: "string" },+ file_name: { type: "string" },+ name: { type: "string" },+ size: { type: "number" },+ },+ required: ["download_url", "file_id"],+ additionalProperties: true,+ },+ dest: { type: "string", description: "Existing destination directory on the VPS, within OS_FS_WRITE_ROOTS." },+ filename: { type: "string", description: "Optional safe destination basename; defaults to the ChatGPT filename." },+ }, ["file", "dest"]),+ run: async (a) => importOpenAiProvidedFile({+ file: a.file,+ dest: str(a, "dest"),+ filename: opt(a, "filename"),+ }),+ },{name: "fs_mkdir",limit: { key: "fs.mkdir", max: 120, windowMs: 60_000 },diff --git a/lib/mcp/toolset.ts b/lib/mcp/toolset.tsindex 5956b5da..f92a86c5 100644--- a/lib/mcp/toolset.ts+++ b/lib/mcp/toolset.ts@@ -2,9 +2,9 @@ import { createHash } from "crypto";import type { Scope } from "./scope";import type { McpTool } from "./tool-kit";-export const MCP_SERVER_VERSION = "1.4.0";-export const MCP_TOOLSET_VERSION = "2026.08.20.1";-export const MCP_TOOLSET_CHANGED_AT = "2026-08-19T20:41:23Z";+export const MCP_SERVER_VERSION = "1.4.1";+export const MCP_TOOLSET_VERSION = "2026.08.20.2";+export const MCP_TOOLSET_CHANGED_AT = "2026-08-19T21:24:00Z";export type McpToolsetInfo = {serverVersion: string;@@ -25,6 +25,7 @@ export function toolsetInfo(tools: readonly McpTool[], scope?: Scope): McpToolsescope: tool.scope,inputSchema: tool.inputSchema,annotations: tool.annotations,+ meta: tool.meta,limit: tool.limit,}));const hash = createHash("sha256").update(JSON.stringify(hashInput)).digest("hex").slice(0, 16);