# ajtazer/zap-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/ajtazer/zap-mcp
- Repository: https://github.com/ajtazer/zap-mcp

## Overview

##### Project Type & Purpose
- This is a full-stack integration project that exposes ZAP’s scanning capabilities to AI models via a server component. The MCP server (found in packages like “mcp” and “zap_mcp”) provides APIs, services, and a WebSocket interface for real-time interactions.
- The project mixes a client–server architecture with a clearly delineated service layer, aimed at enabling AI-driven security testing.

##### Analyzing the File Structure
- Top-level configuration and setup files (such as .env, setup scripts, and the claude_desktop_config.json) provide initial configuration and deployment instructions.
- There are two main Python packages:
- The “mcp” package and related server scripts (mcp_server.py, setup.py) that handle the Model Context Protocol server functionality.
- The “zap_mcp” package that contains several subdirectories:
▪ api – For routing and exposing endpoints.
▪ core – Housing core business logic (authentication, configuration, and integration with MCP).
▪ models – Likely representing data structures for scans.
▪ services – Implementing essential functionalities like the “claude_service” and “zap_service” which encapsulate the integration logic with ZAP and the AI client.
▪ templates – Used for HTML output, perhaps for a basic UI or status page.
- Utility files (run.py, run_servers.sh, setup scripts) indicate multiple entry points, suggesting both development and production modes.
- There’s integration to an external tool (OWASP ZAP) and an external client (Claude Desktop App).

a. Main Components to Include:
- MCP Server: Represented by the Python entry scripts (mcp-server, run.py, etc.).
- API Layer: The “zap_mcp/api” package which defines routes for incoming requests.
- Core Services: The “zap_mcp/core” and “zap_mcp/services” components, which house the business logic, including service modules (i.e., zap_service and claude_service) that mediate interactions with ZAP and with the AI client.
- External Integrations:
- OWASP ZAP: The security testing tool that is called via its API.
- Claude Desktop App (or any MCP-compatible client): Consumes the MCP services.
- Configuration & Environment: Configuration files (claude_desktop_config.json, .env) that inform how the system is initialized and how external systems are reached.

b. Relationships and Interactions:
- The Claude Desktop App communicates with the MCP Server over WebSocket (ws://localhost:7456/ws) to request scanning services.
- The MCP Server relays commands via designated API endpoints (exposed in “zap_mcp/api/routes.py”) and calls underlying services in “zap_mcp/services”.
- These services then interact with OWASP ZAP (using the provided API key and URL from the config) to start scans, fetch alerts, and get scan summaries.
- The system may utilize internal modules (in “mcp” and “zap_mcp/core”) for authentication, configuration management, and response formatting.

c. Architectural Patterns & Design Principles:
- Client-server architecture with clear abstraction: API layer isolates client interactions from internal service logic.
- Modularity is clear with separate directories for API, core logic, services, and models.
- Real-time communication is achieved via WebSocket connections for monitoring and alerts.
- Separation of concerns: configuration, service logic, and routing are located in their respective modules.

d. Relevant Technologies, Frameworks, and Libraries:
- Python 3.8+ serves as the primary runtime.
- OWASP ZAP is integrated as an external dependency for security testing.
- WebSocket communication is employed, as evidenced by configuration details.
- The project leverages standard Python packaging practices, and build/configuration tools like setup.py and requirements.txt ensure dependency management.

##### Final Recommendations
- Flow of data: requests coming in from the client, service calls being made to OWASP ZAP, and the result flow back to the client.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layer
    subgraph "Client Layer"
        A["Claude Desktop App"]:::external
        B["Client Integration"]:::client
    end

    %% Configuration
    I["Configuration (.env)"]:::config
    J["Claude Config"]:::config

    %% Backend System
    subgraph "Backend"
        C["MCP Server"]:::server
        D["API Layer"]:::server
        E["Core Business Logic & Config"]:::core
        subgraph "Services"
            F1["zap_service"]:::service
            F2["claude_service"]:::service
        end
        G["Data Models"]:::core
    end

    %% External Integration
    H["OWASP ZAP"]:::external

    %% Flow Connections
    A -->|"WebSocketAPICall"| C
    B -->|"APICall"| C
    C -->|"RoutesRequest"| D
    D -->|"DelegatesProcessing"| E
    E -->|"CallsServices"| F1
    E -->|"CallsServices"| F2
    F1 -->|"RESTAPICall"| H
    F2 -->|"RESTAPICall"| H
    E -->|"UsesDataModel"| G

    %% Configuration influences
    I --> C
    I --> E
    J --> C
    J --> E

    %% Styling Classes
    classDef external fill:#AEDFF7,stroke:#1F78C1,stroke-width:2px;
    classDef server fill:#C3FDB8,stroke:#79BD8F,stroke-width:2px;
    classDef core fill:#FDE9A9,stroke:#FDB813,stroke-width:2px;
    classDef service fill:#F9D57A,stroke:#E6952E,stroke-width:2px;
    classDef config fill:#D3CCE3,stroke:#6D5B98,stroke-width:2px;
    classDef client fill:#FFB6C1,stroke:#C71585,stroke-width:2px;

    %% Click Events
    click C "https://github.com/ajtazer/zap-mcp/blob/main/mcp/mcp_server.py"
    click D "https://github.com/ajtazer/zap-mcp/blob/main/zap_mcp/api/routes.py"
    click E "https://github.com/ajtazer/zap-mcp/tree/main/zap_mcp/core"
    click F1 "https://github.com/ajtazer/zap-mcp/blob/main/zap_mcp/services/zap_service.py"
    click F2 "https://github.com/ajtazer/zap-mcp/blob/main/zap_mcp/services/claude_service.py"
    click G "https://github.com/ajtazer/zap-mcp/blob/main/zap_mcp/models/mcp.py"
    click I "https://github.com/ajtazer/zap-mcp/blob/main/.env"
    click J "https://github.com/ajtazer/zap-mcp/blob/main/claude_desktop_config.json"
    click B "https://github.com/ajtazer/zap-mcp/blob/main/claude_integration.py"
```
