refactor(devframe): simplify MCP resource lifecycle

Author: dvcolomban

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

@@ -80,25 +80,21 @@ const handle = ctx.agent.registerToolProvider(() =>
 handle.notifyChanged() // fires tools/list_changed
 ```
 
-## Registering fixed resources
+## Registering a resource
 
 Readable snapshots by URI:
 
 ```ts
-const sessionResource = ctx.agent.registerResource({
+ctx.agent.registerResource({
   id: 'current-session',
-  uri: 'rolldown://session/current', // optional
   name: 'Current Rolldown session',
   description: 'Markdown snapshot of the active build session.',
   mimeType: 'text/markdown',
-  read: uri => ({ text: renderMarkdown(currentSession, uri) }),
+  read: () => ({ text: renderMarkdown(currentSession) }),
 })
-
-// Notify subscribed MCP clients after the content changes.
-sessionResource.notifyUpdated()
 ```
 
-Without `uri`, Devframe assigns `devframe://resource/<encoded-id>`. `read` runs for every MCP read and receives the requested URI. A zero-argument reader remains valid.
+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
 
@@ -127,21 +123,21 @@ logsResource.notifyUpdated('rolldown://logs/worker')
 
 MCP exposes templates through `resources/templates/list`. When `list` is present, its concrete entries also appear in `resources/list`.
 
-## Resource subscriptions
+## Updating a subscribed resource
 
 `subscribe` and `unsubscribe` follow the MCP resource lifecycle. Devframe calls them once per URI and MCP connection, and releases active subscriptions when the connection, registration, or provider goes away.
 
 ```ts
-ctx.agent.registerResource({
+const buildResource = ctx.agent.registerResource({
   id: 'live-build',
   name: 'Live build',
   read: () => ({ json: currentBuild() }),
-  subscribe: uri => buildEvents.watch(uri.toString()),
-  unsubscribe: uri => buildEvents.unwatch(uri.toString()),
+  subscribe: uri => buildEvents.retain(uri, () => buildResource.notifyUpdated()),
+  unsubscribe: uri => buildEvents.release(uri),
 })
 ```
 
-The callbacks manage the producer listener. They do not send content. Call the registration handle's `notifyUpdated()` method after a change; subscribed clients receive `resources/updated` and can read the current value.
+The producer owns its listener and any reference counting across MCP connections. `notifyUpdated()` sends no content. It tells subscribed clients to read the current value.
 
 ## Deriving resources from other state
 
@@ -161,7 +157,7 @@ resources.notifyChanged() // resources/list_changed
 resources.notifyUpdated('dataset://builds/active') // resources/updated for subscribers
 ```
 
-Direct registrations win over providers. Earlier providers win over later providers, and exact fixed URIs win over templates.
+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/<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.
 

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

@@ -234,7 +234,7 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('reads fixed resources from their explicit URI', async () => {
+  it('reads resources from their explicit URI', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {
       const read = vi.fn((uri: URL) => ({ json: { uri: uri.toString() } }))
@@ -302,7 +302,7 @@ describe('mcp adapter (in-memory)', () => {
     }
   })
 
-  it('resolves an exact fixed URI before a matching template', async () => {
+  it('resolves an exact resource URI before a matching template', async () => {
     const { ctx, client, cleanup } = await bootPair()
     try {
       ctx.agent.registerResource({
@@ -578,7 +578,7 @@ describe('mcp adapter (in-memory)', () => {
 })
 
 describe('mcp adapter (stdio)', () => {
-  it('lists, reads, and subscribes to fixed and template resources', async () => {
+  it('lists, reads, and subscribes to registered and template resources', async () => {
     const fixture = fileURLToPath(new URL('./fixtures/resource-stdio-server.ts', import.meta.url))
     const transport = new StdioClientTransport({
       command: process.execPath,

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

@@ -10,7 +10,6 @@ import { toAgentToolName } from 'devframe/utils/agent-tool-name'
 import { join } from 'pathe'
 import { DEVFRAME_EVENTS } from '../../events'
 import { diagnostics } from '../../node/diagnostics'
-import { AGENT_RESOURCE_SOURCE } from '../../node/host-agent'
 import { formatMcpError, stringifyForMcp } from './stringify'
 import { argsToJsonSchema, returnToJsonSchema } from './to-json-schema'
 
@@ -43,7 +42,7 @@ export interface McpServerHandle {
 
 /**
  * Wire an MCP {@link Server} to a devframe context. Returns the server
- * plus a disposal function for the subscriptions it sets up. The
+ * plus an async disposal function for the subscriptions it sets up. The
  * transport is the caller's responsibility — `createMcpServer` connects
  * stdio; tests can connect an {@link InMemoryTransport} instead.
  *
@@ -304,13 +303,7 @@ function registerResourceHandlers(
   ctx: DevframeNodeContext,
   exposeSharedState: boolean | ((key: string) => boolean),
 ): () => Promise<void> {
-  interface Subscription {
-    resourceId: string
-    source: object
-    cleanup: () => void | Promise<void>
-  }
-
-  const subscriptions = new Map<string, Subscription>()
+  const subscriptions = new Map<string, () => void | Promise<void>>()
   let subscriptionOperations = Promise.resolve()
   const runSubscriptionOperation = <Result>(operation: () => Promise<Result>): Promise<Result> => {
     const result = subscriptionOperations.then(operation)
@@ -404,20 +397,20 @@ function registerResourceHandlers(
         throw new Error(`[devframe/mcp] unknown resource URI "${uri}"`)
 
       const cleanup = await ctx.agent.subscribeResource(resource.id, uri)
-      subscriptions.set(uri, { resourceId: resource.id, source: resource.source, cleanup })
+      subscriptions.set(uri, cleanup)
       return {}
     })
   })
 
   server.setRequestHandler('resources/unsubscribe', async (request) => {
     const { uri } = request.params
     return await runSubscriptionOperation(async () => {
-      const subscription = subscriptions.get(uri)
-      if (!subscription)
+      const cleanup = subscriptions.get(uri)
+      if (!cleanup)
         return {}
 
       subscriptions.delete(uri)
-      await subscription.cleanup()
+      await cleanup()
       return {}
     })
   })
@@ -430,21 +423,13 @@ function registerResourceHandlers(
 
   const offManifest = ctx.agent.events.on(DEVFRAME_EVENTS.bus.agentManifestChanged, () => {
     void runSubscriptionOperation(async () => {
-      for (const [uri, subscription] of subscriptions) {
+      for (const [uri, cleanup] of [...subscriptions]) {
+        subscriptions.delete(uri)
+        await cleanup()
         const resource = resolveAgentResource(ctx, uri)
-        if (resource?.id === subscription.resourceId && resource.source === subscription.source)
+        if (!resource)
           continue
-        await subscription.cleanup()
-        if (!resource) {
-          subscriptions.delete(uri)
-          continue
-        }
-        const cleanup = await ctx.agent.subscribeResource(resource.id, uri)
-        subscriptions.set(uri, {
-          resourceId: resource.id,
-          source: resource.source,
-          cleanup,
-        })
+        subscriptions.set(uri, await ctx.agent.subscribeResource(resource.id, uri))
       }
     }).catch(() => { /* ignore subscription cleanup errors during reconciliation */ })
   })
@@ -455,36 +440,31 @@ function registerResourceHandlers(
     await runSubscriptionOperation(async () => {
       const active = [...subscriptions.values()]
       subscriptions.clear()
-      await Promise.all(active.map(subscription => subscription.cleanup()))
+      await Promise.all(active.map(cleanup => cleanup()))
     })
   }
 }
 
 function resolveAgentResource(
   ctx: DevframeNodeContext,
   uri: string,
-): { id: string, variables: Variables, source: object } | undefined {
+): { id: string, variables: Variables } | undefined {
   const manifest = ctx.agent.list()
-  const fixed = manifest.resources.find(resource => resource.uri === uri)
-  if (fixed)
-    return { id: fixed.id, variables: {}, source: getResourceSource(fixed) }
+  const resource = manifest.resources.find(candidate => candidate.uri === uri)
+  if (resource)
+    return { id: resource.id, variables: {} }
 
   for (const template of manifest.resourceTemplates) {
     const variables = new UriTemplate(template.uriTemplate).match(uri)
     if (variables) {
       return {
         id: template.id,
         variables,
-        source: getResourceSource(template),
       }
     }
   }
 }
 
-function getResourceSource(resource: object): object {
-  return Reflect.get(resource, AGENT_RESOURCE_SOURCE) as object
-}
-
 /**
  * MCP constrains a tool's `outputSchema` to a JSON Schema of `type:
  * "object"` — clients (the SDK included) reject anything else. Non-object

packages/devframe/src/node/__tests__/host-agent.test.ts

@@ -316,7 +316,7 @@ describe('devToolsAgentHost', () => {
       expect(unsubscribe).toHaveBeenCalledWith(new URL('devframe://resource/live'))
     })
 
-    it('emits updates through fixed and template handles', () => {
+    it('emits updates through resource and template handles', () => {
       const ctx = createContext()
       const updated = vi.fn()
       ctx.agent.events.on('agent:resource:updated', updated)