Skip to content

The VS Code of video editing, built for agents.

TypeScript

Enhance MCP server integration and add help functionality

konstantin-paulusa7039fe8b2d3
diff --git a/apps/cli/package.json b/apps/cli/package.json
index d708d36a..3541cf91 100644
--- a/apps/cli/package.json
+++ b/apps/cli/package.json
@@ -19,7 +19,8 @@
"@modelcontextprotocol/sdk": "^1.30.0",
"babel-preset-solid": "^1.9.12",
"commander": "^14.0.3",
- "esbuild": "^0.28.1"
+ "esbuild": "^0.28.1",
+ "zod": "^4.4.3"
},
"devDependencies": {
"@types/babel__core": "^7.20.5",
diff --git a/apps/cli/src/cli-client.ts b/apps/cli/src/cli-client.ts
index bd3189ff..45e54a1d 100644
--- a/apps/cli/src/cli-client.ts
+++ b/apps/cli/src/cli-client.ts
@@ -2,6 +2,7 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+import { execFile } from "node:child_process";
import { connect } from "node:net";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";
@@ -10,9 +11,25 @@ import { version } from "../../../package.json";
import type { Socket } from "node:net";
import type { ToolInput, ToolName, ToolOutput } from "@diffusionstudio/dapi";
+export const APP_NAME = "Diffusion Studio";
+
const DEFAULT_TIMEOUT_MS = 60000;
-export const GENERATE_TIMEOUT_MS = 600000;
-export const EXPORT_TIMEOUT_MS = 3600000;
+const GENERATE_TIMEOUT_MS = 600000;
+const EXPORT_TIMEOUT_MS = 3600000;
+
+// Long-running tools (renders, AI generation, downloads) override the
+// default 60s. Keyed by name so `call` and the wrappers agree.
+const TIMEOUTS: Record<string, number> = {
+ export: EXPORT_TIMEOUT_MS,
+ capture: GENERATE_TIMEOUT_MS,
+ media_transcribe: GENERATE_TIMEOUT_MS,
+ media_listen: GENERATE_TIMEOUT_MS,
+ fetch: GENERATE_TIMEOUT_MS,
+};
+
+export function timeoutFor(tool: string): number {
+ return TIMEOUTS[tool] ?? DEFAULT_TIMEOUT_MS;
+}
export type CallOptions = { timeoutMs?: number };
@@ -22,16 +39,12 @@ export type CallOptions = { timeoutMs?: number };
* output its structured content. One session per call; a command makes one
* or two, and the process exits when it settles.
*/
-export async function call<N extends ToolName>(
- name: N,
- input: ToolInput<N>,
- options: CallOptions = {},
-): Promise<ToolOutput<N>> {
+export async function call<N extends ToolName>(name: N, input: ToolInput<N>, options: CallOptions = {}): Promise<ToolOutput<N>> {
return withClient(async (client) => {
const result = await client.callTool(
{ name, arguments: input as Record<string, unknown> },
undefined,
- { timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS },
+ { timeout: options.timeoutMs ?? timeoutFor(name) },
);
if (result.isError) {
const text = (result.content as Array<{ type: string; text?: string }>)
@@ -63,8 +76,8 @@ async function withClient<T>(fn: (client: Client) => Promise<T>): Promise<T> {
}
// Connecting is where "the app is not running" shows up, as ENOENT (no
-// socket file) or ECONNREFUSED (a stale one); see `errnoCode`.
-function openSocket(): Promise<Socket> {
+// socket file) or ECONNREFUSED (a stale one); see `isAppDown`.
+export function openSocket(): Promise<Socket> {
return new Promise((resolve, reject) => {
const socket = connect(SOCKET_PATH);
socket.once("connect", () => {
@@ -80,9 +93,48 @@ export function errnoCode(e: unknown): string | undefined {
return (e as NodeJS.ErrnoException | undefined)?.code;
}
-// Bridges the cold-start gap after launching the app: the socket appears
-// once main is ready, and `ping` proves the server answers. The retry loop
-// only handles the brief window before the socket binds.
+export function isAppDown(e: unknown): boolean {
+ const code = errnoCode(e);
+ return code === "ENOENT" || code === "ECONNREFUSED";
+}
+
+/**
+ * Launches the app, or surfaces the running instance: `open -a` on a running
+ * app only activates it, so this is safe to always run. macOS only; elsewhere
+ * it resolves false and the caller falls through to the socket.
+ */
+export function launchApp(background: boolean): Promise<boolean> {
+ if (process.platform !== "darwin") return Promise.resolve(false);
+ const args = background ? ["-g", "-a", APP_NAME, "--args", "--hidden"] : ["-a", APP_NAME];
+ return new Promise((res) => execFile("open", args, (err) => res(!err)));
+}
+
+/**
+ * Bridges the cold-start gap after launching the app: the socket appears once
+ * main is ready. Retries only while the app looks down; any other error is
+ * the caller's.
+ */
+export async function connectWithRetry(timeoutMs = 30000): Promise<Socket> {
+ const start = Date.now();
+ let lastError: unknown = null;
+ while (Date.now() - start < timeoutMs) {
+ try {
+ return await openSocket();
+ } catch (e) {
+ if (!isAppDown(e)) throw e;
+ lastError = e;
+ await new Promise((r) => setTimeout(r, 200));
+ }
+ }
+ throw timedOut(timeoutMs, lastError);
+}
+
+function timedOut(timeoutMs: number, lastError: unknown): Error {
+ const detail = lastError instanceof Error ? ` (${lastError.message})` : "";
+ return new Error(`${APP_NAME} did not answer within ${Math.round(timeoutMs / 1000)}s of launching${detail}`);
+}
+
+/** Like `connectWithRetry`, but also proves the server answers: a cold app binds the socket before its session is ready. */
export async function waitForApp(timeoutMs = 30000): Promise<void> {
const start = Date.now();
let lastError: unknown = null;
@@ -91,11 +143,10 @@ export async function waitForApp(timeoutMs = 30000): Promise<void> {
await ping();
return;
} catch (e) {
+ if (!isAppDown(e)) throw e;
lastError = e;
- const code = errnoCode(e);
- if (code !== "ENOENT" && code !== "ECONNREFUSED") throw e;
await new Promise((r) => setTimeout(r, 200));
}
}
- throw lastError instanceof Error ? lastError : new Error("Timed out waiting for the app to start");
+ throw timedOut(timeoutMs, lastError);
}
diff --git a/apps/cli/src/help.ts b/apps/cli/src/help.ts
new file mode 100644
index 00000000..e902d2f9
--- /dev/null
+++ b/apps/cli/src/help.ts
@@ -0,0 +1,44 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// The wrappers' help text and validation come from the catalog, so
+// `dapi <cmd> --help` and the app's `tools/list` say the same thing because
+// they are the same string, and a bad argument fails here with the message
+// the app would have sent back.
+
+import { z } from "zod";
+import { toolByName } from "@diffusionstudio/dapi";
+
+import type { GenericTool, ToolName } from "@diffusionstudio/dapi";
+
+/** The tool's description, verbatim. */
+export function describe(name: ToolName): string {
+ return toolByName(name).description;
+}
+
+/**
+ * An input field's description, for the option that maps onto it. The
+ * fallback covers fields the catalog leaves undescribed and options whose
+ * meaning is the CLI's own (`--separate` inverts `combine`).
+ */
+export function field(name: ToolName, key: string, fallback?: string): string {
+ const tool: GenericTool = toolByName(name);
+ const schema = tool.input.shape[key];
+ if (schema === undefined && fallback === undefined) {
+ throw new Error(`tool ${name} has no input field "${key}"`);
+ }
+ return schema?.description ?? fallback ?? "";
+}
+
+/**
+ * Checks the input against the catalog before it leaves the process, so a
+ * bad argument fails here with the message the app would have sent back.
+ * Prints the issues and exits on failure.
+ */
+export function validate(name: ToolName, input: Record<string, unknown>): void {
+ const result = toolByName(name).input.safeParse(input);
+ if (result.success) return;
+ console.error(z.prettifyError(result.error));
+ process.exit(1);
+}
diff --git a/apps/cli/src/index.ts b/apps/cli/src/index.ts
index 4058434e..2216fcdb 100644
--- a/apps/cli/src/index.ts
+++ b/apps/cli/src/index.ts
@@ -3,206 +3,77 @@
* License, v. 2.0. If a copy of the MPL was not distributed with this
* file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-import { execFile } from "node:child_process";
import { existsSync } from "node:fs";
import { isAbsolute, resolve } from "node:path";
import { Command } from "commander";
import { version } from "../../../package.json";
-import { parseTime, TIME_FPS } from "@diffusionstudio/jsx";
-import { call, errnoCode, EXPORT_TIMEOUT_MS, GENERATE_TIMEOUT_MS, ping, waitForApp } from "./cli-client";
-import { ISSUE_LOG_TAIL, MAX_FRAMES_PER_SHEET } from "@diffusionstudio/dapi";
-import type { FrameQuality, ImageRef, LogEntry, LogLevel } from "@diffusionstudio/dapi";
+import { TIME_FPS } from "@diffusionstudio/jsx";
+import { ISSUE_LOG_TAIL, NonNegativeTime } from "@diffusionstudio/dapi";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
+import { APP_NAME, call, isAppDown, launchApp, ping, waitForApp } from "./cli-client";
+import { describe, field, validate } from "./help";
+import { runProxy } from "./mcp-proxy";
-// Long-running commands (renders, AI generation) override the default 60s.
-const GENERATE = { timeoutMs: GENERATE_TIMEOUT_MS };
-const EXPORT = { timeoutMs: EXPORT_TIMEOUT_MS };
+import type { ToolInput, ToolName, ToolOutput } from "@diffusionstudio/dapi";
-const APP_NAME = "Diffusion Studio";
-
-function handleSocketError(e: unknown): never {
- const code = errnoCode(e);
- if (code === "ENOENT" || code === "ECONNREFUSED") {
- console.error(`${APP_NAME} is not running. Launch the app first, then retry.`);
- } else {
- console.error((e as Error).message);
- }
+function fail(message: string): never {
+ console.error(message);
process.exit(1);
}
-const FRAME_QUALITIES: FrameQuality[] = ["small", "medium", "large", "fullres"];
-
-// Guardrail against accidentally decoding a huge number of frames; --uncapped lifts it.
-const FRAME_CAP = 100;
-
-type MediaFrameOptions = {
- time?: string[];
- count?: string;
- start?: string;
- end?: string;
- quality?: string;
- uncapped?: boolean;
- output?: string;
- auto?: boolean;
- separate?: boolean;
- perSheet?: string;
-};
-
-async function mediaFrame(ref: string, opts: MediaFrameOptions): Promise<void> {
- if (opts.time !== undefined && opts.count !== undefined) {
- console.error("Pass either --time or --count, not both.");
- process.exit(1);
- }
- if (opts.auto && opts.time !== undefined) {
- console.error("--auto picks its own timestamps; it cannot be combined with --time.");
- process.exit(1);
- }
-
- let times: number[] | undefined;
- if (opts.time !== undefined) {
- times = opts.time.map((t) => parseTimeArg(t, "--time", true));
- }
-
- let count: number | undefined;
- if (opts.count !== undefined) {
- count = Number(opts.count);
- if (!Number.isInteger(count) || count < 1) {
- console.error(`--count must be a positive integer (got "${opts.count}")`);
- process.exit(1);
- }
- }
-
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
- if ((start !== undefined || end !== undefined) && count === undefined && !opts.auto) {
- console.error("--start and --end only apply together with --count or --auto.");
- process.exit(1);
- }
-
- const requested = count ?? times?.length ?? 1;
- if (!opts.uncapped && requested > FRAME_CAP) {
- console.error(`Grabbing ${requested} frames exceeds the ${FRAME_CAP}-frame cap; pass --uncapped to override.`);
- process.exit(1);
- }
-
- let quality: FrameQuality | undefined;
- if (opts.quality !== undefined) {
- if (!FRAME_QUALITIES.includes(opts.quality as FrameQuality)) {
- console.error(`--quality must be one of ${FRAME_QUALITIES.join(", ")} (got "${opts.quality}")`);
- process.exit(1);
- }
- quality = opts.quality as FrameQuality;
- }
-
- const perSheet = parsePerSheet(opts.perSheet, opts.separate);
- const target = resolveAssetRef(ref);
- try {
- const { images } = await call("media_grab", {
- ...target,
- times,
- count,
- start,
- end,
- quality,
- auto: opts.auto,
- combine: !opts.separate,
- perSheet,
- uncapped: opts.uncapped,
- output: resolveOutput(opts.output),
- });
- printImages(images);
- } catch (e) {
- handleSocketError(e);
- }
+function handleSocketError(e: unknown): never {
+ if (isAppDown(e)) fail(`${APP_NAME} is not running. Launch the app first, then retry.`);
+ fail((e as Error).message);
}
/**
- * A local file (or frames folder) that exists is sent as its absolute path;
- * anything else — a URL, or a library path (`b-roll/clip.mp4`) — is passed
- * through for the app to resolve. Library paths need an open project.
+ * One wrapper's whole job: check the input against the catalog, call the
+ * tool, print the result the way the app returns it — its structured content,
+ * as one JSON object, the same thing an agent receives. Everything the app
+ * validates is sent as typed (strings stay strings: times like "45f" are
+ * parsed by the schema on both sides).
*/
-function resolveAssetRef(ref: string): { path: string } {
- const absPath = isAbsolute(ref) ? ref : resolve(process.cwd(), ref);
- if (existsSync(absPath)) return { path: absPath };
- if (isAbsolute(ref)) {
- console.error(`File not found: ${absPath}`);
- process.exit(1);
- }
- return { path: ref };
-}
-
-async function mediaProbe(ref: string): Promise<void> {
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Probing asset");
- try {
- const result = await call("media_probe", target);
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
+async function run<N extends ToolName>(name: N, input: ToolInput<N>, spinner?: string): Promise<void> {
+ await invoke(name, input, spinner);
}
-async function mediaTranscribe(ref: string): Promise<void> {
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Transcribing asset");
+/** `run`, handing the result back for the one command that inspects it (`check`, for its exit code). */
+async function invoke<N extends ToolName>(name: N, input: ToolInput<N>, spinner?: string): Promise<ToolOutput<N>> {
+ validate(name, input as Record<string, unknown>);
+ const stop = spinner ? startSpinner(spinner) : () => {};
try {
- const result = await call("media_transcribe", target, GENERATE);
+ const output = await call(name, input);
stop();
- console.log(JSON.stringify(result));
+ console.log(JSON.stringify(output));
+ return output;
} catch (e) {
stop();
handleSocketError(e);
}
}
-type MediaListenOptions = { prompt?: string; start?: string; end?: string; keepVideo?: boolean };
-
-async function mediaListen(ref: string, opts: MediaListenOptions): Promise<void> {
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
+// Option parsers. Numbers are converted so the schema can check them as
+// numbers; an empty or non-numeric string becomes NaN, which the schema
+// rejects with its own message.
+const numeric = (value: string): number => (value.trim() === "" ? NaN : Number(value));
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Analyzing asset");
- try {
- const result = await call(
- "media_listen",
- { ...target, prompt: opts.prompt, start, end, stripVideo: !opts.keepVideo },
- GENERATE,
- );
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
+/** A time as the CLI takes it, in seconds, checked the way the catalog checks it. */
+function seconds(value: string, flag: string): number {
+ const result = NonNegativeTime.safeParse(value);
+ if (!result.success) fail(`${flag}: ${result.error.issues[0]?.message ?? `invalid time (got "${value}")`}`);
+ return result.data;
}
-type MediaPreviewOptions = { start?: string; end?: string; scale?: string; output?: string };
-
-function parseTimeArg(value: string, flag: string, allowNegative = false): number {
- const seconds = parseTime(value);
- if (seconds === undefined || (!allowNegative && seconds < 0)) {
- console.error(
- `${flag} must be a ${allowNegative ? "" : "non-negative "}Time — seconds ("1.5"), frames ("45f"), or "MM:SS" (got "${value}")`,
- );
- process.exit(1);
- }
- return seconds;
-}
-
-// The app wrote the PNGs (one per frame or contact sheet, named by
-// timecode); print where each landed, one line per image.
-function printImages(images: ImageRef[]): void {
- for (const image of images) console.log(JSON.stringify(image));
+/**
+ * A local file (or frames folder) that exists is sent as its absolute path;
+ * anything else — a URL, or a library path (`b-roll/clip.mp4`) — is passed
+ * through for the app to resolve. Library paths need an open project.
+ */
+function resolveAssetRef(ref: string): { path: string } {
+ const absPath = isAbsolute(ref) ? ref : resolve(process.cwd(), ref);
+ if (existsSync(absPath)) return { path: absPath };
+ if (isAbsolute(ref)) fail(`File not found: ${absPath}`);
+ return { path: ref };
}
/** An output path as the app needs it: absolute, or absent for the app's default. */
@@ -210,233 +81,10 @@ function resolveOutput(path: string | undefined): string | undefined {
return path === undefined ? undefined : resolve(process.cwd(), path);
}
-function parsePerSheet(value: string | undefined, separate?: boolean): number | undefined {
- if (value === undefined) return undefined;
- if (separate) {
- console.error("--per-sheet lays out contact sheets; it cannot be combined with --separate.");
- process.exit(1);
- }
- const n = Number(value);
- if (!Number.isInteger(n) || n < 1 || n > MAX_FRAMES_PER_SHEET) {
- console.error(`--per-sheet must be an integer between 1 and ${MAX_FRAMES_PER_SHEET} (got "${value}")`);
- process.exit(1);
- }
- return n;
-}
-
-// Parse the window/scale flags shared by `filmstrip` and `waveform`.
-function parsePreviewWindow(opts: MediaPreviewOptions): { start?: number; end?: number; scale?: number } {
- const start = opts.start !== undefined ? parseTimeArg(opts.start, "--start") : undefined;
- const end = opts.end !== undefined ? parseTimeArg(opts.end, "--end") : undefined;
- if (start !== undefined && end !== undefined && start >= end) {
- console.error(`--start (${start}s) must be less than --end (${end}s).`);
- process.exit(1);
- }
-
- let scale: number | undefined;
- if (opts.scale !== undefined) {
- scale = Number(opts.scale);
- if (!Number.isFinite(scale) || scale <= 0) {
- console.error(`--scale must be a positive number (got "${opts.scale}")`);
- process.exit(1);
- }
- }
-
- return { start, end, scale };
-}
-
-async function mediaFilmstrip(ref: string, opts: MediaPreviewOptions): Promise<void> {
- const { start, end, scale } = parsePreviewWindow(opts);
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Rendering filmstrip");
- try {
- const result = await call("media_filmstrip", { ...target, start, end, scale, output: resolveOutput(opts.output) });
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-async function mediaWaveform(ref: string, opts: MediaPreviewOptions): Promise<void> {
- const { start, end, scale } = parsePreviewWindow(opts);
- const target = resolveAssetRef(ref);
- const stop = startSpinner("Rendering waveform");
- try {
- const result = await call("media_waveform", { ...target, start, end, scale, output: resolveOutput(opts.output) });
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-type CaptureOptions = { time?: string[]; output?: string; separate?: boolean; perSheet?: string };
-
-async function captureNode(id: string, opts: CaptureOptions): Promise<void> {
- const times = (opts.time ?? ["0"]).map((t) => parseTimeArg(t, "--time"));
- const frames = times.map((t) => Math.round(t * TIME_FPS));
- const perSheet = parsePerSheet(opts.perSheet, opts.separate);
-
- try {
- const { images } = await call(
- "capture",
- { id, frames, combine: !opts.separate, perSheet, output: resolveOutput(opts.output) },
- GENERATE,
- );
- printImages(images);
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-async function exportScene(id: string, output: string | undefined): Promise<void> {
- // The app owns everything else: settings come from the project's
- // package.json, the extension check and the default output path need the
- // config and project folder, which live on its side of the socket.
- const path = output !== undefined ? resolve(process.cwd(), output) : undefined;
- const stop = startSpinner("Exporting scene");
- try {
- const result = await call("export", { id, path }, EXPORT);
- stop();
- console.log(JSON.stringify(result));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
-
-async function checkNode(id: string): Promise<void> {
- try {
- const result = await call("check", { id });
- console.log(JSON.stringify(result));
- // Linter convention: issues found is a different failure than "could not run".
- if (result.issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-type OpenOptions = { background?: boolean };
-
-/** `open -a` on a running app only activates it, so this is safe to always run. */
-function launchApp(background: boolean): Promise<boolean> {
- const args = background ? ["-g", "-a", APP_NAME, "--args", "--hidden"] : ["-a", APP_NAME];
- return new Promise((res) => execFile("open", args, (err) => res(!err)));
-}
-
-async function openProject(path: string | undefined, opts: OpenOptions): Promise<void> {
- // Launching is macOS's job; elsewhere (and when the app is not installed,
- // e.g. a dev checkout run from the terminal) fall through to the socket,
- // which answers if the app is running and errors usefully if not.
- const launched = process.platform === "darwin" && (await launchApp(opts.background ?? false));
-
- try {
- // A cold launch needs the renderer up before the app can answer; when
- // nothing was launched there is nothing to wait for, so fail fast.
- if (launched) await waitForApp();
- else await ping();
-
- if (path !== undefined) {
- const result = await call("open", { dir: resolve(path) });
- console.log(JSON.stringify(result));
- }
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-async function context(): Promise<void> {
- try {
- const result = await call("context", {});
- console.log(JSON.stringify(result));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-async function whoami(): Promise<void> {
- try {
- const { user } = await call("whoami", {});
- console.log(JSON.stringify(user));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-const LOG_LEVELS = ["debug", "info", "warning", "error"] as const;
-
-type LogsOptions = { tail?: string; level?: string };
-
-async function showLogs(opts: LogsOptions): Promise<void> {
- if (opts.level !== undefined && !LOG_LEVELS.includes(opts.level as LogLevel)) {
- console.error(`--level must be one of ${LOG_LEVELS.join(", ")} (got "${opts.level}")`);
- process.exit(1);
- }
- let tail: number | undefined;
- if (opts.tail !== undefined) {
- const n = Number(opts.tail);
- if (!Number.isInteger(n) || n <= 0) {
- console.error(`--tail must be a positive integer (got "${opts.tail}")`);
- process.exit(1);
- }
- tail = n;
- }
-
- try {
- const { entries } = await call("logs", { tail, level: opts.level as LogLevel | undefined });
- for (const entry of entries) console.log(formatLogEntry(entry));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-function formatLogEntry(entry: LogEntry): string {
- const pad = (n: number, w = 2) => String(n).padStart(w, "0");
- const d = new Date(entry.ts);
- const time = `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
- const source = entry.source ? ` (${entry.source})` : "";
- return `${time} [${entry.level}] ${entry.message}${source}`;
-}
-
-type ScreenshotOptions = { output?: string };
-
-// `diffusion-studio_2026-07-31_08-55-12.png`
-async function appScreenshot(opts: ScreenshotOptions): Promise<void> {
- try {
- const result = await call("screenshot", { output: resolveOutput(opts.output) });
- console.log(JSON.stringify(result));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-type IssueOptions = { body?: string; command?: string[]; logs?: string };
-
-async function reportIssue(title: string, opts: IssueOptions): Promise<void> {
- let logs: number | undefined;
- if (opts.logs !== undefined) {
- const n = Number(opts.logs);
- if (!Number.isInteger(n) || n < 0) {
- console.error(`--logs must be a non-negative integer (got "${opts.logs}")`);
- process.exit(1);
- }
- logs = n;
- }
- try {
- const result = await call("report", { title, body: opts.body, commands: opts.command, logs });
- console.log(JSON.stringify(result));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
function startSpinner(label: string): () => void {
if (!process.stderr.isTTY) {
process.stderr.write(`${label}…\n`);
- return () => { };
+ return () => {};
}
const frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
const start = Date.now();
@@ -454,82 +102,29 @@ function startSpinner(label: string): () => void {
};
}
-async function listModels(type: string | undefined): Promise<void> {
- if (type !== undefined && type !== "image" && type !== "video" && type !== "audio") {
- console.error(`[type] must be one of "image", "video", "audio" (got "${type}")`);
- process.exit(1);
- }
- try {
- const { models } = await call("models", { type: type as "image" | "video" | "audio" | undefined });
- for (const model of models) console.log(JSON.stringify(model));
- } catch (e) {
- handleSocketError(e);
- }
-}
+// ---------------------------------------------------------------------------
+// Commands that are the CLI's own: launching, and the proxy.
-async function listVoices(): Promise<void> {
- try {
- const { voices } = await call("voices", {});
- for (const voice of voices) console.log(JSON.stringify(voice));
- } catch (e) {
- handleSocketError(e);
- }
-}
-
-type ListFontsOptions = {
- family?: string;
- weight?: string[];
- style?: string;
- limit?: string;
- namesOnly?: boolean;
-};
-
-async function listFonts(opts: ListFontsOptions): Promise<void> {
- let style: "normal" | "italic" | undefined;
- if (opts.style !== undefined) {
- if (opts.style !== "normal" && opts.style !== "italic") {
- console.error(`--style must be "normal" or "italic" (got "${opts.style}")`);
- process.exit(1);
- }
- style = opts.style;
- }
-
- let limit: number | undefined;
- if (opts.limit !== undefined) {
- const n = Number(opts.limit);
- if (!Number.isInteger(n) || n <= 0) {
- console.error(`--limit must be a positive integer (got "${opts.limit}")`);
- process.exit(1);
- }
- limit = n;
- }
+type OpenOptions = { background?: boolean };
+async function openProject(path: string | undefined, opts: OpenOptions): Promise<void> {
+ // Launching is macOS's job; elsewhere (and when the app is not installed,
+ // e.g. a dev checkout run from the terminal) fall through to the socket,
+ // which answers if the app is running and errors usefully if not.
+ const launched = await launchApp(opts.background ?? false);
try {
- const { families } = await call("fonts", { family: opts.family, weights: opts.weight, style, limit });
- if (opts.namesOnly) {
- for (const family of families) console.log(family.family);
- } else {
- for (const family of families) console.log(JSON.stringify(family));
- }
+ // A cold launch needs the renderer up before the app can answer; when
+ // nothing was launched there is nothing to wait for, so fail fast.
+ if (launched) await waitForApp();
+ else await ping();
} catch (e) {
handleSocketError(e);
}
+ if (path !== undefined) await run("open", { dir: resolve(path) });
}
-type FetchCliOptions = { output?: string; format?: string; audio?: boolean };
-
-// `raw` is every operand after `url` — the yt-dlp passthrough placed after `--`.
-async function fetch(url: string, opts: FetchCliOptions, raw: string[]): Promise<void> {
- const stop = startSpinner("Downloading");
- try {
- const { paths } = await call("fetch", { url, ...opts, raw, output: resolveOutput(opts.output) }, GENERATE);
- stop();
- for (const path of paths) console.log(JSON.stringify({ path }));
- } catch (e) {
- stop();
- handleSocketError(e);
- }
-}
+// ---------------------------------------------------------------------------
+// The program.
const program = new Command();
@@ -538,58 +133,68 @@ program
.description(
`The Diffusion Studio CLI: understand, generate, and edit footage.
Analyze video/audio/images, generate them with AI, and compose assets.
-Use for any media analysis, media generation, or video editing task. No ffmpeg needed.`,
+Use for any media analysis, media generation, or video editing task. No ffmpeg needed.
+
+Every command wraps one tool of the running app's MCP server, which agents reach at ${MCP_URL} once the app runs (\`dapi open\`).`,
)
.version(version);
+program
+ .command("mcp")
+ .description(
+ `Serve the app's MCP server on stdio, for agents that cannot connect over HTTP (Claude Desktop). Every other agent should register the URL ${MCP_URL} instead, which the running app serves — \`dapi open\` starts it. Register this with \`claude mcp add dapi -- dapi mcp\` (or the equivalent entry in the agent's MCP config) and the agent gets every command below as a tool, with the same descriptions. Launches ${APP_NAME} in the background if it is not running (macOS).`,
+ )
+ .action(() => runProxy().catch((e: Error) => fail(e.message)));
+
program
.command("open")
.description(
- `Launch ${APP_NAME} (or surface the running instance) and, given a path, open that folder as a project.`,
+ `Launch ${APP_NAME} (or surface the running instance) and, given a path, open that folder as a project, creating the project files if the folder is not one yet. Prints the project's id, display name, and folder. Run this once before commands that need an open project (capture, check, export, context, and library paths in media commands).`,
)
- .argument("[path]", "project folder to open or create (default: none — just launch the app)")
+ .argument("[path]", `${field("open", "dir")} (default: none — just launch the app)`)
.option("-b, --background", "launch or keep the app in the background, without raising a window")
.action((path: string | undefined, opts: OpenOptions) => openProject(path, opts));
program
.command("context")
.alias("ctx")
- .description(
- `Print the current app context: the application root folder (always reported), the folder of the project the app has open (null when none is), where its playhead sits, in seconds, the registered font families, and where its generations stand.`,
- )
- .action(() => context());
+ .description(describe("context"))
+ .action(() => run("context", {}));
+
+type CaptureOptions = { time?: string[]; output?: string; separate?: boolean; perSheet?: number };
program
.command("capture")
- .description(
- `Render single frames of a scene to PNGs — each frame is the frame an export of that scene would encode, drawn offscreen at the scene's own size. By default the positions are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (\`08s10f\`, zero segments dropped) and rendered as large as fits, so a few positions arrive as one high-resolution picture instead of a directory to open one by one (\`--separate\` writes a PNG per position, at 720p height). The tool for checking composition ("what plays at time T": layout, overlaps, text, timing) and for verifying frames before an export. Scenes only — a single element renders inside its scene, so capture the scene at the times it plays. For a video asset's own full-resolution pixels use \`media grab\`.`,
+ .description(describe("capture"))
+ .argument("<id>", field("capture", "id"))
+ .option(
+ "-t, --time <time...>",
+ `one or more positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0)`,
)
- .argument("<id>", 'scene id to capture or `file:id` when two files use the same id')
- .option("-t, --time <time...>", `one or more positions to capture, relative to the export's first frame, the workarea's start (0 = the export's frame 0) — seconds ("1.5"), frames ("45f"), or "MM:SS" (default: 0)`)
- .option("-S, --separate", "write one PNG per position instead of merging them into contact sheets")
- .option("--per-sheet <n>", "positions per contact sheet, 1-12; fewer means a larger cell each (default: as many as fit)")
- .option("-o, --output <dir>", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
- .action((id: string, opts: CaptureOptions) => captureNode(id, opts));
+ .option("-S, --separate", "write one PNG per position instead of merging them into contact sheets (combine: false)")
+ .option("--per-sheet <n>", field("capture", "perSheet"), numeric)
+ .option("-o, --output <dir>", field("capture", "output"))
+ .action((id: string, opts: CaptureOptions) => {
+ const frames = (opts.time ?? ["0"]).map((t) => Math.round(seconds(t, "--time") * TIME_FPS));
+ return run("capture", { id, frames, combine: !opts.separate, perSheet: opts.perSheet, output: resolveOutput(opts.output) });
+ });
program
.command("export")
- .description(
- `Encode a scene to a video file — the same render the app's export runs, covering the scene's workarea. Settings come from the scene's \`diffusion.export.<id>\` entry in the project's package.json (the entry the app's export panel writes); a scene without one exports with the defaults (1080p H.264 MP4, AAC audio). The [output] extension picks the container, overriding the configured format. Prints one JSON object with the written path and the settings used. One export runs at a time; progress shows in the app.`,
- )
- .argument("<id>", 'scene id to export or `file:id` when two files use the same id')
- .argument(
- "[output]",
- 'output file path, ffmpeg-style; its extension picks the container (default: "exports/<id>.<format>" in the project folder)',
- )
- .action((id: string, output: string | undefined) => exportScene(id, output));
+ .description(describe("export"))
+ .argument("<id>", field("export", "id"))
+ .argument("[output]", field("export", "path"))
+ .action((id: string, output: string | undefined) => run("export", { id, path: resolveOutput(output) }, "Exporting scene"));
program
.command("check")
- .description(
- `Check a node's subtree for obvious structural mistakes, without rendering (local analysis, no credits): spans where no visual is scheduled (likely black frames), children that never become visible, zero-duration or fully transparent nodes, and assets that failed to load or generate — plus subtree stats (node count by kind, nesting depth, played duration). Prints one JSON object; times in issue ranges are seconds relative to the node's start — for a scene whose workarea starts at 0, the same clock \`capture --time\` uses. Exits 1 when an error-severity issue is found. Structural only: a scheduled clip can still render black (dark footage, content smaller than the canvas), so confirm suspicious spans visually with \`capture\`.`,
- )
- .argument("<id>", 'node id to check or `file:id` when two files use the same id')
- .action((id: string) => checkNode(id));
+ .description(`${describe("check")} Exits 1 when an error-severity issue is found.`)
+ .argument("<id>", field("check", "id"))
+ .action(async (id: string) => {
+ const { issues } = await invoke("check", { id });
+ // Linter convention: issues found is a different failure than "could not run".
+ if (issues.some((issue) => issue.severity === "error")) process.exitCode = 1;
+ });
const media = program
.command("media")
@@ -600,148 +205,186 @@ const media = program
media
.command("probe")
- .description(
- `Read the container and per-track technical metadata of a media file (local read, no credits): container format, duration, tags, and each track's codec params, without decoding. Commonly useful for a quick technical read, e.g. checking codec compatibility or duration before cutting. Packet stats (fps, bitrate) are estimated from a leading sample; images and transcripts report file-level info only.`,
- )
- .argument("<path>", "local file path")
- .action((ref: string) => mediaProbe(ref));
+ .description(describe("media_probe"))
+ .argument("<path>", field("media_probe", "path"))
+ .action((ref: string) => run("media_probe", resolveAssetRef(ref), "Probing asset"));
media
.command("transcribe")
- .description(
- `Transcribe the speech in a video or audio file and print the timed transcript, with word-level start/end times in seconds. Commonly useful for footage with speakers (talking head, interview), where the word times let you cut on a line. A transcript marks only speech; the gaps are not necessarily silent (music, score, applause).`,
- )
- .argument("<path>", "local video or audio file path")
- .action((ref: string) => mediaTranscribe(ref));
+ .description(describe("media_transcribe"))
+ .argument("<path>", field("media_transcribe", "path"))
+ .action((ref: string) => run("media_transcribe", resolveAssetRef(ref), "Transcribing asset"));
+
+type GrabOptions = {
+ time?: string[];
+ count?: number;
+ start?: string;
+ end?: string;
+ quality?: string;
+ uncapped?: boolean;
+ output?: string;
+ auto?: boolean;
+ separate?: boolean;
+ perSheet?: number;
+};
media
.command("grab")
.alias("sample")
- .description(
- `Decode frames of a video file and write them as PNGs (local render, no credits). By default the frames are merged into contact sheets: up to 12 per image, each cell labelled with its timecode (\`08s10f\`, zero segments dropped) and drawn as large as fits, so a handful of frames arrives as one high-resolution picture instead of a directory to open one by one (\`--separate\` writes a PNG per frame). Grabs the asset's own pixels, unlike \`capture\` which renders the composited node. The recommended tool for understanding a video at the frame level; past ~12 frames prefer \`media filmstrip\`.`,
- )
- .argument("<path>", "local video file path to grab frames from")
- .option("-t, --time <time...>", `one or more timestamps to grab — seconds ("1.5"), frames ("45f"), or "MM:SS"; negatives count back from the end, so -1 is one second before the end and -1f one frame before it (default: 0)`)
- .option("-c, --count <n>", "instead of --time, grab this many frames evenly spaced across the clip (or across the --start/--end window)")
- .option("-a, --auto", "scan the clip at 2fps and keep a frame each time the footage settles into a new visual state (transitions are waited out, so picks stay sharp); returns at most --count frames (default cap: 30), static footage like screen recordings returns far fewer; requires WebGPU")
- .option("-s, --start <time>", `with --count or --auto, start of the window to sample (seconds, "45f" frames, or "MM:SS"; default: 0)`)
- .option("-e, --end <time>", `with --count or --auto, end of the window to sample (seconds, "45f" frames, or "MM:SS"; default: asset duration)`)
- .option("-q, --quality <preset>", "frame resolution: small (384x384), medium (768x768), large (1536x1536), or fullres (native); default: as large as the sheet cell allows, or small with --separate")
- .option("-S, --separate", "write one PNG per frame instead of merging them into contact sheets")
- .option("--per-sheet <n>", "frames per contact sheet, 1-12; fewer frames means a larger cell each (default: as many as fit)")
- .option("--uncapped", "lift the 100-frame safety cap (grabbing many frames is slow and token-heavy)")
- .option("-o, --output <dir>", "directory to write the PNGs into (default: a fresh dir in the system temp dir)")
- .action((ref: string, opts: MediaFrameOptions) => mediaFrame(ref, opts));
+ .description(describe("media_grab"))
+ .argument("<path>", field("media_grab", "path"))
+ .option("-t, --time <time...>", field("media_grab", "times"))
+ .option("-c, --count <n>", field("media_grab", "count"), numeric)
+ .option("-a, --auto", field("media_grab", "auto"))
+ .option("-s, --start <time>", field("media_grab", "start", `with --count or --auto, start of the window to sample (seconds, "45f" frames, or "MM:SS"; default: 0)`))
+ .option("-e, --end <time>", field("media_grab", "end", `with --count or --auto, end of the window to sample (seconds, "45f" frames, or "MM:SS"; default: asset duration)`))
+ .option("-q, --quality <preset>", field("media_grab", "quality"))
+ .option("-S, --separate", "write one PNG per frame instead of merging them into contact sheets (combine: false)")
+ .option("--per-sheet <n>", field("media_grab", "perSheet"), numeric)
+ .option("--uncapped", field("media_grab", "uncapped"))
+ .option("-o, --output <dir>", field("media_grab", "output"))
+ .action((ref: string, opts: GrabOptions) =>
+ run(
+ "media_grab",
+ {
+ ...resolveAssetRef(ref),
+ times: opts.time,
+ count: opts.count,
+ auto: opts.auto,
+ start: opts.start,
+ end: opts.end,
+ quality: opts.quality as ToolInput<"media_grab">["quality"],
+ combine: !opts.separate,
+ perSheet: opts.perSheet,
+ uncapped: opts.uncapped,
+ output: resolveOutput(opts.output),
+ },
+ ),
+ );
+
+type PreviewOptions = { start?: string; end?: string; scale?: number; output?: string };
+
+const previewInput = (ref: string, opts: PreviewOptions) => ({
+ ...resolveAssetRef(ref),
+ start: opts.start,
+ end: opts.end,
+ scale: opts.scale,
+ output: resolveOutput(opts.output),
+});
media
.command("filmstrip")
.alias("film")
- .description(
- `Render a grid of thumbnails sampled across the timeline to a PNG (local render, no credits), each row stamped with an HH:MM:SS:FF ruler. A fast, token-efficient video track preview; narrow the window to zoom into a region of interest. Video only (use \`media waveform\` for audio).`,
- )
- .argument("<path>", "local video file path to preview")
- .option("-s, --start <time>", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`)
- .option("-e, --end <time>", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`)
- .option("-x, --scale <factor>", "scale factor for the thumbnails; smaller thumbnails fit more rows and columns, larger fit fewer (default: 1)")
- .option("-o, --output <path>", "write the PNG here instead of a temp file")
- .action((ref: string, opts: MediaPreviewOptions) => mediaFilmstrip(ref, opts));
+ .description(describe("media_filmstrip"))
+ .argument("<path>", field("media_filmstrip", "path"))
+ .option("-s, --start <time>", field("media_filmstrip", "start", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`))
+ .option("-e, --end <time>", field("media_filmstrip", "end", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`))
+ .option("-x, --scale <factor>", field("media_filmstrip", "scale"), numeric)
+ .option("-o, --output <path>", field("media_filmstrip", "output"))
+ .action((ref: string, opts: PreviewOptions) => run("media_filmstrip", previewInput(ref, opts), "Rendering filmstrip"));
media
.command("waveform")
.alias("wave")
- .description(
- `Render the audio track of a video or audio file as a waveform PNG (local render, no credits) with a timestamp ruler: loudness over time, with silent stretches highlighted in red. A fast, token-efficient audio track preview; the silent spans are also returned as second ranges.`,
- )
- .argument("<path>", "local video or audio file path to preview")
- .option("-s, --start <time>", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`)
- .option("-e, --end <time>", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`)
- .option("-x, --scale <factor>", "scale factor for the waveform; smaller fits more rows and columns, larger fits fewer (default: 1)")
- .option("-o, --output <path>", "write the PNG here instead of a temp file")
- .action((ref: string, opts: MediaPreviewOptions) => mediaWaveform(ref, opts));
+ .description(describe("media_waveform"))
+ .argument("<path>", field("media_waveform", "path"))
+ .option("-s, --start <time>", field("media_waveform", "start", `start of the window to preview — seconds, "45f" frames, or "MM:SS" (default: 0)`))
+ .option("-e, --end <time>", field("media_waveform", "end", `end of the window to preview — seconds, "45f" frames, or "MM:SS" (default: asset duration)`))
+ .option("-x, --scale <factor>", field("media_waveform", "scale"), numeric)
+ .option("-o, --output <path>", field("media_waveform", "output"))
+ .action((ref: string, opts: PreviewOptions) => run("media_waveform", previewInput(ref, opts), "Rendering waveform"));
+
+type ListenOptions = { prompt?: string; start?: string; end?: string; keepVideo?: boolean };
media
.command("listen")
- .description(
- `Prompt a multimodal model for a semantic analysis of an audio track and print its answer. Shines on audio semantics (the name of the music playing, who is speaking, the spoken content with second-granularity timestamps). Accepts an audio file or a video; by default only the audio track is analyzed.`,
- )
- .argument("<path>", "local video or audio file path to analyze")
- .option("-p, --prompt <str>", "question or instruction to guide the analysis")
- .option("-s, --start <time>", `start of the segment to analyze — seconds, "45f" frames, or "MM:SS" (default: 0); timestamps in the analysis are relative to this point`)
- .option("-e, --end <time>", `end of the segment to analyze — seconds, "45f" frames, or "MM:SS" (default: media duration)`)
- .option("--keep-video", "for a video asset, keep the video track instead of stripping to audio, so the model also reads what is on screen (expensive: uploads the full video)")
- .action((ref: string, opts: MediaListenOptions) => mediaListen(ref, opts));
+ .description(describe("media_listen"))
+ .argument("<path>", field("media_listen", "path"))
+ .option("-p, --prompt <str>", field("media_listen", "prompt"))
+ .option("-s, --start <time>", field("media_listen", "start"))
+ .option("-e, --end <time>", field("media_listen", "end"))
+ .option("--keep-video", "for a video asset, keep the video track instead of stripping to audio, so the model also reads what is on screen (expensive: uploads the full video; stripVideo: false)")
+ .action((ref: string, opts: ListenOptions) =>
+ run(
+ "media_listen",
+ { ...resolveAssetRef(ref), prompt: opts.prompt, start: opts.start, end: opts.end, stripVideo: !opts.keepVideo },
+ "Analyzing asset",
+ ),
+ );
program
.command("models")
- .description(
- `List available AI generation models and their per-model constraints (durations, aspect ratios, features), for \`generate.*\` asset declarations in a project module.`,
- )
- .argument("[type]", `filter to one of "image", "video", "audio" (default: all three)`)
- .action((type: string | undefined) => listModels(type));
+ .description(describe("models"))
+ .argument("[type]", field("models", "type"))
+ .action((type: string | undefined) => run("models", { type: type as ToolInput<"models">["type"] }));
program
.command("voices")
- .description(`List the speech voices available for \`generate.voice\` declarations in a project module.`)
- .action(() => listVoices());
+ .description(describe("voices"))
+ .action(() => run("voices", {}));
program
.command("whoami")
- .description(`Print the authenticated account, or null if signed out.`)
- .action(() => whoami());
+ .description(describe("whoami"))
+ .action(() => run("whoami", {}));
+
+type LogsOptions = { tail?: number; level?: string };
program
.command("logs")
- .description(
- `Print recent console output from the running app (what the devtools console shows: page logs, worker logs, uncaught errors), oldest first, one line per entry: local time, level, message, source location. The app buffers the last 2000 entries across reloads and project switches, so this replaces relaunching with ELECTRON_ENABLE_LOGGING=1 when debugging renderer-side behavior.`,
- )
- .option("-n, --tail <n>", "output only the last <n> entries")
- .option("-l, --level <level>", `minimum level to include: "debug", "info", "warning", or "error"`)
- .action((opts: LogsOptions) => showLogs(opts));
+ .description(describe("logs"))
+ .option("-n, --tail <n>", field("logs", "tail"), numeric)
+ .option("-l, --level <level>", `${field("logs", "level")}: "debug", "info", "warning", or "error"`)
+ .action((opts: LogsOptions) => run("logs", { tail: opts.tail, level: opts.level as ToolInput<"logs">["level"] }));
+
+type ScreenshotOptions = { output?: string };
program
.command("screenshot")
- .description(
- `Capture the entire application window as a PNG — the full UI as the user sees it (panels, timeline, asset library, canvas viewport), at the window's current size. The tool for checking what the app itself looks like; to render a node or scene cleanly for composition checks use \`capture\` instead.`,
- )
- .option("-o, --output <dir>", "directory to write the PNG into (default: system temp dir)")
- .action((opts: ScreenshotOptions) => appScreenshot(opts));
+ .description(describe("screenshot"))
+ .option("-o, --output <dir>", field("screenshot", "output"))
+ .action((opts: ScreenshotOptions) => run("screenshot", { output: resolveOutput(opts.output) }));
+
+type ReportOptions = { body?: string; command?: string[]; logs?: number };
program
.command("report")
.alias("issue")
- .description(
- `Report a bug in dapi or the app itself. Files a GitHub issue on diffusionstudio/editor with diagnostics attached (dapi version, platform, recent app logs) and prints its URL. Submits immediately and publicly through the gh CLI, which must be installed and authenticated; there is no review step, so only report real defects and check the attached logs for anything private.`,
- )
- .argument("<title>", "one-line summary of the problem")
- .option("-b, --body <text>", "what happened, in markdown: expected vs actual, and anything the diagnostics won't show")
- .option("-c, --command <cmd...>", "the dapi command(s) that reproduce it, in order; repeatable")
- .option("--logs <n>", `trailing app log entries to attach (0 to omit; default: ${ISSUE_LOG_TAIL})`)
- .action((title: string, opts: IssueOptions) => reportIssue(title, opts));
+ .description(describe("report"))
+ .argument("<title>", field("report", "title"))
+ .option("-b, --body <text>", field("report", "body"))
+ .option("-c, --command <cmd...>", `${field("report", "commands")}; repeatable`)
+ .option("--logs <n>", field("report", "logs", `trailing app log entries to attach (0 to omit; default: ${ISSUE_LOG_TAIL})`), numeric)
+ .action((title: string, opts: ReportOptions) => run("report", { title, body: opts.body, commands: opts.command, logs: opts.logs }));
+
+type FontsOptions = { family?: string; weight?: string[]; style?: string; limit?: number };
program
.command("fonts")
- .description(
- `List the local fonts available on this machine (macOS only). These family names are valid \`fontFamily\` values on <text>; each family lists its variants.`,
- )
- .option("-f, --family <pattern>", "filter to families whose name contains <pattern> (case-insensitive)")
- .option("-w, --weight <weights...>", "filter to variants with the given CSS weight(s), e.g. -w 400 700")
- .option("-s, --style <style>", `filter to variants with the given style: "normal" or "italic"`)
- .option("-l, --limit <n>", "output at most <n> families")
- .option("-n, --names-only", "output only family names (one per line, no variant detail)")
- .action((opts: ListFontsOptions) => listFonts(opts));
+ .description(describe("fonts"))
+ .option("-f, --family <pattern>", field("fonts", "family"))
+ .option("-w, --weight <weights...>", `${field("fonts", "weights")}, e.g. -w 400 700`)
+ .option("-s, --style <style>", `${field("fonts", "style")}: "normal" or "italic"`)
+ .option("-l, --limit <n>", field("fonts", "limit"), numeric)
+ .action((opts: FontsOptions) =>
+ run("fonts", { family: opts.family, weights: opts.weight, style: opts.style as ToolInput<"fonts">["style"], limit: opts.limit }),
+ );
+
+type FetchOptions = { output?: string; format?: string; audio?: boolean };
program
.command("fetch")
- .description(
- `Download a video with yt-dlp (installed separately). Writes files to disk only (a single URL can yield several, e.g. a playlist).`,
- )
- .argument("<url>", "video or page URL to download")
- .option("-o, --output <path>", "output file path or directory (yt-dlp -o template; default: yt-dlp's default)")
- .option("-f, --format <selector>", `yt-dlp format selector (default: prefer mp4), e.g. "bv*+ba/b"`)
- .option("-a, --audio", "extract audio only (yt-dlp -x)")
+ .description(describe("fetch"))
+ .argument("<url>", field("fetch", "url"))
+ .option("-o, --output <path>", field("fetch", "output"))
+ .option("-f, --format <selector>", field("fetch", "format"))
+ .option("-a, --audio", field("fetch", "audio"))
.allowExcessArguments()
.addHelpText("after", `\nForward raw yt-dlp flags after --, e.g. dapi fetch <url> -- --sponsorblock-remove all`)
- .action((url: string, opts: FetchCliOptions, cmd: Command) => fetch(url, opts, cmd.args.slice(1)));
+ .action((url: string, opts: FetchOptions, cmd: Command) =>
+ // `raw` is every operand after `url` — the yt-dlp passthrough placed after `--`.
+ run("fetch", { url, format: opts.format, audio: opts.audio, raw: cmd.args.slice(1), output: resolveOutput(opts.output) }, "Downloading"),
+ );
// Explicit argv convention: the packaged wrapper runs this bundle on
// Electron in ELECTRON_RUN_AS_NODE mode, where commander would otherwise
diff --git a/apps/cli/src/mcp-proxy.ts b/apps/cli/src/mcp-proxy.ts
new file mode 100644
index 00000000..c89bf3da
--- /dev/null
+++ b/apps/cli/src/mcp-proxy.ts
@@ -0,0 +1,40 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// `dapi mcp`: the entry point agents register. A byte pipe between stdio and
+// the app's socket — the socket already carries MCP in stdio framing, so
+// nothing here parses a message, and any app version works with any proxy
+// version. Stdout belongs to the protocol; anything for a human goes to
+// stderr.
+
+import { APP_NAME, connectWithRetry, isAppDown, launchApp, openSocket } from "./cli-client";
+
+import type { Socket } from "node:net";
+
+export async function runProxy(): Promise<void> {
+ let socket: Socket;
+ try {
+ socket = await openSocket();
+ } catch (e) {
+ if (!isAppDown(e)) throw e;
+ // Launching is macOS's job; elsewhere the user starts the app by hand.
+ if (!(await launchApp(true))) {
+ throw new Error(`${APP_NAME} is not running. Launch the app first, then retry.`);
+ }
+ socket = await connectWithRetry();
+ }
+
+ socket.on("error", (error) => {
+ console.error(`[dapi mcp] ${error.message}`);
+ process.exit(1);
+ });
+ // The app went away (quit, or the session was closed): the agent sees EOF.
+ socket.on("close", () => process.exit(0));
+ // The agent went away: tell the app, which ends the session.
+ process.stdin.on("end", () => socket.end());
+ process.stdout.on("error", () => socket.destroy());
+
+ process.stdin.pipe(socket);
+ socket.pipe(process.stdout);
+}
diff --git a/apps/desktop/scripts/stage-cli.mjs b/apps/desktop/scripts/stage-cli.mjs
index 2183f24f..c3f57909 100644
--- a/apps/desktop/scripts/stage-cli.mjs
+++ b/apps/desktop/scripts/stage-cli.mjs
@@ -6,7 +6,8 @@
// an app resource (Contents/Resources/cli). The staged layout:
// cli/dapi.js bundled CLI (built by apps/cli)
// cli/node_modules deps the bundle keeps external (esbuild, babel)
-// cli/bin/dapi shell wrapper, the file that gets linked into PATH
+// cli/bin/dapi shell wrapper: what agents run as `dapi mcp` (registered
+// by mcp-install.ts) and the file that gets linked into PATH
import { execFileSync } from "node:child_process";
import { chmodSync, cpSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
diff --git a/apps/desktop/src/dapi/http.test.ts b/apps/desktop/src/dapi/http.test.ts
new file mode 100644
index 00000000..2bd6a6c8
--- /dev/null
+++ b/apps/desktop/src/dapi/http.test.ts
@@ -0,0 +1,99 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { request } from "node:http";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { z } from "zod";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DapiHttpServer } from "./http";
+
+// An ephemeral port: the fixed one may be held by a running app.
+const PORT = 3200 + Math.floor(Math.random() * 500);
+const PATH = "/mcp";
+let server: DapiHttpServer;
+let firstConnections = 0;
+let sessionsCreated = 0;
+
+beforeAll(async () => {
+ server = new DapiHttpServer({
+ host: "127.0.0.1",
+ port: PORT,
+ path: PATH,
+ onFirstConnection: () => void firstConnections++,
+ createSession() {
+ sessionsCreated++;
+ const session = new McpServer({ name: "test", version: "0.0.0" }, { instructions: "Test instructions." });
+ session.registerTool(
+ "echo",
+ { inputSchema: z.object({ text: z.string() }), outputSchema: z.object({ text: z.string() }) },
+ async ({ text }) => ({ content: [{ type: "text", text }], structuredContent: { text } }),
+ );
+ session.registerResource("note", "dapi://note", { mimeType: "text/plain" }, async () => ({
+ contents: [{ uri: "dapi://note", mimeType: "text/plain", text: "hello" }],
+ }));
+ return session;
+ },
+ });
+ await server.start();
+});
+
+afterAll(() => server.stop());
+
+async function connect(): Promise<Client> {
+ const client = new Client({ name: "test-client", version: "0.0.0" });
+ await client.connect(new StreamableHTTPClientTransport(new URL(server.url)));
+ return client;
+}
+
+describe("mcp over http", () => {
+ it("serves a session: instructions, tools, resources", async () => {
+ const client = await connect();
+ expect(client.getInstructions()).toBe("Test instructions.");
+ expect((await client.listTools()).tools.map((t) => t.name)).toEqual(["echo"]);
+ const result = await client.callTool({ name: "echo", arguments: { text: "hi" } });
+ expect(result.structuredContent).toEqual({ text: "hi" });
+ const note = await client.readResource({ uri: "dapi://note" });
+ expect(note.contents[0]).toMatchObject({ text: "hello" });
+ await client.close();
+ });
+
+ it("gives each client its own session and reports the first once", async () => {
+ const before = sessionsCreated;
+ const a = await connect();
+ const b = await connect();
+ expect(sessionsCreated - before).toBe(2);
+ expect(firstConnections).toBe(1);
+ await a.close();
+ await b.close();
+ });
+
+ it("rejects a stale session id and a non-mcp path", async () => {
+ const stale = await fetch(server.url, {
+ method: "POST",
+ headers: { "content-type": "application/json", accept: "application/json, text/event-stream", "mcp-session-id": "nope" },
+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "ping" }),
+ });
+ expect(stale.status).toBe(404);
+ const elsewhere = await fetch(`http://127.0.0.1:${PORT}/other`);
+ expect(elsewhere.status).toBe(404);
+ });
+
+ it("rejects a request whose Host is not loopback (dns rebinding)", async () => {
+ // node's fetch drops a custom Host header, so go through node:http.
+ const status = await new Promise<number>((resolve, reject) => {
+ const req = request(
+ { host: "127.0.0.1", port: PORT, path: PATH, method: "POST", headers: { host: "evil.example", "content-type": "application/json", accept: "application/json, text/event-stream" } },
+ (res) => {
+ res.resume();
+ res.on("end", () => resolve(res.statusCode ?? 0));
+ },
+ );
+ req.on("error", reject);
+ req.end(JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "x", version: "0" } } }));
+ });
+ expect(status).toBe(403);
+ });
+});
diff --git a/apps/desktop/src/dapi/http.ts b/apps/desktop/src/dapi/http.ts
new file mode 100644
index 00000000..dbdb1415
--- /dev/null
+++ b/apps/desktop/src/dapi/http.ts
@@ -0,0 +1,133 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// MCP over Streamable HTTP on a fixed loopback port: the transport agents
+// register by URL. One MCP session per client, keyed by the session id the
+// transport hands out on `initialize`; later requests carry it in a header.
+// No token: the server binds to loopback and rejects any Host header that is
+// not the loopback address, which is what keeps browser pages from reaching
+// it. Everything else running as the user can already reach the app.
+
+import { randomUUID } from "node:crypto";
+import { createServer } from "node:http";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+
+import type { IncomingMessage, Server, ServerResponse } from "node:http";
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export type HttpServerDeps = {
+ host: string;
+ port: number;
+ /** The URL path the endpoint answers on; anything else is 404. */
+ path: string;
+ /** A fresh MCP server with the tools and resources registered, one per session. */
+ createSession(): McpServer;
+ /** Called once, when the first session initializes. */
+ onFirstConnection(): void;
+};
+
+type Session = { transport: StreamableHTTPServerTransport; server: McpServer };
+
+const SESSION_HEADER = "mcp-session-id";
+
+export class DapiHttpServer {
+ private readonly deps: HttpServerDeps;
+ private readonly sessions = new Map<string, Session>();
+ private server: Server | null = null;
+ private connected = false;
+
+ constructor(deps: HttpServerDeps) {
+ this.deps = deps;
+ }
+
+ /** Resolves once listening; rejects when the port is taken, so the caller can say so. */
+ start(): Promise<void> {
+ return new Promise((resolve, reject) => {
+ const server = createServer((req, res) => void this.handle(req, res));
+ server.once("error", reject);
+ server.listen(this.deps.port, this.deps.host, () => {
+ server.off("error", reject);
+ server.on("error", (error) => console.error("[dapi] http server error:", error));
+ this.server = server;
+ resolve();
+ });
+ });
+ }
+
+ stop(): void {
+ for (const { transport, server } of this.sessions.values()) {
+ void transport.close();
+ void server.close();
+ }
+ this.sessions.clear();
+ this.server?.close();
+ this.server = null;
+ }
+
+ get url(): string {
+ return `http://${this.deps.host}:${this.deps.port}${this.deps.path}`;
+ }
+
+ private async handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+ const url = new URL(req.url ?? "/", this.url);
+ if (url.pathname !== this.deps.path) {
+ res.writeHead(404, { "content-type": "text/plain" }).end("Not found");
+ return;
+ }
+ try {
+ const id = header(req, SESSION_HEADER);
+ const existing = id === undefined ? undefined : this.sessions.get(id);
+ if (existing) {
+ await existing.transport.handleRequest(req, res);
+ return;
+ }
+ if (id !== undefined) {
+ // The transport would answer the same way; answering here keeps a
+ // stale id from allocating a server it never initializes.
+ res.writeHead(404, { "content-type": "application/json" }).end(
+ JSON.stringify({ jsonrpc: "2.0", error: { code: -32001, message: "Session not found" }, id: null }),
+ );
+ return;
+ }
+ // No session: either an `initialize`, which the transport answers with
+ // a new id, or a stray request it rejects with 400.
+ await this.open().transport.handleRequest(req, res);
+ } catch (error) {
+ console.error("[dapi] http request failed:", error);
+ if (!res.headersSent) res.writeHead(500, { "content-type": "text/plain" }).end("Internal error");
+ }
+ }
+
+ private open(): Session {
+ const server = this.deps.createSession();
+ const hosts = [this.deps.host, "localhost"];
+ const transport = new StreamableHTTPServerTransport({
+ sessionIdGenerator: () => randomUUID(),
+ enableDnsRebindingProtection: true,
+ allowedHosts: [...hosts, ...hosts.map((host) => `${host}:${this.deps.port}`)],
+ onsessioninitialized: (id) => {
+ this.sessions.set(id, session);
+ if (!this.connected) {
+ this.connected = true;
+ this.deps.onFirstConnection();
+ }
+ },
+ onsessionclosed: (id) => {
+ this.sessions.delete(id);
+ },
+ });
+ const session: Session = { transport, server };
+ transport.onclose = () => {
+ if (transport.sessionId !== undefined) this.sessions.delete(transport.sessionId);
+ };
+ // connect() starts the transport; it does not block on I/O.
+ void server.connect(transport);
+ return session;
+ }
+}
+
+function header(req: IncomingMessage, name: string): string | undefined {
+ const value = req.headers[name];
+ return Array.isArray(value) ? value[0] : value;
+}
diff --git a/apps/desktop/src/dapi/knowledge.test.ts b/apps/desktop/src/dapi/knowledge.test.ts
new file mode 100644
index 00000000..32c449cb
--- /dev/null
+++ b/apps/desktop/src/dapi/knowledge.test.ts
@@ -0,0 +1,110 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { instructions, registerResources } from "./knowledge";
+
+import type { KnowledgeDeps } from "./knowledge";
+
+// A staged bundle in miniature: docs with a reference page, an example and a
+// stray file that is not a doc; a skill with frontmatter and a reference.
+const root = mkdtempSync(join(tmpdir(), "dapi-knowledge-"));
+const docsDir = join(root, "docs");
+const skillsDir = join(root, "skills");
+const projectDir = join(root, "project");
+
+beforeAll(() => {
+ mkdirSync(join(docsDir, "reference", "jsx"), { recursive: true });
+ mkdirSync(join(docsDir, "examples", "node_modules"), { recursive: true });
+ writeFileSync(join(docsDir, "reference", "README.md"), "# Reference\n");
+ writeFileSync(join(docsDir, "reference", "jsx", "text.md"), "# text\n");
+ writeFileSync(join(docsDir, "examples", "01-hello.tsx"), "export default <scene />;\n");
+ writeFileSync(join(docsDir, "examples", "package.json"), "{}\n");
+ writeFileSync(join(docsDir, "examples", "node_modules", "ignored.md"), "no\n");
+ mkdirSync(join(skillsDir, "editor", "references"), { recursive: true });
+ writeFileSync(join(skillsDir, "editor", "SKILL.md"), "---\nname: editor\ndescription: trigger text\n---\n\n# Footage analysis\n\nProbe first.\n");
+ writeFileSync(join(skillsDir, "editor", "references", "easings.md"), "# Easings\n");
+ mkdirSync(projectDir);
+ writeFileSync(join(projectDir, "AGENTS.md"), "# Project\n");
+});
+
+afterAll(() => rmSync(root, { recursive: true, force: true }));
+
+const deps = (projectOpen: boolean): KnowledgeDeps => ({
+ docsDir,
+ skillsDir,
+ logs: () => [{ ts: 1, level: "info", message: "hi", source: "" }],
+ context: async () => ({ rootDir: root, projectDir: projectOpen ? projectDir : null, currentTime: null, fontFamilies: [], generations: [] }),
+});
+
+async function connect(d: KnowledgeDeps): Promise<Client> {
+ const server = new McpServer({ name: "test", version: "0" }, { instructions: instructions(d) });
+ registerResources(server, d);
+ const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+ await server.connect(serverTransport);
+ const client = new Client({ name: "test-client", version: "0" });
+ await client.connect(clientTransport);
+ return client;
+}
+
+describe("instructions", () => {
+ it("is the preamble followed by the skill without its frontmatter", () => {
+ const text = instructions(deps(true));
+ expect(text.startsWith("Diffusion Studio, a video editor")).toBe(true);
+ expect(text).toContain("dapi://docs/reference/README.md");
+ expect(text.endsWith("# Footage analysis\n\nProbe first.")).toBe(true);
+ expect(text).not.toContain("trigger text");
+ });
+
+ it("falls back to the preamble alone when nothing is staged", () => {
+ const text = instructions({ ...deps(true), skillsDir: null });
+ expect(text.startsWith("Diffusion Studio, a video editor")).toBe(true);
+ expect(text).not.toContain("Footage analysis");
+ });
+});
+
+describe("resources", () => {
+ it("lists the staged docs and skill references, docs only, no node_modules", async () => {
+ const client = await connect(deps(true));
+ const uris = (await client.listResources()).resources.map((r) => r.uri).sort();
+ expect(uris).toEqual([
+ "dapi://context",
+ "dapi://docs/examples/01-hello.tsx",
+ "dapi://docs/reference/README.md",
+ "dapi://docs/reference/jsx/text.md",
+ "dapi://logs",
+ "dapi://project/AGENTS.md",
+ "dapi://skills/editor/SKILL.md",
+ "dapi://skills/editor/references/easings.md",
+ ]);
+ await client.close();
+ });
+
+ it("reads a file, the live state, and the open project's AGENTS.md", async () => {
+ const client = await connect(deps(true));
+ expect((await client.readResource({ uri: "dapi://docs/reference/jsx/text.md" })).contents[0]).toMatchObject({
+ mimeType: "text/markdown",
+ text: "# text\n",
+ });
+ expect((await client.readResource({ uri: "dapi://docs/examples/01-hello.tsx" })).contents[0]).toMatchObject({ mimeType: "text/plain" });
+ const context = await client.readResource({ uri: "dapi://context" });
+ expect(JSON.parse((context.contents[0] as { text: string }).text).projectDir).toBe(projectDir);
+ const logs = await client.readResource({ uri: "dapi://logs" });
+ expect(JSON.parse((logs.contents[0] as { text: string }).text).entries).toHaveLength(1);
+ expect((await client.readResource({ uri: "dapi://project/AGENTS.md" })).contents[0]).toMatchObject({ text: "# Project\n" });
+ await client.close();
+ });
+
+ it("explains a missing project instead of failing silently", async () => {
+ const client = await connect(deps(false));
+ await expect(client.readResource({ uri: "dapi://project/AGENTS.md" })).rejects.toThrow(/No project open/);
+ await client.close();
+ });
+});
diff --git a/apps/desktop/src/dapi/knowledge.ts b/apps/desktop/src/dapi/knowledge.ts
new file mode 100644
index 00000000..fbdb3daf
--- /dev/null
+++ b/apps/desktop/src/dapi/knowledge.ts
@@ -0,0 +1,139 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// What an agent needs to know besides the tools: the server's instructions,
+// which every client receives on connect, and resources for the docs the app
+// ships, the skill's references, and the live state agents poll. All of it
+// comes from the files staged into the app bundle, so what an agent reads is
+// exactly what the installed version documents.
+
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { LogEntry, ToolOutput } from "@diffusionstudio/dapi";
+
+export type KnowledgeDeps = {
+ /** `Contents/Resources/docs`: `reference/` and `examples/`. Null when not staged. */
+ docsDir: string | null;
+ /** `Contents/Resources/skills`: one folder per skill with a SKILL.md. Null when not staged. */
+ skillsDir: string | null;
+ logs(): LogEntry[];
+ context(signal: AbortSignal): Promise<ToolOutput<"context">>;
+};
+
+const DOC_EXTENSIONS = new Set([".md", ".ts", ".tsx"]);
+
+const PREAMBLE = `Diffusion Studio, a video editor, is running on this machine and you are connected to it. The tools are the whole API: their names, descriptions and input schemas are authoritative and match the \`dapi\` command line one to one (\`media_grab\` is \`dapi media grab\`), so anything written for the CLI applies to the tools. Projects are folders of JSX; \`open\` a folder once, then write its files and save — the app recompiles and re-renders.
+
+Read the resources before relying on memory: \`dapi://docs/reference/README.md\` covers every tool, \`dapi://docs/reference/jsx/README.md\` is the JSX contract, \`dapi://docs/examples/\` holds complete compositions, and the skill's own references (brand, easings, worked examples) live under \`dapi://skills/\`. \`dapi://context\` reports the open project, the playhead and generation state; \`dapi://logs\` is the app's console; \`dapi://project/AGENTS.md\` is the open project's own entry point.`;
+
+/** The text every client gets on connect: a preamble about this server, then the editor skill. */
+export function instructions(deps: KnowledgeDeps): string {
+ const parts = [PREAMBLE];
+ // Resources carry text; brand logos, fonts, and components to copy into a
+ // project are files, so say where the same trees sit on disk.
+ const onDisk = [deps.docsDir && `the docs at \`${deps.docsDir}\``, deps.skillsDir && `the skills at \`${deps.skillsDir}\``].filter(Boolean);
+ if (onDisk.length > 0) parts.push(`The same files are on disk, for anything a resource cannot carry (logos, fonts, components to copy): ${onDisk.join(" and ")}. They belong to the app; read them, never edit them.`);
+ const skill = deps.skillsDir ? readSkill(join(deps.skillsDir, "editor", "SKILL.md")) : null;
+ if (skill) parts.push("The editor skill's guidance follows.", skill);
+ return parts.join("\n\n");
+}
+
+function readSkill(path: string): string | null {
+ let text: string;
+ try {
+ text = readFileSync(path, "utf8");
+ } catch {
+ return null;
+ }
+ // Drop the YAML frontmatter: the name and trigger description are for the
+ // skills index, not for an agent already connected.
+ return text.replace(/^---\n[\s\S]*?\n---\n/, "").trim();
+}
+
+export function registerResources(session: McpServer, deps: KnowledgeDeps): void {
+ for (const file of staticFiles(deps)) {
+ session.registerResource(file.name, file.uri, { title: file.name, mimeType: file.mimeType }, async () => ({
+ contents: [{ uri: file.uri, mimeType: file.mimeType, text: await readFile(file.path, "utf8") }],
+ }));
+ }
+
+ session.registerResource(
+ "context",
+ "dapi://context",
+ { title: "App context", description: "The open project, the playhead, registered fonts, and where generations stand.", mimeType: "application/json" },
+ async (uri, extra) => ({
+ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await deps.context(extra.signal)) }],
+ }),
+ );
+
+ session.registerResource(
+ "logs",
+ "dapi://logs",
+ { title: "App logs", description: "The app's console output, oldest first.", mimeType: "application/json" },
+ async (uri) => ({
+ contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify({ entries: deps.logs() }) }],
+ }),
+ );
+
+ session.registerResource(
+ "project-agents",
+ "dapi://project/AGENTS.md",
+ { title: "Open project's AGENTS.md", description: "The agent entry point the app writes into every project.", mimeType: "text/markdown" },
+ async (uri, extra) => {
+ const { projectDir } = await deps.context(extra.signal);
+ if (!projectDir) throw new Error("No project open — run open first");
+ return { contents: [{ uri: uri.href, mimeType: "text/markdown", text: await readFile(join(projectDir, "AGENTS.md"), "utf8") }] };
+ },
+ );
+}
+
+type StaticFile = { name: string; uri: string; path: string; mimeType: string };
+
+// The listing is the same for every session; walk the staged trees once.
+let cache: { key: string; files: StaticFile[] } | null = null;
+
+function staticFiles(deps: KnowledgeDeps): StaticFile[] {
+ const key = `${deps.docsDir}\n${deps.skillsDir}`;
+ if (cache?.key === key) return cache.files;
+ const files: StaticFile[] = [];
+ if (deps.docsDir) collect(deps.docsDir, deps.docsDir, "dapi://docs", files);
+ if (deps.skillsDir) collect(deps.skillsDir, deps.skillsDir, "dapi://skills", files);
+ cache = { key, files };
+ return files;
+}
+
+function collect(root: string, dir: string, uriBase: string, out: StaticFile[]): void {
+ let entries: string[];
+ try {
+ entries = readdirSync(dir);
+ } catch {
+ return;
+ }
+ for (const entry of entries.sort()) {
+ if (entry.startsWith(".") || entry === "node_modules") continue;
+ const path = join(dir, entry);
+ let isDirectory: boolean;
+ try {
+ isDirectory = statSync(path).isDirectory();
+ } catch {
+ continue;
+ }
+ if (isDirectory) {
+ collect(root, path, uriBase, out);
+ continue;
+ }
+ const extension = entry.slice(entry.lastIndexOf("."));
+ if (!DOC_EXTENSIONS.has(extension)) continue;
+ const name = relative(root, path).split(sep).join("/");
+ out.push({
+ name,
+ uri: `${uriBase}/${name}`,
+ path,
+ mimeType: extension === ".md" ? "text/markdown" : "text/plain",
+ });
+ }
+}
diff --git a/apps/desktop/src/dapi/server.ts b/apps/desktop/src/dapi/server.ts
index 5cd18734..4f726ff7 100644
--- a/apps/desktop/src/dapi/server.ts
+++ b/apps/desktop/src/dapi/server.ts
@@ -6,13 +6,15 @@ import { chmodSync, existsSync, unlinkSync } from "node:fs";
import { createServer } from "node:net";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { tools } from "@diffusionstudio/dapi";
-import { SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";
+import { MCP_HOST, MCP_PATH, MCP_PORT, SOCKET_PATH, SocketTransport } from "@diffusionstudio/dapi/socket";
import { mainHandlers } from "./handlers";
+import { DapiHttpServer } from "./http";
+import { instructions, registerResources } from "./knowledge";
import { present, toCallToolResult, toErrorResult } from "./present";
import { RendererCalls } from "./renderer-calls";
import type { Server, Socket } from "node:net";
-import type { GenericTool, LogEntry, ToolName } from "@diffusionstudio/dapi";
+import type { GenericTool, LogEntry, ToolName, ToolOutput } from "@diffusionstudio/dapi";
import type { MainContext, MainToolName } from "./handler";
export type DapiServerDeps = {
@@ -21,20 +23,28 @@ export type DapiServerDeps = {
logs(): LogEntry[];
/** Called once, on the first connection: an agent is driving, so the UI may step back. */
onFirstConnection(): void;
+ /** The staged docs (`reference/`, `examples/`), served as resources. Null when not staged. */
+ docsDir: string | null;
+ /** The staged skills; the editor skill is the server's instructions. Null when not staged. */
+ skillsDir: string | null;
};
/**
- * The app's MCP server. Listens on the local socket; each connection gets its
- * own MCP session over the catalog. Main-process tools run here; renderer
- * tools are forwarded over IPC and their results presented (files written,
- * small images inlined) before they go back out.
+ * The app's MCP server, on two transports over one catalog: Streamable HTTP
+ * on a fixed loopback port, which agents register by URL, and the local
+ * socket the `dapi` CLI uses (and `dapi mcp` proxies for agents that only
+ * speak stdio). Each connection gets its own MCP session. Main-process tools
+ * run here; renderer tools are forwarded over IPC and their results
+ * presented (files written, small images inlined) before they go back out.
*/
export class DapiServer {
private readonly deps: DapiServerDeps;
private readonly renderer = new RendererCalls();
private readonly sessions = new Set<McpServer>();
+ private readonly http: DapiHttpServer;
private server: Server | null = null;
private connected = false;
+ private instructionsText: string | null = null;
constructor(deps: DapiServerDeps) {
this.deps = deps;
@@ -43,6 +53,18 @@ export class DapiServer {
throw new Error(`Main-process tool "${tool.name}" has no handler`);
}
}
+ this.http = new DapiHttpServer({
+ host: MCP_HOST,
+ port: MCP_PORT,
+ path: MCP_PATH,
+ createSession: () => this.createSession(),
+ onFirstConnection: () => this.firstConnection(),
+ });
+ }
+
+ /** The URL agents register. */
+ get url(): string {
+ return this.http.url;
}
start(): void {
@@ -54,9 +76,13 @@ export class DapiServer {
// Linux shares /tmp between users; the socket file's mode is the auth.
if (process.platform !== "win32") chmodSync(SOCKET_PATH, 0o600);
});
+ // A taken port is the one way this fails; the socket keeps the CLI and
+ // `dapi mcp` working meanwhile, so it is logged, not fatal.
+ this.http.start().catch((error: Error) => console.error(`[dapi] cannot serve MCP at ${this.url}: ${error.message}`));
}
stop(): void {
+ this.http.stop();
for (const session of this.sessions) void session.close();
this.sessions.clear();
this.server?.close();
@@ -64,14 +90,15 @@ export class DapiServer {
removeStaleSocket();
}
- private async accept(socket: Socket): Promise<void> {
- if (!this.connected) {
- this.connected = true;
- this.deps.onFirstConnection();
- }
+ private firstConnection(): void {
+ if (this.connected) return;
+ this.connected = true;
+ this.deps.onFirstConnection();
+ }
- const session = new McpServer({ name: "diffusion-studio", version: this.deps.version });
- for (const tool of tools) this.register(session, tool);
+ private async accept(socket: Socket): Promise<void> {
+ this.firstConnection();
+ const session = this.createSession();
this.sessions.add(session);
session.server.onclose = () => this.sessions.delete(session);
try {
@@ -83,6 +110,21 @@ export class DapiServer {
}
}
+ /** One MCP server over the whole catalog, plus the docs and live state as resources. */
+ private createSession(): McpServer {
+ const knowledge = {
+ docsDir: this.deps.docsDir,
+ skillsDir: this.deps.skillsDir,
+ logs: this.deps.logs,
+ context: (signal: AbortSignal) => this.renderer.call("context", {}, signal) as Promise<ToolOutput<"context">>,
+ };
+ this.instructionsText ??= instructions(knowledge);
+ const session = new McpServer({ name: "diffusion-studio", version: this.deps.version }, { instructions: this.instructionsText });
+ for (const tool of tools) this.register(session, tool);
+ registerResources(session, knowledge);
+ return session;
+ }
+
private register(session: McpServer, tool: GenericTool): void {
session.registerTool(
tool.name,
diff --git a/apps/desktop/src/main-channels.ts b/apps/desktop/src/main-channels.ts
index fd88916d..3e8968c5 100644
--- a/apps/desktop/src/main-channels.ts
+++ b/apps/desktop/src/main-channels.ts
@@ -33,8 +33,8 @@ export const MAIN_CHANNELS = {
CHECKOUT_GET_PENDING_CALLBACK: "checkout:get-pending-callback",
CLI_IS_INSTALLED: "cli:is-installed",
CLI_INSTALL: "cli:install",
- SKILLS_IS_INSTALLED: "skills:is-installed",
- SKILLS_INSTALL: "skills:install",
+ MCP_IS_REGISTERED: "mcp:is-registered",
+ MCP_REGISTER: "mcp:register",
WINDOW_IS_FULLSCREEN: "window:is-fullscreen",
WINDOW_CAPTURE: "window:capture",
FILE_TRANSFER: "file:transfer",
@@ -112,9 +112,12 @@ export type CliInstallResult =
| { status: "cancelled" }
| { status: "error"; error: string };
-// Outcome of symlinking the bundled skills into the agent skill directories.
-export type SkillsInstallResult =
- | { status: "installed" }
+// Outcome of registering the app's MCP server with the agents on this
+// machine. `agents` names the configs written; `url` is the HTTP endpoint
+// most of them got, `command` the stdio proxy the rest run (null when this
+// build has no dapi binary).
+export type McpRegisterResult =
+ | { status: "registered"; agents: string[]; url: string; command: string | null }
| { status: "error"; error: string };
export type { SourceEdit, WriteResult };
@@ -133,8 +136,8 @@ export type MainRequestMap = {
[MAIN_CHANNELS.CHECKOUT_GET_PENDING_CALLBACK]: { request: void; response: string | null };
[MAIN_CHANNELS.CLI_IS_INSTALLED]: { request: void; response: boolean };
[MAIN_CHANNELS.CLI_INSTALL]: { request: void; response: CliInstallResult };
- [MAIN_CHANNELS.SKILLS_IS_INSTALLED]: { request: void; response: boolean };
- [MAIN_CHANNELS.SKILLS_INSTALL]: { request: void; response: SkillsInstallResult };
+ [MAIN_CHANNELS.MCP_IS_REGISTERED]: { request: void; response: boolean };
+ [MAIN_CHANNELS.MCP_REGISTER]: { request: void; response: McpRegisterResult };
[MAIN_CHANNELS.WINDOW_IS_FULLSCREEN]: { request: void; response: boolean };
[MAIN_CHANNELS.WINDOW_CAPTURE]: { request: void; response: ScreenshotResult };
[MAIN_CHANNELS.FILE_TRANSFER]: {
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index 23039413..a0421d5a 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -4,6 +4,7 @@
import { app, BrowserWindow, nativeImage, session, shell } from "electron";
import { dirname, join } from "node:path";
+import { existsSync } from "node:fs";
import { mkdir, open, unlink } from "node:fs/promises";
import { randomUUID } from "node:crypto";
import type { FileHandle } from "node:fs/promises";
@@ -11,7 +12,7 @@ import { updateElectronApp } from "update-electron-app";
import { DapiServer } from "./dapi/server";
import { enableHeadless, isHeadless } from "./headless";
import { installCli, isCliInstalled } from "./cli-install";
-import { healSkillsLinks, installSkills, isSkillsInstalled } from "./skills-install";
+import { healMcpRegistrations, isMcpRegistered, registerMcp } from "./mcp-install";
import { trackInstall } from "./analytics";
import { setupAppMenu } from "./menu";
import { mainBridge } from "./main-manager";
@@ -98,11 +99,21 @@ const pendingDeepLinks = new Map<DeepLinkChannel, string>();
const LOG_BUFFER_MAX = 2000;
const logBuffer: LogEntry[] = [];
+// A folder staged into the app bundle by scripts/stage-*.mjs (Contents/
+// Resources/<name> when packaged, apps/desktop/<name> in dev), or null when
+// it has not been staged.
+function stagedResource(name: string): string | null {
+ const dir = app.isPackaged ? join(process.resourcesPath, name) : join(app.getAppPath(), name);
+ return existsSync(dir) ? dir : null;
+}
+
// The MCP server agents and the dapi CLI talk to. Started once the app is
// ready; the first connection switches the UI into headless mode.
const dapi = new DapiServer({
version: app.getVersion(),
logs: () => logBuffer,
+ docsDir: stagedResource("docs"),
+ skillsDir: stagedResource("skills"),
onFirstConnection() {
enableHeadless();
if (mainWindow && !mainWindow.isDestroyed()) {
@@ -276,8 +287,8 @@ if (app.requestSingleInstanceLock()) {
mainBridge.handle(MAIN_CHANNELS.APP_SHOW_IN_FOLDER, ({ path }) => shell.showItemInFolder(path));
mainBridge.handle(MAIN_CHANNELS.CLI_IS_INSTALLED, () => isCliInstalled());
mainBridge.handle(MAIN_CHANNELS.CLI_INSTALL, () => installCli());
- mainBridge.handle(MAIN_CHANNELS.SKILLS_IS_INSTALLED, () => isSkillsInstalled());
- mainBridge.handle(MAIN_CHANNELS.SKILLS_INSTALL, () => installSkills());
+ mainBridge.handle(MAIN_CHANNELS.MCP_IS_REGISTERED, () => isMcpRegistered());
+ mainBridge.handle(MAIN_CHANNELS.MCP_REGISTER, () => registerMcp());
mainBridge.handle(MAIN_CHANNELS.AUTH_GET_PENDING_CALLBACK, () =>
takePendingDeepLink(MAIN_CHANNELS.AUTH_CALLBACK),
);
@@ -376,7 +387,7 @@ if (app.requestSingleInstanceLock()) {
if (url) deliverDeepLink(url);
dapi.start();
- healSkillsLinks();
+ healMcpRegistrations();
trackInstall();
createWindow(!isHiddenLaunch(process.argv));
});
diff --git a/apps/desktop/src/mcp-config.test.ts b/apps/desktop/src/mcp-config.test.ts
new file mode 100644
index 00000000..470dc2f6
--- /dev/null
+++ b/apps/desktop/src/mcp-config.test.ts
@@ -0,0 +1,111 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+import { describe, expect, it } from "vitest";
+import { AGENT_TARGETS, readServer, upsertServer } from "./mcp-config";
+
+const spec = {
+ url: "http://127.0.0.1:3274/mcp",
+ command: "/Applications/Diffusion Studio.app/Contents/Resources/cli/bin/dapi",
+ args: ["mcp"],
+};
+
+const target = (label: string) => {
+ const found = AGENT_TARGETS.find((t) => t.label === label);
+ if (!found) throw new Error(label);
+ return found;
+};
+
+describe("per-agent entries", () => {
+ it("spells the URL the way each agent expects", () => {
+ expect(target("Claude Code").entry(spec)).toEqual({ type: "http", url: spec.url });
+ expect(target("Cursor").entry(spec)).toEqual({ url: spec.url });
+ expect(target("Codex").entry(spec)).toEqual({ url: spec.url });
+ expect(target("Gemini CLI").entry(spec)).toEqual({ httpUrl: spec.url });
+ expect(target("Windsurf").entry(spec)).toEqual({ serverUrl: spec.url });
+ });
+
+ it("gives Claude Desktop the stdio proxy", () => {
+ expect(target("Claude Desktop").entry(spec)).toEqual({ command: spec.command, args: ["mcp"] });
+ });
+});
+
+describe("json configs", () => {
+ it("creates the file from nothing", () => {
+ const text = upsertServer(null, "json", { type: "http", url: spec.url });
+ expect(JSON.parse(text)).toEqual({ mcpServers: { dapi: { type: "http", url: spec.url } } });
+ expect(text.endsWith("\n")).toBe(true);
+ });
+
+ it("keeps other servers and unrelated keys", () => {
+ const before = JSON.stringify({
+ numStartups: 12,
+ mcpServers: { other: { command: "x", args: [] } },
+ projects: { "/a": { allowedTools: [] } },
+ });
+ const after = JSON.parse(upsertServer(before, "json", { url: spec.url }));
+ expect(after.numStartups).toBe(12);
+ expect(after.projects).toEqual({ "/a": { allowedTools: [] } });
+ expect(after.mcpServers.other).toEqual({ command: "x", args: [] });
+ expect(after.mcpServers.dapi).toEqual({ url: spec.url });
+ });
+
+ it("replaces a stdio entry with a URL entry, and reads either", () => {
+ const before = upsertServer(null, "json", { command: "/old/dapi", args: ["mcp"] });
+ expect(readServer(before, "json")).toEqual({ command: "/old/dapi" });
+ const after = upsertServer(before, "json", { type: "http", url: spec.url });
+ expect(readServer(after, "json")).toEqual({ url: spec.url });
+ expect(JSON.parse(after).mcpServers.dapi.command).toBeUndefined();
+ });
+
+ it("reads the URL under each agent's key", () => {
+ for (const key of ["url", "httpUrl", "serverUrl"]) {
+ expect(readServer(upsertServer(null, "json", { [key]: spec.url }), "json")).toEqual({ url: spec.url });
+ }
+ });
+
+ it("refuses to overwrite a file it cannot parse", () => {
+ expect(() => upsertServer("{ not json", "json", { url: spec.url })).toThrow();
+ expect(() => upsertServer("[1, 2]", "json", { url: spec.url })).toThrow();
+ expect(readServer("{ not json", "json")).toBeNull();
+ });
+
+ it("treats an empty file as no config", () => {
+ expect(readServer("", "json")).toBeNull();
+ expect(JSON.parse(upsertServer(" \n", "json", { url: spec.url }))).toEqual({ mcpServers: { dapi: { url: spec.url } } });
+ });
+});
+
+describe("toml configs (codex)", () => {
+ it("appends a table to an existing config", () => {
+ const before = 'model = "o3"\n\n[mcp_servers.other]\ncommand = "x"\n';
+ const after = upsertServer(before, "toml", { url: spec.url });
+ expect(after).toBe('model = "o3"\n\n[mcp_servers.other]\ncommand = "x"\n\n[mcp_servers.dapi]\nurl = "http://127.0.0.1:3274/mcp"\n');
+ expect(readServer(after, "toml")).toEqual({ url: spec.url });
+ });
+
+ it("replaces our table in place and leaves the next one alone", () => {
+ const before = '[mcp_servers.dapi]\ncommand = "/old/dapi"\nargs = ["mcp"]\n\n[mcp_servers.other]\ncommand = "x"\n';
+ expect(readServer(before, "toml")).toEqual({ command: "/old/dapi" });
+ const after = upsertServer(before, "toml", { url: spec.url });
+ expect(after).toBe('[mcp_servers.dapi]\nurl = "http://127.0.0.1:3274/mcp"\n[mcp_servers.other]\ncommand = "x"\n');
+ expect(readServer(after, "toml")).toEqual({ url: spec.url });
+ });
+
+ it("starts a file from nothing", () => {
+ const text = upsertServer(null, "toml", { url: spec.url });
+ expect(text).toBe('[mcp_servers.dapi]\nurl = "http://127.0.0.1:3274/mcp"\n');
+ });
+
+ it("escapes quotes and backslashes in stdio paths", () => {
+ const odd = { command: 'C:\\Apps\\"Diffusion"\\dapi', args: ["mcp"] };
+ const text = upsertServer(null, "toml", odd);
+ expect(text).toContain('command = "C:\\\\Apps\\\\\\"Diffusion\\"\\\\dapi"');
+ expect(readServer(text, "toml")).toEqual({ command: odd.command });
+ });
+
+ it("reads nothing from a config without our table", () => {
+ expect(readServer('model = "o3"\n', "toml")).toBeNull();
+ });
+});
diff --git a/apps/desktop/src/mcp-config.ts b/apps/desktop/src/mcp-config.ts
new file mode 100644
index 00000000..b910c5e3
--- /dev/null
+++ b/apps/desktop/src/mcp-config.ts
@@ -0,0 +1,161 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// How the app's MCP server is written into each agent's config, as pure
+// text transforms: no file system, no Electron, so the merge rules are
+// testable. `mcp-install.ts` decides which files and does the I/O.
+
+/**
+ * The two ways to reach the app. Agents that speak Streamable HTTP get the
+ * URL, which is the same on every machine; the rest get the bundled `dapi`
+ * binary in stdio proxy mode.
+ */
+export type McpServerSpec = { url: string; command: string; args: string[] };
+
+/** The key our entry lives under in every agent's server map. */
+export const SERVER_NAME = "dapi";
+
+/** One agent's config entry: what its file format spells a server as. */
+export type ServerEntry = Record<string, string | string[]>;
+
+export type AgentTarget = {
+ /** Human name, for the result dialog. */
+ label: string;
+ /** Home-relative path whose presence means the agent is set up on this machine. */
+ marker: string;
+ /** Home-relative path of the config file our entry goes into. */
+ config: string;
+ format: "json" | "toml";
+ /** The entry for this agent: which transport it gets, under the keys its format uses. */
+ entry(spec: McpServerSpec): ServerEntry;
+};
+
+const http = (key: string, extra: ServerEntry = {}) => (spec: McpServerSpec): ServerEntry => ({ ...extra, [key]: spec.url });
+const stdio = (spec: McpServerSpec): ServerEntry => ({ command: spec.command, args: [...spec.args] });
+
+// Agents whose MCP config we know how to write. Claude Code's user scope is
+// the top-level `mcpServers` of ~/.claude.json, the same file `claude mcp
+// add --scope user` edits. Claude Desktop's file takes stdio commands only,
+// so it gets the proxy.
+export const AGENT_TARGETS: readonly AgentTarget[] = [
+ { label: "Claude Code", marker: ".claude", config: ".claude.json", format: "json", entry: http("url", { type: "http" }) },
+ { label: "Codex", marker: ".codex", config: ".codex/config.toml", format: "toml", entry: http("url") },
+ { label: "Cursor", marker: ".cursor", config: ".cursor/mcp.json", format: "json", entry: http("url") },
+ { label: "Gemini CLI", marker: ".gemini", config: ".gemini/settings.json", format: "json", entry: http("httpUrl") },
+ { label: "Windsurf", marker: ".codeium/windsurf", config: ".codeium/windsurf/mcp_config.json", format: "json", entry: http("serverUrl") },
+ {
+ label: "Claude Desktop",
+ marker: "Library/Application Support/Claude",
+ config: "Library/Application Support/Claude/claude_desktop_config.json",
+ format: "json",
+ entry: stdio,
+ },
+];
+
+/** The agent a machine with none of the above still gets set up for. */
+export const FALLBACK_TARGET = AGENT_TARGETS[0];
+
+/**
+ * The config with our entry set, leaving everything else as it was. `text`
+ * is the file's current content, or null when there is none yet. Throws
+ * when the file cannot be parsed: a config we cannot read is not one we
+ * should overwrite.
+ */
+export function upsertServer(text: string | null, format: AgentTarget["format"], entry: ServerEntry): string {
+ return format === "toml" ? upsertToml(text, entry) : upsertJson(text, entry);
+}
+
+/** Where our entry currently points, whatever keys the agent spells it with; null when there is none. */
+export type Registered = { url?: string; command?: string };
+
+export function readServer(text: string | null, format: AgentTarget["format"]): Registered | null {
+ if (text === null) return null;
+ const entry = format === "toml" ? readToml(text) : readJson(text);
+ if (!entry) return null;
+ const url = entry.url ?? entry.httpUrl ?? entry.serverUrl;
+ const command = entry.command;
+ if (typeof url !== "string" && typeof command !== "string") return null;
+ return {
+ ...(typeof url === "string" ? { url } : {}),
+ ...(typeof command === "string" ? { command } : {}),
+ };
+}
+
+// --- JSON ------------------------------------------------------------------
+
+type JsonConfig = { mcpServers?: Record<string, unknown> } & Record<string, unknown>;
+
+function parseJson(text: string | null): JsonConfig {
+ if (text === null || text.trim() === "") return {};
+ const parsed: unknown = JSON.parse(text);
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+ throw new Error("expected a JSON object at the top level");
+ }
+ return parsed as JsonConfig;
+}
+
+function upsertJson(text: string | null, entry: ServerEntry): string {
+ const config = parseJson(text);
+ const servers = typeof config.mcpServers === "object" && config.mcpServers !== null ? config.mcpServers : {};
+ config.mcpServers = { ...servers, [SERVER_NAME]: entry };
+ return `${JSON.stringify(config, null, 2)}\n`;
+}
+
+function readJson(text: string): Record<string, unknown> | null {
+ let config: JsonConfig;
+ try {
+ config = parseJson(text);
+ } catch {
+ return null;
+ }
+ const entry = config.mcpServers?.[SERVER_NAME];
+ return typeof entry === "object" && entry !== null ? (entry as Record<string, unknown>) : null;
+}
+
+// --- TOML (Codex) ----------------------------------------------------------
+
+// Our table, from its header up to the next table header or the end. A
+// header line is `[...]` at column 0; indented or commented ones are not.
+const TOML_TABLE = new RegExp(String.raw`^\[mcp_servers\.${SERVER_NAME}\][^\n]*\n(?:(?!\[)[^\n]*\n?)*`, "m");
+
+function tomlString(value: string): string {
+ return `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function tomlValue(value: string | string[]): string {
+ return Array.isArray(value) ? `[${value.map(tomlString).join(", ")}]` : tomlString(value);
+}
+
+function tomlTable(entry: ServerEntry): string {
+ const lines = Object.entries(entry).map(([key, value]) => `${key} = ${tomlValue(value)}`);
+ return [`[mcp_servers.${SERVER_NAME}]`, ...lines, ""].join("\n");
+}
+
+function upsertToml(text: string | null, entry: ServerEntry): string {
+ const current = text ?? "";
+ const table = tomlTable(entry);
+ if (TOML_TABLE.test(current)) return current.replace(TOML_TABLE, table);
+ const separator = current === "" || current.endsWith("\n\n") ? "" : current.endsWith("\n") ? "\n" : "\n\n";
+ return `${current}${separator}${table}`;
+}
+
+function readToml(text: string): Record<string, unknown> | null {
+ const table = text.match(TOML_TABLE)?.[0];
+ if (!table) return null;
+ const entry: Record<string, unknown> = {};
+ for (const line of table.split("\n").slice(1)) {
+ const scalar = line.match(/^(\w+)\s*=\s*"((?:[^"\\]|\\.)*)"\s*$/);
+ if (scalar) {
+ entry[scalar[1]] = untomlString(scalar[2]);
+ continue;
+ }
+ const list = line.match(/^(\w+)\s*=\s*\[([^\]]*)\]\s*$/);
+ if (list) entry[list[1]] = [...list[2].matchAll(/"((?:[^"\\]|\\.)*)"/g)].map((m) => untomlString(m[1]));
+ }
+ return entry;
+}
+
+function untomlString(value: string): string {
+ return value.replaceAll('\\"', '"').replaceAll("\\\\", "\\");
+}
diff --git a/apps/desktop/src/mcp-install.ts b/apps/desktop/src/mcp-install.ts
new file mode 100644
index 00000000..b37d8400
--- /dev/null
+++ b/apps/desktop/src/mcp-install.ts
@@ -0,0 +1,131 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
+
+// Registers the app's MCP server with the agents on this machine: the fixed
+// loopback URL for agents that speak HTTP, the bundled `dapi mcp` proxy for
+// the rest. No PATH symlink and no admin prompt — the counterpart of the
+// shell install in `cli-install.ts`, which stays for people who type `dapi`.
+
+import { app } from "electron";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
+import { AGENT_TARGETS, FALLBACK_TARGET, readServer, upsertServer } from "./mcp-config";
+
+import type { AgentTarget, McpServerSpec } from "./mcp-config";
+import type { McpRegisterResult } from "./main-channels";
+
+// The dev workflow links the workspace build into Homebrew's bin
+// (`symlink:create` in apps/cli); that is the binary a dev build registers.
+const DEV_BINARY = "/opt/homebrew/bin/dapi";
+
+/** The bundled `dapi` binary, or null when none is available (an unstaged dev build). */
+export function dapiBinary(): string | null {
+ const command = app.isPackaged ? join(process.resourcesPath, "cli", "bin", "dapi") : DEV_BINARY;
+ return existsSync(command) ? command : null;
+}
+
+function spec(): McpServerSpec {
+ return { url: MCP_URL, command: dapiBinary() ?? "", args: ["mcp"] };
+}
+
+function configPath(target: AgentTarget): string {
+ return join(homedir(), target.config);
+}
+
+function readConfig(target: AgentTarget): string | null {
+ const path = configPath(target);
+ return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+function writeConfig(target: AgentTarget, text: string): void {
+ const path = configPath(target);
+ mkdirSync(dirname(path), { recursive: true });
+ writeFileSync(path, text);
+}
+
+function needsBinary(target: AgentTarget): boolean {
+ return "command" in target.entry({ url: MCP_URL, command: "x", args: [] });
+}
+
+// Agents present on this machine, falling back to Claude Code so a machine
+// with no agent yet still gets set up for the primary one.
+function targetAgents(): AgentTarget[] {
+ const home = homedir();
+ const present = AGENT_TARGETS.filter((target) => existsSync(join(home, target.marker)));
+ return present.length > 0 ? present : [FALLBACK_TARGET];
+}
+
+/** True when at least one agent's config points at this app. */
+export function isMcpRegistered(): boolean {
+ const current = spec();
+ return AGENT_TARGETS.some((target) => {
+ const registered = readServer(readConfig(target), target.format);
+ return registered?.url === current.url || (current.command !== "" && registered?.command === current.command);
+ });
+}
+
+export function registerMcp(): McpRegisterResult {
+ // A quarantined first launch runs from a translocated read-only mount whose
+ // path won't survive the next launch — registering it would dangle.
+ if (app.isPackaged && process.resourcesPath.includes("/AppTranslocation/")) {
+ return {
+ status: "error",
+ error: "Move Diffusion Studio to the Applications folder and relaunch it, then try again.",
+ };
+ }
+ const current = spec();
+ const agents: string[] = [];
+ const failures: string[] = [];
+ for (const target of targetAgents()) {
+ if (needsBinary(target) && current.command === "") {
+ failures.push(`${target.label}: needs the dapi binary, which this build does not have`);
+ continue;
+ }
+ try {
+ writeConfig(target, upsertServer(readConfig(target), target.format, target.entry(current)));
+ agents.push(target.label);
+ } catch (e) {
+ failures.push(`${target.label} (${target.config}): ${(e as Error).message}`);
+ }
+ }
+ if (agents.length === 0) {
+ return { status: "error", error: `Could not write any agent config:\n${failures.join("\n")}` };
+ }
+ return {
+ status: "registered",
+ agents,
+ url: current.url,
+ command: current.command === "" ? null : `${current.command} ${current.args.join(" ")}`,
+ };
+}
+
+/**
+ * Launch-time self-heal. Two cases: an entry that still runs the stdio proxy
+ * from a bundle that moved (or was translocated when it was written), and an
+ * entry written before the app served HTTP, which the agent could be using
+ * the URL for instead. Both are rewritten to what `registerMcp` would write
+ * today. Entries the user wrote by hand for something else are left alone.
+ */
+export function healMcpRegistrations(): void {
+ if (!app.isPackaged) return;
+ const current = spec();
+ if (current.command === "" || current.command.includes("/AppTranslocation/")) return;
+
+ for (const target of AGENT_TARGETS) {
+ const text = readConfig(target);
+ const registered = readServer(text, target.format);
+ if (!registered?.command) continue;
+ const ours = registered.command.includes("Diffusion Studio") || registered.command.includes("/AppTranslocation/");
+ if (!ours) continue;
+ const entry = target.entry(current);
+ if (registered.command === entry.command) continue;
+ try {
+ writeConfig(target, upsertServer(text, target.format, entry));
+ } catch {
+ // best effort — the connect button remains as a manual fix
+ }
+ }
+}
diff --git a/apps/desktop/src/menu.ts b/apps/desktop/src/menu.ts
index 31bef6aa..3893344a 100644
--- a/apps/desktop/src/menu.ts
+++ b/apps/desktop/src/menu.ts
@@ -6,6 +6,27 @@ import { app, dialog, Menu } from "electron";
import type { MenuItemConstructorOptions } from "electron";
import { CLI_LINK_PATH, installCli } from "./cli-install";
+import { registerMcp } from "./mcp-install";
+
+async function registerMcpFromMenu() {
+ const result = registerMcp();
+ if (result.status === "registered") {
+ await dialog.showMessageBox({
+ type: "info",
+ message: "Diffusion Studio is registered as an MCP server.",
+ detail: [
+ `Connected: ${result.agents.join(", ")}. Restart the agent to pick it up.`,
+ `Any other agent can use the URL ${result.url}${result.command ? `, or run "${result.command}" over stdio` : ""}.`,
+ ].join("\n\n"),
+ });
+ } else {
+ await dialog.showMessageBox({
+ type: "error",
+ message: "Could not register the MCP server.",
+ detail: result.error,
+ });
+ }
+}
async function installCliFromMenu() {
const result = await installCli();
@@ -34,6 +55,10 @@ export function setupAppMenu() {
submenu: [
{ role: "about" },
{ type: "separator" },
+ {
+ label: "Connect Agents (MCP)…",
+ click: registerMcpFromMenu,
+ },
{
label: "Install dapi Command Line Tool…",
enabled: app.isPackaged,
diff --git a/apps/desktop/src/projects.ts b/apps/desktop/src/projects.ts
index d7303b25..ecfd6086 100644
--- a/apps/desktop/src/projects.ts
+++ b/apps/desktop/src/projects.ts
@@ -5,10 +5,11 @@
import { app, dialog, shell, type BrowserWindow } from "electron";
import { execFile } from "node:child_process";
import { watch, type FSWatcher } from "node:fs";
-import { cp, mkdir, readdir, readFile, realpath, rename, rm, stat, writeFile } from "node:fs/promises";
+import { cp, mkdir, readdir, readFile, realpath, rename, rm, rmdir, stat, writeFile } from "node:fs/promises";
import { createRequire } from "node:module";
import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { nanoid } from "nanoid";
+import { MCP_URL } from "@diffusionstudio/dapi/socket";
import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
import type { PluginItem, TransformOptions } from "@babel/core";
@@ -530,7 +531,7 @@ const TSCONFIG = `{
}
`;
-/** What a project folder produces but should not check in: installs, derived data (thumbnails, waveforms), and the app-owned docs. */
+/** What a project folder produces but should not check in: installs, derived data (thumbnails, waveforms), and the app-owned folder. */
const GITIGNORE = `node_modules/
cache/
.diffusion/
@@ -574,8 +575,7 @@ on the canvas.
| \`assets.yml\` | The asset library: for every asset its library path, where its bytes are, and what it was found to be. Written by the app; hand edits are read on the next load. |
| \`assets/\` | The library's files: put one here and it is taken in while the app watches, and the app writes its own here too — generations under \`assets/generated/\`. Media imported through the app is linked where it lies instead, never copied. |
| \`cache/\` | Derived data (thumbnails, waveforms). Disposable, and not checked in. |
-| \`AGENTS.md\` | The agent entry point: what to read in \`.diffusion/docs/\` and how to work here. |
-| \`.diffusion/\` | App-owned. \`docs/\` is the authoring reference and examples for the installed app version; the app regenerates it, and it is not checked in. |
+| \`AGENTS.md\` | The agent entry point: how to connect to the app, whose MCP server carries the authoring reference, and how to work here. |
## Authoring
@@ -670,10 +670,10 @@ All of them talk to the running app, except \`fonts\` and \`fetch\`.
/**
* The agent entry point, written once like the README: the file coding agents
* load without being asked, and therefore the one place a project is reliably
- * discovered from. Loaded into context whole, so it stays a thin index into
- * `.diffusion/docs` rather than the docs themselves — and being the author's
- * file after the first write, an agent can append project conventions to it
- * while the paths it points at stay put.
+ * discovered from. It points at the app rather than carrying docs of its own:
+ * the reference lives in the app's MCP server, so it is always the installed
+ * version's, and being the author's file after the first write, an agent can
+ * append project conventions to it while the pointer stays put.
*/
const AGENTS = `# Authoring this project
@@ -684,30 +684,33 @@ canvas. The source is the document in both directions: saving recompiles and
remounts the project, and edits made in the app land back in the JSX as props
on the element they were authored as.
-## Docs
+## Connect to the app
-\`.diffusion/docs/\` holds the authoring reference and runnable examples for
-the installed app version. The app regenerates it on version changes: read it,
-never edit it, and trust it over memory.
+The authoring reference lives in the app, not in this folder, so it is always
+the installed version's. Connect to the app's MCP server at
+\`${MCP_URL}\` — \`dapi open <this folder>\` launches the app and opens the
+project, or launch the app and open it there. The server's instructions say
+how to work; its resources are the docs; its tools are the API.
| Read | For |
| ---- | --- |
-| \`.diffusion/docs/reference/jsx/README.md\` | The JSX contract — elements, props, pipeline. Start here. |
-| \`.diffusion/docs/reference/jsx/timing.md\` | \`start\`/\`end\`/\`sourceIn\`/\`sourceOut\`, and the time formats. |
-| \`.diffusion/docs/reference/jsx/generate.md\` | Declaring AI-generated assets (\`generate.*\`). |
-| \`.diffusion/docs/reference/jsx/variables.md\` | \`@inspect\` variables: annotated consts as live inspector controls. |
-| \`.diffusion/docs/reference/README.md\` | Every dapi command, its options and its output. |
-| \`.diffusion/docs/examples/\` | Complete compositions, basics through shaders. |
+| \`dapi://docs/reference/jsx/README.md\` | The JSX contract — elements, props, pipeline. Start here. |
+| \`dapi://docs/reference/jsx/timing.md\` | \`start\`/\`end\`/\`sourceIn\`/\`sourceOut\`, and the time formats. |
+| \`dapi://docs/reference/jsx/generate.md\` | Declaring AI-generated assets (\`generate.*\`). |
+| \`dapi://docs/reference/jsx/variables.md\` | \`@inspect\` variables: annotated consts as live inspector controls. |
+| \`dapi://docs/reference/README.md\` | Every tool, its arguments and its output. |
+| \`dapi://docs/examples/\` | Complete compositions, basics through shaders. |
+| \`dapi://context\` | What the app has open, where its playhead sits, and where generations stand. |
+
+Without MCP, the same tools are the \`dapi\` command line, with the same
+descriptions under \`--help\`. Every command is an npm script here:
+\`npm run\` lists them, \`npm run <name> -- <args>\` runs one.
## Working here
-- Every dapi command is an npm script: \`npm run\` lists them, and
- \`npm run <name> -- <args>\` runs one.
-- \`npm run context\` reports what the app has open, where its playhead sits,
- and where generations stand.
-- Verify visually with \`npm run capture -- <sceneId>\`: it renders the
- scene's frames exactly as an export encodes them. Do not export a video to
- check work.
+- Verify visually with the \`capture\` tool (\`npm run capture -- <sceneId>\`):
+ it renders the scene's frames exactly as an export encodes them. Do not
+ export a video to check work.
- Position and size are explicit, in pixels. There is no layout pass and no CSS.
- A composition you author from scratch marks one scene \`active\` and gives
\`<stage>\` a \`camera\` framing it, or the project opens on an empty timeline
@@ -717,59 +720,28 @@ never edit it, and trust it over memory.
`;
// ---------------------------------------------------------------------------
-// Authoring docs
+// The app-owned folder
/**
- * The project-relative folder the app owns outright. Everything else the
- * scaffold writes is written once and is the author's from then on; this
- * folder is regenerated wholesale, which is why it gets a namespace of its
- * own instead of files among the author's.
+ * The project-relative folder the app owns outright, ignored by git and by
+ * the project watcher. Earlier versions copied the authoring docs into it;
+ * the docs now live in the app's MCP server, so the folder is only cleared.
*/
const APP_DIR = ".diffusion";
-/** Repo housekeeping that has no business in a project's copy of the docs. */
-const DOCS_SKIP = new Set(["tsconfig.json", ".DS_Store"]);
-
-/**
- * Where the shipped docs come from: staged app resources when packaged (see
- * scripts/stage-docs.mjs), the repo checkout in development. Both lay the
- * tree out as the repo does — `reference/` beside `examples/` — so the
- * relative links between the pages keep resolving after the copy.
- */
-function docsSources(): string {
- return app.isPackaged ? join(process.resourcesPath, "docs") : join(app.getAppPath(), "..", "..");
-}
-
/**
- * Copies the authoring reference and examples into `.diffusion/docs`, stamped
- * with the app version and refreshed whenever the stamp stops matching. Docs
- * that outlive the app they sit next to would lie about it, so unlike the
- * rest of the scaffold this is rewritten, not written once. The stamp only
- * moves with a release; in development a refresh is forced by deleting the
- * folder. This runs on every compile, so the up-to-date case is one read.
+ * Removes the docs copy earlier versions kept in `.diffusion/docs`. They
+ * would describe an app that is no longer installed, and an agent that finds
+ * them would trust them over the server. Best-effort: nothing depends on it.
*/
-async function syncDocs(dir: string): Promise<void> {
- const docsDir = join(dir, APP_DIR, "docs");
- const stampFile = join(docsDir, ".version");
- const version = app.getVersion();
+async function removeLegacyDocs(dir: string): Promise<void> {
+ const appDir = join(dir, APP_DIR);
+ await rm(join(appDir, "docs"), { recursive: true, force: true });
try {
- if ((await readFile(stampFile, "utf8")).trim() === version) return;
+ await rmdir(appDir);
} catch {
- // No stamp: never synced, or a copy that did not finish. Full copy below.
+ // Not empty, or never there.
}
- const source = docsSources();
- await rm(docsDir, { recursive: true, force: true });
- await mkdir(docsDir, { recursive: true });
- for (const name of ["reference", "examples"]) {
- const src = join(source, name);
- if (!(await exists(src))) continue;
- await cp(src, join(docsDir, name), {
- recursive: true,
- filter: (path) => !DOCS_SKIP.has(basename(path)),
- });
- }
- // Written last, so a copy that died refuses to pass for a synced one.
- await writeFile(stampFile, version + "\n", "utf8");
}
async function writeIfMissing(dir: string, name: string, content: string): Promise<void> {
@@ -824,13 +796,7 @@ export async function scaffold(dir: string, displayName = basename(dir)): Promis
await writeIfMissing(dir, "README.md", readme(displayName));
await writeIfMissing(dir, "AGENTS.md", AGENTS);
- // The docs are auxiliary: a project must still open and compile without
- // them, so a failed sync is a warning rather than a failed scaffold.
- try {
- await syncDocs(dir);
- } catch (error) {
- console.warn(`projects: could not sync the authoring docs into ${dir}`, error);
- }
+ await removeLegacyDocs(dir).catch(() => {});
if (!(await exists(join(dir, MANIFEST_FILE)))) {
await writeManifest(dir, EMPTY_MANIFEST);
diff --git a/apps/desktop/src/skills-install.ts b/apps/desktop/src/skills-install.ts
deleted file mode 100644
index c7cd4dd5..00000000
--- a/apps/desktop/src/skills-install.ts
+++ /dev/null
@@ -1,191 +0,0 @@
-/* This Source Code Form is subject to the terms of the Mozilla Public
- * License, v. 2.0. If a copy of the MPL was not distributed with this
- * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
-
-import { app } from "electron";
-import { existsSync, lstatSync, mkdirSync, readdirSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join } from "node:path";
-import type { SkillsInstallResult } from "./main-channels";
-
-const AGENT_SKILLS_DIRS = [
- ".adal/skills",
- ".agents/skills",
- ".aider-desk/skills",
- ".astrbot/data/skills",
- ".augment/skills",
- ".autohand/skills",
- ".bob/skills",
- ".claude/skills",
- ".clawdbot/skills",
- ".codeartsdoer/skills",
- ".codebuddy/skills",
- ".codeium/windsurf/skills",
- ".codemaker/skills",
- ".codestudio/skills",
- ".codex/skills",
- ".commandcode/skills",
- ".config/agents/skills",
- ".config/crush/skills",
- ".config/devin/skills",
- ".config/goose/skills",
- ".config/kimchi/harness/skills",
- ".config/opencode/skills",
- ".continue/skills",
- ".copilot/skills",
- ".cursor/skills",
- ".deepagents/agent/skills",
- ".factory/skills",
- ".firebender/skills",
- ".forge/skills",
- ".gemini/antigravity-cli/skills",
- ".gemini/antigravity/skills",
- ".gemini/skills",
- ".grok/skills",
- ".hermes/skills",
- ".iflow/skills",
- ".inferencesh/skills",
- ".jazz/skills",
- ".junie/skills",
- ".kilocode/skills",
- ".kiro/skills",
- ".kode/skills",
- ".lingma/skills",
- ".mcpjam/skills",
- ".minimax/skills",
- ".moltbot/skills",
- ".moxby/skills",
- ".mux/skills",
- ".neovate/skills",
- ".ona/skills",
- ".openclaw/skills",
- ".openhands/skills",
- ".pi/agent/skills",
- ".pochi/skills",
- ".posit/assistant/skills",
- ".qoder-cn/skills",
- ".qoder/skills",
- ".qwen/skills",
- ".reasonix/skills",
- ".roo/skills",
- ".rovodev/skills",
- ".snowflake/cortex/skills",
- ".tabnine/agent/skills",
- ".terramind/skills",
- ".tinycloud/skills",
- ".trae-cn/skills",
- ".trae/skills",
- ".vibe/skills",
- ".zcode/skills",
- ".zencoder/skills",
-];
-
-const FALLBACK_AGENT_DIR = ".claude/skills";
-
-function stagedSkillsDir(): string {
- return app.isPackaged
- ? join(process.resourcesPath, "skills")
- : join(app.getAppPath(), "skills");
-}
-
-function stagedSkillNames(): string[] {
- const dir = stagedSkillsDir();
- if (!existsSync(dir)) return [];
- return readdirSync(dir, { withFileTypes: true })
- .filter((entry) => entry.isDirectory())
- .map((entry) => entry.name);
-}
-
-// Agents whose config dir exists on this machine, falling back to Claude Code
-// so a machine with no agent yet still gets set up for the primary one.
-function targetAgentDirs(): string[] {
- const home = homedir();
- const present = AGENT_SKILLS_DIRS.filter((dir) => existsSync(join(home, dirname(dir))));
- return (present.length > 0 ? present : [FALLBACK_AGENT_DIR]).map((dir) => join(home, dir));
-}
-
-// `existsSync` follows symlinks, so a dangling link doesn't count.
-export function isSkillsInstalled(): boolean {
- const home = homedir();
- const marker = stagedSkillNames()[0] ?? "editor";
- return AGENT_SKILLS_DIRS.some((dir) => existsSync(join(home, dir, marker, "SKILL.md")));
-}
-
-// ln -sf semantics that never clobber real files: an existing symlink is
-// repointed (ours or the skills CLI's — the user asked to install), but a
-// real directory (a `skills add --copy` install) is left alone.
-function linkSkill(linkPath: string, target: string): void {
- try {
- if (!lstatSync(linkPath).isSymbolicLink()) return;
- rmSync(linkPath);
- } catch {
- // nothing at linkPath
- }
- symlinkSync(target, linkPath);
-}
-
-export function installSkills(): SkillsInstallResult {
- const source = stagedSkillsDir();
- // A quarantined first launch runs from a translocated read-only mount whose
- // path won't survive the next launch — linking to it would dangle.
- if (source.includes("/AppTranslocation/")) {
- return {
- status: "error",
- error: "Move Diffusion Studio to the Applications folder and relaunch it, then try again.",
- };
- }
- const skills = stagedSkillNames();
- if (skills.length === 0) {
- return {
- status: "error",
- error: app.isPackaged
- ? "The app bundle is missing its skills resources."
- : "Skills are not staged — run `npm run stage:skills` in apps/desktop.",
- };
- }
- try {
- for (const agentDir of targetAgentDirs()) {
- mkdirSync(agentDir, { recursive: true });
- for (const name of skills) {
- linkSkill(join(agentDir, name), join(source, name));
- }
- }
- return { status: "installed" };
- } catch (e) {
- return { status: "error", error: (e as Error).message };
- }
-}
-
-/**
- * Launch-time self-heal: links created by installSkills break when the app
- * moves or was translocated when they were made. Any symlink that targets a
- * Diffusion Studio bundle but not the running app's resources is repointed.
- * Links owned by the skills CLI and copied installs are left alone.
- */
-export function healSkillsLinks(): void {
- if (!app.isPackaged) return;
- const source = stagedSkillsDir();
- if (source.includes("/AppTranslocation/")) return;
-
- const home = homedir();
- for (const dir of AGENT_SKILLS_DIRS) {
- for (const name of stagedSkillNames()) {
- const linkPath = join(home, dir, name);
- let target: string;
- try {
- target = readlinkSync(linkPath);
- } catch {
- continue; // missing, or not a symlink
- }
- const ours = target.includes("Diffusion Studio") || target.includes("/AppTranslocation/");
- const current = join(source, name);
- if (!ours || target === current) continue;
- try {
- rmSync(linkPath);
- symlinkSync(current, linkPath);
- } catch {
- // best effort — the install button remains as a manual fix
- }
- }
- }
-}
diff --git a/apps/web/src/pages/onboarding.tsx b/apps/web/src/pages/onboarding.tsx
index 268dc3e9..923aea60 100644
--- a/apps/web/src/pages/onboarding.tsx
+++ b/apps/web/src/pages/onboarding.tsx
@@ -15,8 +15,6 @@ import { mainBridge } from '@/lib/ipc';
import { track } from '@/lib/analytics';
import { store } from '@/init';
-const SKILLS_COMMAND = 'npx skills add diffusionstudio/skills -g -y --all';
-
const [onboardingCompleted, setOnboardingCompleted] = createStoredSignal(
store.define('onboarding.completed', false),
);
@@ -73,33 +71,57 @@ function StepButton(props: StepButtonProps) {
}
/**
- * Post-signup screen for setting up the agent dependencies: the dapi CLI and
- * the agent skills. Shown by AuthGate until dismissed; the dismissal is
- * per-device (same store as the promo banners).
+ * Post-signup screen for connecting agents to the app: its MCP server, which
+ * carries the tools and the authoring reference, and the dapi CLI. Shown by
+ * AuthGate until dismissed; the dismissal is per-device (same store as the
+ * promo banners).
*
- * On desktop the CLI button links the bundled CLI into PATH via main (the
- * same flow as the "Install dapi Command Line Tool…" menu item); on the web,
- * where the CLI can't be installed, it offers the desktop app instead.
+ * On desktop there are two agent steps, both via main and both also in the
+ * app menu: registering the bundled `dapi mcp` with the agents on this
+ * machine, and linking the `dapi` binary into PATH for shells and scripts.
+ * On the web, where neither exists, one row offers the desktop app instead.
*/
export function OnboardingPage() {
const isDesktop = !!window.desktop;
+ const [mcpState, setMcpState] = createSignal<StepState>('todo');
const [cliState, setCliState] = createSignal<StepState>('todo');
- const [skillsState, setSkillsState] = createSignal<StepState>('todo');
onMount(async () => {
if (!isDesktop) return;
try {
- const [cli, skills] = await Promise.all([
+ const [mcp, cli] = await Promise.all([
+ mainBridge.call(MAIN_CHANNELS.MCP_IS_REGISTERED, undefined),
mainBridge.call(MAIN_CHANNELS.CLI_IS_INSTALLED, undefined),
- mainBridge.call(MAIN_CHANNELS.SKILLS_IS_INSTALLED, undefined),
]);
+ if (mcp) setMcpState('done');
if (cli) setCliState('done');
- if (skills) setSkillsState('done');
} catch {
// Can't tell — leave the install buttons available.
}
});
+ const registerMcp = async () => {
+ setMcpState('busy');
+ try {
+ const result = await mainBridge.call(MAIN_CHANNELS.MCP_REGISTER, undefined);
+ if (result.status === 'registered') {
+ track('onboarding_mcp_registered', { agents: result.agents.join(',') });
+ setMcpState('done');
+ toast('Connected', {
+ description: `Registered with ${result.agents.join(', ')}. Restart the agent to pick it up.`,
+ });
+ } else {
+ setMcpState('todo');
+ toast('Could not connect your agents', { description: result.error });
+ }
+ } catch (error) {
+ setMcpState('todo');
+ toast('Could not connect your agents', {
+ description: error instanceof Error ? error.message : 'Unknown error',
+ });
+ }
+ };
+
const installCli = async () => {
setCliState('busy');
try {
@@ -121,46 +143,14 @@ export function OnboardingPage() {
}
};
+ // The web has one row for both: the server and the CLI ship with the app.
const downloadApp = () => {
downloadDesktopApp('onboarding');
+ setMcpState('done');
setCliState('done');
};
- const copySkillsCommand = async () => {
- try {
- await navigator.clipboard.writeText(SKILLS_COMMAND);
- track('onboarding_skills_copied');
- setSkillsState('done');
- toast('Copied!', {
- description: 'Run the command in your terminal to install the agent skills.',
- });
- } catch (error) {
- toast('Failed to copy', {
- description: error instanceof Error ? error.message : 'Unknown error',
- });
- }
- };
-
- const installSkills = async () => {
- setSkillsState('busy');
- try {
- const result = await mainBridge.call(MAIN_CHANNELS.SKILLS_INSTALL, undefined);
- if (result.status === 'installed') {
- track('onboarding_skills_installed');
- setSkillsState('done');
- return;
- }
- setSkillsState('todo');
- toast('Could not install the agent skills', { description: result.error });
- } catch (error) {
- setSkillsState('todo');
- toast('Could not install the agent skills', {
- description: error instanceof Error ? error.message : 'Unknown error',
- });
- }
- };
-
- const allDone = () => cliState() === 'done' && skillsState() === 'done';
+ const allDone = () => mcpState() === 'done' && cliState() === 'done';
const finish = (event: 'onboarding_completed' | 'onboarding_skipped') => {
track(event);
@@ -187,57 +177,54 @@ export function OnboardingPage() {
</div>
<div class="flex flex-col gap-3 rounded-xl bg-accent/40 p-4">
- <SetupRow
- title="dapi CLI"
- description={
- isDesktop
- ? 'The command line tool for agents to control the editor.'
- : 'The command line tool for agents. Ships with the desktop app.'
+ <Show
+ when={isDesktop}
+ fallback={
+ <SetupRow
+ title="Desktop app"
+ description="Ships the MCP server and the dapi CLI that agents control the editor with."
+ action={
+ <StepButton
+ state={mcpState()}
+ label="Get app"
+ doneLabel="Downloaded"
+ onClick={downloadApp}
+ />
+ }
+ />
}
- action={
- isDesktop ? (
+ >
+ <SetupRow
+ title="MCP server"
+ description="Lets agents like Claude Code, Codex, and Cursor control the editor."
+ action={
<StepButton
- state={cliState()}
- label="Install"
- busyLabel="Installing…"
- doneLabel="Installed"
- onClick={installCli}
+ state={mcpState()}
+ label="Connect"
+ busyLabel="Connecting…"
+ doneLabel="Connected"
+ onClick={registerMcp}
/>
- ) : (
- <StepButton
- state={cliState()}
- label="Get app"
- doneLabel="Downloaded"
- onClick={downloadApp}
- />
- )
- }
- />
+ }
+ />
- <div class="h-px w-full bg-border" />
+ <div class="h-px w-full bg-border" />
- <SetupRow
- title="Agent skills"
- description="Instructions that help agents edit videos through dapi."
- action={
- isDesktop ? (
+ <SetupRow
+ title="dapi CLI"
+ description="The dapi command in your shell, for scripts and for agents without MCP."
+ action={
<StepButton
- state={skillsState()}
+ state={cliState()}
label="Install"
busyLabel="Installing…"
doneLabel="Installed"
- onClick={installSkills}
- />
- ) : (
- <StepButton
- state={skillsState()}
- label="Copy command"
- doneLabel="Copied"
- onClick={copySkillsCommand}
+ onClick={installCli}
/>
- )
- }
- />
+ }
+ />
+ </Show>
+
</div>
</div>
diff --git a/docs/mcp-server.md b/docs/mcp-server.md
index 94d0a1dd..dd5bb157 100644
--- a/docs/mcp-server.md
+++ b/docs/mcp-server.md
@@ -153,7 +153,9 @@ Main keeps a map of in-flight calls. Before sending it waits for the renderer to
This does mean main sees payloads, which the current design deliberately avoids. The cost is one structured-clone copy over Electron IPC per call. Frame data crosses as `Uint8Array` rather than base64 strings to keep that copy cheap; base64 encoding happens once, in main, only for the blocks that are inlined.
-**Resources.** Two things agents poll today are better as MCP resources: `dapi://context` (what `context` returns, so a client can subscribe to changes) and `dapi://logs`. The per-project authoring reference the app writes into each project, which `AGENTS.md` points at, can be listed as a resource too, so an agent can read it without knowing the path. None of this is required for the cut-over; it is listed because it is cheap once the server exists.
+**Resources and instructions.** Every session carries `instructions`: a short preamble about this server followed by the editor skill's `SKILL.md`, read from the staged skills folder, so an agent that connects knows how to work with the app without a separate skills install. The staged docs are served as resources (`dapi://docs/reference/…`, `dapi://docs/examples/…`) alongside the skill's references (`dapi://skills/editor/…`), and three live ones: `dapi://context` (what `context` returns), `dapi://logs`, and `dapi://project/AGENTS.md` for the open project. Implemented in `apps/desktop/src/dapi/knowledge.ts`.
+
+**HTTP.** Beside the socket, main serves the same sessions over Streamable HTTP at `http://127.0.0.1:3274/mcp` (`apps/desktop/src/dapi/http.ts`; the constants live in `@diffusionstudio/dapi/socket`). One MCP server per session, keyed by the transport's session id; the SDK's DNS-rebinding protection is on with the loopback hosts allowed. This is the transport agents register: a URL that is the same on every machine.
### 3. The `dapi` binary
@@ -177,6 +179,9 @@ Removed from the CLI package: `cli-client.ts`, `cli-channels.ts`, the tRPC and `
### 4. Skill and reference docs
+*Superseded on `mcp-support`: with the server carrying the skill as `instructions` and the docs as resources, the two external copies are gone. The app no longer symlinks skills into agent directories (`skills-install.ts` is deleted, with its onboarding row), and it no longer copies `reference/` and `examples/` into every project's `.diffusion/docs` (the scaffold removes a copy left by an earlier version). A project's `AGENTS.md` now points at the server: the URL, the resource URIs to read first, and the CLI as the no-MCP fallback. Only the staged copies inside the app bundle remain, and they are what the server serves, so an agent can only ever read the installed version's docs. The skill text itself still comes from the skills repo at staging time and is what step 5 updates.*
+
+
`apps/desktop/skills/editor/SKILL.md` currently says the CLI is self-describing via `--help`. It changes to name the MCP tools and to say that `tools/list` is authoritative, with a short fallback paragraph for environments without MCP (use `dapi call`). The per-command files in `reference/` become per-tool, and their option tables are generated from the catalog so they cannot drift either. `reference/README.md` loses the sentence about "every command talks to the running app over a local socket" and gains one about the server.
## Behaviour that must not change
@@ -194,7 +199,7 @@ The CLI ships inside the app bundle, so there is no compatibility window to main
1. **Catalog.** Create `packages/dapi` with the tool catalog, `Time`, and `DapiError`, plus tests. Point the renderer handlers' request and result types at it. Delete `apps/cli/src/cli-channels.ts`; `apps/cli/src/protocol.ts` keeps only the handshake and envelope types of the current transport. No behaviour change. *Landed on `mcp-support`.*
2. **Renderer.** Replace the tRPC router in `api.tsx` with one handler per tool behind a uniform `(args, ctx)` signature, validated by the catalog schemas, with an `AbortSignal` per call. Handlers return bytes; the WebSocket transport carries them as tagged base64 until step 3 replaces it. The CLI drops tRPC for a typed `call(name, input)` over the same catalog, so it keeps working at every step and its import of `apps/web` is gone. *Landed on `mcp-support`.*
3. **Main.** Add `dapi/server.ts` with catalog registration, `dapi/renderer-calls.ts` with the in-flight map, `dapi/present.ts` for files and inline images, and the `logs`, `fonts`, `fetch` and `report` handlers. The socket transport lives in `@diffusionstudio/dapi/socket`, shared with the CLI, which becomes an MCP client over it in this step so it keeps working. Delete `cli-server.ts`. *Landed on `mcp-support`; verified by an in-process client/server round trip, not yet against the running app.*
-4. **CLI.** Add `dapi mcp` and `dapi call`, and generate the wrappers from the catalog. Update `cli-install.ts` and the settings UI to offer MCP registration.
+4. **CLI.** Add `dapi mcp` and `dapi call`, and generate the wrappers from the catalog. Update `cli-install.ts` and the settings UI to offer MCP registration. *Landed on `mcp-support`, with two changes. `dapi call` was dropped. The CLI ships inside the app, so it always matches the app's catalog and every tool has a wrapper; a generic client would only duplicate what an MCP inspector on `dapi mcp` shows. `dapi mcp` is a byte pipe in `apps/cli/src/mcp-proxy.ts`; every wrapper's description and option help comes from the catalog through `apps/cli/src/help.ts`, which also validates the input locally with the same schemas, and prints the tool's structured content unchanged. And registration writes the HTTP URL, not the proxy: the app registers `http://127.0.0.1:3274/mcp` with every agent present on the machine that speaks Streamable HTTP (Claude Code, Codex, Cursor, Gemini CLI, Windsurf) and `<bundle>/Contents/Resources/cli/bin/dapi mcp` with the one that does not (Claude Desktop), each under the keys its config format uses (`apps/desktop/src/mcp-install.ts`, merge rules in `mcp-config.ts`), from the onboarding screen and a menu item. The PATH symlink install stays as its own onboarding row and menu item.*
5. **Docs.** Update the skill and regenerate `reference/`. Update the installation reference the skill points to.
6. **Cleanup.** Remove `CLI_WIRE`, the handshake types, and the `./protocol` and `./channels` exports from the CLI package.
@@ -202,7 +207,7 @@ The CLI ships inside the app bundle, so there is no compatibility window to main
- **Inline image thresholds.** Four images and about a megabyte each is a starting point. It should be tuned against what a contact sheet at the default sizes actually weighs.
- **Windows launch.** `open -a` is macOS-only today and the proposal keeps that. Windows and Linux users get a clear "launch the app first" error, as they do now. Worth fixing, not in scope here.
-- **HTTP transport later.** Streamable HTTP on loopback would let clients that cannot spawn a process connect. It needs a discovery file for the port and brings back the token. Not needed while every client we care about can run `dapi mcp`.
+- **HTTP transport.** *Resolved: the app serves Streamable HTTP on a fixed loopback port (`http://127.0.0.1:3274/mcp`, see part 2) beside the socket, and that URL is what agents register. No token: the server binds to loopback and rejects any `Host` other than the loopback address, which is what keeps browser pages out; other processes running as the user can already reach the socket. `dapi mcp` stays for clients that only spawn stdio servers (Claude Desktop). The cost accepted: an agent whose app is closed gets connection refused and must run `dapi open` first, and a taken port means no HTTP endpoint until it is freed (the socket keeps working; the app logs it).*
- **Should `open` launch the app?** The tool cannot launch its own host, so launching stays in the proxy. The alternative, a separate tiny launcher binary, adds a second thing to install for no gain.
- **Concurrency limits.** Today two `dapi` processes can run two captures at once and the renderer copes. With one server that is unchanged, but it becomes easy for an agent to fire several exports in parallel. A per-tool concurrency cap in main is cheap if it turns out to matter.
diff --git a/package-lock.json b/package-lock.json
index 296b1771..7af4447d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -28,7 +28,8 @@
"@modelcontextprotocol/sdk": "^1.30.0",
"babel-preset-solid": "^1.9.12",
"commander": "^14.0.3",
- "esbuild": "^0.28.1"
+ "esbuild": "^0.28.1",
+ "zod": "^4.4.3"
},
"bin": {
"dapi": "dist/index.js"
diff --git a/packages/dapi/src/socket.ts b/packages/dapi/src/socket.ts
index a46fb457..08573b0d 100644
--- a/packages/dapi/src/socket.ts
+++ b/packages/dapi/src/socket.ts
@@ -14,8 +14,19 @@ import type { Socket } from "node:net";
import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
import type { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";
-// One socket / named pipe per host. On macOS tmpdir is per-user; on Linux /tmp
-// is global but the socket file's owner-only mode 0600 keeps it isolated.
+// Where the app serves MCP over HTTP, for agents: a fixed loopback port, so
+// the URL is the same on every machine and can be written into a config once.
+// 3274 spells "dapi" on a phone keypad. Loopback only; no token — the server
+// checks the Host header, which is what keeps browser pages out, and anything
+// else running as the user can already reach the socket below.
+export const MCP_HOST = "127.0.0.1";
+export const MCP_PORT = 3274;
+export const MCP_PATH = "/mcp";
+export const MCP_URL = `http://${MCP_HOST}:${MCP_PORT}${MCP_PATH}`;
+
+// One socket / named pipe per host, for the CLI. On macOS tmpdir is per-user;
+// on Linux /tmp is global but the socket file's owner-only mode 0600 keeps it
+// isolated.
export const SOCKET_PATH =
platform() === "win32"
? "\\\\.\\pipe\\diffusion-studio"
diff --git a/reference/README.md b/reference/README.md
index 9bf1420a..7316bedc 100644
--- a/reference/README.md
+++ b/reference/README.md
@@ -70,7 +70,7 @@ Time inputs take the `Time` format unless noted otherwise. Times in **outputs**
## Conventions
-- **Stdout is JSON.** Commands that return a single record emit one JSON value. Commands that return a collection emit JSON Lines (one object per line, no surrounding array) so per-item results stay streamable. Exceptions: `fonts --names-only` writes plain family names; `logs` writes plain formatted log lines.
+- **Stdout is the tool's result.** Every command prints one JSON object: the structured content the app's MCP tool returns, exactly what an agent connected to the app's MCP server receives. No command reshapes it.
- **Unix-style names are canonical.** Commands without a natural Unix equivalent (`context`, `whoami`) keep their descriptive names.
- **Stderr:** human-readable error messages.
- **Exit codes:** `0` on success, `1` on any error (missing file, app not running, invalid input, IPC error).
diff --git a/reference/capture.md b/reference/capture.md
index dd7cd1be..862ec840 100644
--- a/reference/capture.md
+++ b/reference/capture.md
@@ -33,10 +33,10 @@ Sheets are opaque: a scene's transparent background composites onto flat grey, a
## Output
-JSON Lines, one object per written image: a contact sheet by default, a position with `--separate`.
+One JSON object with one entry per written image: a contact sheet by default, a position with `--separate`.
```ts
-{ timecode: string; path: string } // e.g. { "timecode": "0f-01s15f", "path": "/tmp/dapi-capture-3f2c1a8e/0f-01s15f.png" }
+{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-01s15f", "path": "/tmp/dapi-capture-3f2c1a8e/0f-01s15f.png" }] }
```
A sheet's timecode is the span it covers; a single position's is its own. Sheets come in timeline order, and their cells in the order the positions were requested in.
diff --git a/reference/fetch.md b/reference/fetch.md
index 1ed87627..64c5d403 100644
--- a/reference/fetch.md
+++ b/reference/fetch.md
@@ -24,10 +24,10 @@ dapi fetch https://youtu.be/xyz -f "bv*+ba/b" -- --sponsorblock-remove all --lim
## Output
-JSON Lines, one per file written (a single URL can yield several, e.g. a playlist):
+One JSON object (a single URL can yield several files, e.g. a playlist):
```ts
-{ path: string } // absolute path of the file on disk, after any extraction / rename
+{ paths: string[] } // absolute paths of the files on disk, after any extraction / rename
```
Download progress is rendered by yt-dlp on stderr while the command runs.
diff --git a/reference/fonts.md b/reference/fonts.md
index 34b96b4e..8dc60dfd 100644
--- a/reference/fonts.md
+++ b/reference/fonts.md
@@ -8,19 +8,20 @@ Lists local fonts available on this machine. macOS only. Does not require the ap
- `-w, --weight <weights...>`: filter to variants with the given CSS weight(s), e.g. `-w 400 700`
- `-s, --style <style>`: `"normal"` or `"italic"`
- `-l, --limit <n>`: output at most `<n>` families
-- `-n, --names-only`: output only family names, one per line, plain text (no JSON)
## Output
-JSON Lines, one per family (or plain family names when `--names-only` is set):
+One JSON object:
```ts
{
- family: string;
- variants: Array<{
- weight: string; // CSS weight, e.g. "400"
- style: "normal" | "italic";
- source: string; // CSS local() source
+ families: Array<{
+ family: string;
+ variants: Array<{
+ weight: string; // CSS weight, e.g. "400"
+ style: "normal" | "italic";
+ source: string; // CSS local() source
+ }>;
}>;
}
```
diff --git a/reference/jsx/module.md b/reference/jsx/module.md
index cf067bc3..8f85bc9a 100644
--- a/reference/jsx/module.md
+++ b/reference/jsx/module.md
@@ -28,10 +28,9 @@ The component receives no props. [`dapi open <dir>`](../open.md) opens the folde
| `assets.yml` | The asset library (see [media.md](./media.md#the-library)). |
| `assets/` | The library's files: symlinks to media brought in from elsewhere, plus what the app produced itself, generations under `assets/generated/`. Media imported through the app is linked where it lies, never copied. |
| `cache/` | Derived data (thumbnails, waveforms). Disposable. |
-| `AGENTS.md` | The agent entry point: what to read in `.diffusion/docs/`. |
-| `.diffusion/docs/` | App-owned copy of this reference and the examples, stamped with the app version and regenerated when it changes. Read it, never edit it. |
+| `AGENTS.md` | The agent entry point: how to connect to the app, whose MCP server carries this reference, and how to work here. |
-Everything but `.diffusion/` is written once and is yours from then on.
+Everything is written once and is yours from then on. The reference itself is not copied into the project: the app serves the installed version's as MCP resources under `dapi://docs/`.
## Ids
diff --git a/reference/logs.md b/reference/logs.md
index 5f8a39e8..a4a6fcc8 100644
--- a/reference/logs.md
+++ b/reference/logs.md
@@ -9,14 +9,19 @@ Prints recent console output from the running app: everything the devtools conso
## Output
-Plain text (no JSON), one line per entry:
-
-```
-HH:MM:SS.mmm [level] message (source:line)
+One JSON object, the entries oldest first:
+
+```ts
+{
+ entries: Array<{
+ ts: number; // unix time, milliseconds
+ level: "debug" | "info" | "warning" | "error";
+ message: string;
+ source: string; // file:line the entry came from (a URL in dev builds); empty for synthetic entries such as renderer crashes and preload errors
+ }>;
+}
```
-Timestamps are local time. `source:line` is the logging call site (a URL in dev builds); omitted for synthetic entries such as renderer crashes and preload errors.
-
## Errors
Exits non-zero on an invalid `--tail` or `--level`, or if the app is not running.
diff --git a/reference/media/grab.md b/reference/media/grab.md
index 5b735d26..f54734cc 100644
--- a/reference/media/grab.md
+++ b/reference/media/grab.md
@@ -32,10 +32,10 @@ A sheet never exceeds 2576x1456, the largest image a vision model reads at full
## Output
-JSON Lines, one object per written image: a contact sheet by default, a frame with `--separate`.
+One JSON object with one entry per written image: a contact sheet by default, a frame with `--separate`.
```ts
-{ timecode: string; path: string } // e.g. { "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }
+{ images: Array<{ timecode: string; path: string }> } // e.g. { "images": [{ "timecode": "0f-08s10f", "path": "…/0f-08s10f.png" }] }
```
A sheet's timecode is the span it covers; a frame's is its own. Sheets come in time order, and their cells in the order the times were requested in.
diff --git a/reference/models.md b/reference/models.md
index 89fb6404..f8ece42c 100644
--- a/reference/models.md
+++ b/reference/models.md
@@ -10,15 +10,17 @@ There are no CLI commands that generate; asset generation is declared in the pro
## Output
-JSON Lines, one per model:
+One JSON object:
```ts
{
- type: "image" | "video" | "audio";
- id: string; // the model id to set on a generate.* declaration
- name: string;
- durations?: string[]; // video only, e.g. ["5s","10s"]
- aspectRatios?: string[]; // video only
- features?: Array<"start-frame" | "end-frame" | "audio">; // video only
+ models: Array<{
+ type: "image" | "video" | "audio";
+ id: string; // the model id to set on a generate.* declaration
+ name: string;
+ durations?: string[]; // video only, e.g. ["5s","10s"]
+ aspectRatios?: string[]; // video only
+ features?: Array<"start-frame" | "end-frame" | "audio">; // video only
+ }>;
}
```
diff --git a/reference/voices.md b/reference/voices.md
index b7cf287a..a49f6973 100644
--- a/reference/voices.md
+++ b/reference/voices.md
@@ -8,8 +8,8 @@ None.
## Output
-JSON Lines, one per voice:
+One JSON object:
```ts
-{ id: string; label: string; description: string }
+{ voices: Array<{ id: string; label: string; description: string }> }
```
diff --git a/reference/whoami.md b/reference/whoami.md
index bdd303f9..c514b6de 100644
--- a/reference/whoami.md
+++ b/reference/whoami.md
@@ -8,8 +8,8 @@ None.
## Output
-One JSON value:
+One JSON object:
```ts
-{ id: string; email: string; provider: string } | null
+{ user: { id: string; email?: string } | null }
```