WebMCP

@pathmx/webmcp lets supported browsers discover and invoke the interactions in an open PathMX site. Enable it once; mounted Sources need no exposure declarations.

bun run pmx plugins add webmcp

The command installs the package and activates it in your root package.json:

{
  "pathmx": {
    "plugins": { "@pathmx/webmcp": {} }
  }
}

Complete the Input reflection example in an initialized project, including its local Actor and writable Home. Keep its paths/reflection.page.md, stable reflection response id, idea field, and saved-value display. Run bun run dev, sign in as Ada, and open /reflection.page.

1. Use a browser/agent environment with document.modelContext.registerTool support. Ask the agent to discover the open site's tools. It should find mounted interaction context for /reflection.page; tool names are generated, so select the current tool by its Source and description rather than hard-coding a name.
2. Enter “Add a worked example” in the visible Your idea field. Ask the agent to read that response's context and confirm values.idea contains the draft.
3. Inspect the available operation described as Submit current response. Invoke it with {}. It submits the visible draft through the same owner as Save and Player, preserving validation and submission guards.
4. Observe the success result and the page's saved-value display. Reload: the submitted idea remains saved for Ada. Editing the draft again does not change the submitted snapshot until the next successful save.

With an empty required field or unavailable session/storage, submission is not available; correct the field or restore the account/Home before rediscovering it. Without the browser API, no site tools register and the ordinary Save control continues to work. See supported-browser setup below; activating the package alone does not add browser support.

A local operation with parameters exposes its existing argument schema. Upload tools use Uppy's existing queue and operations.

Discovery follows mounted interaction owners, including Sources opened in managed same-origin frames. Opening and closing Sources updates the available tools. Unmounted files and arbitrary frames are outside discovery.

read, execute, and result default to true. Set a global option to apply it across Sources, or override individual options under sources:

{
  "pathmx": {
    "plugins": {
      "@pathmx/webmcp": {
        "sources": {
          "/reflection.page": {
            "read": ["/values/idea"],
            "execute": ["submit"],
            "result": ["/submittedAt", "/receipt/occurredAt"]
          },
          "/assessment.page": { "execute": false },
          "/private.page": { "read": false, "execute": false }
        }
      }
    }
  }
}

Source keys are exact identities relative to paths, starting with /; a final .md is optional. A Source override inherits omitted options from the global settings. Sources without overrides use the global defaults. Set execute: false at the Plugin level to make the site read-only, then override selected Sources with execute: true if needed.

JSON Pointer projections preserve selected object structure and omit missing fields. The reflection example selects values.idea from context and receipt fields from the result. Default results exclude raw server authority metadata. Operation availability is checked again when invoked; a retained tool cannot act through an owner that has been disposed. An operation that finishes after its mount disappears returns a limited completion receipt.

The Plugin uses imperative document.modelContext.registerTool() on the top-level page. It detects support automatically; ordinary controls continue to work when the API is unavailable. Browser support and agent discovery depend on the browser and account. See OpenAI's site tools guide for its supported browser setup.

Managed same-origin Source frames publish through the top-level registration. Cross-origin frames and remote invocation are outside this integration.

WebMCP uses each interaction's existing persistence and authorization. Static sites can expose disposable local operations. Committed personal Input requires a writable browser publication or shared host; ordinary static export does not supply writable Sources. Server-backed operations still require their configured host, session, and authorization. Enabling the Plugin does not provide a server or change where responses are saved.

Browser-hosted publication accepts the default manifest activation. To customize that publication target, compose the configured Plugin in a repository Plugin:

import WebMCPPlugin from "@pathmx/webmcp"

export default WebMCPPlugin({ execute: false })

Use this repository Plugin instead of the package activation entry. Server hosting and static export also accept the manifest options shown above. See Plugin configuration for the shared publication rules.

• Packages
• Input forms
• Player
• Attachments