feat(agent)!: agent-native MCP wave — bridges, core surface, instance registry, devframe connect (#145)

Author: antfubot

.gitignore

@@ -18,7 +18,11 @@ temp
 packages/devframe/skills
 test-results
 playwright-report
+tests/e2e/.registries
 playwright/.cache
 blob-report
 .ecosystem
 storybook-static
+
+# Agent skills from npm packages (managed by skills-npm)
+**/skills/npm-*

README.md

@@ -30,6 +30,10 @@ Framework-neutral foundation for building devframes.
   </a>
 </p>
 
+## Credits
+
+The `devframe connect` MCP connector (discovery + gateway tools + agent-steering errors) follows the architecture Vercel's [`next-devtools-mcp`](https://github.com/vercel/next-devtools-mcp) validated: the real MCP endpoint lives inside the framework, and a thin external connector discovers and proxies it.
+
 ## License
 
 [MIT](./LICENSE.md) License © [Anthony Fu](https://github.com/antfu)

alias.ts

@@ -18,6 +18,7 @@ export const alias = {
   'devframe/node/hub-internals': r('devframe/src/node/hub-internals/index.ts'),
   'devframe/node': r('devframe/src/node/index.ts'),
   'devframe/constants': r('devframe/src/constants.ts'),
+  'devframe/utils/agent-tool-name': r('devframe/src/utils/agent-tool-name.ts'),
   'devframe/utils/colors': r('devframe/src/utils/colors.ts'),
   'devframe/utils/crypto-token': r('devframe/src/utils/crypto-token.ts'),
   'devframe/utils/events': r('devframe/src/utils/events.ts'),

docs/adapters/mcp.md

@@ -46,4 +46,50 @@ defineDevframe({
 })
 ```
 
+### Hosted bridges
+
+Both hosted bridges forward the same option to their side-car dev server and advertise the endpoint (with its port) in the `__connection.json` they serve:
+
+```ts
+// Vite
+viteDevBridge(devframe, { devMiddleware: true, mcp: true })
+
+// Next.js (@devframes/next)
+createDevframeNextHandler(devframe, { mcp: true })
+```
+
+## Custom hosts
+
+`createMcpFetchHandler(ctx, options)` returns the endpoint as a web-standard `Request → Response` handler plus a `dispose()` for session teardown — mount it on any fetch-shaped server (a Next.js App Router route, a custom Node server). The h3 `mountMcpHttp` used by the dev server is a thin wrapper over it.
+
+```ts
+import { createMcpFetchHandler } from 'devframe/adapters/mcp'
+
+const mcp = createMcpFetchHandler(ctx, {
+  serverName: 'my-tool (devframe)',
+  serverVersion: '1.0.0',
+  exposeSharedState: true,
+})
+// 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 (the wire names of the `devframe:connect:*` ids — see [tool ids and wire names](/guide/agent-native#tool-ids-and-wire-names)):
+
+- **`devframe_connect_list-instances`** — 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_connect_call-tool`** — 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/DF0045.md

@@ -0,0 +1,23 @@
+---
+outline: deep
+---
+
+# DF0045: 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/DF0046.md

@@ -0,0 +1,26 @@
+---
+outline: deep
+---
+
+# DF0046: Connector Requires the MCP SDK
+
+## Message
+
+> `devframe connect` requires the optional peer dependency @modelcontextprotocol/server: `{reason}`
+
+## Cause
+
+`devframe connect` was started but `@modelcontextprotocol/server` could not be imported. The SDK is an optional peer dependency of `devframe` — the MCP surface stays opt-in, so it 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/server
+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/errors/DF0047.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0047: Agent Tool Wire-Name Collision
+
+## Message
+
+> Agent tool "`{id}`" is hidden from the MCP surface: its wire name "`{name}`" collides with the tool "`{existing}`".
+
+## Cause
+
+MCP clients constrain tool names to `^[a-zA-Z0-9_-]{1,128}$`, so the MCP adapter derives each tool's wire name from its id (runs of characters outside `[a-zA-Z0-9_-]` become a single `_`). Two registered ids sanitized to the same wire name — e.g. `demo:greet` and `demo_greet`. The first registration keeps the name; the later tool is hidden from `tools/list`.
+
+## Example
+
+```ts
+ctx.agent.registerTool({ id: 'demo:greet', description: '…', handler })
+ctx.agent.registerTool({ id: 'demo_greet', description: '…', handler }) // hidden: same wire name
+```
+
+## Fix
+
+Rename one of the two ids so they sanitize to distinct wire names. Namespaced ids (`devframes:plugin:<slug>:<fn>`, `devframe:<area>:<fn>`) collide only when they differ solely in separator characters.
+
+## Source
+
+- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts) — the `tools/list` handler reports this once per hidden tool when deduplicating wire names.

docs/errors/DF0048.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0048: Unknown Shared-State Key
+
+## Message
+
+> Unknown shared-state key "`{key}`".
+
+## Cause
+
+The built-in `devframe_state_read` MCP tool was called with a `key` that is not among the shared-state keys the host publishes (or that the `exposeSharedState` filter allows). The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// The host publishes only `my-plugin:counter`; an agent calls:
+// devframe_state_read({ key: 'my-plugin:cuonter' }) → DF0048
+```
+
+## Fix
+
+Call the `devframe_state_read` tool without arguments to list the available keys, then retry with one of them.
+
+## Source
+
+- [`packages/devframe/src/adapters/mcp/build-server.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/adapters/mcp/build-server.ts) — `readStateResult()` throws this when the requested key is absent from the filtered key list.

docs/errors/DF0049.md

@@ -0,0 +1,27 @@
+---
+outline: deep
+---
+
+# DF0049: Connector Call Requires Port and Tool
+
+## Message
+
+> The devframe_connect_call-tool tool requires { port: number, tool: string }.
+
+## Cause
+
+The `devframe connect` gateway tool `devframe_connect_call-tool` was invoked without a numeric `port` or a string `tool` name — the two fields that identify which instance to dial and which of its tools to call. The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// devframe_connect_call-tool({ tool: 'devframe_state_read' }) → DF0049 (missing port)
+```
+
+## Fix
+
+Call `devframe_connect_list-instances` first — its result carries each instance's `port` and tool names — then retry with both fields.
+
+## Source
+
+- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts) — `call()` throws this when the gateway arguments fail validation.

docs/errors/DF0050.md

@@ -0,0 +1,28 @@
+---
+outline: deep
+---
+
+# DF0050: No Devframe Instance on Port
+
+## Message
+
+> No running devframe instance on port `{port}`.
+
+## Cause
+
+The `devframe connect` gateway tool `devframe_connect_call-tool` targeted a port with no live devframe instance behind it — neither the instance registry nor a direct probe of the port found one serving `__connection.json`. The instance may have stopped, restarted on a different port, or never existed. The error crosses the MCP boundary as structured JSON, so the calling agent can self-correct.
+
+## Example
+
+```ts
+// No dev server on 5199:
+// devframe_connect_call-tool({ port: 5199, tool: 'devframe_state_read' }) → DF0050
+```
+
+## Fix
+
+Call `devframe_connect_list-instances` for the current instance list and retry with a live port.
+
+## Source
+
+- [`packages/devframe/src/cli/connect.ts`](https://github.com/devframes/devframe/blob/main/packages/devframe/src/cli/connect.ts) — `call()` throws this when neither the registry nor the port probe finds an instance.