How taurgis/mcp-aegis works
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)