Pattern Matching Reference

Advanced MCP Server Validation Patterns

MCP Aegis provides 50+ advanced pattern matching capabilities for flexible and powerful Model Context Protocol test validation. All core patterns have been verified with production MCP servers.

🏆 Production Verified Patterns

The following patterns have been extensively tested with real-world MCP servers and are production-ready:

✅ Deep Equality - Exact value matching
✅ Type Validation - Data type checking (string, number, object, array, etc.)
✅ Array Length - Exact element count validation
✅ Array Elements - Pattern matching for all array elements
✅ Array Contains - Check if array contains specific values (with field support)
✅ Field Extraction - Extract and validate specific field values
✅ Partial Matching - Validate only specified object fields
✅ String Contains - Substring matching
✅ String Starts With - Prefix matching
✅ String Ends With - Suffix matching
✅ Regex Matching - Full regular expression support
✅ Object Count - Property counting
✅ Field Exists - Field presence validation
✅ Numeric Comparisons - Greater than, less than, between/range, exact equality, floating-point tolerance, modular arithmetic, decimal precision validations
✅ String Length Validation - Exact length, min/max, ranges, empty/non-empty
✅ Date/Timestamp Validation - Date validity, age checking, format validation, temporal comparisons
✅ Cross-Field Validation - Validate relationships between fields in the same object
✅ Case-Insensitive Matching - Contains and equals ignoring case
✅ Pattern Negation - Negate any pattern with match:not:

Pattern Types Overview

Pattern Type	Syntax	Description	Status
Deep Equality	`value`	Exact match (default)	✅ Core
Type Validation	`"match:type:TYPE"`	Validates data type	✅ Verified
String Contains	`"match:contains:..."`	String contains substring	✅ Verified
String Starts With	`"match:startsWith:..."`	String starts with prefix	✅ Verified
String Ends With	`"match:endsWith:..."`	String ends with suffix	✅ Verified
Regex Match	`"match:regex:..."`	Regular expression match	✅ Verified
Array Length	`"match:arrayLength:N"`	Array has exactly N elements	✅ Verified
Array Elements	`"match:arrayElements:"`	All elements match pattern	✅ Verified
Array Contains	`"match:arrayContains:..."`	Array contains specific value	✅ Verified
Field Extraction	`"match:extractField:..."`	Extract field values (supports dot & bracket notation)	✅ Enhanced
Partial Match	`"match:partial:"`	Partial object matching	✅ Verified
Object Count	`"match:count:N"`	Count object properties	✅ Tested
Field Exists	`"match:exists"`	Field exists validation	✅ Tested
Greater Than	`"match:greaterThan:N"`	Value > N	✅ Tested
Less Than	`"match:lessThan:N"`	Value < N	✅ Tested
Greater/Equal	`"match:greaterThanOrEqual:N"`	Value >= N	✅ Tested
Less/Equal	`"match:lessThanOrEqual:N"`	Value <= N	✅ Tested
Between	`"match:between:MIN:MAX"`	MIN <= Value <= MAX	✅ Tested
Range	`"match:range:MIN:MAX"`	Alias for between	✅ Tested
Equals	`"match:equals:N"`	Exact numeric equality	✅ Tested
Not Equals	`"match:notEquals:N"`	Numeric inequality	✅ Tested
Approximately	`"match:approximately:VAL:TOL"`	Floating-point tolerance (VAL ± TOL)	✅ Tested
String Length	`"match:stringLength..."`	Exact, min, max, range, empty/non-empty	✅ Tested
Multiple Of	`"match:multipleOf:N"`	Must be multiple of N	✅ Tested
Divisible By	`"match:divisibleBy:N"`	Must be divisible by N	✅ Tested
Decimal Places	`"match:decimalPlaces:N"`	Must have exactly N decimal places	✅ Tested
Date Valid	`"match:dateValid"`	Valid date/timestamp	✅ Tested
Date After	`"match:dateAfter:DATE"`	Date after specified date	✅ Tested
Date Before	`"match:dateBefore:DATE"`	Date before specified date	✅ Tested
Date Between	`"match:dateBetween:START:END"`	Date within range	✅ Tested
Date Age	`"match:dateAge:DURATION"`	Date within age limit (1d, 2h, 30m)	✅ Tested
Date Equals	`"match:dateEquals:DATE"`	Exact date match	✅ Tested
Date Format	`"match:dateFormat:FORMAT"`	Validate date format (iso, iso-date, us-date, etc.)	✅ Tested
Cross-Field	`"match:crossField:CONDITION"`	Validate relationships between fields (<, >, <=, >=, =, !=)	✅ Production Ready
Case-Insensitive Contains	`"match:containsIgnoreCase:..."`	String contains substring (case-insensitive)	✅ Tested
Case-Insensitive Equals	`"match:equalsIgnoreCase:..."`	String equals value (case-insensitive)	✅ Tested
Pattern Negation	`"match:not:PATTERN"`	Negate any pattern	✅ Tested

