mcp-test-client/README.md

A testing utility for Model Context Protocol (MCP) servers

# 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

```bash
bun install mcp-test-client
```

## Usage

### Basic Example

```typescript
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:

```typescript
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
```typescript
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](https://bun.sh) (v1.0.0 or higher)

### Setup

1. Clone the repository
```bash
git clone <repository-url>
cd mcp-test-client
```

2. Install dependencies
```bash
bun install
```

3. Run tests
```bash
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