feat(devframe): serve MCP by default when an agent surface exists

[antfubot]

Intent

Make MCP a default feature of devframe — strengthening the "one tool, two views for the human and the coding agent" story — without taxing devframes that never expose an agent surface or users who explicitly disable MCP.

This PR carries both the plan (plans/008-default-on-mcp.md, registered in the plans index) and its implementation, executed after plans 002 (MCP HTTP authentication) and 003 (state exposure policy) landed on main.

The 'auto' default

The omitted mcp setting now resolves to 'auto' in initDevframe, initHub, createDevServer, and the framework kits: the Streamable-HTTP route mounts at <base>__mcp exactly when

1. the agent surface is non-empty — an agent-flagged RPC, or a tool/resource/provider-yielded tool on ctx.agent (new DevframeAgentHost.hasSurface()), and
2. the optional peer @modelcontextprotocol/server resolves.

A devframe with nothing flagged mounts no route and loads zero MCP code (extended bundle guard proves it); a flagged surface with the peer missing warns once (new DF0077) instead of mounting. Explicit values keep their meaning: true forces on (missing peer stays the DF0017 startup failure), false/--no-mcp force off, an object customises — and 'auto' mounts with exactly mcp: true's posture (loopback origin gate; authorization remains the opt-in hardening from plan 002), so the default grants no extra reach.

Reconciliation with plan 002 as landed

The plan as first drafted gated 'auto' on DEVFRAME_MCP_AUTH_TOKEN, written against plan 002's draft contract (mandatory bearer). Plan 002 landed with origin-only as the blessed same-machine default and authorization as opt-in hardening, so 'auto' follows the landed contract; the plan document records the reconciliation.

Product layer

• starter/: the example RPC now carries an agent field, @modelcontextprotocol/server ships in its dependencies, and the README explains the two views.
• hub examples at parity: hub-next drops its explicit mcp: true (the default now covers it) and hub-vite's README documents the aggregate endpoint it now serves; files-inspector relies on the default too.
• Docs: adapter/guide/reference/security pages describe the default-on flow positively; DF0077 page added, DF8005 updated to the new hub semantics (warns only under explicit mcp: false).

Verification

pnpm lint, pnpm knip, pnpm test (full suite, 124 files / 1419 tests), pnpm typecheck, and pnpm build all pass; tsnapi snapshots refreshed with only the intended surface (McpSetting, hasSurface, DF0077, loadAutoMcpAdapter).

---

Created with the help of an agent.

[coldtea-pr-lens]

◈ PR Lens

🟢 +1 new · 🟠 ~8 changed · 🔴 -0 removed · 2 flows · 20 files · commit e2ea474

Architecture

9 components touched across 4 lanes.

Open full size

Inside the changed components — 2 views

Component view — Single-Tool Agent Lifecycle

Internal orchestration within Devframe Core Engine checking agent surface presence before lazily loading the MCP adapter and mounting the HTTP route.

Component view — Hub Aggregate MCP Mounting

Hub orchestration validating mounted devframe configurations and auto-mounting the aggregate MCP endpoint when any mounted frame or command exposes agent tools.

Data flow

Automatic MCP route mounting on agent surface detection · Hub aggregate MCP route initialization

Open full size

The other flows — 1 sequence

Hub aggregate MCP route initialization

Drill down

Framework Kits ＆ Hosts — 3 components

🟡 CHANGED Vite Framework Kit

Vite dev server plugin and bridge adapters forwarding the default 'auto' MCP setting.

• packages/vite/src/single.ts
• packages/vite/src/hub.ts

🟡 CHANGED Next.js Framework Kit

Next.js devframe host and handler utilities supporting dynamic MCP route mounting under App Router.

• packages/next/src/handler.ts
• packages/next/src/host.ts
• packages/next/src/hub.ts

🟡 CHANGED Next.js Reference Hub Host

Next.js reference hub host relying on the default 'auto' MCP configuration for mounted devframe tools.

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

Hub Orchestration — 1 component

🟡 CHANGED Hub Core ＆ Lifecycle

Hub lifecycle orchestrator that aggregates agent surfaces across all mounted devframes and hub commands to mount the shared MCP route.

• packages/hub/src/node/initiate.ts
• packages/hub/src/node/diagnostics.ts

Devframe Core Engine — 5 components

🟡 CHANGED Single-Tool Instance Shell

Single-tool instance shell orchestrating devframe setup, agent surface detection, and dynamic MCP route mounting.

• packages/devframe/src/adapters/initiate.ts
• packages/devframe/src/adapters/_shared.ts
• packages/devframe/src/types/devframe.ts
• packages/devframe/package.json

🟡 CHANGED Host ＆ Build Adapters

CLI (CAC) and dev server adapters defaulting the --mcp flag and options to 'auto'.

• packages/devframe/src/adapters/cac.ts
• packages/devframe/src/adapters/dev.ts

🟢 NEW Devframe Agent Host

Agent subsystem maintaining tools, resources, and providers, offering hasSurface() to detect whether an agent API is active.

• packages/devframe/src/node/host-agent.ts
• packages/devframe/src/types/agent.ts

🟡 CHANGED MCP HTTP Route Handler

Streamable-HTTP route handler loaded dynamically to serve MCP protocol requests over the dev server origin.

• packages/devframe/src/adapters/mcp/http.ts
• packages/devframe/src/adapters/mcp/fetch.ts
• packages/devframe/src/adapters/mcp/index.ts

🟡 CHANGED CLI MCP Gateway

CLI MCP gateway that connects to live devframe instances, updated to require @modelcontextprotocol/client as an optional peer.

• packages/devframe/src/node/diagnostics.ts

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.
• Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
• GitHub will not let you zoom an image in a comment. The link under each diagram opens it full size on a page of its own, where you can.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Something drawn wrong?

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
devframe	Ready	Preview	Sep 3, 2026 5:05am UTC