devframe 0.6.0-beta.3 → 0.6.0

package/dist/build-server-0jWgMrz-.mjs

@@ -0,0 +1,338 @@
+import { a as diagnostics } from "./storage-yrUZaiib.mjs";
+import { n as createHostContext } from "./host-h3-Dsf-Tgwx.mjs";
+import { join } from "pathe";
+import process from "node:process";
+import { homedir } from "node:os";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { toJsonSchema } from "@valibot/to-json-schema";
+//#region src/adapters/mcp/stringify.ts
+/**
+* JSON-coercing serializer for MCP text payloads.
+*
+* MCP carries tool results and resource reads as plain text over a
+* JSON-RPC transport, so we cannot use the `s:`-prefixed structured-clone
+* format the WS RPC transport falls back to for non-JSON values. Instead,
+* we coerce common non-JSON types into JSON-friendly forms so the LLM
+* client sees something useful instead of `[object Object]`.
+*
+* Coercions:
+*   - `BigInt` → `"123n"`
+*   - `Date` → ISO string (via the native `toJSON`)
+*   - `Map` → `{ __type: 'Map', entries: [[k, v], …] }`
+*   - `Set` → `{ __type: 'Set', entries: [v, …] }`
+*   - `Error` → `{ name, message, stack, cause? }` (cause recurses)
+*   - `Function` → `"[Function: name]"`
+*   - `Symbol` → `value.toString()`
+*   - cycles → `"[Circular]"`
+*/
+function stringifyForMcp(value) {
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return value;
+	const seen = /* @__PURE__ */ new WeakSet();
+	return JSON.stringify(value, (_key, val) => {
+		if (typeof val === "bigint") return `${val}n`;
+		if (val instanceof Error) {
+			const out = {
+				name: val.name,
+				message: val.message,
+				stack: val.stack
+			};
+			if (val.cause !== void 0) out.cause = val.cause;
+			return out;
+		}
+		if (val instanceof Map) return {
+			__type: "Map",
+			entries: [...val.entries()]
+		};
+		if (val instanceof Set) return {
+			__type: "Set",
+			entries: [...val]
+		};
+		if (typeof val === "function") return `[Function: ${val.name || "anonymous"}]`;
+		if (typeof val === "symbol") return val.toString();
+		if (val !== null && typeof val === "object") {
+			if (seen.has(val)) return "[Circular]";
+			seen.add(val);
+		}
+		return val;
+	}, 2);
+}
+/**
+* Format a thrown value for an MCP `isError` text payload. Surfaces the
+* `Error.name`/`message`, and one level of `cause.message` so context
+* isn't dropped silently.
+*/
+function formatMcpError(error) {
+	if (!(error instanceof Error)) return String(error);
+	const cause = error.cause;
+	const causeText = cause instanceof Error ? ` (cause: ${cause.message})` : cause !== void 0 ? ` (cause: ${String(cause)})` : "";
+	return `${error.name}: ${error.message}${causeText}`;
+}
+//#endregion
+//#region src/adapters/mcp/to-json-schema.ts
+const FALLBACK_OBJECT_SCHEMA = Object.freeze({
+	type: "object",
+	additionalProperties: true
+});
+/**
+* Convert a valibot return schema to JSON Schema.
+* @internal
+*/
+function valibotReturnToJsonSchema(schema) {
+	if (!schema) return void 0;
+	try {
+		return toJsonSchema(schema);
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+}
+/**
+* Convert positional RPC args schemas to a single MCP-friendly object
+* schema. When the RPC declares `args: [v.object(...)]`, unwrap the
+* single-object schema directly (nicer agent UX than `{ arg0: {...} }`).
+*
+* Returns `undefined` when there are no args (the MCP SDK treats this
+* as `{ type: 'object', properties: {} }`).
+* @internal
+*/
+function valibotArgsToJsonSchema(args) {
+	if (!args || args.length === 0) return {
+		schema: {
+			type: "object",
+			properties: {}
+		},
+		unwrapped: false
+	};
+	if (args.length === 1) {
+		const inner = safeToJsonSchema(args[0]);
+		if (isObjectJsonSchema(inner)) return {
+			schema: inner,
+			unwrapped: true
+		};
+	}
+	const properties = {};
+	const required = [];
+	for (let i = 0; i < args.length; i++) {
+		const key = `arg${i}`;
+		properties[key] = safeToJsonSchema(args[i]);
+		required.push(key);
+	}
+	return {
+		schema: {
+			type: "object",
+			properties,
+			required,
+			additionalProperties: false
+		},
+		unwrapped: false
+	};
+}
+function safeToJsonSchema(schema) {
+	try {
+		return toJsonSchema(schema);
+	} catch {
+		return FALLBACK_OBJECT_SCHEMA;
+	}
+}
+function isObjectJsonSchema(value) {
+	return !!value && typeof value === "object" && value.type === "object";
+}
+//#endregion
+//#region src/adapters/mcp/build-server.ts
+/**
+* Wire an MCP {@link Server} to a devframe context. Returns the server
+* plus a disposal function for the subscriptions it sets up. The
+* transport is the caller's responsibility — `createMcpServer` connects
+* stdio; tests can connect an {@link InMemoryTransport} instead.
+*
+* @internal
+*/
+function buildMcpServerFromContext(ctx, options) {
+	const server = new Server({
+		name: options.serverName,
+		version: options.serverVersion
+	}, { capabilities: {
+		tools: { listChanged: true },
+		resources: { listChanged: true }
+	} });
+	registerToolHandlers(server, ctx);
+	registerResourceHandlers(server, ctx, options.exposeSharedState);
+	const notify = (method) => {
+		server.notification({ method }).catch(() => {});
+	};
+	const offManifest = ctx.agent.events.on("agent:manifest:changed", () => {
+		notify("notifications/tools/list_changed");
+		notify("notifications/resources/list_changed");
+	});
+	const offKeyAdded = ctx.rpc.sharedState.onKeyAdded(() => {
+		notify("notifications/resources/list_changed");
+	});
+	return {
+		server,
+		dispose: () => {
+			offManifest();
+			offKeyAdded();
+		}
+	};
+}
+/**
+* Build an MCP server over the agent surface of a devframe definition.
+* Currently supports `stdio` transport only.
+*
+* @experimental The agent-native surface is experimental and may change
+* without a major version bump until it stabilizes.
+*/
+async function createMcpServer(definition, options = {}) {
+	const transport = options.transport ?? "stdio";
+	if (transport !== "stdio") throw diagnostics.DF0017({
+		transport,
+		reason: "Only stdio transport is supported in this release."
+	});
+	const ctx = await createHostContext({
+		cwd: process.cwd(),
+		mode: "dev",
+		host: {
+			mountStatic: () => {},
+			resolveOrigin: () => "mcp://devframe",
+			getStorageDir: (scope) => scope === "workspace" ? join(process.cwd(), `node_modules/.${definition.id}/devframe`) : join(homedir(), `.${definition.id}/devframe`)
+		}
+	});
+	await definition.setup(ctx);
+	const { server, dispose } = buildMcpServerFromContext(ctx, {
+		serverName: options.serverName ?? `${definition.id} (devframe)`,
+		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
+		exposeSharedState: options.exposeSharedState ?? true
+	});
+	const { startStdioTransport } = await import("./transports-BmDVn4SF.mjs");
+	let stop;
+	try {
+		stop = await startStdioTransport(server);
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		throw diagnostics.DF0017({
+			transport,
+			reason,
+			cause: error
+		});
+	}
+	options.onReady?.({ transport: "stdio" });
+	return { async stop() {
+		dispose();
+		await stop();
+	} };
+}
+function registerToolHandlers(server, ctx) {
+	server.setRequestHandler(ListToolsRequestSchema, async () => {
+		return { tools: ctx.agent.list().tools.map((tool) => projectTool(tool, ctx)) };
+	});
+	server.setRequestHandler(CallToolRequestSchema, async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			return { content: [{
+				type: "text",
+				text: stringifyForMcp(await ctx.agent.invoke(name, args ?? {}))
+			}] };
+		} catch (error) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Error invoking "${name}": ${formatMcpError(error)}`
+				}]
+			};
+		}
+	});
+}
+function registerResourceHandlers(server, ctx, exposeSharedState) {
+	server.setRequestHandler(ListResourcesRequestSchema, async () => {
+		const resources = ctx.agent.list().resources.map((resource) => ({
+			uri: resource.uri,
+			name: resource.name,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+		if (exposeSharedState !== false) {
+			const filter = typeof exposeSharedState === "function" ? exposeSharedState : () => true;
+			for (const key of ctx.rpc.sharedState.keys()) {
+				if (!filter(key)) continue;
+				resources.push({
+					uri: `devframe://state/${encodeURIComponent(key)}`,
+					name: key,
+					description: `Shared state: ${key}`,
+					mimeType: "application/json"
+				});
+			}
+		}
+		return { resources };
+	});
+	server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+		const { uri } = request.params;
+		const parsed = parseResourceUri(uri);
+		if (parsed.kind === "resource") {
+			const content = await ctx.agent.read(parsed.id);
+			return { contents: [{
+				uri,
+				mimeType: content.mimeType ?? "application/json",
+				text: content.text ?? stringifyForMcp(content.json)
+			}] };
+		}
+		if (parsed.kind === "state") return { contents: [{
+			uri,
+			mimeType: "application/json",
+			text: stringifyForMcp((await ctx.rpc.sharedState.get(parsed.key)).value())
+		}] };
+		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
+	});
+}
+function projectTool(tool, ctx) {
+	const inputSchema = tool.inputSchema ?? computeInputSchema(tool, ctx);
+	const outputSchema = tool.outputSchema ?? computeOutputSchema(tool, ctx);
+	return {
+		name: tool.id,
+		title: tool.title,
+		description: tool.description,
+		inputSchema,
+		...outputSchema ? { outputSchema } : {},
+		annotations: {
+			title: tool.title,
+			readOnlyHint: tool.safety === "read",
+			destructiveHint: tool.safety === "destructive"
+		}
+	};
+}
+function computeInputSchema(tool, ctx) {
+	if (tool.kind !== "rpc" || !tool.rpcName) return {
+		type: "object",
+		properties: {}
+	};
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return {
+		type: "object",
+		properties: {}
+	};
+	const args = def.args;
+	return valibotArgsToJsonSchema(args).schema;
+}
+function computeOutputSchema(tool, ctx) {
+	if (tool.kind !== "rpc" || !tool.rpcName) return void 0;
+	const def = ctx.rpc.definitions.get(tool.rpcName);
+	if (!def) return void 0;
+	return valibotReturnToJsonSchema(def.returns);
+}
+function parseResourceUri(uri) {
+	const match = uri.match(/^devframe:\/\/(resource|state)\/(.+)$/);
+	if (!match) return { kind: "unknown" };
+	const [, kind, rest] = match;
+	const decoded = decodeURIComponent(rest);
+	if (kind === "resource") return {
+		kind: "resource",
+		id: decoded
+	};
+	return {
+		kind: "state",
+		key: decoded
+	};
+}
+//#endregion
+export { createMcpServer as n, buildMcpServerFromContext as t };

