mcp-testing-kit

# mcp-testing-kit </br> [](https://coveralls.io/github/thoughtspot/mcp-testing-kit?branch=main)  The testing library you need to test your MCP servers. ## Overview `mcp-testing-kit` provides utilities to test [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol) servers. It allows you to connect to an MCP server instance, send requests, receive notifications, and assert server behavior in your tests. ## Features - Works with any testing framework (vitest, jest etc) - Lightweight, provides "just enough" utils to test an MCP server. - Typescript ## Installation ```bash $ npm i -D mcp-testing-kit ``` ## Example Suppose you have an MCP server defined in `example/basic/src/index.ts`: ```ts // mcp-server.ts import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; const server = new McpServer({ name: 'simple-mcp-server', version: '1.0.0' }); server.tool( 'add', 'Add two numbers MCP style', { a: z.number().describe('first number'), b: z.number().describe('second number') }, async ({ name }) => ({ messages: [ { role: 'user', content: { type: 'text', text: String(a + b) } } ] }) ); export default server; ``` You can write a test using `mcp-testing-kit` like this: ```ts // mcp-server.test.js import server from "../src/index.js"; // Use your favorite testing framework. import { describe, it, expect, afterEach } from "vitest"; import { connect, close } from "../../../index.js"; describe("Basic MCP server", () => { afterEach(async () => { await close(server); }); it("Should return correct sum when `sum` is called", async () => { // Connect to the server and create a mock client. const client = await connect(server); const result = await client.callTool("greeting-template", { a: 10, b: 2 }); expect(result.content[0].text).toEqual("12"); }); }); ``` ## How it works - Creates a dummy transport layer to connect to the MCP Server directly instead of relying on HTTP/SSE. - Provides abstractions for invoking the tools/resources/prompts directly on the server. ## API ### `connect(server: Server)` Connects to an MCP server instance and returns a client with the following methods: | Method | Signature | Description | |--------|-----------|-------------| | `listTools` | `(): Promise<ListToolsResult>` | List all tools registered on the server. | | `callTool` | `(tool: string, params?: any): Promise<any>` | Call a tool by name with optional parameters. | | `listResources` | `(): Promise<ListResourcesResult>` | List all resources registered on the server. | | `listPrompts` | `(): Promise<ListPromptsResult>` | List all prompts registered on the server. | | `getPrompt` | `(prompt: string, params?: any): Promise<any>` | Get a prompt by name with optional parameters. | | `onNotification` | `(cb: (message: JSONRPCMessage) => void): void` | Register a callback for notifications from the server. | | `onError` | `(cb: (message: JSONRPCMessage) => void): void` | Register a callback for error messages from the server. | | `onProgress` | `(cb: (message: JSONRPCMessage) => void): void` | Register a callback for progress notifications from the server. | | `sendToServer` | `(message: Request): Promise<any>` | Send a raw JSON-RPC request to the server. | ### `close(server: Server)` Closes the MCP server instance. ## More Examples See [`example/basic`](./example/basic) for a full-featured MCP server and corresponding tests. ## License MIT