Regex Patterns

Unleash the full power of regular expressions for complex string validation.

For the most complex string validation scenarios, MCP Aegis provides full support for regular expressions, allowing you to match intricate patterns in server responses. All patterns are production-verified with real MCP servers and extensive filesystem server testing.

Basic Regex Patterns

Use "match:regex:<pattern>" to validate strings against regular expressions. Perfect for validating formats like UUIDs, timestamps, or structured error messages.

YAML Escaping Rules

Critical: In YAML strings, backslashes must be escaped. To match a digit (\\d), write "\\\\d" in YAML.

Number Patterns

yaml

# ✅ Basic numbers - verified with filesystem server
text: "match:regex:\\d+"                    # Any number: "123", "42"

# ✅ Temperature patterns - verified with production data
text: "match:regex:Temperature: \\d+°[CF]"  # "Temperature: 25°C"

# Decimal numbers
text: "match:regex:\\d+\\.\\d{2}"       # Price: "19.99"

# Negative numbers  
text: "match:regex:-?\\d+"                  # Temperature: "-5" or "23"

# Percentage
text: "match:regex:\\d+%"                   # Progress: "75%"

Date and Time Patterns

yaml

# ✅ ISO dates - verified with filesystem server timestamp.txt
text: "match:regex:\\d{4}-\\d{2}-\\d{2}"       # "2024-01-15"

# ✅ ISO timestamps - verified with production APIs
text: "match:regex:\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}"  # Full ISO timestamp

# Time format
text: "match:regex:\\d{2}:\\d{2}(:\\d{2})?"    # "14:30" or "14:30:45"

# RFC 2822 dates
text: "match:regex:^[A-Z][a-z]{2}, \\d{1,2} [A-Z][a-z]{2} \\d{4}"  # "Mon, 15 Jan 2024"

Identifier Patterns

yaml

# ✅ Email addresses - verified with contact.txt
text: "match:regex:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"

# ✅ URLs - verified with links.txt  
text: "match:regex:https?://[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}(/[^\\s]*)?"

# ✅ Phone numbers (US) - verified with contact.txt
text: "match:regex:\\(?\\d{3}\\)?[\\s-]?\\d{3}[\\s-]?\\d{4}"

# UUIDs
text: "match:regex:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"

# API Keys
text: "match:regex:[A-Z0-9]{32}"               # 32-character API key

Production Examples

Simple Filesystem Server

Number Validation:

yaml

# ✅ Verified with filesystem server numbers.txt
- it: "should match numbers using regex pattern"
  request:
    method: "tools/call"
    params:
      name: "read_file"
      arguments:
        path: "../shared-test-data/numbers.txt"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:\\d+"    # Matches any number
        isError: false

Email Pattern Matching:

yaml

# ✅ Verified with contact.txt  
- it: "should match email addresses"
  request:
    method: "tools/call"
    params:
      name: "read_file"
      arguments:
        path: "../shared-test-data/contact.txt"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}"
        isError: false

Word Boundary Patterns:

yaml

# ✅ Verified with text-sample.txt - precise word matching
- it: "should match word boundaries"
  request:
    method: "tools/call"
    params:
      name: "read_file" 
      arguments:
        path: "../shared-test-data/text-sample.txt"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:\\bError\\b"  # Matches "Error" as complete word
        isError: false

Advanced Regex Patterns

Word Boundaries & Precise Matching

yaml

# ✅ Complete word matching - prevents partial matches
text: "match:regex:\\bError\\b"              # Matches "Error" not "ErrorCode"
status: "match:regex:\\bSTATUS\\b:\\s*ACTIVE" # Matches "STATUS: ACTIVE" 
name: "match:regex:\\b[A-Z][a-z]+\\b"        # Capitalized words only

# ✅ Production monitoring patterns  
result: "match:regex:\\bmonitors\\b.*\\bactive\\b"  # "monitors are active"

Complex Validation Patterns

yaml

# ✅ Semantic versioning - verified with filesystem server
text: "match:regex:v?\\d+\\.\\d+\\.\\d+"  # "1.2.3" or "v1.2.3"

# ✅ File extensions - verified with filesystem server  
text: "match:regex:\\w+\\.(js|ts|json|txt)"      # JavaScript/config files

# ✅ Multiple error patterns - verified with error handling
text: "match:regex:.*ENOENT.*|.*not found.*"         # File not found errors

