MCP

Aegisv1
Rhino InquisitorBlogGitHub

Examples

Real-World MCP Server Testing Scenarios

Comprehensive examples showing real-world usage of MCP Aegis with both YAML declarative and programmatic JavaScript/TypeScript testing approaches for Model Context Protocol servers.

Quick Setup

Before diving into examples, quickly set up MCP Aegis in your project:

bash
# Navigate to your MCP project
cd my-mcp-project

# Initialize MCP Aegis
npx mcp-aegis init

# This creates the test structure and configuration automatically

Available Examples

The examples/ directory contains three complete MCP servers with comprehensive test suites:

  • Filesystem Server - Simple single-tool server demonstrating basic file operations
  • Multi-Tool Server - Complex server with 4 different tools showing advanced patterns
  • Numeric Server - Demonstrates numeric pattern matching with comprehensive comparisons
  • API Testing Server - Sophisticated server for API testing and monitoring

Filesystem Server Example

Complete example demonstrating file operations testing with a single read_file tool.

Configuration (config.json)

json
{
  "name": "Filesystem MCP Server",
  "command": "node",
  "args": ["./server.js"],
  "cwd": "./examples/filesystem-server"
}

YAML Tests (filesystem.test.mcp.yml)

yaml
description: "Filesystem MCP Server Tests"
tests:
  - it: "should list file operations tool"
    request:
      jsonrpc: "2.0"
      id: "list-1"
      method: "tools/list"
    expect:
      response:
        result:
          tools:
            - name: "read_file"
              description: "match:contains:read"

  - it: "should read existing file successfully"
    request:
      jsonrpc: "2.0"
      id: "read-1"
      method: "tools/call"
      params:
        name: "read_file"
        arguments:
          path: "../shared-test-data/hello.txt"
    expect:
      response:
        result:
          content:
            - type: "text"
              text: "Hello, MCP Aegis!"

  - it: "should handle non-existent file gracefully"
    request:
      jsonrpc: "2.0"
      id: "error-1"
      method: "tools/call"
      params:
        name: "read_file"
        arguments:
          path: "./nonexistent.txt"
    expect:
      response:
        result:
          isError: true
          content:
            - type: "text"
              text: "match:contains:ENOENT"

Programmatic Tests (filesystem.test.js)

javascript
import { createClient } from 'mcp-aegis';
import { test, describe, before, after, beforeEach } from 'node:test';
import { strict as assert } from 'node:assert';

describe('Filesystem MCP Server - Programmatic', () => {
  let client;

  before(async () => {
    client = await createClient('./config.json');
    await client.connect();
  });

  after(async () => {
    await client?.disconnect();
  });

  beforeEach(() => {
    // CRITICAL: Clear stderr to prevent test interference
    client.clearStderr();
  });

  test('should read file content correctly', async () => {
    const result = await client.callTool('read_file', {
      path: '../shared-test-data/hello.txt'
    });

    assert.strictEqual(result.isError, undefined);
    assert.ok(result.content[0].text.includes('Hello, MCP Aegis!'));
  });

  test('should handle file read errors', async () => {
    const result = await client.callTool('read_file', {
      path: './nonexistent-file.txt'
    });

    assert.strictEqual(result.isError, true);
    assert.ok(result.content[0].text.includes('ENOENT'));
  });
});

Multi-Tool Server Example

Advanced example with 4 different tools demonstrating complex MCP server patterns:

  • calculator - Performs mathematical operations
  • text_processor - Text manipulation and analysis
  • data_validator - Data format validation
  • file_manager - File system operations

YAML Tests (multi-tool.test.mcp.yml)

yaml
description: "Multi-Tool MCP Server Tests"
tests:
  - it: "should list all 4 tools"
    request:
      method: "tools/list"
    expect:
      response:
        result:
          tools: "match:arrayLength:4"
          
  - it: "should perform calculation"
    request:
      method: "tools/call"
      params:
        name: "calculator"
        arguments:
          operation: "add"
          a: 15
          b: 27
    expect:
      response:
        result:
          content:
            - type: "text"
              text: "match:contains:42"

  - it: "should process text"
    request:
      method: "tools/call"
      params:
        name: "text_processor"
        arguments:
          text: "Hello World"
          operation: "uppercase"
    expect:
      response:
        result:
          content:
            - type: "text"
              text: "match:contains:HELLO WORLD"

