# general-analysis/mcp-guard architecture

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

- Interactive diagram: https://gitdiagram.com/general-analysis/mcp-guard
- Repository: https://github.com/general-analysis/mcp-guard

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Components
    MCP_Client["MCP Client"]:::externalClient
    subgraph "MCP Guard CLI"
        direction TB
        CLIEntrypoint["CLI Entrypoint"]:::internal
        ConfigLoader["Config Loader\n(env & args)"]:::internal
        Handler["Message Routing Layer"]:::internal
        Moderation["Moderation Module"]:::internal
        Transport["Transport Layer\n(stdio & HTTP/SSE)"]:::internal
        Types["Shared Types"]:::internal
    end
    LocalServer["Local MCP Server"]:::local
    RemoteServer["Remote MCP Server"]:::remote
    AIService["AI Moderation Service\n(General Analysis API)"]:::external

    Alert["Alert\n(Blocked)"]:::alert

    %% Data Flows
    MCP_Client -->|"stdio/HTTP-SSE"| CLIEntrypoint
    CLIEntrypoint -->|"bootstrap"| ConfigLoader
    CLIEntrypoint -->|"invoke"| Handler
    Handler -->|"if ENABLE_GUARD_API"| Moderation
    Moderation -->|"HTTPS"| AIService
    AIService -->|"Safe/Blocked"| Moderation
    Moderation -->|"result"| Handler
    Handler -->|"Safe"| Transport
    Transport -->|"stdio"| LocalServer
    Transport -->|"HTTP/SSE"| RemoteServer
    LocalServer -->|"response"| Handler
    RemoteServer -->|"response"| Handler
    Handler -->|"forward"| MCP_Client
    Handler -->|"Blocked"| Alert
    Alert -->|"notify"| MCP_Client

    %% Click Events
    click CLIEntrypoint "https://github.com/general-analysis/mcp-guard/blob/main/src/index.ts"
    click ConfigLoader "https://github.com/general-analysis/mcp-guard/blob/main/src/index.ts"
    click Handler "https://github.com/general-analysis/mcp-guard/blob/main/src/handlers.ts"
    click Moderation "https://github.com/general-analysis/mcp-guard/blob/main/src/moderation.ts"
    click Transport "https://github.com/general-analysis/mcp-guard/blob/main/src/client.ts"
    click Types "https://github.com/general-analysis/mcp-guard/blob/main/src/types.ts"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef local fill:#90EE90,stroke:#333,stroke-width:1px
    classDef remote fill:#FFA500,stroke:#333,stroke-width:1px
    classDef external fill:#FF6347,stroke:#333,stroke-width:1px
    classDef alert fill:#FFCCCC,stroke:#333,stroke-width:1px
    class MCP_Client external
    class AIService external
    class LocalServer local
    class RemoteServer remote
    class Alert alert
```
