# taurgis/mcp-aegis architecture

> Architecture diagram of the GitHub repository taurgis/mcp-aegis, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/taurgis/mcp-aegis
- Repository: https://github.com/taurgis/mcp-aegis

## Overview

##### Project Type and Purpose
- MCP Aegis is an open-source Node.js testing library and CLI tool designed to test Model Context Protocol (MCP) servers.
- It provides both declarative YAML-based tests and a programmatic API, handling JSON-RPC handshakes, advanced pattern matching, and rich reporting.

##### File Structure Analysis
- Top-level directories:
- src — core implementation: CLI, core modules, programmatic client, protocol handler, test engine
- test — unit and integration tests for each layer
- examples — sample MCP servers and test suites
- docs-site-v2 — documentation website code (React/TypeScript)
- AGENTS — documentation for AI agents (auxiliary docs)
- Key subdirectories under src:
- cli — CLI commands (init, test, query) & output formatting
- core — config loader/validator, MCPCommunicator, ProcessManager, StreamBuffer
- programmatic — MCPClient class for JS/TS integration
- protocol — JSON-RPC handshake logic
- test-engine — executor, parser, matchers (pattern analyzers, corrections), reporter
- Configuration/build:
- package.json, .github workflows (CI, docs deploy), .husky hooks, eslint.config.js

##### README Insights
- Describes CLI workflow: init → config → run tests
- Highlights features: YAML and programmatic testing, pattern matching, JSON-RPC automation, reporting
- Shows programmatic API usage via connect( ), listTools( ), callTool( )

##### Main Components and Relationships
a. Components
- CLI Layer — User-facing commands
- Programmatic API — MCPClient for test frameworks
- Core Engine — ConfigLoader/Validator, MCPCommunicator, ProcessManager, StreamBuffer
- Protocol Handler — JSON-RPC handshake, message framing
- Test Engine — Executor (runs tests), Parser (reads YAML or programmatic calls), Matchers (pattern analyzers & validators), Reporter (collects and formats results)
- External MCP Server Process — The target under test (spawned via ProcessManager)
- Documentation Site — Static site generator separate process
b. Interactions
1. CLI or Programmatic API reads config (aegis.config.json) via Core.ConfigLoader
2. ProcessManager spawns MCP server process; StreamBuffer handles stdio streams
3. MCPCommunicator and protocol.handshake manage JSON-RPC handshake over stdio
4. Test Engine Executor invokes tests:
– For YAML tests: parser reads .test.mcp.yml files
– For programmatic tests: MCPClient methods translate into JSON-RPC calls
5. Responses flow back through StreamBuffer → MCPCommunicator → Executor
6. Matchers analyze responses against patterns; Reporter collects results and prints via CLI.output or returns via API
c. Architectural Patterns
- Modular layered architecture: clear separation of concerns (CLI, core, protocol, engine)
- Plugin-style matchers (analyzers, corrections, validators)
- Stream-based processing of stdio using buffered JSON framing
- Process-per-test isolation via ProcessManager
d. Key Technologies
- Node.js (>=18): child_process, streams
- YAML parsing (for declarative tests)
- JSON-RPC over stdio
- React/TypeScript for docs-site
- ESM modules (debug-options.mjs, vite.config.ts)

## Diagram (Mermaid)

