mcp-assert

Deterministic correctness testing for MCP servers. Works with any language, any transport.

A single Go binary that acts as an MCP client: connects to your server over stdio, SSE, or HTTP, calls your tools with predefined inputs, and evaluates the responses against assertions you define in YAML.

Install

npx @blackwell-systems/mcp-assert

Or install globally:

npm install -g @blackwell-systems/mcp-assert

Quick Start

# Zero-config audit
mcp-assert audit --server "npx my-mcp-server"

# Run YAML assertions
mcp-assert run --suite evals/

# CI with threshold
mcp-assert ci --suite evals/ --threshold 95

Vitest Integration

npm install -D vitest-mcp-assert

import { describeMcpSuite } from 'vitest-mcp-assert'
describeMcpSuite('mcp server', 'evals/')

GitHub Action

- uses: blackwell-systems/mcp-assert-action@v1
  with:
    suite: evals/

Links

• Documentation
• GitHub
• Scorecard (58 servers scanned, 25 bugs found)
• GitHub Action
• Vitest plugin
• pytest plugin

License

MIT