Legend:

✅ Verified: Tested with production MCP servers
✅ Core: Fundamental pattern matching

Basic Patterns

Deep Equality (Default)

The simplest pattern - values must match exactly:

yaml

result:
  status: "success"           # Must be exactly "success"
  count: 42                   # Must be exactly 42
  active: true                # Must be exactly true
  tools:
    - name: "calculator"      # Exact array structure required
      description: "Math operations"

Type Validation

Validates data types without checking specific values:

yaml

result:
  serverInfo: "match:type:object"    # Must be object
  tools: "match:type:array"          # Must be array
  count: "match:type:number"         # Must be number
  active: "match:type:boolean"       # Must be boolean
  message: "match:type:string"       # Must be string
  nullable: "match:type:null"        # Must be null

Supported Types: string, number, boolean, object, array, null

Important Note for Arrays: The match:type:array pattern correctly uses Array.isArray() for validation, as JavaScript arrays have typeof array === "object". This ensures reliable array type detection.

Object Structural Utility Patterns

yaml

metadata: "match:count:5"            # Object must have exactly 5 enumerable properties
secrets: "match:not:exists"         # Field must be absent (security regression guard)
flags: "match:exists"               # Field presence required

Use match:count:N to guard against unexpected shape drift and match:not:exists to ensure sensitive fields never appear.

Numeric Comparison Patterns

🎯 Comprehensive Numeric & Precision Validation

The numeric suite covers comparison, equality, tolerance, divisibility, modular, and precision cases. Below we highlight core comparators; see table above for the full extended set (approximately, multiple/divisible, decimal places).

Perfect for validating numeric data from MCP servers including API response times, success rates, user scores, inventory counts, and performance metrics:

yaml

result:
  # Basic comparisons
  score: "match:greaterThan:85"          # Score must be > 85
  count: "match:lessThan:100"            # Count must be < 100 
  percentage: "match:greaterThanOrEqual:95"  # Percentage must be >= 95
  rating: "match:lessThanOrEqual:5"      # Rating must be <= 5

  # Range validations
  temperature: "match:between:20:30"     # Temperature between 20-30 (inclusive)
  port: "match:range:8000:9000"         # Port in range 8000-9000 (inclusive)

  # With pattern negation
  value: "match:not:greaterThan:1000"    # Value should NOT be > 1000
  error_count: "match:not:greaterThan:0" # Should have no errors (0 or negative)
  score: "match:not:between:0:50"        # Score should NOT be in failing range

  # Real-world examples
  api_response_time: "match:lessThan:500"        # Response time < 500ms
  success_rate: "match:greaterThanOrEqual:99"    # Success rate >= 99%
  error_rate: "match:lessThanOrEqual:1"          # Error rate <= 1%
  load_balance: "match:between:40:60"            # Load between 40-60%

Core Comparator Patterns:

greaterThan:N, lessThan:N
greaterThanOrEqual:N, lessThanOrEqual:N
between:MIN:MAX / range:MIN:MAX

Extended Numeric & Precision Patterns:

yaml

metrics:
  latency_ms: "match:lessThan:500"
  availability_pct: "match:greaterThanOrEqual:99"
  rolling_mean: "match:approximately:42:0.5"   # 42 ± 0.5
  batchSize: "match:multipleOf:8"
  partitionCount: "match:divisibleBy:4"
  price: "match:decimalPlaces:2"             # Exactly two decimals
  allocation: "match:not:between:0:50"        # Not in low band