package/dist/client/index.d.mts

@@ -1,4 +1,4 @@
-import { $ as ScopedServerFunctions, D as StreamReader, J as DevframeSettings, L as SharedState, O as StreamSink, bt as EventEmitter, d as ConnectionMeta, et as ScopedSharedStates, it as DevframeRpcServerFunctions, rt as DevframeRpcClientFunctions, tt as SettingsForNamespace, v as RpcSharedStateGetOptions, y as RpcSharedStateHost } from "../devframe-DgvncQy2.mjs";
+import { O as StreamReader, R as SharedState, Y as DevframeSettings, at as DevframeRpcServerFunctions, b as RpcSharedStateHost, et as ScopedServerFunctions, f as ConnectionMeta, it as DevframeRpcClientFunctions, k as StreamSink, nt as SettingsForNamespace, tt as ScopedSharedStates, xt as EventEmitter, y as RpcSharedStateGetOptions } from "../devframe-BtVHhmwM.mjs";
 import { _ as RpcFunctionDefinition, w as RpcFunctionsCollector } from "../types-DZEx4ffs.mjs";
 import { C as RpcCacheManager, w as RpcCacheOptions } from "../index-Dy6GFDRf.mjs";
 import { t as WsRpcChannelOptions } from "../ws-client-D0z0pOhn.mjs";

