What is Mcp Test Client

MCP Test Client is a TypeScript testing utility designed for testing Model Context Protocol (MCP) servers. It provides a simple interface for making tool calls and validating responses from MCP server implementations.

Use cases

Use cases for MCP Test Client include testing the functionality of MCP servers, validating tool responses, and providing examples for developers on how to implement and test their own MCP server functionalities.

How to use

To use MCP Test Client, install it via ‘bun install mcp-test-client’. Import the MCPTestClient in your test files, initialize it with the server command and arguments, and then use its methods to list tools, call specific tools, and assert the results.

Key features

Key features include an easy-to-use testing interface, built-in support for tool listing and calls, type-safe implementation using TypeScript, assertion utilities for validating server responses, and a mock calculator server for demonstration purposes.

Where to use

undefined

MCP Test Client

A testing utility for Model Context Protocol (MCP) servers. This client helps you test MCP server implementations by providing a simple interface for making tool calls and validating responses.

Features

• Easy-to-use testing interface for MCP servers
• Built-in support for tool listing and tool calls
• Type-safe implementation using TypeScript
• Assertion utilities for validating server responses
• Mock calculator server implementation for examples

Installation

bun install mcp-test-client

Usage

Basic Example

import { MCPTestClient } from 'mcp-test-client';

describe('MCP Server Tests', () => {
  let client: MCPTestClient;

  beforeAll(async () => {
    client = new MCPTestClient({
      serverCommand: 'bun',
      serverArgs: ['./path/to/your/server.ts'],
    });
    await client.init();
  });

  afterAll(async () => {
    await client.cleanup();
  });

  test('should list available tools', async () => {
    const tools = await client.listTools();
    expect(tools).toContainEqual(
      expect.objectContaining({
        name: 'your-tool-name',
        description: 'Your tool description',
      })
    );
  });

  test('should call a tool', async () => {
    await client.assertToolCall(
      'your-tool-name',
      { arg1: 'value1', arg2: 'value2' },
      (result) => {
        expect(result.content[0].text).toBe('expected result');
      }
    );
  });
});

Calculator Server Example

The package includes a mock calculator server for testing and learning purposes:

import { MCPTestClient } from 'mcp-test-client';

describe('Calculator Server Tests', () => {
  let client: MCPTestClient;

  beforeAll(async () => {
    client = new MCPTestClient({
      serverCommand: 'bun',
      serverArgs: ['./tests/mocks/calculator.ts'],
    });
    await client.init();
  });

  afterAll(async () => {
    await client.cleanup();
  });

  test('should perform addition', async () => {
    await client.assertToolCall(
      'calculate',
      { operation: 'add', a: 5, b: 3 },
      (result) => {
        expect(result.content[0].text).toBe('8');
      }
    );
  });
});

API Reference

MCPTestClient

Constructor

constructor(config: { serverCommand: string; serverArgs: string[] })

Methods

• init(): Promise<void> - Initialize the client and connect to the server
• listTools(): Promise<Tool[]> - Get a list of available tools from the server
• callTool(toolName: string, args: Record<string, unknown>): Promise<ToolResult> - Call a specific tool
• assertToolCall(toolName: string, args: Record<string, unknown>, assertion: (result: ToolResult) => void | Promise<void>): Promise<void> - Call a tool and run assertions on the result
• cleanup(): Promise<void> - Clean up resources and disconnect from the server

Development

Prerequisites

• Bun (v1.0.0 or higher)

Setup

1. Clone the repository

git clone <repository-url>
cd mcp-test-client

2. Install dependencies

bun install

3. Run tests

bun test

License

MIT

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request