# ✅ Complex password/ID patterns
text: "match:regex:(?=.*\\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*]).*|^(?:user|admin|guest)_\\w+_\\d{4}
quot;

JSON Structure Patterns

yaml

# JSON object validation
text: "match:regex:\\{.*\"status\":\\s*\"success\".*\\}"

# Array format
text: "match:regex:\\[.*\\]"

# Key-value pairs
text: "match:regex:\"\\w+\":\\s*\"[^\"]+\""

# Nested JSON paths
text: "match:regex:\"data\":\\s*\\{.*\"items\":\\s*\\[.*\\]"

⚠️ Critical: Minimum Length Patterns for Multiline Content

IMPORTANT: Standard dot notation fails on multiline content!

When validating substantial content like hook lists, documentation, or API responses, you must use multiline-safe patterns.

Multiline-Safe Patterns

yaml

# ✅ CORRECT: Multiline content validation 
text: "match:regex:[\\s\\S]{1000,}"      # At least 1000 characters (any content)
text: "match:regex:[\\s\\S]{500,}"       # At least 500 characters  
text: "match:regex:[\\s\\S]{100,}"       # At least 100 characters

# ❌ WRONG: Standard dot notation fails on multiline
text: "match:regex:.{1000,}"                # FAILS: dot doesn't match newlines!

Why This Matters

Standard Pattern (fails on multiline):

.{1000,} - Matches 1000+ non-newline characters

❌ Fails when content contains newlines (common in MCP responses)

Multiline-Safe Pattern (always works):

[\\s\\S]{1000,} - Matches 1000+ ANY characters including newlines

✅ Works with all content types: documentation, hook lists, formatted responses

Real-World Use Cases

yaml

# ✅ Hook list validation - ensure comprehensive response
- it: "should return substantial hook documentation"
  request:
    method: "tools/call"
    params:
      name: "list_hooks"
      arguments: {}
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:[\\s\\S]{1000,}"  # At least 1000 chars
        isError: false

# ✅ Documentation validation - ensure complete docs
- it: "should return comprehensive API documentation"
  request:
    method: "tools/call"
    params:
      name: "get_docs"
      arguments: 
        section: "api-reference"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:[\\s\\S]{2000,}"  # Substantial docs (2000+ chars)
        isError: false

# ✅ Error message validation - ensure detailed errors  
- it: "should return detailed error information"
  request:
    method: "tools/call"
    params:
      name: "validate_data"
      arguments:
        data: "invalid"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:[\\s\\S]{200,}"   # Detailed error (200+ chars)
        isError: true

Flexible Minimum Lengths

yaml

# Choose appropriate minimums for your content type:

# Brief content validation
text: "match:regex:[\\s\\S]{50,}"        # Short messages, status updates
text: "match:regex:[\\s\\S]{100,}"       # Basic responses, simple data

# Moderate content validation  
text: "match:regex:[\\s\\S]{500,}"       # API responses, tool outputs
text: "match:regex:[\\s\\S]{750,}"       # Component lists, configurations

# Substantial content validation
text: "match:regex:[\\s\\S]{1000,}"      # Hook lists, documentation
text: "match:regex:[\\s\\S]{2000,}"      # Comprehensive guides, large datasets
text: "match:regex:[\\s\\S]{5000,}"      # Complete documentation, full reports

Combining Length with Content Validation

Use separate test cases to validate both minimum length and specific content:

yaml

# Test 1: Validate minimum length
- it: "should return substantial hook list content"
  request:
    method: "tools/call"
    params:
      name: "list_hooks"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:regex:[\\s\\S]{1000,}"  # Length check
        isError: false

# Test 2: Validate specific content  
- it: "should include specific hook names"
  request:
    method: "tools/call"
    params:
      name: "list_hooks"
  expect:
    response:
      result:
        content:
          - type: "text"
            text: "match:contains:useAddProductToBasket"  # Content check
        isError: false

🏆 Production Success

These multiline-safe patterns have been successfully tested with production MCP servers including FastForward BM and other comprehensive hook/component systems. They ensure your tests validate substantial, meaningful content rather than minimal placeholder responses.

Error Message Patterns

Error Response Validation

yaml

# ✅ Generic error patterns
text: "match:regex:.*[Ee]rror.*"                # Any error message
text: "match:regex:[A-Z_]+_ERROR"               # Structured error codes

# ✅ HTTP status patterns  
text: "match:regex:Status: (200|201|202|400|404|500)"  # HTTP status codes

