# MCPMock

Mock MCP (Model Context Protocol) server for testing tool integrations. Implements the Streamable HTTP transport with JSON-RPC dispatch, session management, and full tools/resources/prompts support.

## Quick Start

Standalone mode typescript

    import { MCPMock } from "@copilotkit/aimock";

    const mcp = new MCPMock();

    mcp.addTool({ name: "search", description: "Search the web" });
    mcp.onToolCall("search", (args) => {
      return `Results for: ${(args as { query: string }).query}`;
    });

    const url = await mcp.start();
    // Point your MCP client at `url`

## Mounted Mode

Mount MCPMock onto an LLMock server to share a single port with LLM mocking and other services:

Mount on LLMock typescript

    import { LLMock, MCPMock } from "@copilotkit/aimock";

    const llm = new LLMock({ port: 5555 });
    const mcp = new MCPMock();

    mcp.addTool({ name: "calc", description: "Calculator" });
    mcp.onToolCall("calc", (args) => "42");

    llm.mount("/mcp", mcp);
    await llm.start();
    // MCP available at http://127.0.0.1:5555/mcp

## Subpath Import

MCPMock is also available via a dedicated subpath import for tree-shaking:

Subpath import typescript

    import { MCPMock } from "@copilotkit/aimock/mcp";

## Tools

Register tools and their handlers:

Tools API typescript

    // Register a tool definition
    mcp.addTool({
      name: "search",
      description: "Search the web",
      inputSchema: { type: "object", properties: { query: { type: "string" } } },
    });

    // Register a handler (returns string or MCPContent[])
    mcp.onToolCall("search", (args) => {
      const { query } = args as { query: string };
      return `Found 3 results for "${query}"`;
    });

    // Or return rich content
    mcp.onToolCall("rich-tool", () => [
      { type: "text", text: "Hello" },
      { type: "image", data: "base64...", mimeType: "image/png" },
    ]);

## Resources

Register static resources that clients can read:

Resources API typescript

    mcp.addResource(
      { uri: "file:///readme.md", name: "README", mimeType: "text/markdown" },
      { text: "# My Project\nWelcome!" },
    );

## Prompts

Register prompt templates with optional handlers:

Prompts API typescript

    mcp.addPrompt(
      { name: "summarize", arguments: [{ name: "text", required: true }] },
      (args) => ({
        messages: [
          { role: "user", content: { type: "text", text: `Summarize: ${(args as { text: string }).text}` } },
        ],
      }),
    );

## Config File

MCPMock can be configured via the aimock JSON config file:

aimock.json json

    {
      "mcp": {
        "path": "/mcp",
        "tools": [
          { "name": "search", "description": "Search", "result": "Found it" }
        ],
        "resources": [
          { "uri": "file:///data.json", "name": "Data", "text": "{\"key\": \"value\"}" }
        ]
      }
    }

## Session Management

MCPMock implements full session management per the MCP Streamable HTTP spec. Each `initialize` request creates a new session, and the session ID is returned via the `Mcp-Session-Id` header. All subsequent requests must include this header.

Method | Description
--- | ---
`initialize` | Creates session, returns capabilities and session ID
`tools/list` | Lists all registered tools
`tools/call` | Calls a tool by name with arguments
`resources/list` | Lists all registered resources
`resources/read` | Reads a resource by URI
`prompts/list` | Lists all registered prompts
`prompts/get` | Gets a prompt by name with arguments
`ping` | Returns empty object (health check)
`DELETE /` | Destroys a session

## Inspection

Inspection API typescript

    mcp.health();       // { status: "ok", tools: 2, resources: 1, prompts: 0, sessions: 1 }
    mcp.getSessions();  // Map of active sessions
    mcp.getRequests();  // Journal entries (when mounted with shared journal)
    mcp.reset();        // Clears all tools, resources, prompts, and sessions