web-mcp

WebMCP - 使 AI 代理能够通过结构化工具与您的 Web 应用程序交互。通过工具注册、事件桥模式和上下文工具加载，为 Next.js/React 应用程序实现 WebMCP 标准。在构建 AI 代理可访问的 Web 应用程序、向现有项目添加 MCP 功能或为 AI 交互创建基于工具的界面时使用。

## 概述（中文）

WebMCP - 使 AI 代理能够通过结构化工具与您的 Web 应用程序交互。通过工具注册、事件桥模式和上下文工具加载，为 Next.js/React 应用程序实现 WebMCP 标准。在构建 AI 代理可访问的 Web 应用程序、向现有项目添加 MCP 功能或为 AI 交互创建基于工具的界面时使用。

## 原文

# WebMCP

Enable AI agents to interact with your web applications through structured tools. WebMCP provides a clean, self-documenting interface between AI agents and your web app.

## What is WebMCP?

WebMCP is a web standard that gives AI agents an explicit, structured contract for interacting with websites. Instead of screen-scraping or brittle DOM selectors, a WebMCP-enabled page exposes **tools** — each with:
- A name
- A JSON Schema describing inputs and outputs
- An executable function
- Optional annotations (read-only hints, etc.)

## Quick Start

```bash
# Initialize WebMCP in your Next.js project
webmcp init

# Add a new tool
webmcp add-tool searchProducts

# Generate TypeScript types
webmcp generate-types
```

## Core Concepts

### 1. Tool Definition

```typescript
const searchTool = {
  name: "searchProducts",
  description: "Search for products by query",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string", description: "Search query" }
    },
    required: ["query"]
  },
  outputSchema: { type: "string" },
  execute: async (params) => {
    // Implementation
  },
  annotations: {
    readOnlyHint: "true"
  }
};
```

### 2. Contextual Tool Loading

Tools are registered when components mount and unregistered when they unmount:

```tsx
useEffect(() => {
  registerSearchTools();  // Tools appear to agent
  return () => {
    unregisterSearchTools();  // Tools disappear
  };
}, []);
```

### 3. Event Bridge Pattern

Tools communicate with React through CustomEvents:

```
Agent → execute() → dispatch CustomEvent → React updates → signal completion → Agent receives result
```

## Architecture

```
┌─────────────────────────────────────────┐
│  Browser (navigator.modelContext)       │
│                                         │
│  ┌───────────┐    registers/     ┌────┐ │
│  │ AI Agent  │◄──unregisters────│web │ │
│  │ (Claude)  │    tools         │mcp│ │
│  │           │                  │.ts│ │
│  │ calls─────┼─────────────────►│    │ │
│  └───────────┘                  └──┬─┘ │
│                                    │    │
│                         CustomEvent│    │
│                         dispatch   │    │
│                                    ▼    │
│  ┌──────────────────────────────────┐   │
│  │ React Component Tree             │   │
│  │                                  │   │
│  │ ┌──────────┐   ┌──────────┐     │   │
│  │ │/products │   │  /cart   │     │   │
│  │ │useEffect:│   │useEffect:│     │   │
│  │ │ register │   │ register │     │   │
│  │ │ search   │   │  cart    │     │   │
│  │ │  tools   │   │  tools   │     │   │
│  │ └──────────┘   └──────────┘     │   │
│  └──────────────────────────────────┘   │
└─────────────────────────────────────────┘
```

## Installation

```bash
# In your Next.js project
npx webmcp init

# Or install globally
npm install -g @webmcp/cli
webmcp init
```

## Usage

### 1. Initialize WebMCP

```bash
webmcp init
```

This creates:
- `lib/webmcp.ts` - Core implementation
- `hooks/useWebMCP.ts` - React hook
- `components/WebMCPProvider.tsx` - Provider component

### 2. Define Tools

```typescript
// lib/webmcp.ts
export const searchProductsTool = {
  name: "searchProducts",
  description: "Search for products",
  execute: async (params) => {
    return dispatchAndWait("searchProducts", params, "Search completed");
  },
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" }
    },
    required: ["query"]
  },
  annotations: { readOnlyHint: "true" }
};
```

