# invariantlabs-ai/mcp-scan architecture

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

- Interactive diagram: https://gitdiagram.com/invariantlabs-ai/mcp-scan
- Repository: https://github.com/invariantlabs-ai/mcp-scan

## Overview

##### Main Components

- Command Line Interface (CLI)
- Represented by the “cli.py” module.
- Handles user invocation (e.g., via “uvx mcp-scan@latest”).
- Initiates the scanning process.

- Scanning Engine
- Key logic contained in “MCPScanner.py”.
- Implements core scanning routines: locating MCP server configurations, connecting to servers, retrieving tool descriptions, and processing them.
- Integrates both local checks and remote API calls (via Invariant Guardrails).

- Data Models
- Defined in “models.py” for representing MCP configurations, tool descriptions, and possibly scan results.
- Use these models to standardize data handling across the scan pipeline.

- I/O Utilities
- “surpressIO.py” is likely used to handle or suppress console output (or logging) during scanning.
- This supports cleaner output and may be part of the debugging or logging configuration.

- Versioning and Packaging
- “version.py” contains version information.
- The build configuration via “pyproject.toml” and “Makefile” indicates packaging, installation, and deployment mechanisms.

- External Services
- The scanner communicates with the Invariant Guardrails API (external service provided by invariantlabs.ai) to perform part of its vulnerability detection.

##### Relationships and Interactions

- MCPScanner as the Core Engine:
- That it calls functions from “models.py” to parse and represent MCP data.

- External API Interaction:

- Data Flow from MCP Server Configurations:

##### Architectural Patterns and Design Principles

- Modular Design:
- The project is modular – separate modules for CLI, scanning logic, models, and I/O utilities.
- Use clear labeling to emphasize separation of concerns.

- Pipeline Architecture:
- The system follows a pipeline process: starting from user command → configuration/data retrieval → local vulnerability scanning → external API validation → outputting results.

- External Dependency Integration:
- The integration with Invariant Guardrails highlights the use of external API calls as part of the scanning process.
- This dependency clearly to show that the system offloads part of its work to an external service.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input Layer
    subgraph "User Input Layer"
        CLI["CLI (cli.py)"]:::cli
    end

    %% Core Scanning Modules
    subgraph "Core Scanning Modules"
        CONFIG["MCP Server Configurations"]:::config
        MCP["MCPScanner (MCPScanner.py)"]:::engine
        MODELS["Data Models (models.py)"]:::models
        IO["I/O Utilities (surpressIO.py)"]:::io
    end

    %% External Services
    subgraph "External Services"
        API["Invariant Guardrails API (invariantlabs.ai)"]:::external
    end

    %% Versioning & Packaging
    subgraph "Versioning & Packaging"
        VER["Version Info (version.py)"]:::version
        TOML["Build Config (pyproject.toml)"]:::version
        MAKE["Build Script (Makefile)"]:::version
    end

    %% Connections
    CLI -->|"initiates_scan"| MCP
    CONFIG -->|"feeds_config"| MCP
    MCP -->|"processes_data_with"| MODELS
    MCP -->|"manages_output_via"| IO
    MCP -->|"submits_to"| API

    %% Click Events
    click CLI "https://github.com/invariantlabs-ai/mcp-scan/blob/main/src/mcp_scan/cli.py"
    click MCP "https://github.com/invariantlabs-ai/mcp-scan/blob/main/src/mcp_scan/MCPScanner.py"
    click MODELS "https://github.com/invariantlabs-ai/mcp-scan/blob/main/src/mcp_scan/models.py"
    click IO "https://github.com/invariantlabs-ai/mcp-scan/blob/main/src/mcp_scan/surpressIO.py"
    click VER "https://github.com/invariantlabs-ai/mcp-scan/blob/main/src/mcp_scan/version.py"
    click TOML "https://github.com/invariantlabs-ai/mcp-scan/blob/main/pyproject.toml"
    click MAKE "https://github.com/invariantlabs-ai/mcp-scan/tree/main/Makefile"

    %% Styles
    classDef cli fill:#F39C12,stroke:#000,stroke-width:2px;
    classDef engine fill:#3498DB,stroke:#000,stroke-width:2px;
    classDef models fill:#9B59B6,stroke:#000,stroke-width:2px;
    classDef io fill:#1ABC9C,stroke:#000,stroke-width:2px;
    classDef external fill:#E74C3C,stroke:#000,stroke-width:2px;
    classDef config fill:#BDC3C7,stroke:#000,stroke-width:2px;
    classDef version fill:#D35400,stroke:#000,stroke-width:2px;
```
