feat(devframe): add MCP resource templates, providers, and updates

Author: dvcolomban

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

@@ -96,7 +96,72 @@ ctx.agent.registerResource({
 })
 ```
 
-Every `ctx.rpc.sharedState` key is exposed as a `devframe://state/<key>` resource and via the **`devframe:state:read` tool** (wire `devframe_state_read`): no args → key list, `key` → its value. `exposeSharedState: false` (or a filter) on `createMcpServer` opts out.
+Devframe assigns `devframe://resource/<encoded-id>` by default. Set `uri` to expose another URI. `read` runs for every MCP read and may receive the requested `URL`.
+
+## Registering resource templates
+
+Templates describe resources whose URI contains variables. Devframe uses the MCP SDK's URI-template parser and passes the parsed variables to `read`.
+
+```ts
+const logsResource = ctx.agent.registerResource({
+  id: 'process-logs',
+  uriTemplate: 'rolldown://logs/{process}',
+  name: 'Process logs',
+  mimeType: 'text/plain',
+  list: () => ({
+    resources: runningProcesses().map(process => ({
+      uri: `rolldown://logs/${encodeURIComponent(process.name)}`,
+      name: `${process.name} logs`,
+      mimeType: 'text/plain',
+    })),
+  }),
+  read: (_uri, variables) => ({
+    text: readLogs(String(variables.process)),
+  }),
+})
+
+logsResource.notifyUpdated('rolldown://logs/worker')
+```
+
+MCP exposes templates through `resources/templates/list`. When `list` is present, its concrete entries also appear in `resources/list`.
+
+## Publishing resource updates
+
+Resource handles publish invalidations after their underlying value changes:
+
+```ts
+const buildResource = ctx.agent.registerResource({
+  id: 'live-build',
+  name: 'Live build',
+  read: () => ({ json: currentBuild() }),
+})
+
+buildEvents.on('changed', () => buildResource.notifyUpdated())
+```
+
+`notifyUpdated()` sends no content. MCP 2026 callers receive the invalidation through `subscriptions/listen` when its `resourceSubscriptions` filter contains the URI, then call `resources/read` for the current value. Legacy MCP callers use `resources/list`, `resources/templates/list`, and `resources/read` to pull current values.
+
+## Deriving resources from other state
+
+Resource providers are queried when Devframe lists, resolves, or reads resources. Use them when another registry already owns the definitions.
+
+```ts
+const resources = ctx.agent.registerResourceProvider(() =>
+  currentDatasets().map(dataset => ({
+    id: `dataset:${dataset.id}`,
+    uri: `dataset://${dataset.id}`,
+    name: dataset.name,
+    read: () => ({ json: dataset.snapshot() }),
+  })),
+)
+
+resources.notifyChanged() // resources/list_changed
+resources.notifyUpdated('dataset://builds/active') // resources/updated through MCP 2026 subscriptions/listen
+```
+
+Direct registrations win over providers. Earlier providers win over later providers, and exact resource URIs win over templates.
+
+Every `ctx.rpc.sharedState` key is exposed as a `devframe://state/<encoded-key>` resource and via the **`devframe:state:read` tool** (wire `devframe_state_read`): no args → key list, `key` → its value. MCP 2026 subscriptions receive shared-state invalidations under the same encoded URI. `exposeSharedState: false` (or a filter) on `createMcpServer` opts out.
 
 ## Starting the MCP server
 
@@ -135,7 +200,7 @@ In `claude_desktop_config.json`:
 }
 ```
 
-Restart; tools appear in the drawer, resources as `devframe://resource/<id>` / `devframe://state/<key>` URIs.
+Restart; tools appear in the drawer. Resources use their declared URI, the generated `devframe://resource/<id>` URI, or `devframe://state/<key>` for implicit shared state.
 
 ## Writing descriptions agents act on
 

docs/content/8.references/3.events.md

@@ -68,7 +68,8 @@ Emitted on `ctx.agent.events`; adapters (e.g. the MCP server) re-publish their m
 |---|---|---|
 | `agent:manifest:changed` | any tool/resource/provider change | — |
 | `agent:tool:registered` / `agent:tool:unregistered` | `registerTool` / `unregisterTool` | `AgentTool` / id |
