WebMCP Implementation Guidelines for AI Agents

# WebMCP Implementation Guidelines for AI Agents

## 0. Architectural Directive

* **Target Environment:** This project utilizes the client-side Web Machine Context Protocol (WebMCP).

* **Restriction:** DO NOT create backend Model Context Protocol (MCP) servers using Python, Node.js, or Go. All tool execution logic must remain within the frontend client-side JavaScript context.

## 1. Dependencies and Setup

* Install the global polyfill dependency: `npm install @mcp-b/global`.

* Import the polyfill at the top of the relevant component or application entry point: `import '@mcp-b/global';`.

## 2. Imperative API Implementation (JavaScript Tools)

Expose programmatic capabilities by registering tools via the global navigator object.

* **Registration:** Use `window.navigator.modelContext.registerTool(toolObject)`.

* **Tool Dictionary Schema:**

* `name`: A unique string identifier for the tool (e.g., `calculate\_sum`). Tool name collisions will throw synchronous errors.

* `description`: A clear, positive natural language prompt explaining the tool's purpose and the logic behind its parameters.

* `inputSchema`: A strictly typed object adhering to JSON Schema Draft 2020-12 defining all expected arguments. Use specific enums, required arrays, and primitives.

* `execute(args)`: An asynchronous callback function that executes the logic and MUST return a `Promise` resolving to the content payload.

* **Lifecycle Management (React/Vue):** Tools must be registered inside component lifecycle hooks (e.g., `useEffect` in React). You must implement cleanup logic using `unregisterTool(name)` when the component unmounts to prevent context collisions.

* **Performance:** For long-running tasks, stream intermediate updates or logs to prevent the agent from timing out. For database queries, enforce limits and pagination to avoid exceeding context windows.

## 3. Declarative API Implementation (HTML Forms)

When refactoring existing HTML forms, convert them into agent-callable tools by injecting declarative attributes.

* Add `toolname="unique\_identifier"` directly to the `<form>` tag.

* Add `tooldescription="Description of the form's purpose"` to the `<form>` tag.

* Add `toolparamdescription="Description of expected data"` to individual `<input>`, `<select>`, or `<textarea>` elements to automatically generate the tool's schema properties.

* *(Optional)* Add the `toolautosubmit` boolean attribute to the `<form>` if the agent is authorized to submit the payload without waiting for manual human confirmation.

## 4. Implicit Actuation Optimization (Fallback)

Ensure the User Interface remains accessible for fallback agents relying on Document Object Model parsing rather than explicit APIs.

* Strictly utilize semantic HTML5 elements (`<main>`, `<article>`, `<section>`, `<nav>`, and native `<button>` tags).

* Apply explicit `aria-label` attributes to custom interactive elements (e.g., visually styled calculator operators). Do not use ARIA attributes if a native HTML element accomplishes the same task.

## 5. Testing Protocols

* When generating unit tests that execute in headless virtual machines, utilize the `window.navigator.modelContextTesting.setMockToolResponse("tool\_name", mockResponse)` method. This bypasses the live `execute()` callback and simulates a successful agent execution loop.

## 6. Discovery Integration

* Upon creating a new WebMCP tool or exposing a new declarative form, you must update the `llms.txt` file located at the repository/domain root. Ensure the new tool endpoints and capabilities are documented in the markdown index so navigating agents can discover them.