WebMCP: In-Browser MCP Server Architecture

graph LR
    subgraph Host Window: Main Thread
        AgentClient[MCP Client: React / Web Agent]
    end

    subgraph Web Worker Sandbox
        WorkerTransport[WorkerPostMessageTransport]
        WebMCPServer[WebMCP Server Instance]
        DOMHandler[DOM / IndexedDB / Canvas Tools]
    end

    AgentClient <-->|postMessage: JSON-RPC 2.0| WorkerTransport
    WorkerTransport <--> WebMCPServer
    WebMCPServer <--> DOMHandler

// webmcp-transport.ts
import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
import { JSONRPCMessage } from "@modelcontextprotocol/sdk/types.js";

export class BrowserWorkerTransport implements Transport {
  private worker: Worker;
  public onclose?: () => void;
  public onerror?: (error: Error) => void;
  public onmessage?: (message: JSONRPCMessage) => void;

  constructor(worker: Worker) {
    this.worker = worker;
    this.worker.onmessage = (event: MessageEvent) => {
      if (this.onmessage && event.data?.jsonrpc) {
        this.onmessage(event.data);
      }
    };
    this.worker.onerror = (err) => {
      if (this.onerror) this.onerror(new Error(err.message));
    };
  }

  async start(): Promise<void> {
    // Worker is already running
    return Promise.resolve();
  }

  async send(message: JSONRPCMessage): Promise<void> {
    this.worker.postMessage(message);
  }

  async close(): Promise<void> {
    this.worker.terminate();
    if (this.onclose) this.onclose();
  }
}

// webmcp.worker.ts
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import {
  ListToolsRequestSchema,
  CallToolRequestSchema
} from "@modelcontextprotocol/sdk/types.js";

const server = new Server(
  { name: "WebMCP-DOM-Inspector", version: "1.0.0" },
  { capabilities: { tools: {} } }
);

// Expose browser-native tools
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [
      {
        name: "extract_page_headings",
        description: "Extract all semantic h1, h2, and h3 headings from the current web document.",
        inputSchema: {
          type: "object",
          properties: {
            include_ids: { type: "boolean", description: "Whether to return element anchor IDs" }
          }
        }
      },
      {
        name: "query_local_storage",
        description: "Read a specific key or list all keys from browser localStorage safely.",
        inputSchema: {
          type: "object",
          properties: {
            key: { type: "string", description: "Storage key to query" }
          },
          required: ["key"]
        }
      }
    ]
  };
});

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "extract_page_headings") {
    // In actual implementation, postMessage to main thread to query DOM
    return {
      content: [
        {
          type: "text",
          text: JSON.stringify([
            { tag: "h1", text: "Product Catalog" },
            { tag: "h2", text: "Enterprise Solutions" }
          ])
        }
      ]
    };
  }

  throw new Error(`Tool not found: ${name}`);
});

// Bind Worker self to custom JSON-RPC listener
self.onmessage = async (e) => {
  if (e.data?.method) {
    // Process JSON-RPC request through Server router
  }
};