-| `agent:resource:registered` / `agent:resource:unregistered` | `registerResource` / `unregisterResource` | `AgentResource` / id |
+| `agent:resource:registered` / `agent:resource:unregistered` | `registerResource` / `unregisterResource` | `AgentResource` or `AgentResourceTemplate` / id |
+| `agent:resource:updated` | resource or provider handle `notifyUpdated` | concrete URI |
 
 ### RPC client connection events
 

packages/devframe/src/adapters/initiate.ts

@@ -321,7 +321,7 @@ export function initDevframe(
         const mounted = mountMcpHttp(app, context, mcpPath, {
           serverName: `${def.id} (devframe)`,
           serverVersion: def.version ?? '0.0.0',
-          exposeSharedState: true,
+          exposeSharedState: mcpConfig.exposeSharedState ?? true,
           allowedOrigins: mcpConfig.allowedOrigins,
         })
         mcpDispose = mounted.dispose

packages/devframe/src/adapters/mcp/__tests__/fixtures/resource-stdio-server.ts

@@ -0,0 +1,47 @@
+import type { DevframeDefinition } from '../../../../types/devframe'
+import { createMcpServer } from '../../build-server'
+
+const definition: DevframeDefinition = {
+  id: 'resource-stdio-test',
+  name: 'Resource stdio test',
+  version: '1.0.0',
+  packageName: '@devframe/resource-stdio-test',
+  homepage: 'https://example.com',
+  description: 'Stdio resource test fixture.',
+  async setup(ctx) {
+    const state = await ctx.rpc.sharedState.get('stdio:counter', {
+      initialValue: { count: 0 },
+    })
+    const fixed = ctx.agent.registerResource({
+      id: 'status',
+      uri: 'https://example.com/status',
+      name: 'Status',
+      read: uri => ({ json: { uri: uri.toString(), status: 'ok' } }),
+    })
+    const ignored = ctx.agent.registerResource({
+      id: 'ignored',
+      name: 'Ignored',
+      read: () => ({ json: { ignored: true } }),
+    })
+    ctx.agent.registerTool({
+      id: 'increment-state',
+      description: 'Increment the fixture state.',
+      handler: () => {
+        state.mutate(value => void (value.count += 1))
+        fixed.notifyUpdated()
+        ignored.notifyUpdated()
+      },
+    })
+    ctx.agent.registerResource({
+      id: 'logs',
+      uriTemplate: 'devframe://logs/{name}',
+      name: 'Logs',
+      list: () => ({ resources: [{ uri: 'devframe://logs/app', name: 'App logs' }] }),
+      read: (_uri: URL, variables: Readonly<Record<string, string | string[]>>) => ({
+        json: { process: variables.name },
+      }),
+    })
+  },
+}
+
+await createMcpServer(definition, { transport: 'stdio' })

packages/devframe/src/adapters/mcp/__tests__/mcp-http.test.ts

@@ -1,7 +1,7 @@
 import type { StartedServer } from '../../../node/instance-shell'
 import type { DevframeDefinition } from '../../../types/devframe'
 import { Client, StreamableHTTPClientTransport } from '@modelcontextprotocol/client'
-import { afterEach, describe, expect, it } from 'vitest'
+import { afterEach, describe, expect, it, vi } from 'vitest'
 import { createDevServer } from '../../dev'
 
 function defineTestDef(overrides?: Partial<DevframeDefinition>): DevframeDefinition {
@@ -82,6 +82,7 @@ describe('mcp adapter (streamable http route)', () => {
       // `Mcp-Session-Id` — there is no session to key state on.
       expect(client.getProtocolEra()).toBe('modern')
       expect(transport.sessionId).toBeUndefined()
+      expect(client.getServerCapabilities()?.resources).toEqual({ listChanged: true, subscribe: true })
 
       const tools = await client.listTools()
       expect(tools.tools.map(t => t.name)).toContain('greet')
@@ -95,6 +96,124 @@ describe('mcp adapter (streamable http route)', () => {
     }
   })
 
+  it('delivers filtered resource updates through modern subscriptions/listen', async () => {
+    let notifyBuildUpdated!: () => void
+    let notifyIgnoredUpdated!: () => void
+    let updateExistingState!: () => void
+    let createAndUpdateLateState!: () => Promise<void>
+    const started = await boot(defineTestDef({
+      async setup(ctx) {
+        const build = ctx.agent.registerResource({
+          id: 'build',
+          name: 'Build',
+          read: () => ({ json: { status: 'ok' } }),
+        })
+        const ignored = ctx.agent.registerResource({
+          id: 'ignored',
+          name: 'Ignored',
+          read: () => ({ json: { ignored: true } }),
+        })
+        const existingState = await ctx.rpc.sharedState.get('build:status', {
+          initialValue: { revision: 0 },
+        })
+        notifyBuildUpdated = build.notifyUpdated
+        notifyIgnoredUpdated = ignored.notifyUpdated
+        updateExistingState = () => existingState.mutate(value => void (value.revision += 1))
+        createAndUpdateLateState = async () => {
+          const lateState = await ctx.rpc.sharedState.get('build:late', {
+            initialValue: { revision: 0 },
+          })
+          lateState.mutate(value => void (value.revision += 1))
+        }
+      },
+    }))
+    const client = new Client(
+      { name: 'test-client', version: '0.0.0' },
+      { versionNegotiation: { mode: 'auto' } },
+    )
+    const updates: string[] = []
+    client.setNotificationHandler('notifications/resources/updated', (notification) => {
+      updates.push(notification.params.uri)
+    })
+
+    await client.connect(originTransport(started))
+    const subscription = await client.listen({
+      resourceSubscriptions: [
+        'devframe://resource/build',
+        'devframe://state/build%3Astatus',
+        'devframe://state/build%3Alate',
+      ],
+    })
+    try {
+      notifyIgnoredUpdated()
+      notifyBuildUpdated()
+      updateExistingState()
+      await createAndUpdateLateState()
+
+      await vi.waitFor(() => expect(updates).toEqual([
+        'devframe://resource/build',
+        'devframe://state/build%3Astatus',
+        'devframe://state/build%3Alate',
+      ]))
+    }
+    finally {
+      await subscription.close()
+      await client.close()
+    }
+  })
+
+  it('keeps legacy resource access pull-only', async () => {
+    const started = await boot(defineTestDef({
+      setup(ctx) {
+        ctx.agent.registerResource({
+          id: 'build',
+          name: 'Build',
+          read: () => ({ json: { status: 'ok' } }),
+        })
+      },
+    }))
+    const client = new Client({ name: 'legacy-test-client', version: '0.0.0' })
+    try {
+      await client.connect(originTransport(started))
+      expect(client.getProtocolEra()).toBe('legacy')
+      expect(client.getServerCapabilities()?.resources).toEqual({})
+
+      const resources = await client.listResources()
+      expect(resources.resources.map(resource => resource.uri)).toContain('devframe://resource/build')
+      const result = await client.readResource({ uri: 'devframe://resource/build' })
+      expect(JSON.parse((result.contents[0] as { text: string }).text)).toEqual({ status: 'ok' })
+    }
+    finally {
+      await client.close()
+    }
+  })
+
+  it('can disable implicit shared-state MCP exposure for the HTTP route', async () => {
+    server = await createDevServer(defineTestDef({
+      async setup(ctx) {
+        await ctx.rpc.sharedState.get('hidden:state', { initialValue: { value: true } })
+      },
+    }), {
+      host: '127.0.0.1',
+      port: 0,
+      mcp: { exposeSharedState: false },
+    })
+    const client = new Client(
+      { name: 'test-client', version: '0.0.0' },
+      { versionNegotiation: { mode: 'auto' } },
+    )
+    try {
+      await client.connect(originTransport(server))
+      const resources = await client.listResources()
+      const tools = await client.listTools()
+      expect(resources.resources).toEqual([])
+      expect(tools.tools.map(tool => tool.name)).not.toContain('devframe_state_read')
+    }
+    finally {
+      await client.close()
+    }
+  })
+
   it('answers a bare GET with 405 (no session lifecycle)', async () => {
     const started = await boot()
     // Stateless serving has no session stream to open — the SDK answers a