MCP Rigor

official

MCP server that gives AI coding agents a deterministic test loop for the MCP servers they build: write acceptance tests in natural language, validate the wording, run them, and read structured pass/fail results — no AI interprets the tests at runtime. Run with: npx mcprigor serve <project>. Also a full CLI/CI test framework with contract drift detection and transport parity. Apache-2.0.

View on mcprigor.com

What can you do with Rigor MCP?

  • Validate test files — Ask to run npx mcprigor check on a .mcpr file to verify syntax and readiness without connecting to a server.
  • Execute acceptance tests — Run npx mcprigor test against a .mcpr file to call MCP tools and assert on structured results like structuredContent.sum.
  • Generate HTML reports — Request to produce a shareable test report for tickets or CI artifacts.
  • Discover tools via guided authoring — Use npx mcprigor author to auto-detect tools, resources, and prompts, then generate a test file interactively.
  • Launch the QA workspace — Start npx mcprigor workspace . to edit, validate, and run multiple test suites with syntax highlighting and run history.

Documentation

This guide takes you from installation to one passing MCP test.

1. Install MCP Rigor

You need Node.js 20 or 22. MCP Rigor is published on npm as mcprigor — the package ships ready-to-run compiled code, so there is nothing to build from source.

mkdir mcp-acceptance-tests
cd mcp-acceptance-tests
npm init -y
npm install mcprigor

To check the installation:

npx mcprigor --help

2. Create a test file

Create calculator.mcpr:

MCP Test 1

Suite: "Calculator acceptance tests"
Server: node ../calculator-server/dist/server.js

Test: "Adding 20 and 22 gives 42"
  Call tool "add" with:
    a: 20
    b: 22

  Expect "structuredContent.sum" equals 42

Change the Server command to the command that starts your MCP server.

For a deployed Streamable HTTP server, use:

MCP URL: https://qa.example.com/mcp

3. Check the wording

npx mcprigor check calculator.mcpr

A valid file prints:

✓ calculator.mcpr looks good and is ready to run

check does not connect to the server.

4. Run the test

npx mcprigor test calculator.mcpr

A passing result looks like:

MCP Rigor — Calculator acceptance tests
✓ Adding 20 and 22 gives 42

1 passed, 0 failed, 0 skipped, 0 blocked

5. Create a shareable report

npx mcprigor test calculator.mcpr --html report.html

Open report.html or attach it to a ticket.

6. Try the browser workspace

npx mcprigor workspace .

Open the printed local URL. Select calculator.mcpr — the editor gives you syntax highlighting and autocomplete — then choose Validate and ▶ Run tests. You can also create new test files, run several suites at once with the checkboxes, and review run history and trends in the results panel. See the QA workspace guide.

If you do not know tool names

Create a small target file such as server.mcpr:

MCP Test 1
Suite: "Server target"
Server: node ../calculator-server/dist/server.js
Test: "Connection"
  Send "ping"

Start guided authoring:

npx mcprigor author server.mcpr --out calculator.mcpr

MCP Rigor discovers tools, resources, and prompts and asks what you want to verify.

Recommended project layout

mcp-acceptance-tests/
  package.json
  tests/
    smoke.mcpr
    regression.mcpr
    data/
      customers.csv
  .mcprigor/
    # generated evidence; normally ignored or stored as CI artifacts

Next steps