Use This MCP client To

Test MCP server tool listing functionality Validate MCP server tool call responses Perform type-safe MCP server integration tests Mock MCP server behavior for testing Automate MCP server response assertions

README

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

Clone the repository

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

Install dependencies

bun install

Run tests

bun test

License

MIT

Contributing

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

mcp-test-client FAQ

How do I install the MCP Test Client?

You can install it using Bun with the command `bun install mcp-test-client`.

What programming language is MCP Test Client written in?

It is implemented in TypeScript, providing type safety and modern development features.

Can MCP Test Client run and manage MCP server processes?

Yes, it can start your MCP server using specified commands and arguments, then interact with it for testing.

Does MCP Test Client support validating server responses?

Yes, it includes assertion utilities to help validate the correctness of MCP server responses.

Is there an example server included for testing?

Yes, a mock calculator server implementation is provided as an example to demonstrate usage.

Can MCP Test Client be used with different MCP servers?

Yes, it is designed to test any MCP server implementation by making tool calls and validating responses.

How does MCP Test Client help with tool calls?

It provides built-in support for listing available tools and making calls to those tools on the MCP server.

Is MCP Test Client compatible with multiple LLM providers?

While it focuses on MCP servers, it can be used in environments with OpenAI, Claude, Gemini, and other LLM providers by testing the MCP server layer.