Getting started 

What is WebMCP? 

WebMCP exposes page-scoped tools to AI agents through the browser's ModelContext interface ( document.modelContext, with a fallback to navigator.modelContext used by Chrome's origin trial). 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.

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:

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

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.

Feature detection & progressive enhancement 

Everything degrades gracefully: without a ModelContext implementation, without configuration, or with a malformed manifest, nothing is registered and regular visitors are unaffected.

Requirements 

Install the extension 

composer require neoblack/webmcp

Set up the extension 

Run the setup command to create the analytics table tx_neoblackwebmcp_event:

vendor/bin/typo3 extension:setup --extension neoblack_webmcp

Prerequisites 

• The extension is installed and set up (see Installation).
• You have a site package where you can add PHP classes and TypoScript.

Step 1 – Write a tool provider 

Create a small PHP class in your site package (or any extension). Because the \Neoblack\Webmcp\Tool\ToolProviderInterface carries the #[AutoconfigureTag('webmcp.tool')] attribute, an autoconfigured service implementing it is picked up automatically — no Services.yaml entry is needed as long as your extension enables autoconfiguration.

<?php

declare(strict_types=1);

namespace Vendor\SitePackage\Tool;

use Neoblack\Webmcp\Tool\Manifest;
use Neoblack\Webmcp\Tool\Primitive;
use Neoblack\Webmcp\Tool\ToolProviderInterface;
use TYPO3\CMS\Frontend\ContentObject\ContentObjectRenderer;

final class ServicesToolProvider implements ToolProviderInterface
{
    public function name(): string
    {
        return 'list_services';
    }

    public function manifest(ContentObjectRenderer $cObj, array $processedData): ?Manifest
    {
        return new Manifest(
            name: 'list_services',
            description: 'List the services this company offers.',
            inputSchema: ['type' => 'object', 'properties' => new \stdClass()],
            primitive: Primitive::StaticList,
            data: [
                'items' => [
                    ['title' => 'Consulting', 'url' => 'https://example.org/consulting'],
                    ['title' => 'Development', 'url' => 'https://example.org/development'],
                ],
                'resultKey' => 'services',
                'text' => [
                    'heading' => 'Our services:',
                    'line' => '{n}. {title} – {url}',
                ],
            ],
        );
    }
}

Vendor\SitePackage\Tool\ServicesToolProvider:
  tags:
    - name: webmcp.tool

Step 2 – Wire the manifest into the page 

Add the three pieces described in Configuration to your site package. In short:

page.10.dataProcessing {
    40 = Neoblack\Webmcp\DataProcessing\ToolManifestProcessor
    40 {
        endpoint = /webmcp-event
        as = webmcpConfigJson
    }
}

page.includeJSFooter {
    webmcp = EXT:neoblack_webmcp/Resources/Public/JavaScript/webmcp.js
    webmcp.defer = 1
}

Render the JSON block once in your page template:

<f:if condition="{webmcpConfigJson}">
    <script type="application/json" id="webmcp-config"><f:format.raw>{webmcpConfigJson}</f:format.raw></script>
</f:if>

Step 3 – Verify it in the browser 

Reload a frontend page and open the browser's developer console.

1. Confirm the manifest is on the page:

   Console — inspect the manifest

   JSON.parse(document.getElementById('webmcp-config').textContent).tools

   Copied!

   You should see your list_services tool in the returned array.

   

2. Confirm the runtime registered it against the ModelContext:

   Console — check for an agent surface

   document.modelContext || navigator.modelContext

   Copied!

   A ModelContext implementation is only present in agent-capable browsers (or Chrome with the origin trial enabled). If document.modelContext and navigator.modelContext are both undefined, the page is fine — there is simply no agent surface to register against.

Next steps 

• Swap static for another primitive — search, navigate or mailto — see Writing tools.
• Return null from manifest() to hide a tool on pages where it does not apply.

Extension configuration 

Set these in the TYPO3 backend under Admin Tools > Settings > Extension Configuration > neoblack_webmcp (the defaults live in ext_conf_template.txt).

