docs/WEBMCP.md

Rama main · réplica de lectura del repositorio original.

# WebMCP: driving AgentRQ from a browser agent

AgentRQ offers its own interface to an AI agent running in your browser. If your
browser supports [WebMCP](https://github.com/webmachinelearning/webmcp), an
agent you talk to there can list your workspaces, open a task, reply in it,
change a status, build a workflow — anything you can do by clicking, it can do
by calling a tool.

Nothing to install and nothing to configure. Open AgentRQ, sign in, and the
tools are there.

---

## What it is

WebMCP is a browser API that lets a *page* hand the agent a set of typed tools.
It is the same idea as an MCP server, with one difference that matters: the
tools run inside the page you already have open, as you, in your session. The
agent never needs a token, never sees your credentials, and can do exactly what
your account can do — no more.

That last point is worth being concrete about. A tool call is the same HTTP
request the interface itself makes, carrying the same cookie. If you cannot
delete a workspace, neither can the agent.

## What you can ask for

Every capability of the interface, grouped roughly as the app is:

| Area | Examples |
|---|---|
| **Where you are** | `getCurrentPage`, `navigate` |
| **Workspaces** | list, read, create, update, archive, unarchive, delete, stats, Slack channel, connection token |
| **Tasks** | list, read (and page in older tool calls), create, reply, respond, fork, status, assignee, order, move, stop, delete, permission verdicts, elicitation answers, scheduled-task template, counts |
| **Events** | list, read, create, update, delete, triggers (list/create/update/delete), tasks an event spawned |
| **Workflows** | list, read, create, update, delete, steps, tasks, and the whole workflow as editable text |

`getCurrentPage` is the one to know about. It tells the agent which page you are
looking at and the IDs in the URL, which is what turns "reply to this task" into
a real call. Without it the agent would have to ask you for IDs you should never
have to read.

`navigate` takes you to a page. Its description maps every page in the app,
query parameters included (a workspace's `?filter=`, its settings' `?tab=`), so
an agent can build the path itself. It refuses anything that isn't an in-app
path, or that matches no page, and answers with the page you actually landed on.

When an agent changes something, the page you have open shows it straight
away: workflows, events, workspaces and machines re-read in place, and tasks
arrive live as they always have. A form with unsaved input is left as you had it.

Two things in the interface are deliberately **not** tools:

- **Attachments.** Their URLs are rendered by the page and fetched by the
  browser with your session; there is nothing an agent can usefully do with one.
- **Telemetry.** The app records a little about its own use. That is not an
  action you take, so it is not something to offer.

## Reading the annotations

Every tool says what kind of thing it is, so an agent can decide what to do
without asking you and what to check first:

- **`readOnlyHint`** — reads nothing but data. `listWorkspaces`, `getTask`,
  `getCurrentPage` and the rest of the read side.
- **`destructiveHint`** — removes something that does not come back:
  `deleteWorkspace`, `deleteTask`, `deleteEvent`, `deleteEventTrigger`,
  `deleteWorkflow`, `deleteWorkflowStep`, and `replaceWorkflowFromText`, which
  drops anything not in the text you give it.

A good agent will confirm a destructive call with you first. AgentRQ marks them
so it can.

## Which browsers

WebMCP is new and support is uneven. AgentRQ looks for it in both places the
specification has used — `document.modelContext` (current) and
`navigator.modelContext` (deprecated in Chromium 150) — and if neither is there,
does nothing at all. The app is unchanged; there are simply no tools.

The API also requires a secure context, so it will not appear on a plain `http://`
page. Serve AgentRQ over HTTPS, or use `http://localhost`, which browsers treat
as secure.

This works the same way in the desktop app, which runs the same interface.

## Signing out

The tools are registered when you sign in and withdrawn the moment you sign out.
Because they act as you, leaving them registered would leave an agent holding a
session that has ended — so it does not happen, and there is a test that fails
if it ever starts.

---

## Letting agents use other websites' tools

The other direction works too. When a website you use offers its own WebMCP
tools (a shop, a CRM, a docs site), you can share it with one of your
workspaces. The agent working there can then call those tools in your Chrome,
signed in as you, from Claude Code or any other harness connected to the
workspace.

**Turn it on.** Install the AgentRQ Chrome extension, open its popup, and choose
**Turn on** in the strip at the top. Chrome asks for access to all sites: the
extension needs it to notice which pages offer tools. It reads nothing else.

**Share a site.** On a page that offers tools, the AgentRQ icon shows how many.
Open the popup, pick a workspace, and click **Share**. Only sites you share are
visible to agents, and each site goes to one workspace. **Stop sharing** in the
popup, or the **Shared websites** list in Options, takes it away again.

**What the agent sees.** Three tools on the workspace server: `listSiteTools`
lists the shared sites and each tool's name and description (ranked by `q`
with BM25, filtered by a regular expression `pattern`, and paged with `limit`
and `offset`; with neither `q` nor `pattern` the tools come by name),
`getSiteToolDefinition` gives one tool's input schema, and `callSiteTool` runs
it. From a terminal, `agentrq-ws site-tools`, `agentrq-ws site-tool` and
`agentrq-ws call-site-tool` do the same.

**Approvals.** A tool the site marks read-only runs straight away. Anything else
asks you in the task first: **Allow once**, **Always allow** that tool on that
site, or **Deny**.

**No tab open?** The extension opens the site in a background tab and leaves it
open. Chrome must be running with the extension, and you must still be signed in
to the site. Otherwise the agent is told why the call failed.

Some limits:

- Only browsers with native WebMCP. The extension never adds the API to a page
  that lacks it.
- Only the page itself, never its iframes, so an ad or an embed cannot offer
  tools.
- A site's tools and results come from that site. Agents are told to treat them
  as data, not as instructions.
- A site's claim that a tool is read-only is its own. It can only act on itself,
  and only because you shared it.

---

## For contributors

Three files, and the split between them is deliberate:

- `frontend/src/webmcp/modelContext.js` — the browser seam. Finds the API,
  registers tools one at a time so a refusal costs one tool rather than the
  page, and reports why nothing registered. No Vue.
- `frontend/src/webmcp/tools.js` — the catalogue. Pure: it takes the API client
  and a router and returns descriptors.
- `frontend/src/composables/useWebMCP.js` — the wiring, and the only part that
  knows about Vue.

**The invariant to keep:** the catalogue mirrors `frontend/src/api.js`. That
module is the interface's capability surface, so mirroring it is what makes
"anything you can do in the UI" checkable. `frontend/test/webmcpTools.test.js`
enforces it — it drives every tool against a recording stub and asserts that
every exported API function was reached. Add a function to `api.js` without
adding a tool and that test fails, which is the intent.

Verify the whole path in a real browser with:

```bash
cd desktop && npm run verify:webmcp
```

It needs no backend: it installs a stub `document.modelContext` exactly as a
supporting browser would, answers the API itself so each tool call is
observable, and checks registration, invocation, navigation, annotations and
withdrawal on sign-out.