SNOWSTORK-SPO-3-Add WebMCP tools for docs search, tutorials, and demo booking

[Simone Poggiali at Snowplow.io (gibbok-snowplow)]

What changed?

The docs site now exposes four WebMCP tools, so an AI agent browsing docs.snowplow.io (for example the ChatGPT desktop app's built-in browser) can act on the site through structured tool calls instead of clicking through the UI.

Tool	What it does
search_docs	Keyword search over the documentation. Queries the same Algolia DocSearch index that powers the site's search box and returns one result per matching page (title, URL, excerpt).
list_tutorials	Lists the tutorials and solution accelerators from the tutorials index, with optional useCase, topic, and technology filters (case-insensitive partial match).
get_tutorial	Returns the step list of a tutorial by slug, plus the reader's progress: completed steps, current step, and percentage complete. Progress comes from the same localStorage entry the tutorial progress tracker already maintains.
book_demo	Selects the Book a demo button on the page, which opens the Snowplow booking page in a new tab.

Files:

• src/js/webmcp.js (new): registers the tools with document.modelContext (falling back to navigator.modelContext for early Chrome builds). No dependencies beyond the browser API. Tutorial helpers are loaded on demand so the main bundle doesn't grow.
• docusaurus.config.ts: adds the module to clientModules.
• ARCHITECTURE.md: notes the tools under "LLM support".

Two assumptions worth checking:

• The request named the last tool bok_demo; I read that as a typo and named it book_demo.
• "The site's documentation search interface" is implemented as a direct call to the site's Algolia index using the public search credentials already in docusaurus.config.ts, rather than driving the search modal. Same backend, same results, deterministic for an agent.

Why?

WebMCP lets a website hand an agent well-defined tools instead of making it scrape and click. These four tools cover the journeys we want agents to complete on the docs site: find the right article, discover tutorials, check where a reader is in a tutorial, and book a demo.

How to test

Site tools in ChatGPT only work over HTTPS or on localhost, and only in the ChatGPT desktop app's built-in browser.

1. Update the ChatGPT desktop app to the latest version. In the app, open Browser settings > Permissions and make sure Enable site tools is on. Site tools are not available in Enterprise or Edu workspaces.
2. Pick a model that supports site tools (GPT-5.6 Sol or GPT-5.6 Terra at the time of writing; Luna has WebMCP disabled).
3. Run the site locally with yarn start, or use a preview deployment.
4. Open the built-in browser from the ChatGPT toolbar and go to a docs page, for example http://localhost:3000/docs/fundamentals/events/. An arrow appears in the address bar when the page offers site tools; select it and check that search_docs, list_tutorials, get_tutorial, and book_demo are listed.
5. Try these prompts in the chat:
   • "Search the docs for how the JavaScript tracker sets cookies." ChatGPT should call search_docs and answer with links from docs.snowplow.io.
   • "Which tutorials are about real-time personalization?" ChatGPT should call list_tutorials with a useCase filter.
   • Open http://localhost:3000/tutorials/signals-quickstart/start/, scroll to the bottom of a step or two, then ask "How far am I through the Signals quick start tutorial?" ChatGPT should call get_tutorial and report the completed steps and the current one.
   • On a docs page in a wide window, ask "Book a demo with Snowplow." ChatGPT should call book_demo and a new tab with the booking page should open. If the browser blocks the pop-up, the tool result includes the booking URL. On pages without the button (for example in a narrow window, where the table of contents column is hidden), the tool explains where to find it.

Without an agent, you can confirm the tools are registered from the browser console on any page: document.modelContext is defined in browsers that ship WebMCP; in others the module does nothing.

Reviewer guidance

• Tool results follow the WebMCP shape { content: [{ type: 'text', text }] }, with isError: true on failures so the agent gets a readable message rather than an exception.
• search_docs sends no facet filters on purpose, so results span docs, tutorials, and release notes.
• Verified locally with yarn build and a headless Chromium run that stubs document.modelContext, exercises all four tools against the built site, and mocks the Algolia response (the sandbox has no outbound access to Algolia). The ChatGPT desktop app itself was not available in the sandbox, so step 4 and 5 above still need a manual run.

AI reviews

Claude will automatically review this PR against the docs style guide.

If you have questions or want it to look again at something specific, tag @claude in a comment.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X6zbjMa6DXgqjvaXCWskv4

---

Generated by Claude Code

[github-actions]

Missing SEO metadata

The following markdown files are missing required metadata fields:

• ARCHITECTURE.md: missing frontmatter block

Required fields

The file metadata is important for SEO and marketing. All markdown files, except for those with filenames starting with _, should include:

• title: Full, descriptive page title
• sidebar_label: Short title for navigation sidebar (can be the same as the main title)
• description: One to two sentences summarizing the page contents
• keywords: Array of marketing/SEO keywords

Please add the missing metadata.

[wiz-2cefcfbd9e]

Wiz Scan Summary

Scanner	Findings
Vulnerabilities	-
Sensitive Data	-
Secrets	-
IaC Misconfigurations	-
SAST Findings	1
Software Management Findings	-
Total	1

View scan details in Wiz

To detect these findings earlier in the dev lifecycle, try the Wiz Code extension for VS Code, JetBrains, or Visual Studio.

[claude]

Docs style review

This PR is almost entirely code (src/js/webmcp.js, docusaurus.config.ts) plus a single bullet in ARCHITECTURE.md. No pages under docs/ or tutorials/ changed, so most of CLAUDE.md doesn't apply. I reviewed the ARCHITECTURE.md addition and the user-visible strings in the new module — tool descriptions and result messages are read by agents and surfaced to readers, so terminology still matters.

Two things to fix, both small.

1. The technology filter example "Snowflake" matches no tutorial

src/js/webmcp.js:

'Filter by technology, for example "Snowflake", "Kafka", or "Signals".'

"Kafka" and "Signals" are real facet values, but no tutorial has Snowflake in technologies or snowplowTech. The full set across tutorials/*/meta.json is: AI assistants, AWS Bedrock, Census, Braze, ClickHouse, Claude Code, CopilotKit, Flink, Gemini, Google ADK, Jupyter notebook, Kafka, Machine learning, MCP, Next.js, OpenAI, Python, React, Redis, Strands Agents, Vercel AI SDK, dbt, plus the Snowplow ones (Console, Local, Micro, Signals, Snowplow CLI, Snowtype).

An agent that copies the first example gets No tutorials matched the filters. Documentation examples should be values that work, so suggest swapping "Snowflake" for one that exists:

'Filter by technology, for example "ClickHouse", "Kafka", or "Signals".',

The useCase and topic examples (Composable CDP, Real-time personalization, Tracking implementation, Solution accelerator) all check out against the metadata.

2. Capitalize "JavaScript" in the search_docs example

src/js/webmcp.js:

'Keywords to search for, for example "javascript tracker cookies".'

The style guide requires the language capitalized with "tracker" lowercase — "JavaScript tracker" (Snowplow terminology, src/pages/style-guide/llm/index.md) — and third-party names matched to their official styling. Suggest:

'Keywords to search for, for example "JavaScript tracker cookies".',

Checked and fine

• The ARCHITECTURE.md bullet follows the conventions: active voice, Oxford comma, backticks on file and tool names, no marketing language, and it sits correctly under LLM support alongside the other LLM-facing features.
• The https://docs.snowplow.io/tutorials/<slug>/... string in the get_tutorial description is a URL-shape illustration for an agent, not an internal link, so CLAUDE.md's "no docs.snowplow.io links to internal pages" rule doesn't bite here. Flagging only so it isn't mistaken for a violation later.
• Error and result strings use straight double quotes, present tense, and no marketing or filler language.
• The one external URL added in the diff, https://webmachinelearning.github.io/webmcp/ in the module header comment, returns 200.
• No release note needed: this is a docs-site capability rather than a product change, and release-notes/_README.md explicitly excludes internal repo changes such as tooling.

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Preview URL	Updated (UTC)
✅ Deployment successful! View logs	documentation	5291705	Commit Preview URL Branch Preview URL	Sep 15 2026, 12:06 PM