refactor: lazy-load agentic inside the devframe/adapters/mcp functions

Replaces the alias's top-level await with a per-function lazy import:
importing the entry is now side-effect-free (DF0079 moves to call time),
and without TLA the entry rejoins the main server build graph, dropping
the isolated tsdown config. createMcpFetchHandler and mountMcpHttp become
async through this entry; the migration guide covers the added await.

Author: antfubot

docs/content/6.errors/DF0079.md

@@ -9,7 +9,7 @@ description: 'The mcp option is enabled, but the optional peer "@devframes/agent
 
 ## Cause
 
-An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface - or `devframe/adapters/mcp` was imported directly - but the implementation could not be loaded from the optional `@devframes/agentic` peer, typically because it is not installed. Unlike the omitted `'auto'` default (which degrades to a one-time [DF0078](/errors/DF0078) warning), an explicit opt-in fails fast rather than silently running without MCP.
+An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface - or a `devframe/adapters/mcp` function was called - but the implementation could not be loaded from the optional `@devframes/agentic` peer, typically because it is not installed. Unlike the omitted `'auto'` default (which degrades to a one-time [DF0078](/errors/DF0078) warning), an explicit opt-in fails fast rather than silently running without MCP.
 
 ## Fix
 

docs/content/7.migrations/1.migration-0.10.md

@@ -21,9 +21,16 @@ Every surface reacts to the missing peer the same way:
 | `true` / route options object | always mounts | throws [DF0079](/errors/DF0079) |
 | `false` | never mounts, never probes | same |
 
-Importing `devframe/adapters/mcp` itself without the peer also throws [DF0079](/errors/DF0079). This applies everywhere the `mcp` setting exists: `createCac` / `--mcp`, `createDevServer`, `initDevframe`, `initHub`'s aggregate endpoint, and the framework kits.
+Calling a `devframe/adapters/mcp` function without the peer also throws [DF0079](/errors/DF0079); the import itself stays side-effect-free and loads no MCP code. This applies everywhere the `mcp` setting exists: `createCac` / `--mcp`, `createDevServer`, `initDevframe`, `initHub`'s aggregate endpoint, and the framework kits.
 
-The exports are unchanged: `createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`, and their option types (the option and handle types are also importable from `devframe/types`). The `<your-app> mcp` stdio subcommand keeps working with the peer installed.
+The exports keep their names and option types (also importable from `devframe/types`): `createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`. The latter two are now **async** - they await the lazy peer load - so add an `await` where you called them synchronously:
+
+```diff
+- const handler = createMcpFetchHandler(ctx, options)
++ const handler = await createMcpFetchHandler(ctx, options)
+```
+
+The `<your-app> mcp` stdio subcommand keeps working with the peer installed.
 
 ## `devframe connect` requires `@devframes/agentic`
 

packages/devframe/src/adapters/mcp.ts

@@ -1,8 +1,16 @@
 // The user-facing MCP adapter entry. The implementation (and the MCP SDK)
 // lives in the optional `@devframes/agentic` peer, which is never imported
-// directly: this entry lazy-loads it (throwing a coded DF0079 when the peer
-// is not installed) and re-exports the surface, typed against devframe's own
-// contract in `types/mcp.ts`.
+// directly: each function lazy-loads it on first call (throwing a coded
+// DF0079 when the peer is not installed), so importing this entry stays
+// side-effect-free and loads no MCP code. Signatures are typed against
+// devframe's own contract in `types/mcp.ts`; `createMcpFetchHandler` and
+// `mountMcpHttp` are async here (they await the lazy load), unlike the
+// synchronous implementations behind them.
+import type { H3 } from 'h3'
+import type { MountedMcpHttp, MountMcpHttpOptions } from '../node/agentic'
+import type { DevframeNodeContext } from '../types/context'
+import type { DevframeDefinition } from '../types/devframe'
+import type { CreateMcpFetchHandlerOptions, CreateMcpServerOptions, McpFetchHandler, McpServerHandle } from '../types/mcp'
 import { importAgenticMcp } from '../node/agentic'
 
 export type { MountedMcpHttp, MountMcpHttpOptions } from '../node/agentic'
@@ -14,12 +22,31 @@ export type {
   McpServerHandle,
 } from '../types/mcp'
 
-// The alias must resolve its exports at module evaluation (they are consumed
-// as plain named imports), so the lazy load is a deliberate top-level await;
-// it builds in its own graph (see tsdown.config.ts) to keep TLA contained.
-// eslint-disable-next-line antfu/no-top-level-await
-const mcp = await importAgenticMcp()
+/** Build an MCP server over the agent surface of a devframe definition (stdio). */
+export async function createMcpServer(
+  definition: DevframeDefinition,
+  options?: CreateMcpServerOptions,
+): Promise<McpServerHandle> {
+  const mcp = await importAgenticMcp()
+  return mcp.createMcpServer(definition, options)
+}
 