package/dist/constants.d.mts

@@ -11,6 +11,13 @@ declare const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
  * handler here without colliding with its own routes (HMR, asset serving).
  */
 declare const DEVFRAME_WS_ROUTE = "__devframe_ws";
+/**
+ * Route the Streamable-HTTP MCP endpoint is bound to, relative to a
+ * devframe's base path. Sits next to `__connection.json` and the WS route
+ * so an MCP client reaches it on the same origin the SPA loaded from — the
+ * dev server shares one port for HTTP, WS, and MCP. Opt-in via `cli.mcp`.
+ */
+declare const DEVFRAME_MCP_ROUTE = "__mcp";
 declare const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 declare const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 declare const DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID = "/__devframe-client-imports.js";
@@ -53,4 +60,4 @@ declare const ANONYMOUS_RPC_PREFIX = "anonymous:";
  */
 declare function isAnonymousRpcMethod(name: string): boolean;
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };

package/dist/constants.mjs

@@ -11,6 +11,13 @@ const DEVFRAME_CONNECTION_META_FILENAME = "__connection.json";
 * handler here without colliding with its own routes (HMR, asset serving).
 */
 const DEVFRAME_WS_ROUTE = "__devframe_ws";
+/**
+* Route the Streamable-HTTP MCP endpoint is bound to, relative to a
+* devframe's base path. Sits next to `__connection.json` and the WS route
+* so an MCP client reaches it on the same origin the SPA loaded from — the
+* dev server shares one port for HTTP, WS, and MCP. Opt-in via `cli.mcp`.
+*/
+const DEVFRAME_MCP_ROUTE = "__mcp";
 const DEVFRAME_RPC_DUMP_MANIFEST_FILENAME = "__rpc-dump/index.json";
 const DEVFRAME_DOCK_IMPORTS_FILENAME = "__client-imports.js";
 const DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID = "/__devframe-client-imports.js";
