[@layout]: ../docs.layout.md

# 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.

---

## Install and activate

```sh
bun run pmx plugins add webmcp
```

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

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

Complete the [Input reflection example](../authoring/input.reference.md#author-a-response)
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`.

---

## Discover, inspect, and submit a reflection

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.

---

## Optional customization

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

```json
{
  "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 }
        }
      }
    }
  }
}
```

| Option | `true` | `false` | Array |
| --- | --- | --- | --- |
| `read` | Return available context. | Disable context reads. | Select context fields with JSON Pointers. |
| `execute` | Expose currently admitted operations. | Disable execution. | Select operation names. |
| `result` | Return the permitted operation result. | Omit result data. | Select result fields with JSON Pointers. |

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.

---

## Browser and hosting behavior

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](https://learn.chatgpt.com/docs/webmcp)
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](./state.reference.md#save-input-and-progress-in-the-browser)
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:

```ts
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](./plugin-configuration.reference) for the shared publication
rules.

## Related

- [Packages](../packages.reference)
- [Input forms](../authoring/input.reference)
- [Player](../learning/player.reference)
- [Attachments](../accounts/attachments.reference)