feat(devframe): add MCP resource subscriptions and templates

[dvcolomban]

Summary

Adds resource-content invalidations and RFC 6570 URI templates to Devframe's agent API while preserving the stateless MCP architecture introduced in 8d58eb5.

Devframe authors use one API: concrete resource handles call notifyUpdated(), and template handles call notifyUpdated(concreteUri). Protocol negotiation stays inside the MCP SDK adapter; MCP callers do not select a mode.

Architecture

• HTTP list, template-list, and read requests remain stateless. The SDK builds a fresh MCP server instance for each request.
• One endpoint-level bridge publishes Devframe resource invalidations to the SDK notification bus.
• MCP 2026 owns the long-lived streaming POST used by subscriptions/listen and filters invalidations through each call's resourceSubscriptions.
• Stdio keeps the SDK-owned, connection-pinned server instance and publishes MCP 2026 invalidations through that instance.
• MCP 2025 retains list, template-list, and read access. Resource contents remain pull-based because the deprecated resources/subscribe and resources/unsubscribe methods are not registered.
• No Mcp-Session-Id, URI subscription map, cleanup registry, or other HTTP session state is introduced.

Resources and URI templates

• Concrete resources keep generated, custom, and nested URIs.
• RFC 6570 templates are registered through the same registerResource() API.
• Template readers receive the concrete URL and parsed variables.
• resources/templates/list exposes dynamic templates; those templates remain absent from resources/list.
• Reads resolve exact URIs before templates, and overlapping templates follow registration order.
• Shared-state creation and removal publish catalog changes. Mutations publish the encoded devframe://state/... URI, with endpoint disposal removing every listener.

Protocol compatibility

Transport	MCP 2026-07-28	MCP 2025 fallback
HTTP	Stateless list/read/template requests plus resource updates through a subscriptions/listen streaming POST	Stateless list/read/template requests, pull-only resource contents
stdio	Connection-pinned list/read/templates plus resource updates through subscriptions/listen	Connection-pinned list/read/templates, pull-only resource contents
Resource subscription methods	subscriptions/listen with resourceSubscriptions	resources/subscribe and resources/unsubscribe are not registered
Session state	No Mcp-Session-Id or subscription map	No HTTP session machinery; stdio keeps only the SDK-owned connection

Compatibility preserves resource discovery and reads across both protocol revisions. Push invalidations use the MCP 2026 subscription model.

Verification

• pnpm lint
• pnpm knip
• pnpm test — 119 files passed; 1,329 tests passed and 9 skipped
• pnpm typecheck — 38 tasks passed
• pnpm build — 27 tasks passed

Coverage includes concrete and template registration, parsed variables, nested paths, precedence, unregistering, update events, MCP 2026 HTTP and stdio delivery, URI filtering, MCP 2025 pull access, shared-state lifecycle notifications, listener disposal, event-document parity, and API snapshots.

[vercel]

@dvcolomban is attempting to deploy a commit to the NuxtLabs Team on Vercel.

A member of the Team first needs to authorize it.

[Copilot]

Pull request overview

Adds first-class MCP resource capabilities to Devframe’s agent surface by introducing resource templates, lazy resource providers, and per-connection resource subscriptions. This extends the existing “tools vs readable context” model so adapters (notably MCP) can advertise URI families, list concrete instances, and push invalidation updates to subscribed clients without polling.

Changes:

• Extend the agent API/types to support concrete resources, URI templates, resource providers, and subscription lifecycle hooks (read/list/subscribe/unsubscribe + updated notifications).
• Implement MCP server support for resources/templates/list, template-backed resources/list, resources/subscribe/resources/unsubscribe, and filtered resources/updated notifications with async disposal.
• Add/expand tests (in-memory + stdio + HTTP) and update docs to describe the new resource model and events.

Reviewed changes

Copilot reviewed 12 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/snapshots/tsnapi/devframe/types.snapshot.d.ts	Snapshot updates for newly exported agent resource/provider/template types.
tests/snapshots/tsnapi/devframe/internal.snapshot.d.ts	Snapshot updates for DevframeAgentHost’s updated private fields and new resource APIs.
tests/snapshots/tsnapi/devframe/index.snapshot.d.ts	Snapshot updates for public agent interfaces (templates/providers/subscriptions).
tests/snapshots/tsnapi/devframe/constants.snapshot.d.ts	Snapshot update for the new agent:resource:updated event constant.
skills/devframe/SKILL.md	Update skill docs/examples to include templates/providers/subscriptions usage.
packages/devframe/src/types/agent.ts	Core type additions for templates, providers, variables, handles, and new agent host methods/events.
packages/devframe/src/node/host-agent.ts	Agent host implementation for registering templates/providers and forwarding reads/subscriptions + update notifications.
packages/devframe/src/node/tests/host-agent.test.ts	Unit tests covering custom URIs, templates, variables, subscriptions, handles, and providers.
packages/devframe/src/events.ts	Add the agent:resource:updated event name to the central event map.
packages/devframe/src/adapters/mcp/fetch.ts	Ensure MCP session disposal awaits async resource cleanup.
packages/devframe/src/adapters/mcp/build-server.ts	MCP resources: list/read/templates + subscribe/unsubscribe + subscription reconciliation/disposal.
packages/devframe/src/adapters/mcp/tests/mcp-server.test.ts	In-memory MCP tests for explicit URIs, templates, subscription behavior, provider churn, and stdio coverage.
packages/devframe/src/adapters/mcp/tests/mcp-http.test.ts	HTTP transport test verifying session-local subscriptions and cleanup on disconnect.
packages/devframe/src/adapters/mcp/tests/fixtures/resource-stdio-server.ts	Stdio fixture server wiring resources + template and emitting updates.
docs/content/1.guide/20.events.md	Document agent:resource:updated and clarify registered payload types.
docs/content/1.guide/14.agent-native.md	Document resource URIs, templates, subscriptions, and providers for native agent usage.

Suppressed comments (1)

packages/devframe/src/adapters/mcp/build-server.ts:430

• During manifest reconciliation, the code removes each subscription from the subscriptions map before awaiting its cleanup. If a cleanup throws/rejects, the outer .catch() swallows the error and the subscription is permanently lost (not tracked for later disposal/retry), causing leaks and inconsistent subscription state. Keep the subscription tracked until cleanup succeeds, and handle cleanup errors per-URI so one failure doesn’t abort the entire reconciliation pass.

      for (const [uri, cleanup] of [...subscriptions]) {
        subscriptions.delete(uri)
        await cleanup()
        const resource = resolveAgentResource(ctx, uri)
        if (!resource)

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[dvcolomban]

This is getting a bit sprawling, before investing more time, @antfu do you think this is something worth investigating further ?

And if so, how far (if any) should devframes support pre 2026 MCP spec for subscriptions ?

I'm struggling to reconcile api complexity with backward compatibility 🤔