Data Patterns Server Example

🎯 Comprehensive Pattern Matching Demonstration

This example showcases all numeric comparison patterns and date/timestamp validation patterns with real datasets for comprehensive testing.

Complete example demonstrating comprehensive pattern matching with two main tools that return various datasets for testing numeric comparisons and date/timestamp validation:

  • API Metrics - Response times, error rates, success rates
  • Performance Data - CPU usage, memory usage, load balancing
  • E-commerce Stats - User scores, discounts, inventory
  • Validation Ranges - Temperature, ports, percentages

Numeric Pattern Tests (patterns-numeric.test.mcp.yml)

yaml
description: "Numeric Pattern Matching Tests"
tests:
  - it: "should validate API performance metrics"
    request:
      jsonrpc: "2.0"
      id: "api-metrics"
      method: "tools/call"
      params:
        name: "get_numeric_data"
        arguments:
          dataset: "api"
    expect:
      response:
        result:
          response_time: "match:lessThan:500"        # < 500ms
          error_rate: "match:lessThanOrEqual:1"      # <= 1%
          success_rate: "match:greaterThanOrEqual:99" # >= 99%

  - it: "should validate performance within acceptable ranges"
    request:
      jsonrpc: "2.0"
      id: "performance"
      method: "tools/call"
      params:
        name: "get_numeric_data"
        arguments:
          dataset: "performance"
    expect:
      response:
        result:
          cpu_usage: "match:between:45:65"           # 45-65% range
          memory_usage: "match:lessThanOrEqual:512"  # <= 512MB
          load_balance: "match:between:40:60"        # 40-60% balance

  - it: "should validate scores with negation patterns"
    request:
      jsonrpc: "2.0"
      id: "ecommerce"
      method: "tools/call"
      params:
        name: "get_numeric_data"
        arguments:
          dataset: "ecommerce"
    expect:
      response:
        result:
          user_score: "match:not:lessThan:70"        # Should NOT be < 70
          discount: "match:not:greaterThan:25"       # Should NOT be > 25%
          inventory: "match:greaterThan:0"           # Must be in stock

Programmatic Numeric Testing

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

describe('Numeric Server Tests', () => {
  let client;
  
  before(async () => {
    client = await connect('./server.config.json');
  });
  
  after(async () => {
    await client?.disconnect();
  });
  
  beforeEach(() => {
    client.clearStderr(); // Prevent test interference
  });

  test('should validate API response times', async () => {
    const result = await client.callTool('get_numeric_data', { 
      dataset: 'api' 
    });
    
    assert.ok(result.response_time < 500, 'Response time should be under 500ms');
    assert.ok(result.error_rate <= 1, 'Error rate should be 1% or less');
    assert.ok(result.success_rate >= 99, 'Success rate should be 99% or higher');
  });

  test('should validate performance metrics within ranges', async () => {
    const result = await client.callTool('get_numeric_data', { 
      dataset: 'performance' 
    });
    
    // Range validation
    assert.ok(result.cpu_usage >= 45 && result.cpu_usage <= 65, 
      'CPU usage should be between 45-65%');
    assert.ok(result.memory_usage <= 512, 
      'Memory usage should not exceed 512MB');
  });
});

API Testing & Monitoring Server

Sophisticated MCP server for API testing, monitoring, and analysis with 6 advanced tools and 76 comprehensive tests:

  • http_request - Make HTTP requests with full configuration
  • response_analyzer - Analyze HTTP responses and extract data
  • endpoint_monitor - Monitor API endpoints for availability
  • data_transformer - Transform data between formats
  • load_tester - Perform load testing on endpoints
  • webhook_simulator - Simulate webhook events

Advanced Configuration

json
{
  "name": "API Testing & Monitoring Server",
  "command": "node",
  "args": ["./server.js"],
  "cwd": "./examples/api-testing-server",
  "startupTimeout": 8000,
  "readyPattern": "API Testing Server listening",
  "env": {
    "NODE_ENV": "test",
    "LOG_LEVEL": "info"
  }
}

