WebMCP TypeScript Library

A TypeScript implementation of the Web Model Context Protocol (WebMCP) for creating MCP servers and tools.

Overview

WebMCP (Web Model Context Protocol) is a JavaScript API that allows web developers to expose their web application functionality as "tools" - JavaScript functions with natural language descriptions and structured schemas that can be invoked by AI agents, browser assistants, and assistive technologies.

This TypeScript library provides a complete implementation of the WebMCP specification, allowing you to:

• Create and manage WebMCP tools
• Implement an MCP server that can communicate with AI agents
• Handle client connections and communication
• Validate tool schemas and inputs

Installation

npm install @webmcp/core

Quick Start

Creating a Simple Tool

import { ModelContext, ToolManager } from "@webmcp/core";

// Create a model context
const modelContext = new ModelContext();

// Create a tool manager
const toolManager = new ToolManager(modelContext);

// Create a simple tool
const helloTool = toolManager.createTool(
  "hello",
  "Say hello to someone",
  async (input: { name: string }) => {
    return `Hello, ${input.name}!`;
  },
  {
    inputSchema: {
      type: "object",
      properties: {
        name: {
          type: "string",
          description: "The name of the person to greet",
        },
      },
      required: ["name"],
    },
  },
);

// Register the tool
toolManager.registerTool(helloTool);

// Execute the tool
const result = await modelContext.executeTool("hello", { name: "World" });
console.log(result); // "Hello, World!"

Creating an MCP Server

import { MCPServer, ToolManager } from "@webmcp/core";

// Create an MCP server
const server = new MCPServer();

// Create and register tools
const toolManager = new ToolManager(server.getModelContext());

const calculatorTool = toolManager.createTool(
  "add",
  "Add two numbers together",
  async (input: { a: number; b: number }) => {
    return { result: input.a + input.b };
  },
  {
    inputSchema: {
      type: "object",
      properties: {
        a: { type: "number", description: "First number" },
        b: { type: "number", description: "Second number" },
      },
      required: ["a", "b"],
    },
  },
);

toolManager.registerTool(calculatorTool);

// Handle incoming requests (example)
const request = {
  jsonrpc: "2.0",
  id: 1,
  method: "tools/call",
  params: {
    name: "add",
    arguments: { a: 5, b: 3 },
  },
};

const response = await server.receive(request);
console.log(response); // { jsonrpc: '2.0', id: 1, result: { result: 8 } }

Creating Categorized Tools

import { ToolManager } from "@webmcp/core";

const toolManager = new ToolManager(modelContext);

// Create a categorized tool
const searchTool = toolManager.createCategorizedTool(
  "search-docs",
  "Search documentation for specific terms",
  "search",
  async (input: { query: string }) => {
    // Implementation here
    return { results: [`Result for: ${input.query}`] };
  },
  {
    inputSchema: {
      type: "object",
      properties: {
        query: { type: "string", description: "Search query" },
      },
      required: ["query"],
    },
    tags: ["documentation", "search"],
  },
);

toolManager.registerTool(searchTool);

API Reference

ModelContext

The core class for managing WebMCP tools.

Methods

• provideContext(options: ModelContextOptions): Registers tools with the browser
• clearContext(): Unregisters all tools
• registerTool(tool: ModelContextTool): Registers a single tool
• unregisterTool(name: string): Removes a tool
• getTool(name: string): Gets a tool by name
• getAllTools(): Gets all registered tools
• executeTool(name: string, input: Record<string, any>, client: ModelContextClient): Executes a tool

ToolManager

Utility class for creating and managing tools.

Methods

• createTool(...): Creates a new tool
• createCategorizedTool(...): Creates a tool with category annotation
• createAuthenticatedTool(...): Creates a tool with authentication requirements
• createReadOnlyTool(...): Creates a read-only tool
• registerTool(tool: ModelContextTool): Registers a tool
• registerTools(tools: ModelContextTool[]): Batch registers tools

MCPServer

MCP server implementation that handles JSON-RPC communication.

Methods

• receive(request: JSONRPCRequest, clientId?: string): Handles incoming requests
• addTool(tool: ModelContextTool): Adds a tool
• removeTool(name: string): Removes a tool
• getTools(): Gets all registered tools

Tool Categories

The library supports categorizing tools for better organization and discovery:

• search: Find/query information
• read: Retrieve specific data
• create: Create new resources
• update: Modify existing resources
• delete: Remove resources
• analysis: Process/analyze data
• navigation: Page/UI navigation
• media: Images, audio, video

License

MIT