How general-analysis/mcp-guard works
Project Type and Purpose
• This is a CLI-based Node.js (TypeScript) package that acts as a transparent proxy (“guardrail”) for one or more MCP (Model Context Protocol) servers.
• Its purpose is to intercept MCP traffic, apply AI-powered moderation (via the General Analysis API), and forward safe messages to configured local or remote MCP servers.
File Structure
• Top-level files: package.json, tsconfig.json, README.md, LICENSE
• src/
• index.ts: CLI entrypoint (argument/env parsing, configuration detection, bootstrap)
• client.ts: MCP client wrapper for stdin/stdout or HTTP/SSE
• handlers.ts: central message router (fan-out to servers & moderation)
• moderation.ts: calls out to the external AI moderation API
• types.ts: shared type definitions
• No frontend or UI components—pure CLI and proxy logic.
• No deployment scripts; distributed via npm/“npx”.
README for Additional Insights
• Describes dual connectivity: local (stdio child processes) and remote (HTTP/SSE).
• Environment variables (API_KEY, ENABLE_GUARD_API) toggle moderation behavior.
Main Components and Their Interactions
a. MCP Client
• The downstream process or application (e.g., Cursor, Claude Desktop).
• Communicates over stdio or HTTP/SSE to the “guard” CLI.
b. MCP Guard (CLI Tool)
• index.ts: loads configuration, parses the JSON array of servers passed via args.
• handlers.ts: routes incoming requests to moderation and server modules.
• moderation.ts: issues HTTP calls to the General Analysis Moderation API when enabled.
• client.ts: abstracts transport to underlying servers (child_process spawn or HTTP connector).
c. Local MCP Servers
• Spawned via child_process; communicate over stdio.
d. Remote MCP Servers
• Connected via HTTP/SSE endpoints.
e. AI Moderation Service (General Analysis API)
• External cloud service (HTTPS) that returns “Safe” or “Blocked.”
Data Flow:
1) MCP Client → Guard CLI (index.ts)
2) Guard → handlers.ts → moderation.ts (if ENABLE_GUARD_API=true)
3) Based on moderation result:
• If “Safe”: forward to configured servers (client.ts fan-out)
• If “Blocked”: emit an alert back to the client
4) Servers respond → handlers.ts → (optional second moderation pass) → back to MCP Client
Architectural Patterns and Design Principles
• Proxy/Gateway pattern: intercepts and controls access to downstream servers.
• Modular layering:
• CLI layer (config & bootstrap)
• Routing layer (handlers)
• Moderation layer (external API calls)
• Transport layer (local vs remote connectors)
• Dependency injection via JSON arguments and environment variables for extensibility.
Technologies, Frameworks, Libraries
• Node.js >=18, TypeScript
• child_process for stdio-based servers
• HTTP or EventSource for remote servers
• fetch or axios for AI moderation API calls
• npm package distribution, npx invocation