Wiring the manifest into your site 

Three pieces connect the tools to the page. All of them live in your site package / TypoScript, so you stay in control of where the tools are exposed.

page.10.dataProcessing {
    # optional: a menu a navigate tool can build on
    35 = menu
    35 {
        entryLevel = 0
        levels = 1
        as = webmcpTopics
    }
    40 = Neoblack\Webmcp\DataProcessing\ToolManifestProcessor
    40 {
        endpoint = /webmcp-event
        as = webmcpConfigJson
    }
}

<f:if condition="{webmcpConfigJson}">
    <script type="application/json" id="webmcp-config"><f:format.raw>{webmcpConfigJson}</f:format.raw></script>
</f:if>

page.includeJSFooter {
    webmcp = EXT:neoblack_webmcp/Resources/Public/JavaScript/webmcp.js
    webmcp.defer = 1
}

Backend module 

When analytics is enabled, the System > WebMCP module visualises tool usage.

The interface 

interface ToolProviderInterface

Fully qualified name

\Neoblack\Webmcp\Tool\ToolProviderInterface

Implemented by every tool and tagged webmcp.tool via the interface's #[AutoconfigureTag] attribute.

name ( )

Context-free, stable tool name. Used for the analytics whitelist before the frontend is resolved, so it must equal the Manifest name.

Returns

string – the stable tool name

manifest ( $cObj, $processedData)

Build the tool's manifest for the current request.

param ContentObjectRenderer $cObj

the current content object renderer

param array $processedData

results of data processors that ran earlier in the same content object, so you can build on them (e.g. a menu)

Returns

a Manifest, or null to omit the tool for this request (e.g. a blog tool on a site without a blog)

The manifest 

class Manifest

Fully qualified name

\Neoblack\Webmcp\Tool\Manifest

The serialisable description of a single tool. A provider returns one of these; the data processor collects them into the page's JSON block.

Construct it with named arguments:

new Manifest(
    name: 'search_articles',
    description: 'Search all articles …',
    inputSchema: [ /* JSON schema for the arguments */ ],
    primitive: Primitive::Search,
    data: [ /* primitive-specific payload, see below */ ],
    moduleUrl: null, // optional escape hatch, see below
);

Read-only hint 

Each manifest carries a WebMCP annotations.readOnlyHint flag telling the agent whether the tool merely reads state or changes it. Agents use it to decide whether a call may run without user confirmation.

The value is derived from the primitive: search and static are read-only, navigate (changes the browser location) and mailto (opens a mail client) are not. Pass readOnly: true/false explicitly to override the default — for example when an escape-hatch module built on the search primitive actually mutates state.

Untrusted-content hint 

The manifest also carries a WebMCP annotations.untrustedContentHint flag. It tells the agent that the tool's output may contain untrusted, third-party data that should be treated with caution — a prompt-injection defence.

It is derived from the primitive: only search is flagged, because its results come from a JSON index that can hold user-generated content. static is curated, and navigate / mailto only return messages the runtime built itself, so all three default to false. Pass untrustedContent: true/false to override — for instance when a static list is assembled from user-supplied data, or an escape-hatch module returns third-party content.

Primitives 

Every tool maps to exactly one primitive. The generic runtime interprets the data payload; you never write JavaScript.

primitive: Primitive::Navigate,
data: [
    'param' => 'kategorie',                       // which argument selects
    'options' => [
        ['match' => 'software', 'label' => 'Software', 'url' => 'https://…'],
    ],
    'confirm' => 'Open „{label}"?',               // optional; see below
    'messages' => [                               // optional templates
        'success' => 'Navigating to „{label}".',
        'unknown' => 'Unknown option. Available: {options}.',
        'cancelled' => 'Navigation to „{label}" was cancelled.',
    ],
]

