expect

expect-mcp provides MCP tooling integration for testing and validating MCP-based interactions. It exposes a set of custom test matchers for Vitest and Jest, allowing you to assert on MCP tools, resources, and prompts exposed by a running MCP server. Use the mcpShell helper to spawn and manage an MCP server during tests, then leverage matchers like toHaveTool, toHaveResource, and callTool to verify that the server responds as expected. This library also ships with a specialized MCP client that makes it easier to simulate and validate MCP flows within your test suite. In your tests, initialize the shell with the path to your MCP server, assert that required tools and resources exist, run tools against input data, and inspect results to ensure correct MCP behavior.

Prerequisites:

• Node.js v20 or later
• npm or pnpm/yarn as a package manager

Install the library as a development dependency:

npm install --save-dev expect-mcp

Or with other package managers:

# pnpm
pnpm add -D expect-mcp

# yarn
yarn add -D expect-mcp

Usage notes:

• Ensure you have an MCP server or a testable MCP server executable reachable by your tests.
• The library expects a path to the MCP server when initializing the mcpShell in tests, e.g. mcpShell('path/to/mcp-server').
• The library integrates with Vitest and Jest; include the appropriate setup file as indicated in the library docs.

Example minimal test snippet:

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

it('validates MCP server tools and prompts', 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).toBeDefined();
  await app.close();
});

Tips and common considerations:

• Node.js >= 20 is the typical requirement for expect-mcp usage in conjunction with modern MCP servers.
• Ensure your MCP server path is correct and that the server exposes the expected tools, resources, and prompts before running tests.
• The library focuses on testing MCP interactions (tools, resources, prompts) and supports both Vitest and Jest environments.
• If your MCP server uses custom environment variables or ports, you can pass them via the env field in mcp_config or configure the server accordingly in your CI environment.
• Keep the MCP server under test isolated from production endpoints to avoid unintended side effects during test runs.