Expect Mcp

expect-mcp

[](https://github.com/facetlayer/expect-mcp/actions/workflows/ci.yml) [](https://badge.fury.io/js/expect-mcp) [](https://opensource.org/licenses/MIT)

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.

Optional: Agentic Setup

If you're using a coding agent like Claude Code or Codex, you can use our builtin prompt to instruct the agent on how to use the library. Copy-paste this text as the prompt and it should do pretty well:

Run `npx -y expect-mcp@latest how-to-use` and follow the instructions to set up tests for this project.

Installation

Steps to install the library the normal way

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](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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: facetlayer
• Source: facetlayer/expect-mcp
• License: MIT
• Homepage: https://facetlayer.github.io/expect-mcp/

Install and usage instructions live in the source repository linked above.