How to write automated tests for an MCP server

1npm install -D vitest @types/node
2
3# In package.json, add:
4# "scripts": { "test": "vitest run", "test:watch": "vitest" }
5
6# Create test directory
7mkdir tests

1// tests/helpers/in-memory-transport.ts
2import { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
3
4export class InMemoryTransport implements Transport {
5  private otherEnd: InMemoryTransport | null = null;
6  onmessage: ((message: any) => void) | null = null;
7  onclose: (() => void) | null = null;
8  onerror: ((error: Error) => void) | null = null;
9
10  static createPair(): [InMemoryTransport, InMemoryTransport] {
11    const a = new InMemoryTransport();
12    const b = new InMemoryTransport();
13    a.otherEnd = b;
14    b.otherEnd = a;
15    return [a, b];
16  }
17
18  async start(): Promise<void> {}
19
20  async send(message: any): Promise<void> {
21    // Simulate async delivery
22    await new Promise(resolve => setTimeout(resolve, 0));
23    this.otherEnd?.onmessage?.(JSON.parse(JSON.stringify(message)));
24  }
25
26  async close(): Promise<void> {
27    this.otherEnd?.onclose?.();
28    this.otherEnd = null;
29  }
30}

1// tests/server.test.ts
2import { describe, it, expect, beforeEach, afterEach } from "vitest";
3import { Client } from "@modelcontextprotocol/sdk/client/index.js";
4import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
5import { InMemoryTransport } from "./helpers/in-memory-transport.js";
6import { z } from "zod";
7
8describe("MCP Server Integration Tests", () => {
9  let client: Client;
10  let server: McpServer;
11
12  beforeEach(async () => {
13    // Create server with test tools
14    server = new McpServer({ name: "test-server", version: "1.0.0" });
15
16    server.tool("echo", "Echo the input back", {
17      message: z.string(),
18    }, async ({ message }) => ({
19      content: [{ type: "text", text: `Echo: ${message}` }],
20    }));
21
22    server.tool("divide", "Divide two numbers", {
23      a: z.number(), b: z.number(),
24    }, async ({ a, b }) => {
25      if (b === 0) return { content: [{ type: "text", text: "Error: Division by zero" }], isError: true };
26      return { content: [{ type: "text", text: String(a / b) }] };
27    });
28
29    // Connect via in-memory transport
30    const [clientTransport, serverTransport] = InMemoryTransport.createPair();
31    client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
32
33    await server.connect(serverTransport);
34    await client.connect(clientTransport);
35  });
36
37  afterEach(async () => {
38    await client.close();
39  });
40
41  it("should discover all registered tools", async () => {
42    const { tools } = await client.listTools();
43    expect(tools).toHaveLength(2);
44    expect(tools.map(t => t.name)).toContain("echo");
45    expect(tools.map(t => t.name)).toContain("divide");
46  });
47
48  it("should call echo tool and return correct result", async () => {
49    const result = await client.callTool({ name: "echo", arguments: { message: "hello" } });
50    const text = (result.content as any[])[0].text;
51    expect(text).toBe("Echo: hello");
52  });
53
54  it("should handle division by zero with isError", async () => {
55    const result = await client.callTool({ name: "divide", arguments: { a: 10, b: 0 } });
56    expect((result as any).isError).toBe(true);
57    expect((result.content as any[])[0].text).toContain("Division by zero");
58  });
59});

1// src/tools/search.ts — export handler for unit testing
2import { z } from "zod";
3
4export async function searchHandler({ pattern, directory }: {
5  pattern: string;
6  directory: string;
7}) {
8  const regex = new RegExp(pattern, "i");
9  // ... search logic
10  return { content: [{ type: "text" as const, text: "results" }] };
11}
12
13// tests/tools/search.test.ts
14import { describe, it, expect } from "vitest";
15import { searchHandler } from "../../src/tools/search.js";
16
17describe("searchHandler", () => {
18  it("should return results for valid pattern", async () => {
19    const result = await searchHandler({ pattern: "test", directory: "." });
20    expect(result.content).toHaveLength(1);
21    expect(result.content[0].type).toBe("text");
22  });
23
24  it("should handle invalid regex gracefully", async () => {
25    // If your handler catches regex errors:
26    const result = await searchHandler({ pattern: "[invalid", directory: "." });
27    expect((result as any).isError).toBe(true);
28  });
29});

1# .github/workflows/test.yml
2name: MCP Server Tests
3on: [push, pull_request]
4
5jobs:
6  test:
7    runs-on: ubuntu-latest
8    steps:
9      - uses: actions/checkout@v4
10      - uses: actions/setup-node@v4
11        with:
12          node-version: 20
13          cache: npm
14      - run: npm ci
15      - run: npx tsc --noEmit  # Type check
16      - run: npm test           # Run vitest
17
18  # Optional: smoke test with MCP Inspector
19  smoke:
20    runs-on: ubuntu-latest
21    needs: test
22    steps:
23      - uses: actions/checkout@v4
24      - uses: actions/setup-node@v4
25        with:
26          node-version: 20
27          cache: npm
28      - run: npm ci && npx tsc
29      - name: Verify server starts and lists tools
30        run: |
31          timeout 10 npx @modelcontextprotocol/inspector node dist/index.js --list-tools || true