feat!: move the MCP adapter into the optional @devframes/agentic peer

The MCP adapter, the connect gateway, and the MCP SDK behind them move out
of devframe into the new @devframes/agentic package, an optional peer of
devframe and @devframes/hub. devframe stays slim; installing the peer is
what turns the agent surface on.

- @devframes/agentic ships /mcp (createMcpServer, createMcpFetchHandler,
  mountMcpHttp) and /connect (the devframe connect gateway); the bare root
  throws. Signatures are typed against devframe's own contract, so no SDK
  type leaks and the SDK stays swappable.
- The mcp enable matrix: 'auto' mounts iff the agent surface is non-empty
  AND the peer resolves (missing peer: one DF0078 warning per process); an
  explicit setting throws DF0079 without the peer; false stays silent.
- devframe/adapters/mcp keeps working as an alias for @devframes/agentic/mcp
  (same exports; throws DF0079 when the peer is absent), built in its own
  graph so its top-level await cannot reshape the server chunking.
- Pure agent projections (to-json-schema, stringify) stay in devframe under
  src/agent/, shared by browser WebMCP and agentic via devframe/internal.
- devframe drops @modelcontextprotocol/server (dep) and /client (optional
  peer); DF0046 now points at @devframes/agentic.

Author: antfubot

alias.ts

