feat(agent): agent-native wave phase 3 — instance registry, devframe connect, in-process Next MCP

- instance registry: registerDevframeInstance/readDevframeInstances/
  probeDevframeInstance/listLiveDevframeInstances in devframe/node —
  atomic same-dir writes, prune-on-read, ghost dedup per (port, basePath),
  dialable-origin adoption for family-ambiguous localhost binds;
  createDevServer registers automatically and unregisters on close;
  DEVFRAME_INSTANCES_DIR / DEVFRAME_DISABLE_INSTANCE_REGISTRY overrides
- first devframe bin: `devframe connect` runs the stdio MCP connector —
  devframe_index (discover instances + their tools, funnel hints for
  MCP-less servers) and devframe_call (proxy one tool call over
  Streamable-HTTP); errors carry actionable fix payloads; missing SDK
  peer throws coded DF0043
- @devframes/next: DevframeNextHost.mountMcp serves MCP in-process on the
  Next app's own origin (the /_next/mcp shape); hub example wires it,
  advertises it in connection meta, registers the instance, and
  agent-flags its ping command; catch-all route exports POST/DELETE
- mcp adapter: drop non-object outputSchema projections (MCP requires
  type object; a v.void() returns schema broke SDK clients)
- e2e: devframe-connect (files-inspector round-trip incl. gateway tool)
  and minimal-next-devframe-hub (in-process discovery + command call);
  hermetic per-suite registries; vitest keeps unit runs out of the
  global registry
- diagnostics DF0042/DF0043 + docs pages; connect/registry docs in the
  MCP adapter page

Author: antfubot

.gitignore

@@ -18,6 +18,7 @@ temp
 packages/devframe/skills
 test-results
 playwright-report
+tests/e2e/.registries
 playwright/.cache
 blob-report
 .ecosystem

docs/adapters/mcp.md