```mermaid
graph TB

  subgraph "Presentation Layer"
    CLI["CLI Layer"]:::presentation
    InitCmd["init.js"]:::presentation
    click InitCmd "https://github.com/taurgis/mcp-aegis/blob/main/src/cli/commands/init.js"
    TestCmd["test.js"]:::presentation
    click TestCmd "https://github.com/taurgis/mcp-aegis/blob/main/src/cli/commands/test.js"
    QueryCmd["query.js"]:::presentation
    click QueryCmd "https://github.com/taurgis/mcp-aegis/blob/main/src/cli/commands/query.js"
    Options["options.js"]:::presentation
    click Options "https://github.com/taurgis/mcp-aegis/blob/main/src/cli/interface/options.js"
    OutputInt["output.js"]:::presentation
    click OutputInt "https://github.com/taurgis/mcp-aegis/blob/main/src/cli/interface/output.js"
    ProgAPI["Programmatic API (MCPClient)"]:::presentation
    click ProgAPI "https://github.com/taurgis/mcp-aegis/blob/main/src/programmatic/MCPClient.js"
  end

  subgraph "Core Modules"
    ConfigLoader["ConfigLoader.js"]:::core
    click ConfigLoader "https://github.com/taurgis/mcp-aegis/blob/main/src/core/ConfigLoader.js"
    ConfigValidator["ConfigValidator.js"]:::core
    click ConfigValidator "https://github.com/taurgis/mcp-aegis/blob/main/src/core/ConfigValidator.js"
    MCPComm["MCPCommunicator.js"]:::core
    click MCPComm "https://github.com/taurgis/mcp-aegis/blob/main/src/core/MCPCommunicator.js"
    MsgHandler["MessageHandler.js"]:::core
    click MsgHandler "https://github.com/taurgis/mcp-aegis/blob/main/src/core/MessageHandler.js"
    ProcessMgr["ProcessManager.js"]:::core
    click ProcessMgr "https://github.com/taurgis/mcp-aegis/blob/main/src/core/ProcessManager.js"
    StreamBuf["StreamBuffer.js"]:::core
    click StreamBuf "https://github.com/taurgis/mcp-aegis/blob/main/src/core/StreamBuffer.js"
    ConfigParser["configParser.js"]:::core
    click ConfigParser "https://github.com/taurgis/mcp-aegis/blob/main/src/core/configParser.js"
    ParamParser["parameterParser.js"]:::core
    click ParamParser "https://github.com/taurgis/mcp-aegis/blob/main/src/core/parameterParser.js"
  end

  subgraph "Protocol Handler"
    Handshake["handshake.js"]:::core
    click Handshake "https://github.com/taurgis/mcp-aegis/blob/main/src/protocol/handshake.js"
  end

  subgraph "Test Engine"
    Executor["executor.js"]:::engine
    click Executor "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/executor.js"
    Parser["parser.js"]:::engine
    click Parser "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/parser.js"
    Runner["runner.js"]:::engine
    click Runner "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/runner.js"
    subgraph "Matchers"
      Analyzers["analyzers/*.js"]:::engine
      click Analyzers "https://github.com/taurgis/mcp-aegis/tree/main/src/test-engine/matchers/analyzers"
      Corrections["corrections/**"]:::engine
      click Corrections "https://github.com/taurgis/mcp-aegis/tree/main/src/test-engine/matchers/corrections"
      CrossField["crossFieldPatterns.js"]:::engine
      click CrossField "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/matchers/crossFieldPatterns.js"
      DatePat["datePatterns.js"]:::engine
      click DatePat "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/matchers/datePatterns.js"
      NumPat["numericPatterns.js"]:::engine
      click NumPat "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/matchers/numericPatterns.js"
      StrPat["stringPatterns.js"]:::engine
      click StrPat "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/matchers/stringPatterns.js"
      TypePat["typePatterns.js"]:::engine
      click TypePat "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/matchers/typePatterns.js"
      subgraph "Validation & Utils"
        Validations["validation/**"]:::engine
        click Validations "https://github.com/taurgis/mcp-aegis/tree/main/src/test-engine/matchers/validation"
        Utils["utils/**"]:::engine
        click Utils "https://github.com/taurgis/mcp-aegis/tree/main/src/test-engine/matchers/utils"
      end
    end
    subgraph "Reporter"
      OutputFmt["OutputFormatter.js"]:::engine
      click OutputFmt "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/OutputFormatter.js"
      ReporterCore["Reporter.js"]:::engine
      click ReporterCore "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/Reporter.js"
      ResultsCol["ResultsCollector.js"]:::engine
      click ResultsCol "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/ResultsCollector.js"
      PatternAn["PatternAnalyzer.js"]:::engine
      click PatternAn "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/PatternAnalyzer.js"
      PerfTrack["PerformanceTracker.js"]:::engine
      click PerfTrack "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/PerformanceTracker.js"
      VEAnalyzer["ValidationErrorAnalyzer.js"]:::engine
      click VEAnalyzer "https://github.com/taurgis/mcp-aegis/blob/main/src/test-engine/reporter/ValidationErrorAnalyzer.js"
    end
  end

  ExternalMCP["External MCP Server Process"]:::external
  DocsSite["Documentation Site"]:::docs
  click DocsSite "https://github.com/taurgis/mcp-aegis/tree/main/docs-site-v2"
  Examples["Examples"]:::external
  click Examples "https://github.com/taurgis/mcp-aegis/tree/main/examples"

  CLI --> InitCmd
  CLI --> TestCmd
  CLI --> QueryCmd
  CLI --> Options
  CLI --> OutputInt
  CLI -->|"reads config"| ConfigLoader
  ProgAPI -->|"uses"| ConfigLoader

  ConfigLoader --> ConfigValidator
  ConfigLoader --> Runner
  ConfigValidator --> Runner

  Runner --> ProcessMgr
  ProcessMgr --> ExternalMCP
  ExternalMCP --> StreamBuf
  StreamBuf --> MCPComm
  MCPComm --> Handshake

  Handshake --> Executor
  Parser --> Executor
  Executor --> MCPComm
  MCPComm --> Executor

  Executor --> Matchers
  Matchers --> ReporterCore
  ReporterCore --> OutputFmt
  ReporterCore --> ResultsCol
  OutputFmt --> CLI
  OutputFmt --> ProgAPI

  DocsSite -.-> CLI

  classDef presentation fill:#cce5ff,stroke:#004085,color:#004085;
  classDef core fill:#d4edda,stroke:#155724,color:#155724;
  classDef engine fill:#fff3cd,stroke:#856404,color:#856404;
  classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
  classDef docs fill:#d6d8db,stroke:#343a40,color:#343a40;
```
