@devframes/agentic 0.9.19

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT Anthony Fu <https://github.com/antfu>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/connect/index.d.mts

@@ -0,0 +1,58 @@
+import { DevframeInstanceRecord } from "devframe/internal";
+//#region src/connect/index.d.ts
+export interface ConnectServerOptions {
+  /**
+   * Explicit ports to probe besides the registry, for instances started
+   * before the registry existed, or reachable only by convention. Each port
+   * is probed at `/` (`http://localhost:<port>/__connection.json`).
+   */
+  ports?: number[];
+  /** Override the registry directory (`DEVFRAME_INSTANCES_DIR` also applies). */
+  instancesDir?: string;
+  /** Probe timeout per instance, ms. Default 1000. */
+  timeoutMs?: number;
+  /**
+   * The bearer credential the connector presents to each instance's
+   * authenticated MCP route, sent as `Authorization: Bearer <token>`.
+   *
+   * - a **string**: one shared token for every instance;
+   * - a **resolver** `(record) => string | undefined`: a per-instance token,
+   *   for connecting to a fleet with distinct credentials (return `undefined`
+   *   to send none for that instance).
+   *
+   * The token is only ever placed in a request header: it never enters the
+   * instance registry records, the indexed results, connection URLs, or
+   * formatted errors. Left unset, no `Authorization` header is sent, so only an
+   * instance whose route opted out of identity (`authorization: false`) will
+   * answer.
+   */
+  authToken?: string | ((record: DevframeInstanceRecord) => string | undefined);
+}
+/**
+ * Resolve the per-record bearer from the {@link ConnectServerOptions.authToken}
+ * option. Exported for focused tests of the credential resolution.
+ */
+export declare function resolveAuthToken(authToken: ConnectServerOptions['authToken'], record: DevframeInstanceRecord): string | undefined;
+/**
+ * Build the request headers the connector sends to one instance's MCP route:
+ * the instance's own (loopback) `origin` so the route's origin gate accepts
+ * this native client, plus `Authorization: Bearer <token>` when a bearer is
+ * configured. The bearer appears **only** here, never in the connection URL,
+ * the registry records, or the indexed results. Exported for focused tests.
+ */
+export declare function buildInstanceRequestHeaders(url: string, token: string | undefined): Record<string, string>;
+export interface ConnectServerHandle {
+  stop: () => Promise<void>;
+}
+/**
+ * Start the devframe MCP connector on stdio: a thin discovery + proxy server
+ * in the shape Vercel's next-devtools-mcp (https://github.com/vercel/next-devtools-mcp)
+ * validated; credit is due there for the architecture this connector follows.
+ * It exposes two gateway tools:
+ * `devframe_connect_list-instances` (discover running devframe instances via
+ * the instance registry and list each one's MCP tools) and
+ * `devframe_connect_call-tool` (invoke one tool on one instance over its
+ * Streamable-HTTP endpoint), and holds no domain knowledge of its own.
+ */
+export declare function startConnectServer(options?: ConnectServerOptions): Promise<ConnectServerHandle>;
+//#endregion

package/dist/connect/index.mjs

