📌Overview

Purpose: To provide a testing utility for Model Context Protocol (MCP) servers, facilitating the validation of server implementations through a simple interface.

Overview: The MCP Test Client is designed to streamline the testing process for MCP servers, allowing developers to easily interact with server tools, verify responses, and ensure proper functionality. It features an intuitive TypeScript implementation that enhances type safety and simplifies testing operations.

Key Features:

• User-Friendly Interface: Simplifies the process of testing MCP servers with an easy-to-use interface for making tool calls and logging responses.

• Type-Safe Implementation: Utilizes TypeScript to provide a robust, type-safe environment, minimizing runtime errors and enhancing developer experience.

• Assertion Utilities: Offers built-in assertion capabilities to validate server responses, ensuring that the tools behave as expected.

• Mock Server Example: Includes a mock calculator server implementation for educational purposes and to aid in testing functionalities without needing a full server setup.

---

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): https://bun.sh

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