expect-mcp

Custom test matchers for Vitest and Jest to write automated test assertions for Model Context Protocol (MCP) tools.

Documentation

Features

• Custom Matchers: Adds expect() matchers to assert on MCP interactions.
• MCP Client: Implements a special MCP client with extra features for testing and validation.

Latest support

Currently the library supports:

• Testing MCP features: tools, resources, prompts.
• Testing stdin protocol servers.
• Integration with Vitest and Jest.

On the roadmap for future support:

• Planned: Testing HTTP services and Oauth.
• Planned: Testing for features: Discovery, Sampling, Roots, Elicitation.

Installation

npm install --save-dev expect-mcp

Or using other package managers:

# pnpm
pnpm add -D expect-mcp

# yarn
yarn add -D expect-mcp

Quick Start

Importing and using the library:

import { mcpShell } from 'expect-mcp';
import 'expect-mcp/vitest-setup'; // Install 'expect' matchers

it("the test", async () => {
  const app = mcpShell('path/to/mcp-server');
  await expect(app).toHaveTool('toolName');
  await expect(app).toHaveResource('config.json');

  const toolResult = await app.callTool('toolName', {});
  expect(toolResult); // ... check the result

  await app.close();
});

ESM / CommonJS Support

By default the library is ESM but we also include a CJS build. If your tests need to use CommonJS then import from expect-mcp/cjs. Example:

const { mcpShell } = require('expect-mcp/cjs');
require('expect-mcp/cjs/vitest-setup');

Documentation

See the Documentation site for the full API and more examples.

Requirements

• Node.js >= 20
• Vitest ^1.5.0 or Jest ^29.0.0

Feedback

For bugs or feature requests, please use GitHub Issues!

License

MIT License - see the LICENSE file for details.

Author

andyfischer

Related Projects

• Model Context Protocol - Learn more about MCP
• Vitest - Testing framework supported by this library
• Jest - Testing framework supported by this library