Tip: Use approximately for floating-point tolerance, decimalPlaces for currency-like exact precision, and multipleOf/divisibleBy for alignment constraints.

Common Use Cases:

Performance Testing: Response times, memory usage, CPU utilization
Business Logic: User scores, discount ranges, inventory levels
Quality Metrics: Error rates, uptime percentages, accuracy scores
Range Validation: Valid input ranges, configuration limits

Pattern Negation with `match:not:`

🎉 Universal Pattern Negation

Negate ANY existing pattern by prefixing with not:. Perfect for testing that values do NOT match specific criteria!

The match:not: prefix works with ALL existing pattern types to verify values do NOT match specific criteria. Syntax rule: insert not: immediately after match: and before the original pattern tokens (e.g. match:not:arrayLength:0, match:not:contains:error, match:not:regex:^ERR).

yaml

# Test 1: Basic negation patterns
tests:
  - it: "should enforce basic negations"
    expect:
      response:
        result:
          tools: "match:not:arrayLength:0"              # Tools array should NOT be empty
          name: "match:not:startsWith:invalid_"         # Name should NOT start with "invalid_"
          text: "match:not:contains:error"              # Text should NOT contain "error"
          data: "match:not:type:string"                 # Data should NOT be a string
          message: "match:not:endsWith:failed"          # Message should NOT end with "failed"
          pattern: "match:not:regex:^ERROR:"            # Should NOT match regex pattern

  - it: "should support negation with field extraction"
    expect:
      response:
        result:
          match:extractField: "tools.*.name"
          value: "match:not:arrayContains:get_latest_error"  # Array should NOT contain this value

  - it: "should support negation inside arrayElements"
    expect:
      response:
        result:
          tools:
            match:arrayElements:
              name: "match:not:startsWith:invalid_"     # No tool name should start with "invalid_"
              description: "match:not:contains:deprecated"  # No description should contain "deprecated"

Supported Negation Patterns:

match:not:contains:text - String should NOT contain text
match:not:startsWith:prefix - String should NOT start with prefix
match:not:endsWith:suffix - String should NOT end with suffix
match:not:type:string - Should NOT be specified type
match:not:arrayLength:N - Array should NOT have N elements
match:not:arrayContains:value - Array should NOT contain value
match:not:regex:pattern - Should NOT match regex
match:not:exists - Field should NOT exist
match:not:count:N - Should NOT have N properties
match:not:crossField:EXPR - Cross-field condition must NOT hold

Common Use Cases for Pattern Negation

Error Prevention: Ensure responses don't contain error messages
Security Validation: Verify sensitive data is not exposed
Tool Filtering: Confirm deprecated/invalid tools are not present
Quality Assurance: Check that unwanted patterns are absent
Regression Testing: Ensure known problems don't reappear

Detailed Pattern Guides

For comprehensive examples and usage patterns, visit our detailed guides:

Numeric Patterns

Greater than, less than, between, range patterns for numeric validation!

Date Patterns

Date validation, age checking, format validation, and temporal comparisons!

Pattern Negation

Negate any pattern with match:not: for advanced validation!

Quick Examples

Array Validation

yaml

result:
  # Exactly 1 tool
  tools: "match:arrayLength:1"
  
  # All tools must have these fields
  tools:
    match:arrayElements:
      name: "match:type:string"
      description: "match:type:string"
      
  # Array contains specific value
  toolNames: "match:arrayContains:calculator"

Field Extraction

yaml

# Extract tool names from array (dot notation)
result:
  match:extractField: "tools.*.name"   # Extract 'name' from all tools
  value:
    - "calculator"
    - "text_processor"

# Extract specific element by index (bracket notation)
result:
  match:extractField: "tools[5].name"  # Extract 6th tool name (0-indexed)  
  value: "search_docs"

# Mixed bracket and dot notation
result:
  match:extractField: "tools[0].inputSchema.properties"
  value: "match:type:object"
    - "calculator"
    - "text_processor"

String Patterns

yaml

result:
  message: "match:contains:success"     # Contains substring
  filename: "match:startsWith:data_"    # Starts with prefix
  extension: "match:endsWith:.json"     # Ends with suffix
  version: "match:regex:v\d+\.\d+\.\d+"  # Semantic version pattern

Partial Matching

yaml