@@ -73,4 +73,23 @@ const mcp = createMcpFetchHandler(ctx, {
 // route every method on /__mcp to mcp.fetch(request)
 ```
 
+## Discovery: `devframe connect`
+
+The `devframe` bin ships an MCP **connector** — a thin discovery + proxy server in the shape [next-devtools-mcp](https://github.com/vercel/next-devtools-mcp) validated. Configure it once in an agent client and it finds every running devframe:
+
+```json
+{
+  "mcpServers": {
+    "devframe": { "command": "npx", "args": ["devframe", "connect"] }
+  }
+}
+```
+
+It exposes two gateway tools:
+
+- **`devframe_index`** — discover running devframe dev servers and list each one's MCP tools. Instances running without an MCP route are listed with a hint to restart with `--mcp`.
+- **`devframe_call`** — invoke one tool on one instance (`{ port, tool, args }`) over its Streamable-HTTP endpoint.
+
+Discovery reads the **instance registry**: every `createDevServer` (CLI `dev`, `viteDevBridge`, `@devframes/next`'s handler) writes a record to `~/.devframe/instances/<pid>-<port>.json` on boot and removes it on close; readers prune records whose liveness probe fails. In-process hosts register explicitly with `registerDevframeInstance` from `devframe/node` — see `createDevframeNextHost().mountMcp` for serving MCP on a Next app's own origin. `--port <n>` probes an explicit port besides the registry; `DEVFRAME_INSTANCES_DIR` relocates the registry and `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` opts a server out.
+
 See the [Agent-Native](/guide/agent-native) page for the full API, safety model, and Claude Desktop integration example.

docs/errors/DF0042.md

@@ -0,0 +1,23 @@
+---
+outline: deep
+---
+
+# DF0042: Instance Registry Update Failed
+
+## Message
+
+> Failed to update the devframe instance registry at "`{file}`": `{reason}`
+
+## Cause
+
+A dev server (or an in-process host calling `registerDevframeInstance`) could not write or remove its record under the instance registry directory — `~/.devframe/instances/` by default, or `$DEVFRAME_INSTANCES_DIR`. Typical causes are a read-only home directory, missing permissions, or a full disk. The server keeps running; only discovery is affected — `devframe connect` will not see this instance.
+
+## Fix
+
+- Check that the registry directory is writable and the disk has free space.
+- Point `DEVFRAME_INSTANCES_DIR` at a writable directory.
+- Set `DEVFRAME_DISABLE_INSTANCE_REGISTRY=1` to opt out of registration entirely.
+
+## Source
+
+- [`packages/devframe/src/node/instance-registry.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/node/instance-registry.ts) — `registerDevframeInstance()` reports this on a failed write and its `unregister()` on a failed removal.

docs/errors/DF0043.md

@@ -0,0 +1,26 @@
+---
+outline: deep
+---
+
+# DF0043: Connector Requires the MCP SDK
+
+## Message
+
+> `devframe connect` requires the optional peer dependency @modelcontextprotocol/sdk: `{reason}`
+
+## Cause
+
+`devframe connect` was started but `@modelcontextprotocol/sdk` could not be imported. The SDK is an optional peer dependency of `devframe` — the MCP surface stays opt-in, so the SDK only needs to be installed where MCP features are used.
+
+## Fix
+
+Install the SDK next to devframe and run the connector again:
+
+```sh
+npm install @modelcontextprotocol/sdk
+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.

docs/guide/agent-native.md

@@ -176,4 +176,6 @@ Agents can act on `fix` directly and follow `docs` for detail — prefer throwin
 
 | Command | Description |
 |---------|-------------|
-| `devframe mcp` | Start an MCP server on `stdio`. |
+| `<your-app> mcp` | Start your app's MCP server on `stdio` (from the `createCac` shell). |
+| `<your-app> dev --mcp` | Serve the agent surface on the dev server's `/__mcp` route. |
+| `devframe connect` | Run the app-independent MCP connector: discover running devframes and proxy their tools — see [MCP adapter](/adapters/mcp#discovery-devframe-connect). |

examples/files-inspector/src/devframe.ts

@@ -22,12 +22,27 @@ export default defineDevframe({
     // Single-user localhost demo — skip the trust handshake so the served
     // SPA can call RPC without an OTP round-trip.
     auth: false,
+    // Serve the agent surface over the dev server's `/__mcp` route and
+    // register the instance for `devframe connect` discovery.
+    mcp: true,
   },
   spa: { loader: 'none' },
   setup(ctx) {
     // A scoped context auto-namespaces every registered id with `NAMESPACE:`.
     const my = ctx.scope(NAMESPACE)
     for (const fn of serverFunctions)
       my.rpc.register(fn)
+
+    // Gateway tool: returns the location of this tool's own docs instead of
+    // proxying their content — the agent reads the files with its own tools.
+    ctx.agent.registerTool({
+      id: `${NAMESPACE}:docs`,
+      description: 'Locate the Files Inspector\'s documentation on disk. Call before answering questions about how this tool works, then read the returned files directly.',
+      safety: 'read',
+      handler: () => ({
+        readmePath: fileURLToPath(new URL('../README.md', import.meta.url)),
+        hint: 'Read the file at readmePath with your own file tools; do not rely on training-data knowledge of this example.',
+      }),
+    })
   },
 })

examples/minimal-next-devframe-hub/src/client/app/%5F_[id]/[[...path]]/route.ts

@@ -5,12 +5,18 @@ export const dynamic = 'force-dynamic'
 
 /**
  * Catch-all for every mounted devframe SPA (`/__git/…`, `/__terminals/…`, the
- * a11y agent module, …) and their `<base>/__connection.json` discovery fetches.
- * The `@devframes/next` bridge owns all of it — static serving (with SPA
- * fallback, content types, and traversal guarding via devframe's shared
- * `serveStaticHandler`) and the connection-meta responses.
+ * a11y agent module, …), their `<base>/__connection.json` discovery fetches,
+ * and the in-process MCP endpoint (`/__hub/__mcp`). The `@devframes/next`
+ * bridge owns all of it — static serving (with SPA fallback, content types,
+ * and traversal guarding via devframe's shared `serveStaticHandler`), the
+ * connection-meta responses, and the MCP mount.
+ *
+ * MCP speaks Streamable-HTTP: `POST` (requests), `GET` (the SSE stream), and
+ * `DELETE` (session teardown) all route to the same bridge `fetch`.
  */
-export async function GET(request: Request): Promise<Response> {
+async function handler(request: Request): Promise<Response> {
   const hub = await ensureMinimalNextDevframeHub()
   return hub.fetch(request)
 }
+
+export { handler as DELETE, handler as GET, handler as POST }

examples/minimal-next-devframe-hub/src/client/devframe/minimal-next-devframe-hub.ts

@@ -8,7 +8,7 @@ import { defineHubRpcFunction } from '@devframes/hub'
 import { createHubContext, mountDevframe } from '@devframes/hub/node'
 import { toJsonRenderDockEntry } from '@devframes/json-render/hub'
 import { createDevframeNextHost } from '@devframes/next'
-import { startHttpAndWs } from 'devframe/node'
+import { registerDevframeInstance, startHttpAndWs } from 'devframe/node'
 import { getPort } from 'get-port-please'
 import { createDashboardView } from 'minimal-json-render/dashboard'
 import { dirname, join } from 'pathe'
@@ -134,13 +134,14 @@ export async function minimalNextDevframeHub(
 ): Promise<StartedMinimalNextDevframeHub> {
   const cwd = options.cwd ?? process.cwd()
   const hostName = options.host ?? 'localhost'
+  const nextPort = Number(process.env.PORT ?? 3000)
 
   // The Next host bridge: its `host` accumulates every `mountStatic` /
   // `mountConnectionMeta` call into a single `fetch` handler (backed by
   // devframe's shared `serveStaticHandler`), which the App Router routes
   // delegate to — no hand-rolled static serving or path matching here.
   const nextHost = createDevframeNextHost({
-    resolveOrigin: () => `http://${hostName}:3000`,
+    resolveOrigin: () => `http://${hostName}:${nextPort}`,
     getStorageDir(scope) {
       if (scope === 'workspace')
         return join(cwd, '.devframe')
@@ -174,6 +175,12 @@ export async function minimalNextDevframeHub(
     title: 'Next Hub: Ping',
     icon: 'ph:bell-duotone',
     category: 'hub',
+    // Opt this command into the agent surface: it shows up as an MCP tool
+    // on the in-process endpoint mounted below.
+    agent: {
+      description: 'Ping the hub to confirm it is alive. Returns "pong". Safe to call freely.',
+      safety: 'read',
+    },
     handler: () => 'pong',
   })
 
@@ -245,14 +252,45 @@ export async function minimalNextDevframeHub(
     auth: false,
   })
 