@@ -55,4 +62,4 @@ function isAnonymousRpcMethod(name) {
 	return name.startsWith(ANONYMOUS_RPC_PREFIX);
 }
 //#endregion
-export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };
+export { ANONYMOUS_RPC_PREFIX, DEVFRAME_AUTH_TOKEN_QUERY_PARAM, DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DIRNAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_DOCK_IMPORTS_VIRTUAL_ID, DEVFRAME_MCP_ROUTE, DEVFRAME_MOUNT_PATH, DEVFRAME_MOUNT_PATH_NO_TRAILING_SLASH, DEVFRAME_OTP_URL_PARAM, DEVFRAME_RPC_DUMP_DIRNAME, DEVFRAME_RPC_DUMP_MANIFEST_FILENAME, DEVFRAME_WS_ROUTE, REMOTE_CONNECTION_KEY, isAnonymousRpcMethod };

package/dist/{context-B_I9fMBc.d.mts → context-UX9qUDK7.d.mts}

@@ -1,4 +1,4 @@
-import { L as SharedState, m as DevframeNodeContext } from "./devframe-DgvncQy2.mjs";
+import { R as SharedState, h as DevframeNodeContext } from "./devframe-BtVHhmwM.mjs";
 
 //#region src/node/hub-internals/context.d.ts
 interface InternalAnonymousAuthStorage {

package/dist/{dev-DSxKFn-v.mjs → dev-zC5542OV.mjs}

@@ -1,6 +1,7 @@
 import { DEVFRAME_CONNECTION_META_FILENAME } from "./constants.mjs";
+import { a as diagnostics } from "./storage-yrUZaiib.mjs";
 import { n as createHostContext, t as createH3DevframeHost } from "./host-h3-Dsf-Tgwx.mjs";
-import { t as startHttpAndWs } from "./server-BdN41ckC.mjs";
+import { t as startHttpAndWs } from "./server-CAsvfJNK.mjs";
 import { n as resolveBasePath, t as normalizeBasePath } from "./_shared-bWRzeSa0.mjs";
 import { t as open } from "./open-Deb5xmIT.mjs";
 import { mountStaticHandler } from "./utils/serve-static.mjs";
@@ -284,14 +285,40 @@ async function createDevServer(def, options = {}) {
 	});
 	const setupInfo = { flags };
 	await def.setup(ctx, setupInfo);