@@ -0,0 +1,243 @@
+import { Server } from "@modelcontextprotocol/server";
+import { diagnostics, listLiveDevframeInstances, probeDevframeOrigin } from "devframe/internal";
+import { toAgentToolName } from "devframe/utils/agent-tool-name";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { Diagnostic } from "devframe/utils/nostics";
+import { joinURL } from "devframe/utils/url";
+//#region src/connect/index.ts
+/**
+* Resolve the per-record bearer from the {@link ConnectServerOptions.authToken}
+* option. Exported for focused tests of the credential resolution.
+*/
+function resolveAuthToken(authToken, record) {
+	return typeof authToken === "function" ? authToken(record) : authToken;
+}
+/**
+* Build the request headers the connector sends to one instance's MCP route:
+* the instance's own (loopback) `origin` so the route's origin gate accepts
+* this native client, plus `Authorization: Bearer <token>` when a bearer is
+* configured. The bearer appears **only** here, never in the connection URL,
+* the registry records, or the indexed results. Exported for focused tests.
+*/
+function buildInstanceRequestHeaders(url, token) {
+	const headers = { origin: new URL(url).origin };
+	if (token) headers.authorization = `Bearer ${token}`;
+	return headers;
+}
+const INDEX_TOOL = toAgentToolName("devframe:connect:list-instances");
+const CALL_TOOL = toAgentToolName("devframe:connect:call-tool");
+const MCP_DISABLED_HINT = "This instance runs without an MCP route. Restart it with the --mcp flag to expose its tools, then list instances again.";
+const GATEWAY_TOOLS = [{
+	name: INDEX_TOOL,
+	title: "Discover running devframes",
+	description: "Discover every running devframe dev server on this machine and list each one's MCP tools. Call this FIRST, before assuming which devtools are available; the result names the instance (id, project root, origin) and the port to pass to the call tool. Safe to call freely.",
+	inputSchema: {
+		type: "object",
+		properties: {}
+	},
+	annotations: {
+		readOnlyHint: true,
+		destructiveHint: false
+	}
+}, {
+	name: CALL_TOOL,
+	title: "Call a devframe tool",
+	description: "Invoke one MCP tool on one running devframe instance discovered via the list-instances tool. Pass the instance's port, the tool name, and the tool's arguments object.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			port: {
+				type: "number",
+				description: "The instance's port, from the list-instances tool."
+			},
+			tool: {
+				type: "string",
+				description: "Tool name, from the instance's tool list."
+			},
+			args: {
+				type: "object",
+				description: "Arguments object for the tool. Omit for zero-argument tools."
+			}
+		},
+		required: ["port", "tool"],
+		additionalProperties: false
+	}
+}];
+/**
+* Start the devframe MCP connector on stdio: a thin discovery + proxy server
+* in the shape Vercel's next-devtools-mcp (https://github.com/vercel/next-devtools-mcp)
+* validated; credit is due there for the architecture this connector follows.
+* It exposes two gateway tools:
+* `devframe_connect_list-instances` (discover running devframe instances via
+* the instance registry and list each one's MCP tools) and
+* `devframe_connect_call-tool` (invoke one tool on one instance over its
+* Streamable-HTTP endpoint), and holds no domain knowledge of its own.
+*/
+async function startConnectServer(options = {}) {
+	const server = new Server({
+		name: "devframe-connect",
+		version: "0.0.0"
+	}, { capabilities: { tools: {} } });
+	server.setRequestHandler("tools/list", async () => ({ tools: GATEWAY_TOOLS }));
+	server.setRequestHandler("tools/call", async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			if (name === INDEX_TOOL) return textResult(await index(options));
+			if (name === CALL_TOOL) return textResult(await call(options, args ?? {}));
+			return errorResult({
+				message: `unknown tool "${name}"`,
+				fix: `Call ${INDEX_TOOL} or ${CALL_TOOL}.`
+			});
+		} catch (error) {
+			return errorResult(toErrorPayload(error));
+		}
+	});
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	return { stop: async () => {
+		await server.close();
+	} };
+}
+/** Discover instances: registry (prune-on-read) + explicit port probes. */
+async function index(options) {
+	const { live } = await listLiveDevframeInstances({
+		instancesDir: options.instancesDir,
+		timeoutMs: options.timeoutMs
+	});
+	const records = [...live];
+	for (const port of options.ports ?? []) {
+		if (records.some((r) => r.port === port)) continue;
+		const probed = await probePort(port, options.timeoutMs);
+		if (probed) records.push(probed);
+	}
+	const instances = await Promise.all(records.map(async (record) => {
+		const { mcp, ...rest } = record;
+		const entry = {
+			...rest,
+			mcp: null
+		};
+		if (!mcp) {
+			entry.hint = MCP_DISABLED_HINT;
+			return entry;
+		}
+		const url = `${record.origin}${mcp.path}`;
+		try {
+			entry.mcp = {
+				url,
+				tools: await listInstanceTools(url, resolveAuthToken(options.authToken, record))
+			};
+		} catch (error) {
+			entry.mcp = {
+				url,
+				error: error instanceof Error ? error.message : String(error)
+			};
+		}
+		return entry;
+	}));
+	return {
+		instances,
+		...instances.length === 0 ? { hint: "No running devframe instances found. Start a devframe dev server (with --mcp for tools), or pass --port <n> to devframe connect if the instance predates the registry." } : {}
+	};
+}
+/**
+* Probe an explicit port for a devframe serving `__connection.json` at `/`,
+* reusing the registry's origin-candidate probe (a `localhost`-bound server
+* may listen on either address family).
+*/
+async function probePort(port, timeoutMs) {
+	const probed = await probeDevframeOrigin(`http://localhost:${port}`, "/", timeoutMs);
+	if (!probed) return null;
+	const mcpPath = probed.meta.mcp ? joinURL("/", probed.meta.mcp.path) : null;
+	return {
+		pid: -1,
+		port,
+		origin: probed.origin,
+		basePath: "/",
+		id: `port-${port}`,
+		rootDir: "",
+		mcp: mcpPath ? { path: mcpPath } : null,
+		startedAt: 0
+	};
+}
+async function listInstanceTools(url, token) {
+	return withInstanceClient(url, token, async (client) => {
+		return (await client.listTools()).tools.map((tool) => ({
+			name: tool.name,
+			description: tool.description
+		}));
+	});
+}
+async function call(options, args) {
+	if (typeof args.port !== "number" || typeof args.tool !== "string") throw diagnostics.DF0049();
+	const { live } = await listLiveDevframeInstances({
+		instancesDir: options.instancesDir,
+		timeoutMs: options.timeoutMs
+	});
+	const record = live.find((r) => r.port === args.port) ?? await probePort(args.port, options.timeoutMs);
+	if (!record) throw diagnostics.DF0050({ port: args.port });
+	if (!record.mcp) throw diagnostics.DF0051({ port: args.port });
+	return withInstanceClient(`${record.origin}${record.mcp.path}`, resolveAuthToken(options.authToken, record), async (client) => {
+		const result = await client.callTool({
+			name: args.tool,
+			arguments: args.args ?? {}
+		});
+		return {
+			instance: {
+				id: record.id,
+				port: record.port
+			},
+			tool: args.tool,
+			isError: result.isError ?? false,
+			content: result.content,
+			...result.structuredContent ? { structuredContent: result.structuredContent } : {}
+		};
+	});
+}
+async function withInstanceClient(url, token, fn) {
+	const transport = new StreamableHTTPClientTransport(new URL(url), { requestInit: { headers: buildInstanceRequestHeaders(url, token) } });
+	const client = new Client({
+		name: "devframe-connect",
+		version: "0.0.0"
+	}, { versionNegotiation: { mode: "auto" } });
+	await client.connect(transport);
+	try {
+		return await fn(client);
+	} finally {
+		await client.close().catch(() => {});
+	}
+}
+function textResult(value) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(value, null, 2)
+	}] };
+}
+/**
+* Project a thrown value into the connector's structured error payload. A
+* nostics `Diagnostic` carries its code, `fix`, and docs URL across so the
+* calling agent gets the actionable next step.
+*/
+function toErrorPayload(error) {
+	if (error instanceof Diagnostic) return {
+		code: error.code,
+		message: error.message,
+		...error.fix ? { fix: error.fix } : {},
+		...error.docs ? { docs: error.docs } : {}
+	};
+	return {
+		message: error instanceof Error ? error.message : String(error),
+		...error && typeof error === "object" && "fix" in error && typeof error.fix === "string" ? { fix: error.fix } : {}
+	};
+}
+function errorResult(error) {
+	return {
+		isError: true,
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error }, null, 2)
+		}]
+	};
+}
+//#endregion
+export { buildInstanceRequestHeaders, resolveAuthToken, startConnectServer };