# Only validate specified fields, ignore others
result:
  match:partial:
    status: "success"
    tools: "match:type:array"
  # Other fields in result are ignored

Date Pattern Examples

yaml

result:
  # Date validity checking
  createdAt: "match:dateValid"                  # Must be valid date
  invalidDate: "match:not:dateValid"            # Must be invalid
  
  # Date comparisons
  publishDate: "match:dateAfter:2023-01-01"     # After Jan 1, 2023
  expireDate: "match:dateBefore:2025-12-31"     # Before Dec 31, 2025
  eventDate: "match:dateBetween:2023-01-01:2024-12-31"  # Within 2023-2024
  
  # Age validation (recent timestamps)
  lastUpdate: "match:dateAge:1d"                # Within last day
  recentActivity: "match:dateAge:2h"            # Within last 2 hours
  oldBackup: "match:not:dateAge:7d"             # NOT within last week
  
  # Format validation
  isoTimestamp: "match:dateFormat:iso"          # ISO 8601 format
  dateString: "match:dateFormat:iso-date"       # YYYY-MM-DD format
  usDate: "match:dateFormat:us-date"            # MM/DD/YYYY format

Cross-Field Validation Examples

yaml

result:
  # Basic field comparisons (same level)
  "match:crossField": "startDate < endDate"           # Date comparison
  "match:crossField": "minPrice <= maxPrice"          # Numeric comparison  
  "match:crossField": "currentStock > minStock"       # Greater than validation
  "match:crossField": "retailPrice = originalPrice"   # Equality check
  "match:crossField": "retries != maxRetries"         # Not equal validation

  # Real-world business validation examples
  # Event management
  "match:crossField": "registrationStart < registrationEnd"
  "match:crossField": "minParticipants <= currentParticipants"
  "match:crossField": "currentParticipants <= maxParticipants"
  
  # Financial constraints
  "match:crossField": "transaction.amount <= account.balance"
  "match:crossField": "account.credit.used < account.credit.limit"
  "match:crossField": "creditScore >= minCreditScore"
  
  # Inventory management  
  "match:crossField": "stock.current >= stock.reserved"
  "match:crossField": "availableStock <= currentStock"
  "match:crossField": "nextDelivery > lastRestocked"
  
  # User permissions and access
  "match:crossField": "user.level >= access.required"
  "match:crossField": "user.profile.maxConnections <= config.system.connectionLimit"
  
  # Complex business rules with deep nesting
  "match:crossField": "order.items.total.price <= customer.account.creditLimit"
  "match:crossField": "order.shipping.estimatedDelivery > order.processing.completedDate"
  "match:crossField": "company.division.team.member.clearanceLevel >= project.security.requirements.minClearance"

# Nested crossField within object structures
result:
  pricing:
    wholesale: "match:type:object"
    retail: "match:type:object"
    "match:crossField": "wholesale.price < retail.price"
  product: "match:type:object"

# Multiple nested crossField patterns
result:
  match:partial:
    stock:
      current: "match:type:number"
      reserved: "match:type:number"
      minimum: "match:type:number"
      "match:crossField": "current >= reserved"
    warehouse:
      capacity:
        maxUnits: "match:type:number"
        currentUnits: "match:type:number"
        "match:crossField": "currentUnits < maxUnits"

# Negated cross-field validation
result:
  "match:not:crossField": "currentStock > maxStock"        # Should NOT exceed capacity
  "match:not:crossField": "used >= limit"                   # Should NOT exceed limits

Pattern Negation Examples

yaml

result:
  # Ensure tools array is not empty
  tools: "match:not:arrayLength:0"
  
  # Ensure no tool names start with "invalid_"  
  match:extractField: "tools.*.name"
  value: "match:not:arrayContains:invalid_tool"
  
  # Ensure error messages are not present
  message: "match:not:contains:error"
  status: "match:not:startsWith:ERROR:"
  
  # Ensure data is not a string (should be object/array)
  data: "match:not:type:string"

Pattern Development Tips

🚨 Critical Pattern Development Guidelines

Always start with --debug: Check actual MCP response structure before writing patterns
One pattern type per test: Don't mix multiple complex patterns in single validation
Test incrementally: Start with deep equality, then add pattern complexity
Validate YAML syntax: Use YAML linters before testing patterns
Separate complex validations: Multiple simple tests > one complex test
Check field paths: Verify dot notation paths are correct
Match actual structure: Don't assume arrays vs objects without verification

