refactor: make devframe/adapters/mcp a static re-export of the agentic peer

Replaces the per-function lazy import with a plain re-export of
@devframes/agentic/mcp, keeping the implementation's synchronous
signatures. Importing the entry without the peer now throws
module-not-found, matching the devframe/adapters/cac precedent for
optional peers; first-party adapters keep the coded DF0078/DF0079
lazy-load path.

Author: antfubot

docs/content/2.adapters/7.mcp.md

@@ -20,7 +20,7 @@ import myDevframe from './my-tool'
 await createMcpServer(myDevframe, { transport: 'stdio' })
 ```
 
-`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection. Importing `devframe/adapters/mcp` without the peer installed throws [DF0079](/errors/DF0079).
+`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection. Importing `devframe/adapters/mcp` without the peer installed throws the usual module-not-found error, exactly like `devframe/adapters/cac` with its optional `cac` peer.
 
 ## Route-based server
 

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 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.
+An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface, 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,16 +21,9 @@ 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 |
 
-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.
+This applies everywhere the `mcp` setting exists: `createCac` / `--mcp`, `createDevServer`, `initDevframe`, `initHub`'s aggregate endpoint, and the framework kits.
 
-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.
+The exports are unchanged - `createMcpServer`, `createMcpFetchHandler`, `mountMcpHttp`, and their option types (also importable from `devframe/types`). Importing `devframe/adapters/mcp` without the peer installed throws the usual module-not-found error, exactly like `devframe/adapters/cac` with its optional `cac` peer. The `<your-app> mcp` stdio subcommand keeps working with the peer installed.
 
 ## `devframe connect` requires `@devframes/agentic`
 

knip.jsonc

@@ -71,11 +71,7 @@
       // `import()` carrying `webpackIgnore`/`turbopackIgnore` comments -
       // deliberately invisible to bundlers (and knip) so Next never inlines
       // their node-only code. They're genuinely used at runtime.
-      // `@devframes/agentic` is install-only: devframe probes and loads it
-      // through `importRuntimeModule` string specifiers to serve the hub's
-      // aggregate MCP endpoint; it is never statically imported.
       "ignoreDependencies": [
-        "@devframes/agentic",
         "@devframes/plugin-a11y",
         "@devframes/plugin-code-server",
         "@devframes/plugin-git",
@@ -107,10 +103,7 @@
       // dock's `action.importFrom` bare specifier, resolved by Vite through
       // the hub's `clientModuleResolution` template (`/@id/{specifier}`),
       // never a static import knip's graph can see.
-      // `@devframes/agentic` is install-only: devframe probes and loads it
-      // through `importRuntimeModule` string specifiers to serve the hub's
-      // aggregate MCP endpoint; it is never statically imported.
-      "ignoreDependencies": ["@devframes/agentic", "demo-dock-client"]
+      "ignoreDependencies": ["demo-dock-client"]
     },
     // Multi-entry example package (see `packages/devframe` above for why
     // exports-mapped entries are listed explicitly): `src/index.ts` is the
@@ -133,12 +126,6 @@
       "entry": ["src/server.ts"]
     },
     "packages/devframe": {
-      // `@devframes/agentic` (devframe's own optional peer) is loaded only
-      // through `importRuntimeModule('@devframes/agentic/...')` string
-      // specifiers and a `require.resolve` probe (`src/node/agentic.ts`),
-      // never a static import knip's graph can see; the devDependency is
-      // what lets tests exercise the installed-peer path.
-      "ignoreDependencies": ["@devframes/agentic"],
       // Every `package.json#exports` subpath maps to one of these source
       // files (see `tsdown.config.ts`'s `serverEntries`/`clientEntries`).
       // Knip's package.json→dist→src source mapping needs `outDir` set on

packages/devframe/src/adapters/mcp.ts

@@ -1,18 +1,8 @@
-// The user-facing MCP adapter entry. The implementation (and the MCP SDK)
-// lives in the optional `@devframes/agentic` peer, which is never imported
-// 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'
-
+// The user-facing MCP adapter entry: a re-export of the implementation in
+// the optional `@devframes/agentic` peer (which also carries the MCP SDK).
+// Like `devframe/adapters/cac` with its optional `cac` peer, importing it
+// without the peer throws module-not-found. First-party adapters lazy-load
+// the peer through `node/agentic.ts` (DF0078/DF0079) instead.
 export type { MountedMcpHttp, MountMcpHttpOptions } from '../node/agentic'
 export type {
   CreateMcpFetchHandlerOptions,
@@ -21,32 +11,4 @@ export type {
   McpFetchHandler,
   McpServerHandle,
 } from '../types/mcp'
-
-/** 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)
-}
-
-/** 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)
-}
+export { createMcpFetchHandler, createMcpServer, mountMcpHttp } from '@devframes/agentic/mcp'

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

@@ -1,18 +1,15 @@
 /**
  * Generated by tsnapi — public API snapshot of `devframe/adapters/mcp`
  */
-// #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
+export { createMcpFetchHandler }
 export { CreateMcpFetchHandlerOptions }
+export { createMcpServer }
 export { CreateMcpServerOptions }
 export { McpConnectionInfo }
 export { McpFetchHandler }
 export { McpServerHandle }
 export { MountedMcpHttp }
+export { mountMcpHttp }
 export { MountMcpHttpOptions }
 // #endregion

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

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

tests/optional-mcp-bundles.test.ts

@@ -6,10 +6,13 @@ import { build } from 'esbuild'
 import { afterEach, describe, expect, it } from 'vitest'
 
 const root = fileURLToPath(new URL('..', import.meta.url))
+// `packages/devframe/dist/adapters/mcp.mjs` is deliberately absent: that
+// entry is a static re-export of `@devframes/agentic/mcp` (like
+// `adapters/cac` with its optional `cac` peer), so it resolves the peer by
+// design; only implicit paths must stay lazy.
 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',
 ]