+	const mcpConfig = resolveMcpConfig(options.mcp ?? def.cli?.mcp);
+	let mcpDispose;
+	let mcpMeta;
+	if (mcpConfig) {
+		const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? "__mcp");
+		const mcpPath = joinURL(basePath, mcpRoute);
+		let mountMcpHttp;
+		try {
+			({mountMcpHttp} = await import("./http-COX960WK.mjs"));
+		} catch (error) {
+			const reason = error instanceof Error ? error.message : String(error);
+			throw diagnostics.DF0017({
+				transport: "http",
+				reason,
+				cause: error
+			});
+		}
+		mcpDispose = mountMcpHttp(app, ctx, mcpPath, {
+			serverName: `${def.id} (devframe)`,
+			serverVersion: def.version ?? "0.0.0",
+			exposeSharedState: true,
+			allowedOrigins: mcpConfig.allowedOrigins
+		}).dispose;
+		mcpMeta = { path: mcpRoute };
+	}
 	const { bindPath, wsPort, meta } = resolveWsConnection(def, options, basePath);
 	const connectionMetaPath = joinURL(basePath, DEVFRAME_CONNECTION_META_FILENAME);
 	app.use(connectionMetaPath, () => ({
 		backend: "websocket",
-		websocket: meta
+		websocket: meta,
+		...mcpMeta ? { mcp: mcpMeta } : {}
 	}));
 	if (distDir) mountStaticHandler(app, basePath, resolve(distDir));
-	return startHttpAndWs({
+	const started = await startHttpAndWs({
 		context: ctx,
 		host,
 		port,
@@ -304,6 +331,22 @@ async function createDevServer(def, options = {}) {
 			await maybeOpenBrowser(def, flags, `${info.origin}${basePath}`, options.openBrowser);
 		}
 	});
+	if (mcpDispose) {
+		const closeServer = started.close;
+		started.close = async () => {
+			await mcpDispose();
+			await closeServer();
+		};
+	}
+	return started;
+}
+/**
+* Normalize the `cli.mcp` / `mcp` option (`boolean | McpRouteOptions`) into
+* concrete options, or `undefined` when the MCP route is disabled.
+*/
+function resolveMcpConfig(mcp) {
+	if (!mcp) return void 0;
+	return mcp === true ? {} : mcp;
 }
 /**
 * Resolve the three WS connection scenarios from the definition / call-site

package/dist/{devframe-DgvncQy2.d.mts → devframe-BtVHhmwM.d.mts}

@@ -1220,6 +1220,16 @@ interface ConnectionMeta {
    *     URL with its protocol swapped, or a path resolved same-origin.
    */
   websocket?: number | string | ConnectionMetaWebsocket;
+  /**
+   * Present when the dev server exposes a route-based MCP endpoint
+   * (`cli.mcp`). Advertises the MCP Streamable-HTTP route so in-browser
+   * tooling (e.g. an MCP inspector) can discover it without guessing the
+   * path. `path` is relative to `__connection.json`'s location, like the
+   * WebSocket `path`.
+   */
+  mcp?: {
+    path: string;
+  };
   /**
    * Names of RPC functions that have declared `jsonSerializable: true`.
    * Used by the WS / static client to dispatch the per-call wire
@@ -1285,6 +1295,36 @@ interface DevframeWsOptions {
    */
   url?: string;
 }