package/dist/index.d.mts

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

package/dist/index.mjs

@@ -0,0 +1,4 @@
+//#region src/index.ts
+throw new Error("[@devframes/agentic] is not imported directly; installing it enables devframe's agent surfaces.\n  • import from \"devframe/adapters/mcp\" to serve a devframe over MCP\n  • run \"devframe connect\" for the stdio discovery gateway\n");
+//#endregion
+export {};

package/dist/mcp/index.d.mts

@@ -0,0 +1,61 @@
+import { Server } from "@modelcontextprotocol/server";
+import { MountMcpHttpOptions, MountMcpHttpOptions as MountMcpHttpOptions$1, MountedMcpHttp, MountedMcpHttp as MountedMcpHttp$1 } from "devframe/internal";
+import { H3 } from "h3";
+import { CreateMcpFetchHandlerOptions, CreateMcpFetchHandlerOptions as CreateMcpFetchHandlerOptions$1, CreateMcpServerOptions, CreateMcpServerOptions as CreateMcpServerOptions$1, DevframeDefinition, DevframeNodeContext, McpConnectionInfo, McpFetchHandler, McpFetchHandler as McpFetchHandler$1, McpServerHandle, McpServerHandle as McpServerHandle$1 } from "devframe/types";
+//#region src/mcp/build-server.d.ts
+/**
+ * Build an MCP server over the agent surface of a devframe definition.
+ * Currently supports `stdio` transport only.
+ */
+export declare function createMcpServer(definition: DevframeDefinition, options?: CreateMcpServerOptions$1): Promise<McpServerHandle$1>;
+//#endregion
+//#region src/mcp/fetch.d.ts
+/**
+ * Build a framework-agnostic MCP endpoint over a devframe context: a
+ * web-standard `Request → Response` handler any host can mount: h3 (see
+ * `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
+ * server.
+ *
+ * The endpoint is **stateless**: it serves the 2026-07-28 revision per request
+ * through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
+ * (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
+ * request: no `Mcp-Session-Id` registry, no session-local routing, no
+ * GET/DELETE teardown protocol. 2025-era clients are still served through the
+ * SDK's default stateless legacy path. `list_changed` events reach modern
+ * `subscriptions/listen` streams through the handler's `notify` bus.
+ *
+ * The origin gate guards every request: loopback-default DNS-rebinding
+ * protection that (unlike the WS upgrade's `isAllowedOrigin`) also rejects
+ * `Origin`-less requests, so a browser can't reach the route across origins (a
+ * disallowed origin gets `403`). The `Origin` header is only browser hardening:
+ * a non-browser client forges it. So on the zero-config default (no widened
+ * `allowedOrigins`, no identity check) a second locality gate requires the
+ * connected peer to be loopback, proven from the host-supplied
+ * {@link McpConnectionInfo.remoteAddress} (which a client cannot forge), so the
+ * "trusts same-machine callers" default holds against a remote raw client.
+ * When same-machine isn't your trust boundary, add an identity gate
+ * ({@link CreateMcpFetchHandlerOptions.authorization}), checked after the
+ * origin gate: a bearer/callback check that proves *who* is calling (a
+ * missing/invalid credential gets `401` with a `WWW-Authenticate: Bearer`
+ * challenge), which also lifts the loopback-peer restriction for authenticated
+ * callers.
+ */
+export declare function createMcpFetchHandler(ctx: DevframeNodeContext, options: CreateMcpFetchHandlerOptions$1): McpFetchHandler$1;
+//#endregion
+//#region src/mcp/http.d.ts
+/**
+ * Mount a stateless MCP endpoint on an h3 app at `path`: the h3 binding over
+ * {@link createMcpFetchHandler}, which owns the per-request serving, the
+ * origin gate, and the transport plumbing.
+ *
+ * The handler is web-standard: it takes the h3 event's web `Request` and
+ * returns a web `Response` (an SSE `ReadableStream` body for a
+ * `subscriptions/listen` stream). We copy that response onto `event.res` and
+ * return its body rather than returning the `Response` object directly, so an
+ * MCP error response (e.g. a 4xx) isn't swallowed by h3's "Response-with-404
+ * falls through to the next handler" rule (which would otherwise hand the
+ * request to the SPA static catch-all).
+ */
+export declare function mountMcpHttp(app: H3, ctx: DevframeNodeContext, path: string, options: MountMcpHttpOptions$1): MountedMcpHttp$1;
+//#endregion
+export type { CreateMcpFetchHandlerOptions, CreateMcpServerOptions, McpConnectionInfo, McpFetchHandler, McpServerHandle, MountMcpHttpOptions, MountedMcpHttp };