-export const createMcpServer = mcp.createMcpServer
-export const createMcpFetchHandler = mcp.createMcpFetchHandler
-export const mountMcpHttp = mcp.mountMcpHttp
+/** Build a framework-agnostic `Request → Response` MCP endpoint over a devframe context. */
+export async function createMcpFetchHandler(
+  ctx: DevframeNodeContext,
+  options: CreateMcpFetchHandlerOptions,
+): Promise<McpFetchHandler> {
+  const mcp = await importAgenticMcp()
+  return mcp.createMcpFetchHandler(ctx, options)
+}
+
+/** Mount a stateless MCP endpoint on an h3 app at `path`. */
+export async function mountMcpHttp(
+  app: H3,
+  ctx: DevframeNodeContext,
+  path: string,
+  options: MountMcpHttpOptions,
+): Promise<MountedMcpHttp> {
+  const mcp = await importAgenticMcp()
+  return mcp.mountMcpHttp(app, ctx, path, options)
+}

packages/devframe/tsdown.config.ts

@@ -116,13 +116,14 @@ const serverEntries = {
   'adapters/build': 'src/adapters/build.ts',
   'adapters/embedded': 'src/adapters/embedded.ts',
   'adapters/initiate': 'src/adapters/initiate.ts',
+  'adapters/mcp': 'src/adapters/mcp.ts',
   'cli/main': 'src/cli/main.ts',
   'recipes/common-rpc-functions': 'src/recipes/common-rpc-functions.ts',
   'recipes/interactive-auth': 'src/recipes/interactive-auth.ts',
 }
 
 /**
- * Four configs:
+ * Three configs:
  *
  * 1. Runtime client/agnostic build (`dts: false`). Independent rolldown
  * chunk graph so server-only imports like `devframe/rpc/transports/ws-server`
@@ -136,11 +137,6 @@ const serverEntries = {
  * `src/types/rpc-augments.ts`, produce exactly one declaration site.
  * This is what lets consumer `declare module 'devframe'` augmentations
  * propagate across every import chain.
- * 4. The `adapters/mcp` alias, alone. Its top-level `await` (lazy-loading
- * `@devframes/agentic/mcp` at module evaluation) would otherwise reshape
- * the server graph's chunking - every sibling entry turns into async-safe
- * re-export facades. An isolated graph keeps the TLA contained; the few
- * helpers it inlines are duplicated only here.
  */
 export default defineConfig([
   {
@@ -195,14 +191,6 @@ export default defineConfig([
     deps,
     dts: { emitDtsOnly: true },
     outExtensions: () => ({ dts: '.d.mts' }),
-    entry: { ...clientEntries, ...serverEntries, 'adapters/mcp': 'src/adapters/mcp.ts' },
-  },
-  {
-    clean: false,
-    platform: 'node',
-    tsconfig,
-    deps: nodeDeps,
-    dts: false,
-    entry: { 'adapters/mcp': 'src/adapters/mcp.ts' },
+    entry: { ...clientEntries, ...serverEntries },
   },
 ])

tests/__snapshots__/tsnapi/devframe/adapters/mcp.snapshot.d.ts

@@ -1,10 +1,10 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe/adapters/mcp`
  */
-// #region Variables
-export declare const createMcpFetchHandler: (ctx: DevframeNodeContext, options: CreateMcpFetchHandlerOptions) => McpFetchHandler;
-export declare const createMcpServer: (definition: DevframeDefinition, options?: CreateMcpServerOptions) => Promise<McpServerHandle>;
-export declare const mountMcpHttp: (app: import("h3").H3, ctx: DevframeNodeContext, path: string, options: MountMcpHttpOptions) => MountedMcpHttp;
+// #region Functions
+export declare function createMcpFetchHandler(_: DevframeNodeContext, _: CreateMcpFetchHandlerOptions): Promise<McpFetchHandler>;
+export declare function createMcpServer(_: DevframeDefinition, _?: CreateMcpServerOptions): Promise<McpServerHandle>;
+export declare function mountMcpHttp(_: H3, _: DevframeNodeContext, _: string, _: MountMcpHttpOptions): Promise<MountedMcpHttp>;
 // #endregion
 
 // #region Other

tests/__snapshots__/tsnapi/devframe/adapters/mcp.snapshot.js

@@ -1,8 +1,8 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe/adapters/mcp`
  */
-// #region Variables
-export var createMcpFetchHandler /* const */
-export var createMcpServer /* const */
-export var mountMcpHttp /* const */
+// #region Functions
+export async function createMcpFetchHandler(_, _) {}
+export async function createMcpServer(_, _) {}
+export async function mountMcpHttp(_, _, _, _) {}
 // #endregion

tests/optional-mcp-bundles.test.ts

@@ -9,6 +9,7 @@ const root = fileURLToPath(new URL('..', import.meta.url))
 const entries = [
   'packages/devframe/dist/adapters/cac.mjs',
   'packages/devframe/dist/adapters/initiate.mjs',
+  'packages/devframe/dist/adapters/mcp.mjs',
   'packages/hub/dist/node/initiate.mjs',
   'packages/next/dist/hub.mjs',
 ]