MCP Test Client

🚀 MCP Test Client

A tool for testing Model Context Protocol (MCP) servers. This client provides you with a simple interface to execute tool calls and validate responses, helping you test MCP server implementations.

🚀 Quick Start

The MCP Test Client is a powerful tool designed to simplify the testing process of MCP servers. It offers a straightforward way to interact with the server, list available tools, and perform tool calls.

✨ Features

• User-Friendly Testing Interface: Specifically designed for MCP servers, making the testing process easy.
• Built-in Tool Support: Supports listing tools and making tool calls.
• Type Safety: Implemented in TypeScript to ensure type safety.
• Assertion Tools: Provides assertion tools to validate server responses.
• Mock Server Example: Includes a mock calculator server for testing and learning purposes.

📦 Installation

bun install mcp-test-client

💻 Usage Examples

Basic Usage

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

describe('MCP Server Test', () => {
  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');
      }
    );
  });
});

Advanced Usage

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

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

describe('Calculator Server Test', () => {
  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');
      }
    );
  });
});

📚 Documentation

MCPTestClient

Constructor

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

Methods

• init(): Promise<void> - Initialize the client and connect to the server.
• listTools(): Promise<Tool[]> - Get the list of available tools on 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 Steps

1. Clone the repository

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

2. Install dependencies

bun install

3. Run tests

bun test

📄 License

MIT

🤝 Contribution Guidelines

• Fork the project repository.
• Create a new branch for your feature implementation or fix.
• Commit your changes and push them to the branch.
• Create a Pull Request to the upstream main branch.

Before submitting a pull request, please ensure that your code passes all existing tests and that the documentation and code style are consistent.