How ajtazer/zap-mcp works
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.