+/**
+ * Configuration for the route-based MCP server mounted alongside the dev
+ * server (opt-in via {@link DevframeCliOptions.mcp}). The endpoint speaks
+ * the MCP Streamable-HTTP transport over the same origin as the SPA,
+ * exposing the definition's `ctx.agent` tools + shared-state resources to
+ * external MCP clients connected to the *running* server.
+ *
+ * @experimental The agent-native surface is experimental and may change
+ * without a major version bump until it stabilizes.
+ */
+interface McpRouteOptions {
+  /**
+   * Route segment the MCP endpoint binds to, relative to the SPA base.
+   * Default: `__mcp` (i.e. `/__mcp` standalone, `/__<id>/__mcp` hosted).
+   */
+  path?: string;
+  /**
+   * Extra `Origin` header values to accept beyond the loopback default
+   * (`localhost`/`127.0.0.1`/`::1` and any `Origin`-less native client).
+   * Add your LAN/tunnel origin here when reaching the endpoint from another
+   * host, mirroring the WS transport's origin gate. Pass `false` to disable
+   * origin checking entirely (not recommended). Default: loopback-only.
+   *
+   * This is the endpoint's DNS-rebinding protection — the shared
+   * `isAllowedOrigin` gate the WS upgrade already uses, applied as external
+   * middleware (the approach the MCP SDK now recommends over its own
+   * deprecated `allowedHosts`/`allowedOrigins` transport flags).
+   */
+  allowedOrigins?: readonly string[] | false;
+}
 interface DevframeCliOptions {
   /** Binary name; default: the devframe's `id`. */
   command?: string;
@@ -1311,6 +1351,22 @@ interface DevframeCliOptions {
    * `devtools.clientAuth` today.
    */
   auth?: boolean;
+  /**
+   * Expose a route-based MCP server alongside the dev server, speaking the
+   * MCP Streamable-HTTP transport at `/__mcp` (relative to the base path).
+   * It surfaces the same `ctx.agent` tools + shared-state resources as the
+   * stdio `mcp` command, but against the live, running server.
+   *
+   * - `false` / omitted (default) — no MCP route is mounted.
+   * - `true` — mount at the default `__mcp` route with the loopback-only
+   *   origin gate.
+   * - {@link McpRouteOptions} — customise the route path / allowed origins.
+   *
+   * The `--mcp` / `--no-mcp` CLI flags override this per run.
+   *
+   * @experimental
+   */
+  mcp?: boolean | McpRouteOptions;
   /** Author's SPA dist directory (served as the devframe's UI). */
   distDir?: string;
   /**
@@ -1422,4 +1478,4 @@ interface DevframeDefinition {
 }
 declare function defineDevframe(d: DevframeDefinition): DevframeDefinition;
 //#endregion
-export { ScopedServerFunctions as $, createStreamReader as A, SharedStatePatch as B, BufferedChunk as C, CliFlagsSchema as Ct, StreamReader as D, StreamErrorPayload as E, parseCliFlags as Et, ImmutableObject as F, DevframeScopedNodeContext as G, EntriesToObject as H, ImmutableSet as I, DevframeSettings as J, DevframeScopedNodeRpc as K, SharedState as L, Immutable as M, ImmutableArray as N, StreamSink as O, ImmutableMap as P, ScopedClientFunctions as Q, SharedStateEvents as R, RpcStreamingHost as S, EventsMap as St, CreateStreamSinkOptions as T, defineCliFlags as Tt, PartialWithoutId as U, createSharedState as V, Thenable as W, DevframeSettingsStore as X, DevframeSettingsRegistry as Y, ScopedBroadcastOptions as Z, RpcFunctionsHost as _, AgentToolInput as _t, DevframeDuplicationStrategy as a, DevframeRpcSharedStates as at, RpcStreamingChannel as b, EventEmitter as bt, DevframeSpaOptions as c, DevframeDiagnosticsDefinition as ct, ConnectionMeta as d, AgentHandle as dt, ScopedSharedStates as et, ConnectionMetaWebsocket as f, AgentManifest as ft, RpcBroadcastOptions as g, AgentTool as gt, DevframeNodeRpcSession as h, AgentResourceInput as ht, DevframeDeploymentKind as i, DevframeRpcServerFunctions as it, createStreamSink as j, StreamSinkEvents as k, DevframeWsOptions as l, DevframeDiagnosticsHost as lt, DevframeNodeContext as m, AgentResourceContent as mt, DevframeCliOptions as n, DevframeViewHost as nt, DevframeRuntime as o, DevframeHost as ot, DevframeCapabilities as p, AgentResource as pt, DevframeScopedStreamingHost as q, DevframeDefinition as r, DevframeRpcClientFunctions as rt, DevframeSetupInfo as s, DevframeDefineDiagnosticsOptions as st, DevframeBrowserContext as t, SettingsForNamespace as tt, defineDevframe as u, DevframeDiagnosticsLogger as ut, RpcSharedStateGetOptions as v, DevframeAgentHost as vt, CreateStreamReaderOptions as w, InferCliFlags as wt, RpcStreamingChannelOptions as x, EventUnsubscribe as xt, RpcSharedStateHost as y, DevframeAgentHostEvents as yt, SharedStateOptions as z };
+export { ScopedClientFunctions as $, StreamSinkEvents as A, SharedStateOptions as B, RpcStreamingHost as C, EventsMap as Ct, StreamErrorPayload as D, parseCliFlags as Dt, CreateStreamSinkOptions as E, defineCliFlags as Et, ImmutableMap as F, Thenable as G, createSharedState as H, ImmutableObject as I, DevframeScopedStreamingHost as J, DevframeScopedNodeContext as K, ImmutableSet as L, createStreamSink as M, Immutable as N, StreamReader as O, ImmutableArray as P, ScopedBroadcastOptions as Q, SharedState as R, RpcStreamingChannelOptions as S, EventUnsubscribe as St, CreateStreamReaderOptions as T, InferCliFlags as Tt, EntriesToObject as U, SharedStatePatch as V, PartialWithoutId as W, DevframeSettingsRegistry as X, DevframeSettings as Y, DevframeSettingsStore as Z, RpcBroadcastOptions as _, AgentTool as _t, DevframeDuplicationStrategy as a, DevframeRpcServerFunctions as at, RpcSharedStateHost as b, DevframeAgentHostEvents as bt, DevframeSpaOptions as c, DevframeDefineDiagnosticsOptions as ct, defineDevframe as d, DevframeDiagnosticsLogger as dt, ScopedServerFunctions as et, ConnectionMeta as f, AgentHandle as ft, DevframeNodeRpcSession as g, AgentResourceInput as gt, DevframeNodeContext as h, AgentResourceContent as ht, DevframeDeploymentKind as i, DevframeRpcClientFunctions as it, createStreamReader as j, StreamSink as k, DevframeWsOptions as l, DevframeDiagnosticsDefinition as lt, DevframeCapabilities as m, AgentResource as mt, DevframeCliOptions as n, SettingsForNamespace as nt, DevframeRuntime as o, DevframeRpcSharedStates as ot, ConnectionMetaWebsocket as p, AgentManifest as pt, DevframeScopedNodeRpc as q, DevframeDefinition as r, DevframeViewHost as rt, DevframeSetupInfo as s, DevframeHost as st, DevframeBrowserContext as t, ScopedSharedStates as tt, McpRouteOptions as u, DevframeDiagnosticsHost as ut, RpcFunctionsHost as v, AgentToolInput as vt, BufferedChunk as w, CliFlagsSchema as wt, RpcStreamingChannel as x, EventEmitter as xt, RpcSharedStateGetOptions as y, DevframeAgentHost as yt, SharedStateEvents as z };

package/dist/helpers/vite.d.mts

@@ -1,4 +1,4 @@
-import { r as DevframeDefinition } from "../devframe-DgvncQy2.mjs";
+import { r as DevframeDefinition } from "../devframe-BtVHhmwM.mjs";
 
 //#region src/helpers/vite.d.ts
 interface ViteDevBridgeOptions {

package/dist/helpers/vite.mjs

@@ -2,7 +2,7 @@ import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_WS_ROUTE } from "../constan
 import { a as diagnostics } from "../storage-yrUZaiib.mjs";
 import { n as resolveBasePath, t as normalizeBasePath } from "../_shared-bWRzeSa0.mjs";
 import { serveStaticNodeMiddleware } from "../utils/serve-static.mjs";
-import { n as resolveDevServerPort, t as createDevServer } from "../dev-DSxKFn-v.mjs";
+import { n as resolveDevServerPort, t as createDevServer } from "../dev-zC5542OV.mjs";
 import { resolve } from "pathe";
 //#region src/helpers/vite.ts
 /**