Common MCP Testing Patterns

Tool Discovery Validation

yaml

- it: "should list all available tools"
  request:
    method: "tools/list"
  expect:
    response:
      result:
        tools:
          match:arrayElements:
            name: "match:type:string"
            description: "match:regex:[\\s\\S]{10,}"  # At least 10 chars (multiline-safe)
            inputSchema: "match:type:object"

Error Response Validation

yaml

- it: "should handle invalid tool gracefully"
  request:
    method: "tools/call"
    params:
      name: "nonexistent_tool"
      arguments: {}
  expect:
    response:
      result:
        isError: true
        content:
          - type: "text"
            text: "match:contains:Unknown tool"

Pattern Documentation Pages

Each pattern category has its own dedicated page with comprehensive examples and real-world usage:

🔧 Basic Patterns

Fundamental validation patterns for everyday testing.

• Deep equality matching
• Type validation
• Field existence checking
• Object property counting

📝 String Patterns

Text validation for messages, content, and identifiers.

• Contains substring matching
• Prefix and suffix validation
• Case-sensitive text checking
• Content validation

🔍 Regex Patterns

Complex pattern matching with regular expressions.

• Email and URL validation
• Timestamp and UUID matching
• Complex format validation
• Custom pattern creation

🔢 Numeric Patterns

Mathematical comparisons and range validation.

• Greater/less than comparisons
• Range and between validation
• Performance metric testing
• Score and count validation

� Date Patterns

Temporal validation and date/time comparisons.

• Date validity checking
• Age and recency validation
• Format validation (ISO, US, etc.)
• Date range comparisons

�📋 Array Patterns

Collection validation and element testing.

• Array length validation
• Element pattern matching
• Contains value checking
• Field-based array searching

🏗️ Object & Field Patterns

Complex object validation and field extraction.

• Field extraction with dot notation
• Partial object matching
• Nested structure validation
• Dynamic field testing

🔗 Cross-Field Patterns

Validate relationships between fields in the same object.

• Field-to-field comparisons (<, >, =, !=)
• Business rule validation
• Nested object relationships
• Data consistency checking

⚡ Advanced Patterns

Sophisticated techniques and pattern combinations.

• Pattern negation (not: prefix)
• Case-insensitive matching
• Complex pattern combinations
• Utility and meta patterns

🚀 Power Pattern: Partial + Array Elements

Most powerful combination: validate required fields in arrays while ignoring optional properties.

• match:arrayElements + match:partial
• Perfect for API evolution & flexible schemas
• Test core fields (title, id) ignore rest
• Essential for production testing

Best Practices

Use --verbose --debug flags when developing patterns to see actual vs expected
Start simple: Begin with match:type patterns before complex regex
Test edge cases: Empty arrays, null values, missing fields
Document patterns: Add comments explaining complex regex patterns
Validate incrementally: Test each pattern addition separately
Use field extraction for complex nested validations
Prefer multiple simple patterns over one complex pattern

MCP

MCP

Pattern Matching Reference

🏆 Production Verified Patterns

Pattern Types Overview

Basic Patterns

Deep Equality (Default)

Type Validation

Numeric Comparison Patterns

Pattern Negation with match:not:

Common Use Cases for Pattern Negation

Detailed Pattern Guides

Basic Patterns

String Patterns

Regex Patterns

Array Patterns

Object & Field Patterns

Numeric Patterns

Date Patterns

Pattern Negation

Quick Examples

Array Validation

Field Extraction

String Patterns

Partial Matching

Date Pattern Examples

Cross-Field Validation Examples

Pattern Negation Examples

Pattern Development Tips

Common MCP Testing Patterns

Tool Discovery Validation

Error Response Validation

Pattern Documentation Pages

🔧 Basic Patterns

📝 String Patterns

🔍 Regex Patterns

🔢 Numeric Patterns

� Date Patterns

�📋 Array Patterns

🏗️ Object & Field Patterns

🔗 Cross-Field Patterns

⚡ Advanced Patterns

🚀 Power Pattern: Partial + Array Elements

Best Practices

Pattern Negation with `match:not:`