---
title: "Introduction"
manual: "WebMCP tool for TYPO3"
version: "0.4"
permalink: "https://docs.typo3.org/permalink/neoblack/webmcp:introduction@0.4"
source: "Introduction/Index.rst"
rendered: "2026-10-07T22:31:54+00:00"
---

> [!WARNING]
> **Experimental.** This extension is experimental and not yet ready for
> production use. It is built on top of
> [WebMCP](https://github.com/webmachinelearning/webmcp), which is itself
> an experimental, early-stage proposal. Both the underlying specification
> and this extension's API may change or break at any time without notice.
> Use at your own risk.

# Introduction {#introduction}

## What is WebMCP? {#what-is-webmcp}

WebMCP exposes page-scoped *tools* to AI agents through the browser's
`ModelContext` interface (`document.modelContext`; older Chrome origin
trial builds and polyfills also offer the deprecated
`navigator.modelContext`). An agent operating
the page can discover these tools and call them – for example to search content,
navigate to a section, or open a pre-filled contact e-mail.

```plantuml
actor "AI agent" as Agent

package "Browser" {
  component "ModelContext" as MC
  component "webmcp.js\nruntime" as RT
  component "Registered\npage tools" as Tools
}

package "TYPO3 site" {
  component "Tool providers\n(PHP)" as TP
  component "Manifest\n(JSON in page)" as MF
}

Agent -> MC : discover & call
MC -> RT
RT -> Tools : register
TP -> MF : declare (server-side)
MF ..> RT : delivered in page HTML
```

Where WebMCP sits — agent, browser and your TYPO3 site

> [!NOTE]
> **See also**
>
> The [WebMCP proposal](https://github.com/webmachinelearning/webmcp) of the
> W3C Web Machine Learning Community Group describes the underlying browser API
> this extension builds on.

## What this extension does {#what-this-extension-does}

The extension turns tool definitions into a *declarative* concern:

-   A tool is a small PHP class implementing
    `\Neoblack\Webmcp\Tool\ToolProviderInterface`. It returns a
    `\Neoblack\Webmcp\Tool\Manifest` describing the tool's name, JSON schema
    and behaviour.
-   Behaviour is expressed through one of four **primitives** whose generic
    interpreters live in a single JavaScript runtime (`webmcp.js`). No
    per-tool JavaScript is required.
-   A `\Neoblack\Webmcp\DataProcessing\ToolManifestProcessor` (a TYPO3 data
    processor) collects every registered provider into one JSON block per page;
    the runtime reads it and registers the tools.

The four primitives at a glance:

| Primitive | Behaviour |
| --- | --- |
| `navigate` | Navigate the browser to a URL chosen from a fixed set of options. |
| `search` | Fetch a same-origin JSON index, filter it client-side, return the hits. |
| `mailto` | Build a pre-filled `mailto:` link and open it (no server storage). |
| `static` | Return a curated, static list of items verbatim. |

Because tools are pure server-side configuration, other extensions and site
packages can add their own without touching JavaScript. For behaviour that no
primitive covers, a tool may point at its own ES module (escape hatch).

> [!TIP]
> See [Writing tools](https://docs.typo3.org/permalink/neoblack/webmcp:developer@0.4) for the full payload of each primitive and the
> escape-hatch contract.

## Privacy-preserving analytics {#privacy-preserving-analytics}

An optional first-party ingest endpoint (`/webmcp-event`) logs one row per
tool call – only the tool name and a coarse, self-reported client hint, never
free text, cookies or IP. A backend module visualises the usage. Analytics can
be disabled in the extension configuration.

> [!NOTE]
> **See also**
>
> [Analytics](https://docs.typo3.org/permalink/neoblack/webmcp:analytics@0.4) covers exactly what is recorded, how long it is kept and how
> the public endpoint is hardened.

## Feature detection & progressive enhancement {#feature-detection-progressive-enhancement}

Everything degrades gracefully: without a `ModelContext` implementation,
without configuration, with a malformed manifest or inside an iframe, nothing is
registered and regular visitors are unaffected. Your pages must — and with this
extension do — work fully without WebMCP.

```plantuml
start
if (top-level document?) then (no, iframe)
  :nothing registered;
  stop
endif
if (config block present and valid?) then (no)
  :nothing registered;
  stop
endif
if (document.modelContext.registerTool available?) then (yes)
  :use document.modelContext;
elseif (legacyNavigatorFallback on and\nnavigator.modelContext.registerTool available?) then (yes)
  :use navigator.modelContext\n(deprecated);
else (neither)
  :nothing registered;
  stop
endif
:registerTool() per tool,\neach with its own AbortSignal;
stop
```

Feature detection — nothing is registered without a ModelContext

> [!WARNING]
> **Experimental.** This extension is built on top of the WebMCP proposal,
> which is itself an early-stage, experimental specification. Both the
> specification and this extension's API may change or break at any time
> without notice. Use at your own risk.