fix: keep optional MCP imports out of bundles (#285)

Author: onmax

package.json

@@ -48,6 +48,7 @@
     "@unocss/reset": "catalog:frontend",
     "bumpp": "catalog:tooling",
     "crossws": "catalog:deps",
+    "esbuild": "catalog:build",
     "eslint": "catalog:tooling",
     "h3": "catalog:deps",
     "knip": "catalog:tooling",

packages/devframe/src/adapters/cac.ts

@@ -12,6 +12,7 @@ import type { DevframeDefinition } from '../types/devframe'
 import process from 'node:process'
 import cac from 'cac'
 import { colors as c } from 'devframe/utils/colors'
+import { importRuntimeModule } from '../node/import-runtime-module'
 import { createBuild } from './build'
 import { createDevServer, resolveDevServerPort } from './dev'
 import { flagKeyToOption, isBooleanFlag, parseCliFlags } from './flags'
@@ -124,7 +125,7 @@ export function createCac(d: DevframeDefinition, options: CreateCacOptions = {})
       // MCP clients expect JSON-RPC on stdout — route welcome/logging
       // noise out of the way. Logs-SDK diagnostics land on stderr by
       // default, so nothing extra needed beyond not printing here.
-      const { createMcpServer } = await import('./mcp')
+      const { createMcpServer } = await importRuntimeModule<typeof import('./mcp')>('devframe/adapters/mcp')
       await createMcpServer(d, {
         transport: 'stdio',
         // Deliberately go to stderr: stdout is the MCP transport.

packages/devframe/src/adapters/initiate.ts

@@ -19,6 +19,7 @@ import { resolveClientAssets } from '../define'
 import { createHostContext } from '../node/context'
 import { diagnostics } from '../node/diagnostics'
 import { createH3DevframeHost } from '../node/host-h3'
+import { importRuntimeModule } from '../node/import-runtime-module'
 import { createInstanceShell, resolveInstanceRegister } from '../node/instance-shell'
 import { normalizeBasePath } from './_shared'
 import { resolveDevServerPort, resolveMcpConnectionMeta } from './dev'
@@ -311,7 +312,7 @@ export function initDevframe(
         const mcpPath = joinURL(base, mcpMeta.path)
         let mountMcpHttp: typeof import('./mcp/http').mountMcpHttp
         try {
-          ;({ mountMcpHttp } = await import('./mcp/http'))
+          ;({ mountMcpHttp } = await importRuntimeModule<typeof import('./mcp')>('devframe/adapters/mcp'))
         }
         catch (error) {
           const reason = error instanceof Error ? error.message : String(error)

packages/devframe/src/internal/index.ts

@@ -38,6 +38,7 @@ export type { AgentArgsFallback } from '../node/agent-args'
 export { diagnostics } from '../node/diagnostics'
 export { DevframeAgentHost } from '../node/host-agent'
 export * from '../node/host-h3'
+export { importRuntimeModule } from '../node/import-runtime-module'
 export { listLiveDevframeInstances, registerDevframeInstance } from '../node/instance-registry'
 export type { DevframeInstanceRecord, DevframeInstanceRegistration } from '../node/instance-registry'
 export { createInstanceShell, resolveInstanceRegister, samePath } from '../node/instance-shell'

packages/devframe/src/node/import-runtime-module.ts

@@ -0,0 +1,12 @@
+import { importServicePackage } from './services-install'
+
+/**
+ * Resolve and import a package at runtime without adding it to a consumer's
+ * bundle graph. First-party adapters use this for optional peers whose code
+ * is needed only when the matching feature is enabled.
+ *
+ * @internal
+ */
+export async function importRuntimeModule<T = unknown>(specifier: string): Promise<T> {
+  return await importServicePackage(specifier, [import.meta.url]) as T
+}

packages/hub/src/node/initiate.ts

@@ -12,7 +12,7 @@ import { existsSync } from 'node:fs'
 import { readFile } from 'node:fs/promises'
 import process from 'node:process'
 import { DEVFRAME_CONNECTION_META_FILENAME, DEVFRAME_DOCK_IMPORTS_FILENAME, DEVFRAME_MCP_ROUTE, DEVFRAME_WS_ROUTE } from 'devframe/constants'
-import { createH3DevframeHost, createInstanceShell, resolveInstanceRegister } from 'devframe/internal'
+import { createH3DevframeHost, createInstanceShell, importRuntimeModule, resolveInstanceRegister } from 'devframe/internal'
 import { mountStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 import { resolve } from 'pathe'
@@ -571,7 +571,7 @@ export function initHub(options: InitHubOptions): HubInstance {
         return { context: ctx }
 
       const mcpRoute = withoutLeadingSlash(mcpConfig.path ?? DEVFRAME_MCP_ROUTE)
-      const { mountMcpHttp } = await import('devframe/adapters/mcp')
+      const { mountMcpHttp } = await importRuntimeModule<typeof import('devframe/adapters/mcp')>('devframe/adapters/mcp')
       const mounted = mountMcpHttp(app, ctx, joinURL(base, mcpRoute), {
         serverName: options.name ?? 'devframes-hub',
         serverVersion: options.version ?? '0.0.0',

packages/next/src/host.ts

@@ -1,5 +1,6 @@
 import type { ConnectionMeta, DevframeHost, DevframeNodeContext, DevframeStorageScope } from 'devframe'
 import { DEVFRAME_CONNECTION_META_FILENAME } from 'devframe/constants'
+import { importRuntimeModule } from 'devframe/internal'
 import { serveStaticHandler } from 'devframe/utils/serve-static'
 import { H3 } from 'h3'
 
@@ -163,7 +164,7 @@ export function createDevframeNextHost(
       connectionMeta = meta
     },
     async mountMcp(ctx, path, mcpOptions = {}) {
-      const { createMcpFetchHandler } = await import('devframe/adapters/mcp')
+      const { createMcpFetchHandler } = await importRuntimeModule<typeof import('devframe/adapters/mcp')>('devframe/adapters/mcp')
       const handler = createMcpFetchHandler(ctx, {
         serverName: mcpOptions.serverName ?? 'devframe (next)',
         serverVersion: mcpOptions.serverVersion ?? '0.0.0',

pnpm-lock.yaml

@@ -90,6 +90,7 @@ catalogs:
     '@sveltejs/adapter-node': ^5.3.3
     '@sveltejs/kit': ^2.46.4
     '@vitejs/plugin-vue': ^6.0.8
+    esbuild: ^0.28.0
     lightningcss: ^1.33.0
     magic-string: ^1.2.0
     mlly: ^1.8.2

pnpm-workspace.yaml

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