MCP Aegis

Unified Declarative + Programmatic Testing for Model Context Protocol Servers

Ship Reliable MCP Servers Faster

Write high-signal tests in YAML or JavaScript. 50+ matcher types. Automated MCP handshake & JSON-RPC lifecycle. Rich diffs. CI optimized. Battle‑tested with 1300+ internal tests and multiple reference servers.

😫 Before Aegis

Fragile scripts: Ad‑hoc JSON-RPC curl scripts & manual stderr watching.
Hidden regressions: Silent protocol breakage until runtime.
Slow iteration: Rewriting assertions across similar flows.
Limited validation: Basic equality—no structural or semantic checks.
Flaky buffers: Leaking stderr/stdout across tests causes noise.
No shared language: Hard for AI agents & humans to collaborate.

🚀 60‑Second Quick Start

Init handles dependency installation automatically—then author your first assertion. Works with test/ or tests/.

bash

# 1. Init (performs install + creates config + test dir + AI agent guide)
npx mcp-aegis init

# 2. Write a YAML test (test*/mcp/yaml/server.test.mcp.yml)
description: "List tools"
tests:
  - it: "lists tools"
    request: { jsonrpc: "2.0", id: "1", method: "tools/list", params: {} }
    expect:
      response:
        id: "1"
        result:
          tools: "match:not:arrayLength:0"  # Not empty

# 3. Run tests
npx mcp-aegis "test*/mcp/yaml/**/*.test.mcp.yml" --verbose

Show dual approach examples (YAML + JS)

YAML Test Example

yaml

description: "Basic MCP server tests"
tests:
  - it: "should list available tools"
    request:
      jsonrpc: "2.0"
      id: "test-1" 
      method: "tools/list"
      params: {}
    expect:
      response:
        jsonrpc: "2.0"
        id: "test-1"
        result:
          tools: "match:type:array"

Programmatic Test Example

javascript

import { test, before, after } from 'node:test';
import { strict as assert } from 'node:assert';
import { connect } from 'mcp-aegis';

let client;
before(async () => { client = await connect('./aegis.config.json'); });
after(async () => { await client.disconnect(); });

test('should list available tools', async () => {
  const tools = await client.listTools();
  assert.ok(Array.isArray(tools), 'Should return array of tools');
});

🧭 When To Use vs Alternatives

Use MCP Aegis When…

You need protocol + semantic validation
Pattern-rich assertions (regex, numeric, dates, cross-field)
Mix of declarative + dynamic flows
Stable CI signals + grouped errors
AI agent-friendly test artifacts

Consider Other Tools If…

You only need raw HTTP (no MCP/stdio)
One-off manual inspection
No pattern semantics—just equality
You're already fully covered by a custom harness

✨ Core Capability Pillars

🎯 Dual Test Modes

Declarative YAML + programmatic JS/TS—compose both as your suite matures.

🔄 Protocol Automation

MCP handshake + JSON-RPC framing handled—focus on expressing intent.

🧪 50+ Matcher Types

Regex, partial/contains, extraction, array introspection, numeric, date/time, cross-field, length, negation.

📊 Insightful Reporting

Colored diffs, grouped errors, syntax analysis, timing, JSON export for CI.

⚙️ Extensible Client

Promise-based API for perf probes, dynamic suites, or integration tests.

🛡️ Stability Focus

Buffer isolation helpers prevent stderr/stdout bleed & flaky cascades.

Why MCP Aegis?

Purpose-built for MCP: high‑fidelity validation with minimal ceremony.

✅
End-to-end lifecycle: Spawn → Handshake → Tools → Shutdown.
✅
Matcher depth: 50+ strategies—structure, semantics & relationships.
✅
Fast feedback: Rich diffs + grouped validation errors reduce iteration time.
✅
Battle-tested: 1300+ internal tests + multiple reference servers.
✅
Agent aware: Ships AI assistant oriented docs (AGENTS.md).

🔍 Pattern Matching Preview

Examples of expressive assertions (full catalog in docs):

yaml

result:
  tools: "match:arrayLengthGreaterThan:2"
  updatedAt: "match:dateAge:1h"
  score: "match:approximately:95.5:0.1"
  user:
    name: "match:containsIgnoreCase:alice"
    id: "match:regex:[a-f0-9-]{36}"
  metrics:
    match:crossField: "min <= current <= max"

📊 Validation Footprint

1300+

Automated Tests

100%

Test Coverage

50+

Matcher Types

Reference Servers

Ready to Close The Integration Gap?

Go from “it runs locally” to provable protocol correctness in minutes. Start with a single YAML test, add pattern depth as contracts solidify, then graduate to programmatic suites for dynamic flows & performance probes.

3-Step Quick Start

npx mcp-aegis init
Create test*/mcp/yaml/first.test.mcp.yml
Run npx mcp-aegis "test*/mcp/yaml/**/*.test.mcp.yml"

First YAML Test

Executable Spec

description: "List tools"
tests:
    - it: "lists tools"
        request:
            jsonrpc: "2.0"
            id: "1"
            method: "tools/list"
            params: {}
        expect:
            response:
                id: "1"
                result:
                    tools: "match:not:arrayLength:0"
            stderr: "toBeEmpty"

Add depth incrementally: array element validation, cross-field rules, extraction patterns & more—same file, stronger guarantees.