# MCP YAML Testing

> Guide for writing and debugging YAML-based declarative MCP server tests using Aegis. Use this when asked to create, fix, or debug MCP YAML tests (*.test.mcp.yml files). Use when this capability is needed.

- Skill: `tomevault-io/mcp-yaml-testing` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/mcp-yaml-testing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/mcp-yaml-testing/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/mcp-yaml-testing

---


# MCP YAML Testing Skill

Use this skill when writing or debugging `*.test.mcp.yml` files for Model Context Protocol servers.

## Golden Rule: Discovery First

**CRITICAL**: Before writing ANY YAML test, discover actual response formats:

```bash
# Test successful execution
npx aegis query [tool_name] '[valid_params]' --config "./aegis.config.docs-only.json"

# Test failure scenarios  
npx aegis query [tool_name] '[invalid_params]' --config "./aegis.config.docs-only.json"
npx aegis query [tool_name] '' --config "./aegis.config.docs-only.json"  # Empty params
```

## Parameter Formats

### Pipe Format (Recommended)
```bash
npx aegis query read_file 'path:test.txt' --config "./aegis.config.docs-only.json"
npx aegis query calculator 'operation:add|a:5|b:3' --config "./aegis.config.docs-only.json"

# Nested via dot notation
npx aegis query api_client 'config.host:localhost|config.port:8080' --config "./aegis.config.docs-only.json"
```

### JSON Format (Complex Structures)
```bash
npx aegis query complex_tool '{"config": {"host": "localhost"}, "data": [1,2,3]}' --config "./aegis.config.docs-only.json"
```

## Basic Test Structure

```yaml
description: "Test suite description"
tests:
  - it: "Test description"
    request:
      jsonrpc: "2.0"
      id: "unique-id"
      method: "tools/list"  # or "tools/call"
      params: {}
    expect:
      response:
        jsonrpc: "2.0"
        id: "unique-id"
        result: {}
      stderr: "toBeEmpty"
```

## Common Pattern Reference

```yaml
# TYPE VALIDATION
result:
  tools: "match:type:array"
  count: "match:type:number"

# STRING PATTERNS
result:
  text: "match:contains:substring"
  name: "match:startsWith:prefix"
  pattern: "match:regex:\\d{4}-\\d{2}-\\d{2}"  # Double-escape backslashes!

# ARRAY PATTERNS
result:
  tools: "match:arrayLength:3"
  tools:
    match:arrayElements:
      match:partial:  # Flexible - only validate specified fields
        name: "match:regex:^[a-z_]+$"
        description: "match:contains:tool"

# NEGATION
result:
  tools: "match:not:arrayLength:0"
  text: "match:not:contains:error"
```

## Common Mistakes to Avoid

```yaml
# ❌ WRONG - Duplicate YAML keys
result:
  tools: "match:arrayLength:1"
  tools: ["read_file"]  # OVERWRITES above!

# ❌ WRONG - Missing double backslash
result:
  text: "match:regex:\d+"  # Wrong
  text: "match:regex:\\d+"  # Correct

# ❌ WRONG - Assuming structure without discovery
result:
  tools: "match:arrayLength:3"  # Did you verify this exists?
```

## Test Execution Commands

```bash
# Run YAML tests (docs-only mode)
npm run test:mcp:yaml

# Run YAML tests (full mode with credentials)
npm run test:mcp:yaml:full

# Run specific test file
npx aegis "tests/mcp/yaml/specific.test.mcp.yml" --config "./aegis.config.docs-only.json"

# Debug mode
npx aegis "tests/**/*.test.mcp.yml" --config "./aegis.config.docs-only.json" --verbose --debug
```

## Discovery Examples for This Project

```bash
# List available tools
npx aegis query --config ./aegis.config.docs-only.json

# Documentation tools
npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
npx aegis query get_sfcc_class_info 'className:dw.catalog.Product' --config ./aegis.config.docs-only.json

# Agent instructions / skills bootstrap
npx aegis query sync_agent_instructions 'destinationType:temp|dryRun:true' --config ./aegis.config.docs-only.json

# Full mode tools (requires credentials)
npx aegis query get_system_object_definitions --config ./aegis.config.with-dw.json
```

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/taurgis) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->