# ✅ File operation errors
text: "match:regex:(ENOENT|EACCES|ENOTDIR)"    # File system errors
text: "match:regex:Permission denied|Access forbidden"  # Permission errors

Debugging Regex Patterns

Step-by-Step Testing

bash

# Use debug mode to see actual vs expected
aegis test.yml --config config.json --debug

# Output shows:
# Expected: "match:regex:\\d+"  
# Actual: "Temperature: 25°C"
# ✅ Pattern matches (contains digits)

Common Regex Issues

yaml

# ❌ Insufficient escaping in YAML
text: "match:regex:\d+"           # Wrong - single backslash
text: "match:regex:\\d+"         # ✅ Correct - double backslash

# ❌ Missing anchors for exact matching
text: "match:regex:admin"          # Matches "administrator" 
text: "match:regex:^adminquot;        # ✅ Matches only "admin"

# ❌ Case sensitivity issues
text: "match:regex:error"          # Won't match "ERROR"
text: "match:regex:[Ee]rror|ERROR" # ✅ Handles case variations

# ❌ Forgetting special character escaping
text: "match:regex:file.txt"       # Dot matches any character
text: "match:regex:file\\.txt"   # ✅ Literal dot match

Best Practices

Test incrementally: Start with simple patterns, add complexity
Use word boundaries: \\b for precise matching
Escape properly: Double backslashes in YAML strings
Provide alternatives: Use | for multiple valid patterns
Anchor when needed: ^ and $ for exact matches
Document complex patterns: Add comments explaining the regex purpose

Performance Considerations

Regex patterns in MCP Aegis are optimized for typical API testing scenarios:

Compiled once: Patterns are compiled and cached per test
Short-circuit evaluation: Simple patterns checked first
Timeout protection: Complex regex patterns have execution limits
Memory efficient: Pattern compilation reused across similar tests

✅ Production Verified

All regex patterns have been extensively tested with Simple Filesystem Server test files (numbers.txt, contact.txt, links.txt, timestamp.txt, text-sample.txt) and production MCP servers. Complex patterns handle real-world data including emails, URLs, phone numbers, timestamps, and error messages.

📋 Comprehensive Pattern Reference

Production-tested regex patterns with example matches from our comprehensive test suite:

Use Case	Pattern	Example Matches	Notes
Email Validation	`[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}`	[email protected] [email protected]	Handles most common email formats
ISO Timestamps	`\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}`	2024-03-15T14:30:45 2023-12-01T09:15:30	Strict YYYY-MM-DDTHH:MM:SS format
HTTP/HTTPS URLs	`https?://[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}(/[^\s]*)?`	https://example.com http://api.service.co.uk/v1	Excludes localhost by design
Semantic Versions	`v?\d+\.\d+\.\d+(-[a-zA-Z]+\.\d+)?`	v1.2.3 2.0.1 v1.0.0-beta.1	Optional v prefix and pre-release
UUIDs	`[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}`	550e8400-e29b-41d4-a716-446655440000	Case-insensitive through pattern
File Extensions	`\w+\.(js\|ts\|jsx\|tsx\|json\|css\|txt)$`	script.js component.tsx config.json	End anchor prevents partial matches
JSON Success	`\{."status":\s"success".*\}`	{"status": "success", "data": {}}	Validates success status in JSON
Error Messages	`.ENOENT.\|.not found.\|.Permission denied.`	File not found: ENOENT Permission denied: EACCES	Multiple error pattern alternatives
Word Boundaries	`\bError\b`	Error occurred System Error detected	Prevents matching "Terrorist"
Currency/Prices	`\$\d+\.\d{2}`	$99.99 $1,234.56	Dollar sign with decimal precision
Temperature	`Temperature: \d+°[CF]`	Temperature: 23°C Temperature: 75°F	Celsius or Fahrenheit formats
ID Codes	`[A-Z]{3}-\d{3}-[A-Z]{3}`	ABC-123-XYZ DEF-456-QWE	Custom format: XXX-000-XXX
Multiline Content	`[\s\S]{1000,}`	Long documentation with newlines and content	Use for substantial multiline content

✅ All patterns tested: Each pattern in this table has been verified through comprehensive unit tests with the actual MCP Aegis handleRegexPattern function, ensuring production reliability.

Next Steps

Object Field Patterns - Field extraction and partial matching
String Patterns - Contains, startsWith, endsWith patterns
Examples - Real-world regex usage in production