@@ -47,7 +47,10 @@ export const alias = {
   'devframe/adapters/build': r('devframe/src/adapters/build.ts'),
   'devframe/adapters/embedded': r('devframe/src/adapters/embedded.ts'),
   'devframe/initiate': r('devframe/src/adapters/initiate.ts'),
-  'devframe/adapters/mcp': r('devframe/src/adapters/mcp/index.ts'),
+  'devframe/adapters/mcp': r('devframe/src/adapters/mcp.ts'),
+  '@devframes/agentic/mcp': r('agentic/src/mcp/index.ts'),
+  '@devframes/agentic/connect': r('agentic/src/connect/index.ts'),
+  '@devframes/agentic': r('agentic/src/index.ts'),
   '@devframes/hub/build': r('hub/src/node/build.ts'),
   '@devframes/hub/client': r('hub/src/client/index.ts'),
   '@devframes/hub/constants': r('hub/src/constants.ts'),

docs/content/1.guide/10.standalone-cli.md

@@ -274,7 +274,7 @@ version.on('updated', () => fetchPayload().then(setData))
 
 ## Use your own CLI framework
 
-Own a CLI framework (commander, yargs, oclif)? Use the three factories `createCac` wraps against one `DevframeDefinition`: `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`devframe/adapters/mcp`); see the [CLI adapter](/adapters/cac#use-your-own-cli-framework).
+Own a CLI framework (commander, yargs, oclif)? Use the three factories `createCac` wraps against one `DevframeDefinition`: `createDevServer` (`devframe/adapters/dev`), `createBuild` (`devframe/adapters/build`), and `createMcpServer` (`@devframes/agentic/mcp`); see the [CLI adapter](/adapters/cac#use-your-own-cli-framework).
 
 ```ts [src/cli.ts]
 import process from 'node:process'

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

@@ -9,7 +9,7 @@ Devframe exposes its API (RPC functions, resources, shared state) to agents, ove
 
 ## How it works
 
-Three pieces: the **`agent` field** on `defineRpcFunction`, **`ctx.agent`** (non-RPC tools + resources), and the **MCP adapter** (`devframe/adapters/mcp`) serving an [MCP](https://modelcontextprotocol.io) server. The same `agent` field on a *client* RPC function surfaces it [over WebMCP](#browser-side-tools-over-webmcp) instead.
+Three pieces: the **`agent` field** on `defineRpcFunction`, **`ctx.agent`** (non-RPC tools + resources), and the **MCP adapter** (`@devframes/agentic/mcp`) serving an [MCP](https://modelcontextprotocol.io) server. The same `agent` field on a *client* RPC function surfaces it [over WebMCP](#browser-side-tools-over-webmcp) instead.
 
 ## Exposing an RPC function
 
@@ -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) - 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) and the optional [`@devframes/agentic`](/adapters/mcp) peer is installed - one flagged function plus one install 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:
 
@@ -112,8 +112,8 @@ devframe mcp
 Programmatically:
 
 ```ts
+import { createMcpServer } from '@devframes/agentic/mcp'
 import { defineDevframe } from 'devframe'
-import { createMcpServer } from 'devframe/adapters/mcp'
 
 const myDevframe = defineDevframe({ /* … */ })
 

docs/content/1.guide/index.md

@@ -63,11 +63,11 @@ The handler serves the web interface, connection metadata, live RPC, authenticat
 [Higher-level adapters](/adapters) package the foundation as a standalone CLI, dev server, Vite DevTools plugin, MCP server, or static report:
 
 ```ts
+import { createMcpServer } from '@devframes/agentic/mcp'
 import { createPluginFromDevframe } from '@vitejs/devtools-kit/node'
 import { createBuild } from 'devframe/adapters/build'
 import { createCac } from 'devframe/adapters/cac'
 import { createDevServer } from 'devframe/adapters/dev'
-import { createMcpServer } from 'devframe/adapters/mcp'
 import devframe from './devframe'
 
 /** Pick the entry points your package ships: */

docs/content/2.adapters/2.cac.md

@@ -104,7 +104,7 @@ Peer factories for a commander/yargs program:
 |----------------|-------|---------|
 | [`createDevServer()`](/adapters/dev) | `devframe/adapters/dev` | h3 + WebSocket RPC + SPA mount |
 | [`createBuild()`](/adapters/build) | `devframe/adapters/build` | Static deploy |
-| [`createMcpServer()`](/adapters/mcp) | `devframe/adapters/mcp` | stdio MCP server |
+| [`createMcpServer()`](/adapters/mcp) | `@devframes/agentic/mcp` | stdio MCP server |
 | `parseCliFlags(schema, raw)` | `devframe/adapters/cac` | Validate flags (`CliFlagsSchema`) |
 
 See the [Standalone CLI guide](/guide/standalone-cli#use-your-own-cli-framework).

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

@@ -7,18 +7,26 @@ description: 'Exposes a devframe''s agent-facing API as a Model Context Protocol
 
 Exposes a devframe's agent-facing API as a [Model Context Protocol](https://modelcontextprotocol.io) server: coding agents call flagged RPCs and read resources.
 
+The adapter lives in **`@devframes/agentic`**, an optional peer of `devframe` that carries the MCP SDK, so a devframe without an agent surface ships with neither installed:
+
+```sh
+npm install @devframes/agentic
+```
+
 ```ts
-import { createMcpServer } from 'devframe/adapters/mcp'
+import { createMcpServer } from '@devframes/agentic/mcp'
 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.
 
+`devframe/adapters/mcp` still resolves as an alias for `@devframes/agentic/mcp` with the same exports; it requires the peer to be installed (importing it without throws [DF0079](/errors/DF0079)).
+
 ## 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) - flag your first function and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code.
+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* `@devframes/agentic` is installed - flag your first function, install the peer, and the agent view is on. A devframe with nothing flagged mounts no route and loads no MCP code; an agent surface without the peer warns once ([DF0078](/errors/DF0078)) and mounts nothing, while an explicit `mcp` setting without the peer throws ([DF0079](/errors/DF0079)). `mcp: false` stays silent either way.
 
 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:
 
@@ -72,7 +80,7 @@ Both honor the same contract: omitted is `'auto'`, `true` forces the origin-only
 `createMcpFetchHandler(ctx, options)` returns the endpoint as a `Request → Response` handler plus a `dispose()`; mount it on any fetch server.
 
 ```ts
-import { createMcpFetchHandler } from 'devframe/adapters/mcp'
+import { createMcpFetchHandler } from '@devframes/agentic/mcp'
 
 const mcp = createMcpFetchHandler(ctx, {
   serverName: 'my-tool (devframe)',
@@ -103,6 +111,8 @@ Two gateway tools (`devframe:connect:*` ids; see [tool ids and wire names](/guid
 
 Discovery reads the **instance registry**: every `createDevServer` writes `~/.devframe/instances/<pid>-<port>.json`, dialed with a loopback origin. In-process host frameworks register via `registerDevframeInstance` (`devframe/node`). `--port <n>` probes a port; `DEVFRAME_INSTANCES_DIR` relocates the registry, `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts out.
 
-Most instances trust same-machine callers, so the connector reaches them with no credential. For an instance you *hardened* with a bearer, the connector reads `DEVFRAME_MCP_AUTH_TOKEN` and presents it (never a CLI flag, since command-line arguments are visible to other processes). Connect to a fleet with distinct credentials by driving `startConnectServer` with a per-instance `authToken` resolver.
+The connector's gateway lives in `@devframes/agentic/connect` (the same optional peer as the adapter; `devframe connect` without it throws [DF0046](/errors/DF0046)).
+
+Most instances trust same-machine callers, so the connector reaches them with no credential. For an instance you *hardened* with a bearer, the connector reads `DEVFRAME_MCP_AUTH_TOKEN` and presents it (never a CLI flag, since command-line arguments are visible to other processes). Connect to a fleet with distinct credentials by driving `startConnectServer` (`@devframes/agentic/connect`) with a per-instance `authToken` resolver.
 
 See [Agent-Native](/guide/agent-native) for the API and safety model.

docs/content/2.adapters/index.md

@@ -19,7 +19,7 @@ Adapters wrap it as `createXxx(def, options?)` at `devframe/adapters/<name>`. `c
 | [`build`](/adapters/build) | `devframe/adapters/build` | `createBuild()` | Static snapshots |
 | [`vite`](/adapters/vite) | `@vitejs/devtools-kit/node` | `createPluginFromDevframe()` | Vite DevTools |
 | [`embedded`](/adapters/embedded) | `devframe/adapters/embedded` | `createEmbedded(def, { ctx })` | Runtime |
-| [`mcp`](/adapters/mcp) | `devframe/adapters/mcp` | `createMcpServer()` | Coding agents |
+| [`mcp`](/adapters/mcp) | `@devframes/agentic/mcp` | `createMcpServer()` | Coding agents |
 
 ## Mount paths
 

docs/content/6.errors/DF0046.md

@@ -1,25 +1,25 @@
 ---
-title: 'DF0046: Connector Requires the MCP SDK'
-description: 'devframe connect requires the optional peer dependency @modelcontextprotocol/client: {reason}'
+title: 'DF0046: Connector Requires @devframes/agentic'
+description: 'devframe connect requires the optional peer dependency @devframes/agentic: {reason}'
 ---
 
 ## Message
 
-> `devframe connect` requires the optional peer dependency @modelcontextprotocol/client: `{reason}`
+> `devframe connect` requires the optional peer dependency @devframes/agentic: `{reason}`
 
 ## Cause
 
-`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.
+`devframe connect` was started but `@devframes/agentic/connect` could not be imported. The connector lives in `@devframes/agentic` (together with the MCP SDK), an optional peer dependency of `devframe`: only agent-facing features need the package installed.
 
 ## Fix
 
-Install the SDK next to devframe and run the connector again:
+Install the package next to devframe and run the connector again:
 
 ```sh
-npm install @modelcontextprotocol/client
+npm install @devframes/agentic
 devframe connect
 ```
 
 ## Source
 
-- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts): `startConnectServer()` throws this when the dynamic SDK import fails.
+- [`packages/devframe/src/cli/main.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/main.ts): the `connect` subcommand throws this when the dynamic `@devframes/agentic/connect` import fails.

docs/content/6.errors/DF0078.md

@@ -0,0 +1,28 @@
+---
+title: 'DF0078: Agent Surface Without @devframes/agentic'
+description: 'This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.'
+---
+
+## Message
+
+> This devframe exposes agent tools, but the MCP endpoint stays off: the optional peer "@devframes/agentic" is not installed.
+
+## Cause
+
+The devframe (or hub) left a non-empty agent surface (RPC functions with an `agent` field, registered agent tools, resources, or providers) and the `mcp` setting is the omitted `'auto'` default, which would mount the MCP route. But `@devframes/agentic`, the optional peer carrying the MCP adapter and the MCP SDK, is not installed, so no route can be served.
+
+The warning is reported once per process; the instance keeps running without an MCP endpoint.
+
+## Fix
+
+Install the peer so the agent surface is served over MCP:
+
+```sh
+npm install @devframes/agentic
+```
+
+Or, if the tools should deliberately stay unexposed, set `mcp: false` to opt out silently.
+
+## Source
+
+- [`packages/devframe/src/adapters/_shared.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/_shared.ts): `loadAutoMcpAdapter()` reports this (once) when the agent surface is non-empty but the peer probe fails.

docs/content/6.errors/DF0079.md

@@ -0,0 +1,26 @@
+---
+title: 'DF0079: MCP Enabled Without @devframes/agentic'
+description: 'The mcp option is enabled, but the optional peer "@devframes/agentic" could not be loaded: {reason}'
+---
+
+## Message
+
+> The `mcp` option is enabled, but the optional peer "@devframes/agentic" could not be loaded: `{reason}`
+
+## Cause
+
+An explicit `mcp` setting (`true`, a route options object, the `--mcp` flag, or the `mcp` CLI subcommand) asked for an MCP surface, but `@devframes/agentic/mcp` could not be imported, typically because the optional peer 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
+
+Install the peer next to devframe:
+
+```sh
+npm install @devframes/agentic
+```
+
+Or remove the explicit `mcp` setting (or pass `mcp: false`) if the endpoint isn't wanted. The underlying import error is attached as `cause`.
+
+## Source
+
+- [`packages/devframe/src/node/agentic.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/agentic.ts): `importAgenticMcp()` maps a failed load of `@devframes/agentic/mcp` to this error.