primitive: Primitive::Search,
data: [
    'indexUrl' => 'https://…/index.json',
    'queryParam' => 'query',
    'limitParam' => 'limit',
    'limitDefault' => 10,
    'queryRequired' => true,                      // false: list all when empty
    'searchFields' => ['title', 'teaser'],        // fields searched
    'resultKey' => 'results',
    'resultFields' => ['title' => 'title', 'cat' => 'categoryLabel'],
    'deepLinkTemplate' => 'https://…/blog#q={query}', // optional
    'text' => [                                   // optional output templates
        'heading' => '{count} hits for „{query}“:',
        'headingAll' => '{count} entries:',
        'line' => '{n}. {title} – {url}',
        'emptyQuery' => 'No hits for „{query}“.',
        'emptyAll' => 'No entries.',
    ],
]

primitive: Primitive::Mailto,
data: [
    'to' => base64_encode('me@example.org'),      // base64, kept out of source
    'subjectTemplate' => 'Request – {anliegen}',
    'bodyLines' => [                              // "Label: value" lines
        ['label' => 'Name', 'param' => 'name'],
        ['label' => 'Organisation', 'param' => 'org', 'optional' => true],
    ],
    'messageParam' => 'message',                  // free text block at the end
    'confirm' => 'Send this e-mail to {to}?',      // optional; see below
    'successTemplate' => 'A pre-filled e-mail to {to} has been opened.',
]

primitive: Primitive::StaticList,
data: [
    'items' => [['title' => 'Software', 'url' => 'https://…']],
    'resultKey' => 'services',
    'text' => ['heading' => 'Services:', 'line' => '{n}. {title} – {url}'],
]

Template placeholders 

The text templates use {field} placeholders filled from the item (or, for headings, from {count} / {query}). {n} yields the 1-based index of the current line.

Confirming side effects 

The navigate and mailto primitives change state — they move the browser or open a mail client. Set a confirm message on their data to require a human-in-the-loop confirmation before the side effect runs. The runtime prefers the WebMCP client's requestUserInteraction() (which lets the agent surface the page to the user first) and falls back to a plain confirm() when the client does not provide it. If the user declines, the tool returns an isError result (navigate uses the cancelled message when set) and the side effect never happens.

Omit confirm to keep the previous behaviour — the tool runs without asking. The confirm string is filled with the same {placeholders} as the other messages (navigate: the chosen option; mailto: {to} and {subject}).

Escape hatch 

If no primitive fits, leave primitive at any value, keep data minimal and set moduleUrl to the URL of an ES module exporting an execute function. The runtime imports the module lazily — on the tool's first call — and delegates to it. A moduleUrl is only used when no built-in primitive matches, so a custom module always wins the fallback, never overrides a primitive.

// served same-origin, or CORS-enabled for dynamic import
export function execute(args, ctx) {
    // args: the tool arguments the agent passed, already normalised
    //       (the runtime unwraps an { arguments: {…} } envelope for you).
    //       Includes the optional `client` analytics hint if the agent set it.
    //
    // ctx:  { tool, config, client }
    //   ctx.tool   – this tool's manifest object
    //                { name, description, inputSchema, primitive, data, moduleUrl }
    //   ctx.config – the whole page manifest { endpoint, tools: [...] }
    //   ctx.client – the WebMCP ModelContextClient (may be undefined); call
    //                ctx.client.requestUserInteraction(cb) for confirmations

    // Return an MCP tool result. `content` is required; `structuredContent`
    // is optional machine-readable output. You may return a Promise.
    return {
        content: [{ type: 'text', text: 'Done.' }],
        structuredContent: { ok: true },
    };
}

return { content: [{ type: 'text', text: 'No match.' }], isError: true };

Analytics 

Every tool call sends a same-origin beacon to the configured endpoint. The \Neoblack\Webmcp\Registry\ToolRegistry::toolNames() list (all registered providers) is the whitelist the ingest middleware validates against – it follows your tools automatically.

Emitting tools (frontend render) 

Ingesting usage events (call time) 

Why the two flows are decoupled 

The middleware runs early, before the frontend page is resolved, so it cannot rely on a rendered manifest. It therefore validates incoming events against \Neoblack\Webmcp\Registry\ToolRegistry::toolNames() — the context-free provider names — rather than against the per-page manifest.

What is recorded 