### 3. Register in Components

```tsx
// app/products/page.tsx
"use client";

import { useEffect, useState } from "react";
import { registerProductTools, unregisterProductTools } from "@/lib/webmcp";

export default function ProductsPage() {
  const [results, setResults] = useState([]);
  const [completedRequestId, setCompletedRequestId] = useState(null);

  // Signal completion after render
  useEffect(() => {
    if (completedRequestId) {
      window.dispatchEvent(
        new CustomEvent(`tool-completion-${completedRequestId}`)
      );
      setCompletedRequestId(null);
    }
  }, [completedRequestId]);

  // Register tools + listen for events
  useEffect(() => {
    const handleSearch = (event: CustomEvent) => {
      const { requestId, query } = event.detail;
      // Perform search
      setResults(searchProducts(query));
      if (requestId) setCompletedRequestId(requestId);
    };

    window.addEventListener("searchProducts", handleSearch);
    registerProductTools();

    return () => {
      window.removeEventListener("searchProducts", handleSearch);
      unregisterProductTools();
    };
  }, []);

  return <div>{/* Product UI */}</div>;
}
```

## CLI Commands

| Command | Description |
|---------|-------------|
| `webmcp init` | Initialize WebMCP in project |
| `webmcp add-tool <name>` | Add new tool definition |
| `webmcp generate-types` | Generate TypeScript types |
| `webmcp example <type>` | Create example project |

## Tool Types

### Read-Only Tools

```typescript
{
  name: "viewCart",
  description: "View cart contents",
  annotations: { readOnlyHint: "true" }
}
```

### Mutating Tools

```typescript
{
  name: "addToCart",
  description: "Add item to cart",
  annotations: { readOnlyHint: "false" }
}
```

### Tools with Parameters

```typescript
{
  name: "setFilters",
  inputSchema: {
    type: "object",
    properties: {
      category: { type: "string", enum: ["electronics", "clothing"] },
      maxPrice: { type: "number" }
    }
  }
}
```

## Examples

### E-Commerce

```bash
webmcp example e-commerce
```

Features:
- Product search
- Cart management
- Checkout flow
- Order tracking

### Dashboard

```bash
webmcp example dashboard
```

Features:
- Widget interactions
- Data filtering
- Export functionality
- Real-time updates

### Blog

```bash
webmcp example blog
```

Features:
- Article search
- Comment posting
- Category filtering
- Related articles

## Best Practices

### 1. Tool Naming

Use camelCase verbs that describe the action:
- ✅ `searchProducts`
- ✅ `addToCart`
- ✅ `updateProfile`
- ❌ `product_search`
- ❌ `handleCart`

### 2. Descriptions

Write clear, specific descriptions:
- ✅ "Search for products by name or category"
- ❌ "Search stuff"

### 3. Schema Completeness

Always include descriptions for parameters:

```typescript
properties: {
  query: {
    type: "string",
    description: "The search query to find products by name or category"
  }
}
```

### 4. Contextual Loading

Register tools only when relevant:

```tsx
// Product page
useEffect(() => {
  registerProductTools();
  return () => unregisterProductTools();
}, []);

// Cart page  
useEffect(() => {
  registerCartTools();
  return () => unregisterCartTools();
}, []);
```

### 5. Error Handling

Always handle timeouts and errors:

```typescript
async function execute(params) {
  try {
    return await dispatchAndWait("action", params, "Success", 5000);
  } catch (error) {
    return `Error: ${error.message}`;
  }
}
```

## Browser Support

WebMCP requires browsers that support:
- CustomEvent API
- navigator.modelContext (proposed standard)

For development, use the WebMCP polyfill:

```typescript
import "@webmcp/polyfill";
```

## Resources

- [WebMCP Specification](https://github.com/webmcp/spec)
- [Example Projects](https://github.com/webmcp/examples)
- [React Integration Guide](https://webmcp.dev/react)

## Integration with Other Skills

- **ai-labs-builder**: Use WebMCP to make AI apps agent-accessible
- **mcp-workflow**: Combine with workflow automation
- **gcc-context**: Version control your tool definitions