feat(devframe): ship @modelcontextprotocol/server as a regular dependency

Author: antfubot

docs/content/1.guide/15.agent-native.md

@@ -100,7 +100,7 @@ Every `ctx.rpc.sharedState` key is exposed as a `devframe://state/<key>` resourc
 
 ## Starting the MCP server
 
-The dev server serves the agent surface over HTTP on its own: the `mcp: 'auto'` default mounts the route at `/__mcp` once anything above exists (an `agent`-flagged RPC, a registered tool or resource) and `@modelcontextprotocol/server` is installed - one flagged function is the whole setup. See the [MCP adapter](/adapters/mcp#route-based-server) for forcing it on or off and hardening the route.
+The dev server serves the agent surface over HTTP on its own: the `mcp: 'auto'` default mounts the route at `/__mcp` once anything above exists (an `agent`-flagged RPC, a registered tool or resource) - one flagged function is the whole setup. See the [MCP adapter](/adapters/mcp#route-based-server) for forcing it on or off and hardening the route.
 
 For a stdio server instead, via the CLI:
 
@@ -120,8 +120,6 @@ const myDevframe = defineDevframe({ /* … */ })
 await createMcpServer(myDevframe, { transport: 'stdio' })
 ```
 
-`@modelcontextprotocol/server` is a peer dependency.
-
 ## Connecting Claude Desktop
 
 In `claude_desktop_config.json`:

docs/content/1.guide/index.md

@@ -114,7 +114,7 @@ The mounted devframes share one RPC registry, state store, connection, auth gate
 pnpm add devframe
 ```
 
-`devframe` ships ESM-only, no Vite dependency. Adapters with optional peers (the MCP adapter needs `@modelcontextprotocol/server`) surface the requirement at import time.
+`devframe` ships ESM-only, no Vite dependency. The CLI adapter's optional peer (`cac`) surfaces its requirement at import time.
 
 ## Hello, Devframe
 

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

@@ -14,13 +14,13 @@ import myDevframe from './my-tool'
 await createMcpServer(myDevframe, { transport: 'stdio' })
 ```
 
-`@modelcontextprotocol/server` is a peer dependency; `createMcpServer` serves `stdio` through the SDK's `serveStdio`, pinning one server instance per connection.
+`createMcpServer` serves `stdio` through the MCP SDK's `serveStdio`, pinning one server instance per connection.
 
 ## Route-based server
 
-The dev server exposes the same MCP API over HTTP, live. The default setting is **`'auto'`**: the route mounts once the devframe exposes an agent surface (an `agent`-flagged RPC, a registered tool or resource) and `@modelcontextprotocol/server` is installed - flag your first function and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code; a flagged surface whose peer is missing warns once ([`DF0077`](/errors/DF0077)) so you know what to install.
+The dev server exposes the same MCP API over HTTP, live. The default setting is **`'auto'`**: the route mounts once the devframe exposes an agent surface (an `agent`-flagged RPC, a registered tool or resource) - flag your first function and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code.
 
-Pin the behavior where you host the tool - it's a hosting decision, so pass `mcp` to `createCac` when you assemble the CLI (or to `createDevServer` / `initDevframe` / `initHub` when you host it programmatically): `true` always mounts (a missing peer becomes a startup failure, [`DF0017`](/errors/DF0017)), `false` never mounts, an object customises the route:
+Pin the behavior where you host the tool - it's a hosting decision, so pass `mcp` to `createCac` when you assemble the CLI (or to `createDevServer` / `initDevframe` / `initHub` when you host it programmatically): `true` always mounts, `false` never mounts, an object customises the route:
 
 ```ts
 import { createCac } from 'devframe/adapters/cac'

docs/content/2.adapters/index.md

@@ -7,7 +7,7 @@ description: 'The lowest-level path is the standard handler, initDevframe(def, {
 
 The lowest-level path is [the standard handler](/adapters/initiate), `initDevframe(def, { base })`: a Web Standard `(request: Request) => Promise<Response>` for any catch-all route. Every path below builds on it.
 
-Adapters wrap it as `createXxx(def, options?)` at `devframe/adapters/<name>`. `cac` and `mcp` need an optional peer ([`cac`](https://github.com/cacjs/cac), [`@modelcontextprotocol/server`](https://github.com/modelcontextprotocol/typescript-sdk)).
+Adapters wrap it as `createXxx(def, options?)` at `devframe/adapters/<name>`. `cac` needs an optional peer ([`cac`](https://github.com/cacjs/cac)).
 
 ## Comparison
 

docs/content/6.errors/DF0017.md

@@ -11,13 +11,13 @@ description: 'Failed to start MCP server ({transport}): {reason}'
 
 The MCP server failed while initializing. Common reasons:
 
-- The `@modelcontextprotocol/server` peer dependency is missing (the stdio and route-based transports both need it).
 - The stdio transport threw during `connect()` (e.g. stdin/stdout unavailable).
+- The MCP adapter module could not be loaded (e.g. a corrupted install missing `@modelcontextprotocol/server`).
 
 ## Fix
 
-- **Missing SDK**: `pnpm add @modelcontextprotocol/server` in the package that imports `devframe/adapters/mcp` or enables the `mcp` setting.
 - **Transport failure**: inspect the underlying error attached as `cause`.
+- **Broken install**: reinstall dependencies so `@modelcontextprotocol/server` (a dependency of `devframe`) resolves.
 
 ## Source
 

docs/content/6.errors/DF0046.md

@@ -1,22 +1,22 @@
 ---
 title: 'DF0046: Connector Requires the MCP SDK'
-description: 'devframe connect requires the optional peer dependency @modelcontextprotocol/server: {reason}'
+description: 'devframe connect requires the optional peer dependency @modelcontextprotocol/client: {reason}'
 ---
 
 ## Message
 
-> `devframe connect` requires the optional peer dependency @modelcontextprotocol/server: `{reason}`
+> `devframe connect` requires the optional peer dependency @modelcontextprotocol/client: `{reason}`
 
 ## Cause
 
-`devframe connect` was started but `@modelcontextprotocol/server` could not be imported. The SDK is an optional peer dependency of `devframe`, so it only needs to be installed where MCP features are used.
+`devframe connect` was started but `@modelcontextprotocol/client` could not be imported. The client SDK is an optional peer dependency of `devframe`: only the connector dials other instances, so only it needs the package installed.
 
 ## Fix
 
 Install the SDK next to devframe and run the connector again:
 
 ```sh
-npm install @modelcontextprotocol/server
+npm install @modelcontextprotocol/client
 devframe connect
 ```
 

docs/content/6.errors/DF0077.md

@@ -83,7 +83,6 @@ Emitted by `devframe`: the framework-neutral host, RPC, streaming, assets, servi
 | [DF0074](/errors/DF0074) | error | JSON-Render Schema Is Asynchronous |
 | [DF0075](/errors/DF0075) | warn | No RPC Transport On This Runtime |
 | [DF0076](/errors/DF0076) | error | WebSocket Upgrade Unsupported On This Runtime |
-| [DF0077](/errors/DF0077) | warn | Agent Surface Without the MCP Peer |
 
 ## Hub: context & lifecycle (DF80xx)
 

docs/content/6.errors/index.md

@@ -83,21 +83,18 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/client": "^2.0.0",
-    "@modelcontextprotocol/server": "^2.0.0",
     "cac": "^7.0.0"
   },
   "peerDependenciesMeta": {
     "@modelcontextprotocol/client": {
       "optional": true
     },
-    "@modelcontextprotocol/server": {
-      "optional": true
-    },
     "cac": {
       "optional": true
     }
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "catalog:deps",
     "@standard-schema/spec": "catalog:deps",
     "birpc": "catalog:deps",
     "crossws": "catalog:deps",
@@ -109,7 +106,6 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "catalog:deps",
-    "@modelcontextprotocol/server": "catalog:deps",
     "cac": "catalog:deps",
     "get-port-please": "catalog:deps",
     "immer": "catalog:deps",

packages/devframe/package.json

@@ -4,7 +4,6 @@ import type { DevframeDefinition, DevframeDeploymentKind, McpAuthorization, McpS
 import { getPort } from 'get-port-please'
 import { cleanDoubleSlashes, withLeadingSlash, withoutLeadingSlash, withTrailingSlash } from 'ufo'
 import { DEVFRAME_MCP_ROUTE } from '../constants'
-import { diagnostics } from '../node/diagnostics'
 import { importRuntimeModule } from '../node/import-runtime-module'
 
 const DEFAULT_PORT = 9999
@@ -100,38 +99,23 @@ export function resolveMcpConfig(mcp: McpSetting | undefined): ResolvedMcpConfig
   }
 }
 
-const autoMcpHinted = new Set<string>()
-
 /**
  * Resolve the `mcp: 'auto'` default at mount time: import the MCP adapter
  * when the devframe's agent surface is non-empty, or return `undefined`
  * (mount nothing) when the surface is empty - the zero-cost path, loading
- * no MCP code at all. A non-empty surface whose optional peer
- * (`@modelcontextprotocol/server`) fails to import also returns `undefined`,
- * warning `DF0077` once per instance id so the author discovers the agent
- * view exists.
+ * no MCP code at all. The adapter (and the MCP SDK behind it) loads through
+ * `importRuntimeModule`, so it never enters a consumer's bundle graph.
  *
  * Generic like `importRuntimeModule`: the caller names the module type
  * (`typeof import('devframe/adapters/mcp')`) so this shared helper carries
  * no type-level dependency on the MCP adapter.
  */
 export async function loadAutoMcpAdapter<T>(
   agent: Pick<DevframeAgentHost, 'hasSurface'>,
-  id: string,
 ): Promise<T | undefined> {
   if (!agent.hasSurface())
     return undefined
-  try {
-    return await importRuntimeModule<T>('devframe/adapters/mcp')
-  }
-  catch (error) {
-    if (!autoMcpHinted.has(id)) {
-      autoMcpHinted.add(id)
-      const reason = error instanceof Error ? error.message : String(error)
-      diagnostics.DF0077({ id, reason, cause: error })
-    }
-    return undefined
-  }
+  return await importRuntimeModule<T>('devframe/adapters/mcp')
 }
 
 /**