+  // Serve MCP in-process on the Next app's own origin (the `/_next/mcp`
+  // shape): the hub's agent surface — agent-flagged commands, plugin tools
+  // (git status/log/diff, terminals), `read_state` — over the same catch-all
+  // route as the SPAs, no side-car port involved.
+  const mcpPath = '/__hub/__mcp'
+  await nextHost.mountMcp(context, mcpPath, {
+    serverName: 'minimal-next-devframe-hub',
+  })
+
   const connectionMeta = {
     backend: 'websocket' as const,
     websocket: started.port,
+    mcp: { path: mcpPath },
   }
   // Publish the live meta to the bridge now the WS port is known, so every
   // registered `<base>/__connection.json` (hub + mounted devframes) resolves.
   nextHost.setConnectionMeta(connectionMeta)
 
+  // Record the instance in the global registry so `devframe connect`
+  // discovers this hub — running inside the Next dev server — like any
+  // standalone devframe. In-process hosts register explicitly; the origin is
+  // the Next app's own.
+  const registration = registerDevframeInstance({
+    pid: process.pid,
+    port: nextPort,
+    origin: `http://${hostName}:${nextPort}`,
+    basePath: '/__hub/',
+    id: 'minimal-next-devframe-hub',
+    name: 'Minimal Next Devframe Hub',
+    rootDir: cwd,
+    mcp: { path: mcpPath },
+    startedAt: Date.now(),
+  })
+  const closeStarted = started.close
+  started.close = async () => {
+    registration.unregister()
+    await closeStarted()
+  }
+
   return Object.assign(started, {
     context,
     connectionMeta,

examples/minimal-next-devframe-hub/tests/minimal-next-devframe-hub.test.ts

@@ -19,12 +19,13 @@ describe('minimal-next-devframe-hub (example)', () => {
     server = undefined
   })
 
-  it('returns connection meta pointing at the WS backend', async () => {
+  it('returns connection meta pointing at the WS backend and in-process MCP', async () => {
     server = await minimalNextDevframeHub({ host: '127.0.0.1' })
 
     expect(server.connectionMeta).toEqual({
       backend: 'websocket',
       websocket: server.port,
+      mcp: { path: '/__hub/__mcp' },
     })
   })
 

package.json

@@ -37,6 +37,7 @@
     "@antfu/eslint-config": "catalog:tooling",
     "@antfu/ni": "catalog:build",
     "@antfu/utils": "catalog:inlined",
+    "@modelcontextprotocol/sdk": "catalog:deps",
     "@playwright/test": "catalog:testing",
     "@types/node": "catalog:types",
     "@types/prompts": "catalog:types",