package/dist/mcp/index.mjs

@@ -0,0 +1,464 @@
+import { homedir } from "node:os";
+import process from "node:process";
+import { Server, createMcpHandler } from "@modelcontextprotocol/server";
+import { DEVFRAME_EVENTS } from "devframe/constants";
+import { argsToJsonSchema, diagnostics, formatMcpError, returnToJsonSchema, stringifyForMcp } from "devframe/internal";
+import { createHostContext } from "devframe/node";
+import { toAgentToolName } from "devframe/utils/agent-tool-name";
+import { join } from "pathe";
+import { timingSafeEqual } from "devframe/utils/crypto-token";
+import { isAllowedOrigin, isLoopbackAddress } from "devframe/utils/origin";
+import { defineHandler, getRequestIP } from "h3";
+//#region src/mcp/build-server.ts
+/**
+* Build a fresh MCP {@link Server} over a devframe context, registering its
+* tool and resource handlers. This is a pure factory: it sets up no
+* long-lived subscriptions and holds no per-connection state, so it is safe
+* to call once per request under `createMcpHandler` or once per connection
+* under `serveStdio`. Change notifications are published separately: over
+* HTTP through the handler's `notify` bus (see `createMcpFetchHandler`), and
+* on stdio through the connection's own `send*ListChanged` calls (see
+* {@link bridgeListChanged}, wired by `serveStdio`).
+*
+* @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, options.exposeSharedState);
+	registerResourceHandlers(server, ctx, options.exposeSharedState);
+	return server;
+}
+/**
+* Publish devframe's `list_changed` events through a set of typed sinks:
+* `tools()` for tool-list changes and `resources()` for resource-list
+* changes (shared-state keys are surfaced as resources). Returns an
+* unsubscribe function.
+*
+* The HTTP path passes the handler's `notify` bus sugar; the stdio path
+* passes the pinned server's `send*ListChanged` methods, which `serveStdio`
+* routes onto the connection's active `subscriptions/listen` streams.
+*
+* @internal
+*/
+function bridgeListChanged(ctx, sinks) {
+	const offManifest = ctx.agent.events.on(DEVFRAME_EVENTS.bus.agentManifestChanged, () => {
+		sinks.tools();
+		sinks.resources();
+	});
+	const offKeyAdded = ctx.rpc.sharedState.onKeyAdded(() => {
+		sinks.resources();
+	});
+	return () => {
+		offManifest();
+		offKeyAdded();
+	};
+}
+/**
+* Build an MCP server over the agent surface of a devframe definition.
+* Currently supports `stdio` transport only.
+*/
+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) => {
+				if (scope === "workspace") return join(process.cwd(), ".devframe");
+				if (scope === "project") return join(process.cwd(), `node_modules/.${definition.id}/devframe`);
+				return join(homedir(), `.${definition.id}/devframe`);
+			}
+		},
+		importMetaUrl: definition.importMetaUrl
+	});
+	for (const input of definition.services ?? []) ctx.services.install(input, { resolveFrom: definition.importMetaUrl });
+	await ctx.services.ready();
+	await definition.setup(ctx);
+	const buildOptions = {
+		serverName: options.serverName ?? `${definition.id} (devframe)`,
+		serverVersion: options.serverVersion ?? definition.version ?? "0.0.0",
+		exposeSharedState: options.exposeSharedState ?? true
+	};
+	let handle;
+	try {
+		const { serveStdio } = await import("@modelcontextprotocol/server/stdio");
+		handle = serveStdio(() => {
+			const server = buildMcpServerFromContext(ctx, buildOptions);
+			const unbridge = bridgeListChanged(ctx, {
+				tools: () => {
+					server.sendToolListChanged().catch(() => {});
+				},
+				resources: () => {
+					server.sendResourceListChanged().catch(() => {});
+				}
+			});
+			const priorOnClose = server.onclose;
+			server.onclose = () => {
+				unbridge();
+				priorOnClose?.();
+			};
+			return 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() {
+		await handle.close();
+	} };
+}
+/**
+* Id of the built-in shared-state read tool, namespaced like every other
+* built-in (`devframe:<area>:<fn>`). Tool-shaped access matters because many
+* MCP clients only consume tools; the parallel `devframe://state/<key>`
+* resource projection stays for the clients that do read resources.
+*/
+const READ_STATE_TOOL = "devframe:state:read";
+/** Wire name of the built-in shared-state read tool: `devframe_state_read`. */
+const READ_STATE_NAME = toAgentToolName(READ_STATE_TOOL);
+function sharedStateFilter(exposeSharedState) {
+	if (exposeSharedState === false) return void 0;
+	return typeof exposeSharedState === "function" ? exposeSharedState : () => true;
+}
+function readStateToolProjection() {
+	return {
+		name: READ_STATE_NAME,
+		title: "Read shared state",
+		description: "Read this devtool's live shared state. Call without arguments to list the available keys, then with a key to get that value as JSON. Safe to call freely.",
+		inputSchema: {
+			type: "object",
+			properties: { key: {
+				type: "string",
+				description: "A shared-state key from the key list. Omit to list all keys."
+			} }
+		},
+		annotations: {
+			title: "Read shared state",
+			readOnlyHint: true,
+			destructiveHint: false
+		}
+	};
+}
+async function readStateResult(ctx, filter, key) {
+	const keys = ctx.rpc.sharedState.keys().filter(filter);
+	if (key === void 0) return { keys };
+	if (!keys.includes(key)) throw diagnostics.DF0048({ key });
+	return {
+		key,
+		value: (await ctx.rpc.sharedState.get(key)).value()
+	};
+}
+function registerToolHandlers(server, ctx, exposeSharedState) {
+	const stateFilter = sharedStateFilter(exposeSharedState);
+	const warnedCollisions = /* @__PURE__ */ new Set();
+	/**
+	* Resolve a wire tool name back to the registered {@link AgentTool}.
+	* Wire-name matching runs first, in manifest order (the same tool the
+	* list projection advertises under that name), with a raw-id fallback so
+	* a colon-namespaced id keeps working as a call name.
+	*/
+	const resolveTool = (name) => {
+		return ctx.agent.list().tools.find((tool) => toAgentToolName(tool.id) === name) ?? ctx.agent.getTool(name);
+	};
+	server.setRequestHandler("tools/list", async () => {
+		const byName = /* @__PURE__ */ new Map();
+		for (const tool of ctx.agent.list().tools) {
+			const name = toAgentToolName(tool.id);
+			const existing = byName.get(name);
+			if (existing) {
+				if (!warnedCollisions.has(`${name}|${tool.id}`)) {
+					warnedCollisions.add(`${name}|${tool.id}`);
+					diagnostics.DF0047({
+						name,
+						id: tool.id,
+						existing: existing.id
+					});
+				}
+				continue;
+			}
+			byName.set(name, tool);
+		}
+		const tools = [...byName.entries()].map(([name, tool]) => projectTool(name, tool, ctx));
+		if (stateFilter && !byName.has(READ_STATE_NAME)) tools.push(readStateToolProjection());
+		return { tools };
+	});
+	server.setRequestHandler("tools/call", async (request) => {
+		const { name, arguments: args } = request.params;
+		try {
+			const tool = resolveTool(name);
+			if (stateFilter && !tool && (name === READ_STATE_NAME || name === READ_STATE_TOOL)) {
+				const key = args?.key;
+				const result = await readStateResult(ctx, stateFilter, key);
+				return {
+					content: [{
+						type: "text",
+						text: stringifyForMcp(result)
+					}],
+					structuredContent: result
+				};
+			}
+			const outputSchema = tool ? usableOutputSchema(tool.outputSchema ?? computeOutputSchema(tool, ctx)) : void 0;
+			const result = await ctx.agent.invoke(tool?.id ?? name, args ?? {});
+			return {
+				content: [{
+					type: "text",
+					text: stringifyForMcp(result)
+				}],
+				...outputSchema ? { structuredContent: result } : {}
+			};
+		} catch (error) {
+			return {
+				isError: true,
+				content: [{
+					type: "text",
+					text: `Error invoking "${name}": ${formatMcpError(error)}`
+				}]
+			};
+		}
+	});
+}
+function registerResourceHandlers(server, ctx, exposeSharedState) {
+	const stateFilter = sharedStateFilter(exposeSharedState);
+	server.setRequestHandler("resources/list", async () => {
+		const resources = ctx.agent.list().resources.map((resource) => ({
+			uri: resource.uri,
+			name: resource.name,
+			description: resource.description,
+			mimeType: resource.mimeType
+		}));
+		if (stateFilter) for (const key of ctx.rpc.sharedState.keys()) {
+			if (!stateFilter(key)) continue;
+			resources.push({
+				uri: `devframe://state/${encodeURIComponent(key)}`,
+				name: key,
+				description: `Shared state: ${key}`,
+				mimeType: "application/json"
+			});
+		}
+		return { resources };
+	});
+	server.setRequestHandler("resources/read", 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") {
+			if (!stateFilter || !stateFilter(parsed.key)) throw diagnostics.DF0048({ key: parsed.key });
+			const state = await ctx.rpc.sharedState.get(parsed.key);
+			return { contents: [{
+				uri,
+				mimeType: "application/json",
+				text: stringifyForMcp(state.value())
+			}] };
+		}
+		throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`);
+	});
+}
+/**
+* MCP constrains a tool's `outputSchema` to a JSON Schema of `type:
+* "object"`; clients (the SDK included) reject anything else. Non-object
+* return schemas (e.g. a schema for `void` / a bare string) simply project
+* no output schema; the text content still carries the result.
+*/
+function usableOutputSchema(schema) {
+	return schema && typeof schema === "object" && schema.type === "object" ? schema : void 0;
+}
+function projectTool(name, tool, ctx) {
+	const inputSchema = tool.inputSchema ?? computeInputSchema(tool, ctx);
+	const outputSchema = usableOutputSchema(tool.outputSchema ?? computeOutputSchema(tool, ctx));
+	return {
+		name,
+		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 === "tool") return argsToJsonSchema(tool.args);
+	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 argsToJsonSchema(args);
+}
+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 returnToJsonSchema(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
+//#region src/mcp/fetch.ts
+/**
+* Parse exactly one `Authorization: Bearer <token>` credential, returning the
+* token or `undefined` for a missing, malformed, empty, or multi-credential
+* header. The token itself is never logged. `\S+` rejects the whitespace that
+* a second credential (fetch merges duplicate headers as `a, b`) or an empty
+* value would introduce.
+*/
+function parseBearerToken(header) {
+	if (!header) return void 0;
+	const match = /^Bearer (\S+)$/i.exec(header.trim());
+	return match ? match[1] : void 0;
+}
+/**
+* Resolve the identity gate for one request. `false` is the origin-only
+* opt-out; a callback delegates identity; a string requires a constant-time
+* bearer match. Never reveals whether a supplied token was close to correct.
+*/
+async function isAuthorized(req, authorization) {
+	if (authorization === false) return true;
+	if (typeof authorization === "function") return await authorization(req) === true;
+	const token = parseBearerToken(req.headers.get("authorization"));
+	if (token === void 0) return false;
+	return timingSafeEqual(token, authorization);
+}
+/**
+* Build a framework-agnostic MCP endpoint over a devframe context: a
+* web-standard `Request → Response` handler any host can mount: h3 (see
+* `mountMcpHttp`), a Next.js App Router route, or any other fetch-shaped
+* server.
+*
+* The endpoint is **stateless**: it serves the 2026-07-28 revision per request
+* through the SDK's {@link createMcpHandler}, which builds a fresh MCP server
+* (from the shared, live `ctx` via `buildMcpServerFromContext`) for each
+* request: no `Mcp-Session-Id` registry, no session-local routing, no
+* GET/DELETE teardown protocol. 2025-era clients are still served through the
+* SDK's default stateless legacy path. `list_changed` events reach modern
+* `subscriptions/listen` streams through the handler's `notify` bus.
+*
+* The origin gate guards every request: loopback-default DNS-rebinding
+* protection that (unlike the WS upgrade's `isAllowedOrigin`) also rejects
+* `Origin`-less requests, so a browser can't reach the route across origins (a
+* disallowed origin gets `403`). The `Origin` header is only browser hardening:
+* a non-browser client forges it. So on the zero-config default (no widened
+* `allowedOrigins`, no identity check) a second locality gate requires the
+* connected peer to be loopback, proven from the host-supplied
+* {@link McpConnectionInfo.remoteAddress} (which a client cannot forge), so the
+* "trusts same-machine callers" default holds against a remote raw client.
+* When same-machine isn't your trust boundary, add an identity gate
+* ({@link CreateMcpFetchHandlerOptions.authorization}), checked after the
+* origin gate: a bearer/callback check that proves *who* is calling (a
+* missing/invalid credential gets `401` with a `WWW-Authenticate: Bearer`
+* challenge), which also lifts the loopback-peer restriction for authenticated
+* callers.
+*/
+function createMcpFetchHandler(ctx, options) {
+	const allowedOrigins = options.allowedOrigins;
+	const authorization = options.authorization ?? false;
+	const handler = createMcpHandler(() => buildMcpServerFromContext(ctx, {
+		serverName: options.serverName,
+		serverVersion: options.serverVersion,
+		exposeSharedState: options.exposeSharedState
+	}));
+	const unbridge = bridgeListChanged(ctx, {
+		tools: () => {
+			handler.notify.toolsChanged();
+		},
+		resources: () => {
+			handler.notify.resourcesChanged();
+		}
+	});
+	const originOnlyDefault = allowedOrigins === void 0 && authorization === false;
+	async function handle(req, connection) {
+		const origin = req.headers.get("origin") ?? void 0;
+		if (allowedOrigins !== false && (origin === void 0 || !isAllowedOrigin(origin, allowedOrigins ?? []))) return new Response("Forbidden", { status: 403 });
+		if (originOnlyDefault && connection?.remoteAddress !== void 0 && !isLoopbackAddress(connection.remoteAddress)) return new Response("Forbidden", { status: 403 });
+		if (!await isAuthorized(req, authorization)) return new Response("Unauthorized", {
+			status: 401,
+			headers: { "WWW-Authenticate": "Bearer" }
+		});
+		return handler.fetch(req);
+	}
+	return {
+		fetch: handle,
+		dispose: async () => {
+			unbridge();
+			await handler.close();
+		}
+	};
+}
+//#endregion
+//#region src/mcp/http.ts
+/**
+* Mount a stateless MCP endpoint on an h3 app at `path`: the h3 binding over
+* {@link createMcpFetchHandler}, which owns the per-request serving, the
+* origin gate, and the transport plumbing.
+*
+* The handler is web-standard: it takes the h3 event's web `Request` and
+* returns a web `Response` (an SSE `ReadableStream` body for a
+* `subscriptions/listen` stream). We copy that response onto `event.res` and
+* return its body rather than returning the `Response` object directly, so an
+* MCP error response (e.g. a 4xx) isn't swallowed by h3's "Response-with-404
+* falls through to the next handler" rule (which would otherwise hand the
+* request to the SPA static catch-all).
+*/
+function mountMcpHttp(app, ctx, path, options) {
+	const handler = createMcpFetchHandler(ctx, options);
+	app.use(path, defineHandler(async (event) => respond(event, await handler.fetch(event.req, { remoteAddress: getRequestIP(event) }))));
+	return { dispose: handler.dispose };
+}
+/**
+* Copy a web `Response` from the MCP transport onto the h3 event's response
+* and return its body. Returning the body (a `ReadableStream` or `null`)
+* rather than the `Response` object avoids h3's 404-fall-through behavior.
+*/
+function respond(event, response) {
+	event.res.status = response.status;
+	event.res.statusText = response.statusText;
+	response.headers.forEach((value, key) => {
+		event.res.headers.set(key, value);
+	});
+	return response.body ?? "";
+}
+//#endregion
+export { createMcpFetchHandler, createMcpServer, mountMcpHttp };

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@devframes/agentic",
+  "type": "module",
+  "version": "0.9.19",
+  "description": "Agent-surface implementation for devframe: installing it next to devframe enables the MCP adapter (devframe/adapters/mcp) and the devframe connect gateway.",
+  "author": "Anthony Fu <anthonyfu117@hotmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/devframes/devframe#readme",
+  "repository": {
+    "directory": "packages/agentic",
+    "type": "git",
+    "url": "git+https://github.com/devframes/devframe.git"
+  },
+  "bugs": "https://github.com/devframes/devframe/issues",
+  "keywords": [
+    "devtools",
+    "devframe",
+    "mcp",
+    "agent"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./mcp": "./dist/mcp/index.mjs",
+    "./connect": "./dist/connect/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "devframe": "0.9.20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "h3": "^2.0.1-rc.31",
+    "pathe": "^2.0.3"
+  },
+  "devDependencies": {
+    "@standard-schema/spec": "^1.1.0",
+    "@types/node": "^26.5.1",
+    "devframe": "0.9.20",
+    "tsdown": "^0.23.0",
+    "valibot": "^1.5.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "watch": "tsdown --watch",
+    "typecheck": "tsc --noEmit"
+  }
+}