Complex Testing Scenarios

yaml
description: "API Testing Server - HTTP Operations"
tests:
  - it: "should make GET request with headers"
    request:
      method: "tools/call"
      params:
        name: "http_request"
        arguments:
          url: "https://api.example.com/users"
          method: "GET"
          headers:
            Authorization: "Bearer token123"
            Content-Type: "application/json"
    expect:
      response:
        result:
          content:
            - type: "text"
              text: "match:regex:HTTP/1\.1 \d{3}"

  - it: "should analyze response data"
    request:
      method: "tools/call"
      params:
        name: "response_analyzer"
        arguments:
          response_body: '{"users": [{"id": 1, "name": "John"}]}'
          content_type: "application/json"
    expect:
      response:
        result:
          content:
            - type: "text"
              text: "match:contains:Found 1 user"

Pattern Examples

The examples also include dedicated pattern testing files demonstrating all 11+ pattern types:

  • patterns-basic.test.mcp.yml - Type validation, deep equality
  • patterns-strings.test.mcp.yml - Contains, startsWith, endsWith
  • patterns-regex.test.mcp.yml - Regular expression patterns
  • patterns-arrays.test.mcp.yml - Array length, elements, contains
  • patterns-field-extraction.test.mcp.yml - Field extraction patterns
  • patterns-partial-matching.test.mcp.yml - Partial object validation
  • patterns-partial-array-elements.test.mcp.yml - 🚀 Power Pattern: Partial + Array Elements combination
  • patterns-utility.test.mcp.yml - Count patterns, utility functions

Running the Examples

Run Individual Examples

bash
aegis filesystem.test.mcp.yml --config config.json --verbose
# Run multi-tool server tests
aegis multi-tool.test.mcp.yml --config config.json --verbose
# Run advanced pattern tests
aegis patterns-numeric.test.mcp.yml --config server.config.json --verbose
# Run API testing examples
aegis api-testing.test.mcp.yml --config config.json --verbose --timing

# Run all pattern tests
aegis patterns-*.test.mcp.yml --config config.json

Pattern Testing Examples

bash
# Test all pattern types with multi-tool server
cd examples/filesystem-server
aegis patterns-*.test.mcp.yml --config config.json

# Specific pattern categories
aegis patterns-basic.test.mcp.yml --config config.json
aegis patterns-arrays.test.mcp.yml --config config.json
aegis patterns-regex.test.mcp.yml --config config.json

# 🚀 Power Pattern: Partial + Array Elements combination
cd examples/multi-tool-server
aegis patterns-partial-array-elements.test.mcp.yml --config config.json

# Data pattern testing (numeric and date patterns)
cd examples/data-patterns-server
aegis patterns-numeric.test.mcp.yml --config server.config.json

Programmatic Testing Examples

bash
# Run programmatic tests with Node.js test runner
cd examples/filesystem-server
node --test filesystem-server.programmatic.test.js

cd examples/data-patterns-server
node --test numeric.programmatic.test.js

cd examples/api-testing-server  
node --test api-testing-server.programmatic.test.js

Best Practices from Examples

  • Start Simple: Begin with the filesystem server example for basic concepts
  • Use Comprehensive Configuration: Include timeout, ready patterns, and environment variables
  • Test Both Success and Error Cases: All examples include error handling tests
  • Combine YAML and Programmatic: Use YAML for declarative tests, programmatic for complex logic
  • Pattern Progression: Start with basic patterns, gradually add complexity
  • Real-world Data: Use actual API responses and realistic test data
  • Performance Testing: Include timing tests for critical operations

Recommended Learning Path

  1. Filesystem Server - Learn basic MCP testing concepts
  2. Pattern Examples - Master all 18+ pattern matching types
  3. Numeric Server - Learn numeric comparison patterns
  4. Multi-Tool Server - Understand complex server patterns
  5. API Testing Server - Advanced real-world scenarios
  6. Programmatic Testing - Integrate with your existing test suites