Every tool call fires a small same-origin beacon ( navigator.sendBeacon, with a fetch fallback) to the ingest endpoint. The \Neoblack\Webmcp\Middleware\EventMiddleware appends exactly two values per call:

• the tool name – validated against the registered providers ( \Neoblack\Webmcp\Registry\ToolRegistry::toolNames()); events for unknown names are not stored.
• a client hint – a short, self-reported or coarsely detected label of the calling agent.

Data model 

Events live in a single append-only table, created by extension:setup:

Retention and deletion 

The table is append-only; the extension does not prune it automatically. Because a row is fully anonymous, there is no per-subject deletion to perform, but you remain free to trim or clear the log at any time, for example:

-- drop everything older than 90 days
DELETE FROM tx_neoblackwebmcp_event WHERE crdate < UNIX_TIMESTAMP() - 90*86400;

-- clear the log completely
TRUNCATE tx_neoblackwebmcp_event;

If you schedule this, a simple periodic DELETE on crdate is enough; the crdate column is indexed.

The ingest endpoint 

POST /webmcp-event is public by design (agents call it without a backend session). It is protected by several deliberate constraints:

Backend module 

When analytics is enabled, the System > WebMCP module shows calls per tool and per client, a per-day timeline and the most recent events. The timeframe (7 / 30 / 90 days) and tool/client filters are selectable; the accepted tool names are derived automatically from the registered providers.

Unreleased 

• Added: each manifest now also carries the WebMCP annotations.untrustedContentHint flag, warning the agent that a tool's output may contain untrusted third-party data. It is derived from the primitive (only search is flagged) and overridable via the new untrustedContent argument on Manifest.
• Added: Manifest gained an optional title argument — a human-readable label for UI display, distinct from the machine-stable name. It is emitted into the manifest and forwarded to the tool descriptor only when set.
• Changed: the runtime now registers its tools atomically via provideContext({ tools }) (the WebMCP spec's primary entry point), falling back to per-tool registerTool only where provideContext is absent. Manifest entries that reuse a name already taken are dropped, so a duplicate tool name no longer aborts registration.
• Added: the navigate and mailto primitives accept an optional confirm message that triggers a human-in-the-loop confirmation before the side effect runs, via the WebMCP client's requestUserInteraction() (with a confirm() fallback). Escape-hatch modules now receive the client as ctx.client. Without a confirm message the behaviour is unchanged.
• Changed: the built-in primitives now flag genuine failure paths (navigate with an unknown option, mailto with no configured contact) with the WebMCP isError result flag, so agents can tell a failed call from a successful one. An empty but valid search result stays a success.
• Added: each tool manifest now carries a WebMCP annotations.readOnlyHint flag, derived from the primitive (search and static are read-only; navigate and mailto are not) and overridable via the new readOnly argument on Manifest. The generic runtime forwards it to registerTool so agents can tell read-only tools from state-changing ones.

0.2.0 - 2026-07-19 

• Breaking: the backend module moved from the Web group to System, and its route identifier changed from web_webmcp to system_webmcp. The module no longer carries a page tree — its statistics are site-wide. Update any backend user/group access rights and hardcoded module links accordingly.
• Changed: the backend module icon was redrawn in the three-colour TYPO3 v14 icon style.
• Added: an ext_emconf.php so the extension can be published to and installed from the TER.
• Documentation: added a Quickstart, an Architecture overview, a dedicated Analytics chapter (data model, retention, endpoint hardening), a Troubleshooting guide and this changelog.

0.1.0 

Initial experimental release.

• Declarative tool framework: define agent tools as server-side PHP providers ( ToolProviderInterface) collected into a per-page manifest.
• Four behaviour primitives interpreted by a single generic runtime (webmcp.js): navigate, search, mailto, static.
• Escape hatch: a tool may point at its own ES module for behaviour no primitive covers.
• Optional, privacy-preserving first-party analytics: anonymous per-call logging via /webmcp-event, rate limiting, and a System > WebMCP backend module.
• Requires TYPO3 v14.3+ and PHP 8.2+.