feat: expose in-page functions through MCP

Author: posva

docs/content/1.guide/12.in-page-channel.md

@@ -100,6 +100,12 @@ pageChannel.events.on('panel:disconnected', () => pauseWorkIfNobodyWatches())
 
 `emit` on the page-script endpoint fans out to every connected panel endpoint. Functions declared under `functions.panel` are called through a specific `pageChannel.panels[0].call()` peer handle.
 
+### Agent tools over MCP
+
+A function carrying `agent` metadata is registered with the page's DevFrame client and becomes available through the node MCP endpoint used by `devframe connect`. The channel name qualifies the otherwise-bare function name. Only functions are exposed; events remain channel-only. Agent functions require `jsonSerializable: true`, and their Standard-Schema `args` produce the advertised `arg0` / `arg1` / … input schema.
+
+The registration follows the endpoint and browser connection lifecycle. Closing the channel or browser tab removes its tools. No panel needs to be open: loading the page establishes the bridge.
+
 ## The panel endpoint
 
 ```ts

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

@@ -157,6 +157,8 @@ rpc.client.register({
 
 `connectDevframe()` wires this on its own when the browser provides a model context; `webmcp: false` keeps the browser side off the WebMCP surface. `registerWebMcpTools(collector)` (from `devframe/client`) applies the same projection to a hand-built collector and returns a dispose that unregisters every tool.
 
+[In-page channel functions](/guide/in-page-channel#agent-tools-over-mcp) use the page's DevFrame connection instead: adding `agent` makes the original handler available through the regular node MCP endpoint without exposing it through WebMCP.
+
 > [!WARNING]
 > WebMCP is an experimental proposal; `registerWebMcpTools` tracks the current draft (`AbortSignal`-based unregistration) and earlier handle-returning drafts, but the browser API may still change.
 

docs/content/8.references/5.browser-api.md

@@ -52,6 +52,8 @@ The browser-only endpoint methods of the [in-page channel](/guide/in-page-channe
 
 `InPageChannelProtocol` separates `functions` and `events`. Each section has optional `pageScript` and `panel` maps naming the receiving direction. Endpoint options require a complete `functions` map with handlers; `events` is optional, and when provided can include optional handlers (use `{}` to declare an event without a handler for `channel.on()`). `call()` uses function names regardless of return type, while `emit()`, `callEvent()` (deprecated), and `on()` use event names. A function returning `void` or `Promise<void>` remains an awaitable request/response call.
 
+In-page endpoint functions carrying `agent` are synchronized through the page's DevFrame connection to the node MCP endpoint. Agent functions require `jsonSerializable: true`; events cannot be exposed.
+
 | Method or property | Page-script endpoint | Panel endpoint |
 |--------------------|-------------|-------|
 | `emit(name, ...args)` | Fans an event out to every connected panel. | Sends an event to the page script, buffering while connecting. |

packages/devframe/src/client/browser-agent-rpc.test.ts

@@ -0,0 +1,52 @@
+import type { BrowserAgentToolManifest } from './browser-agent'
+import type { BrowserAgentInvocationDefinition } from './browser-agent-rpc'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { registerBrowserAgentTool } from './browser-agent'
+import { setupBrowserAgentRpcBridge } from './browser-agent-rpc'
+
+describe('browser agent RPC bridge', () => {
+  const disposals: (() => void)[] = []
+  afterEach(() => disposals.splice(0).forEach(dispose => dispose()))
+
+  it('synchronizes manifests and invokes the original browser tool', async () => {
+    const handlers = new Map<string, (...args: any[]) => unknown>()
+    const callOptional = vi.fn().mockResolvedValue(undefined)
+    const rpc = {
+      client: {
+        register(definition: BrowserAgentInvocationDefinition) {
+          handlers.set(definition.name, definition.handler)
+        },
+      },
+      callOptional(
+        method: 'devframe:agent:sync-client-tools',
+        tools: BrowserAgentToolManifest[],
+      ) {
+        return callOptional(method, tools)
+      },
+      events: { on: () => () => {} },
+    }
+
+    disposals.push(registerBrowserAgentTool({
+      id: 'todos:add',
+      description: 'Add a todo.',
+      safety: 'action',
+      inputSchema: { type: 'object' },
+      invoke: args => ({ added: args.text }),
+    }))
+    disposals.push(setupBrowserAgentRpcBridge(rpc))
+    await vi.waitFor(() => expect(callOptional).toHaveBeenCalledWith(
+      'devframe:agent:sync-client-tools',
+      [{
+        id: 'todos:add',
+        description: 'Add a todo.',
+        safety: 'action',
+        inputSchema: { type: 'object' },
+      }],
+    ))
+
+    await expect(handlers.get('devframe:agent:invoke-client-tool')!(
+      'todos:add',
+      { text: 'milk' },
+    )).resolves.toEqual({ added: 'milk' })
+  })
+})

packages/devframe/src/client/browser-agent-rpc.ts

@@ -0,0 +1,68 @@
+import type { BrowserAgentToolManifest } from './browser-agent'
+import type { DevframeConnectionStatus } from './connection'
+import {
+  listBrowserAgentTools,
+  onBrowserAgentToolsChanged,
+} from './browser-agent'
+
+export interface BrowserAgentInvocationDefinition {
+  name: 'devframe:agent:invoke-client-tool'
+  type: 'action'
+  jsonSerializable: true
+  handler: (id: string, args: Record<string, unknown>) => Promise<unknown>
+}
+
+interface BrowserAgentRpcClient {
+  client: { register: (definition: BrowserAgentInvocationDefinition) => void }
+  callOptional: (
+    method: 'devframe:agent:sync-client-tools',
+    tools: BrowserAgentToolManifest[],
+  ) => Promise<unknown>
+  events: {
+    on: (
+      event: 'connection:status',
+      listener: (status: DevframeConnectionStatus, previous: DevframeConnectionStatus) => void,
+    ) => () => void
+  }
+}
+
+/** Mirror this document's browser-agent registry over its existing RPC connection. */
+export function setupBrowserAgentRpcBridge(rpc: BrowserAgentRpcClient): () => void {
+  rpc.client.register({
+    name: 'devframe:agent:invoke-client-tool',
+    type: 'action',
+    jsonSerializable: true,
+    handler: async (id: string, args: Record<string, unknown>) => {
+      const tool = listBrowserAgentTools().find(tool => tool.id === id)
+      if (!tool)
+        throw new Error(`[devframe/agent] browser tool "${id}" not found`)
+      return await tool.invoke(args)
+    },
+  })
+
+  let queued = false
+  let disposed = false
+  const sync = (): void => {
+    if (queued || disposed)
+      return
+    queued = true
+    queueMicrotask(async () => {
+      queued = false
+      const manifests = listBrowserAgentTools().map(({ invoke: _, ...manifest }) => manifest)
+      await rpc.callOptional('devframe:agent:sync-client-tools', manifests).catch(() => {})
+    })
+  }
+
+  const stopTools = onBrowserAgentToolsChanged(sync)
+  const stopConnection = rpc.events.on('connection:status', (status) => {
+    if (status === 'connected')
+      sync()
+  })
+  sync()
+
+  return () => {
+    disposed = true
+    stopTools()
+    stopConnection()
+  }
+}

packages/devframe/src/client/browser-agent.ts

@@ -0,0 +1,64 @@
+import type { RpcFunctionAgentOptions } from 'devframe/rpc'
+
+export interface BrowserAgentToolManifest {
+  id: string
+  title?: string
+  description: string
+  safety: 'read' | 'action' | 'destructive'
+  tags?: readonly string[]
+  inputSchema?: unknown
+}
+
+export interface BrowserAgentTool extends BrowserAgentToolManifest {
+  invoke: (args: Record<string, unknown>) => unknown | Promise<unknown>
+}
+
+interface BrowserAgentRegistryState {
+  tools: Map<symbol, BrowserAgentTool>
+  listeners: Set<() => void>
+}
+
+const REGISTRY_KEY = Symbol.for('devframe:browser-agent-registry')
+const state = ((globalThis as any)[REGISTRY_KEY] ??= {
+  tools: new Map(),
+  listeners: new Set(),
+}) as BrowserAgentRegistryState
+const { tools, listeners } = state
+
+function notifyChanged(): void {
+  for (const listener of listeners)
+    listener()
+}
+
+export function registerBrowserAgentTool(tool: BrowserAgentTool): () => void {
+  const key = Symbol(tool.id)
+  tools.set(key, tool)
+  notifyChanged()
+  return () => {
+    if (tools.delete(key))
+      notifyChanged()
+  }
+}
+
+export function listBrowserAgentTools(): BrowserAgentTool[] {
+  const unique = new Map<string, BrowserAgentTool>()
+  for (const tool of tools.values()) {
+    if (!unique.has(tool.id))
+      unique.set(tool.id, tool)
+  }
+  return [...unique.values()]
+}
+
+export function onBrowserAgentToolsChanged(listener: () => void): () => void {
+  listeners.add(listener)
+  return () => listeners.delete(listener)
+}
+
+export function resolveBrowserAgentSafety(
+  type: string | undefined,
+  agent: RpcFunctionAgentOptions,
+): BrowserAgentToolManifest['safety'] {
+  if (agent.safety)
+    return agent.safety
+  return type === 'static' || type === 'query' || type == null ? 'read' : 'action'
+}

packages/devframe/src/client/rpc.ts

@@ -11,6 +11,7 @@ import { DEVFRAME_OTP_URL_PARAM } from 'devframe/constants'
 import { RpcCacheManager, RpcFunctionsCollectorBase } from 'devframe/rpc'
 import { createEventEmitter } from 'devframe/utils/events'
 import { withBase } from 'ufo'
+import { setupBrowserAgentRpcBridge } from './browser-agent-rpc'
 import { setupDevframeConnection } from './connection'
 import { storeAuthToken } from './connection-storage'
 import { authenticateWithUrlOtp } from './otp'
@@ -356,6 +357,7 @@ export async function getDevframeRpcClient(
   const clientRpc: DevframeClientRpcHost = new RpcFunctionsCollectorBase<DevframeRpcClientFunctions, DevframeRpcContext>(context)
   // No-op when the browser provides no WebMCP model context.
   const disposeWebMcp = options.webmcp === false ? undefined : registerWebMcpTools(clientRpc)
+  let disposeBrowserAgentBridge: (() => void) | undefined
 
   async function fetchJsonFromBases(path: string): Promise<any> {
     const candidates = [
@@ -496,6 +498,7 @@ export async function getDevframeRpcClient(
     cacheManager,
     scope: undefined!,
     close: () => {
+      disposeBrowserAgentBridge?.()
       disposeWebMcp?.()
       mode.close?.()
     },
@@ -584,6 +587,8 @@ export async function getDevframeRpcClient(
     () => { bootstrapAuthSettled = true },
   )
 
+  disposeBrowserAgentBridge = setupBrowserAgentRpcBridge(rpc)
+
   // Listen for auth updates from other tabs (e.g., the auth page, or another
   // tab that just completed a code exchange).
   if (authChannel) {

packages/devframe/src/in-page-channel/agent.test.ts

@@ -0,0 +1,75 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec'
+import { describe, expect, it } from 'vitest'
+import { listBrowserAgentTools } from '../client/browser-agent'
+import { createPageScriptChannel } from './page-script'
+
+interface TestProtocol {
+  pageScript: {
+    add: (a: number, b: number) => { sum: number }
+    hidden: () => string
+  }
+}
+
+function schema<T>(json: Record<string, unknown>): StandardSchemaV1<T> {
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'test',
+      validate: (value: unknown) => ({ value: value as T }),
+      jsonSchema: {
+        input: () => json,
+        output: () => json,
+      },
+    } as StandardSchemaV1<T>['~standard'],
+  }
+}
+
+describe('in-page channel agent tools', () => {
+  it('registers the original handler for browser-to-node agent transport', async () => {
+    const channel = createPageScriptChannel<TestProtocol>({
+      name: 'devframes:test',
+      window: false,
+      heartbeat: false,
+      functions: {
+        add: {
+          jsonSerializable: true,
+          agent: { description: 'Add two numbers.' },
+          args: [schema<number>({ type: 'number' }), schema<number>({ type: 'number' })],
+          returns: schema<{ sum: number }>({ type: 'object' }),
+          handler: (a, b) => ({ sum: a + b }),
+        },
+        hidden: { handler: () => 'internal' },
+      },
+    })
+
+    const tool = listBrowserAgentTools().find(tool => tool.id === 'devframes:test:add')!
+    expect(tool).toMatchObject({
+      description: 'Add two numbers.',
+      safety: 'read',
+      inputSchema: {
+        type: 'object',
+        properties: { arg0: { type: 'number' }, arg1: { type: 'number' } },
+        required: ['arg0', 'arg1'],
+        additionalProperties: false,
+      },
+    })
+    await expect(tool.invoke({ arg0: 2, arg1: 3 })).resolves.toEqual({ sum: 5 })
+
+    channel.close()
+    expect(listBrowserAgentTools().some(tool => tool.id === 'devframes:test:add')).toBe(false)
+  })
+
+  it('rejects agent exposure without strict JSON serialization', () => {
+    expect(() => createPageScriptChannel<TestProtocol>({
+      name: 'devframes:invalid',
+      window: false,
+      functions: {
+        add: {
+          agent: { description: 'Add two numbers.' },
+          handler: (a, b) => ({ sum: a + b }),
+        },
+        hidden: { handler: () => 'internal' },
+      },
+    })).toThrowError(/MCP requires JSON-serializable/)
+  })
+})

packages/devframe/src/in-page-channel/diagnostics.ts

@@ -7,5 +7,10 @@ export const diagnostics = /* #__PURE__ */ defineDiagnostics({
       why: (p: { name: string }) => `In-page channel function "${p.name}" is not registered on this endpoint.`,
       fix: 'Declare the function in this endpoint\'s `functions` option.',
     },
+    DF0078: {
+      why: (p: { name: string }) =>
+        `In-page channel function "${p.name}" has \`agent\` set but \`jsonSerializable\` is not \`true\`; MCP requires JSON-serializable data.`,
+      fix: 'Set `jsonSerializable: true` if the payload is JSON-safe, or remove `agent` to keep it channel-only.',
+    },
   },
 })