# dtkmn/mcp-zap-server architecture

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

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

## Overview

MCP ZAP Server provides an MCP-over-HTTP interface for agent-directed, operator-controlled ZAP security workflows. The principal journey is a client invoking guided tools, with queued scans progressing through ZAP and results available as findings, reports, and scan history. Authentication, authorization, policy enforcement, and operational guardrails constrain tool use. The README documents the product capabilities; sampled source confirms queue persistence and several internal service relationships, but not all tool-to-service wiring, so uncertain links are omitted or marked unverified.

Main entry points: [`src/main/java/mcp/server/zap/core/service/GuidedSecurityToolsService.java`](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/GuidedSecurityToolsService.java) (Guided Tool Catalog), [`src/main/java/mcp/server/zap/McpServerApplication.java`](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/McpServerApplication.java) (MCP Server), [`src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java`](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java) (Scan Job Queue), [`src/main/java/mcp/server/zap/core/gateway/ZapEngineAdapter.java`](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/gateway/ZapEngineAdapter.java) (ZAP Engine Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["MCP Interface"]
  node_server["MCP Server"]
  node_guided["Guided Tool Catalog"]
  node_authsetup["Guided Auth Setup"]
end

subgraph group_scanning["Scanning Operations"]
  node_queue["Scan Job Queue"]
  node_scanjobs["Scan Job State<br/>[ScanJob.java]"]
  node_active["Active Scans"]
  node_spiders["Spider Scans"]
  node_ajaxclient["AJAX and Client Spiders"]
  node_passive["Passive Analysis"]
  node_apiimport["API Imports"]
end

subgraph group_results["Evidence and Results"]
  node_findings["Findings"]
  node_reports["Reports<br/>[ReportService.java]"]
  node_history["Scan History"]
end

subgraph group_control["Access and Guardrails"]
  node_auth["Authentication"]
  node_authorization["Tool Authorization"]
  node_policy["Runtime Policy"]
  node_protection["Abuse Protection"]
  node_observability["Audit and Metrics"]
end

subgraph group_platform["Engine and State"]
  node_engine["ZAP Engine Gateway"]
  node_jobstore[("Job Store<br/>[ScanJobStore.java]")]
  node_historydb[("History Store")]
end

node_client(("MCP Client"))

node_client -->|"invokes tools"| node_server
node_server -.->|"exposes catalog"| node_guided
node_guided -.->|"queues scans"| node_queue
node_guided -->|"requests findings"| node_findings
node_guided -->|"requests reports"| node_reports
node_guided -->|"requests history"| node_history
node_guided -->|"imports APIs"| node_apiimport
node_guided -->|"requests analysis"| node_passive
node_guided -->|"sets up auth"| node_authsetup
node_queue -->|"manages jobs"| node_scanjobs
node_queue -->|"persists jobs"| node_jobstore
node_queue -.->|"dispatches scans"| node_engine
node_guided -->|"starts scans"| node_active
node_guided -->|"starts scans"| node_spiders
node_guided -->|"starts scans"| node_ajaxclient
node_history -.->|"stores entries"| node_historydb
node_server -->|"authenticates requests"| node_auth
node_server -->|"checks tool scopes"| node_authorization
node_server -->|"enforces policy"| node_policy
node_server -->|"applies guardrails"| node_protection
node_server -->|"records audit events"| node_observability
node_findings -.->|"reads findings"| node_engine
node_reports -.->|"generates reports"| node_engine

click node_server "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/McpServerApplication.java"
click node_guided "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/GuidedSecurityToolsService.java"
click node_authsetup "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/GuidedAuthSessionMcpToolsService.java"
click node_queue "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java"
click node_scanjobs "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/model/ScanJob.java"
click node_active "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ActiveScanService.java"
click node_spiders "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/SpiderScanService.java"
click node_ajaxclient "https://github.com/dtkmn/mcp-zap-server/tree/main/src/main/java/mcp/server/zap/core/service"
click node_passive "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/PassiveScanService.java"
click node_apiimport "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/OpenApiService.java"
click node_findings "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/FindingsService.java"
click node_reports "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ReportService.java"
click node_history "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/history/ScanHistoryLedgerService.java"
click node_auth "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/controller/AuthController.java"
click node_authorization "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/authz/ToolAuthorizationService.java"
click node_policy "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/policy/ToolExecutionPolicyService.java"
click node_protection "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/protection/McpAbuseProtectionService.java"
click node_observability "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/observability/ObservabilityService.java"
click node_engine "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/gateway/ZapEngineAdapter.java"
click node_jobstore "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/jobstore/ScanJobStore.java"
click node_historydb "https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/history/ScanHistoryStore.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_guided,node_authsetup,node_client toneBlue
class node_queue,node_scanjobs,node_active,node_spiders,node_ajaxclient,node_passive,node_apiimport toneAmber
class node_findings,node_reports,node_history toneMint
class node_auth,node_authorization,node_policy,node_protection,node_observability toneRose
class node_engine,node_jobstore,node_historydb toneIndigo
```

## Components

### MCP Interface

- [MCP Server](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/McpServerApplication.java): `src/main/java/mcp/server/zap/McpServerApplication.java`
- [Guided Tool Catalog](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/GuidedSecurityToolsService.java): `src/main/java/mcp/server/zap/core/service/GuidedSecurityToolsService.java`
- [Guided Auth Setup](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/GuidedAuthSessionMcpToolsService.java): `src/main/java/mcp/server/zap/core/service/GuidedAuthSessionMcpToolsService.java`

### Scanning Operations

- [Scan Job Queue](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java): `src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java`
- [Scan Job State](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/model/ScanJob.java): `src/main/java/mcp/server/zap/core/model/ScanJob.java`
- [Active Scans](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ActiveScanService.java): `src/main/java/mcp/server/zap/core/service/ActiveScanService.java`
- [Spider Scans](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/SpiderScanService.java): `src/main/java/mcp/server/zap/core/service/SpiderScanService.java`
- [AJAX and Client Spiders](https://github.com/dtkmn/mcp-zap-server/tree/main/src/main/java/mcp/server/zap/core/service): `src/main/java/mcp/server/zap/core/service`
- [Passive Analysis](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/PassiveScanService.java): `src/main/java/mcp/server/zap/core/service/PassiveScanService.java`
- [API Imports](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/OpenApiService.java): `src/main/java/mcp/server/zap/core/service/OpenApiService.java`

### Evidence and Results

- [Findings](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/FindingsService.java): `src/main/java/mcp/server/zap/core/service/FindingsService.java`
- [Reports](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/ReportService.java): `src/main/java/mcp/server/zap/core/service/ReportService.java`
- [Scan History](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/history/ScanHistoryLedgerService.java): `src/main/java/mcp/server/zap/core/history/ScanHistoryLedgerService.java`

### Access and Guardrails

- [Authentication](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/controller/AuthController.java): `src/main/java/mcp/server/zap/core/controller/AuthController.java`
- [Tool Authorization](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/authz/ToolAuthorizationService.java): `src/main/java/mcp/server/zap/core/service/authz/ToolAuthorizationService.java`
- [Runtime Policy](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/policy/ToolExecutionPolicyService.java): `src/main/java/mcp/server/zap/core/service/policy/ToolExecutionPolicyService.java`
- [Abuse Protection](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/protection/McpAbuseProtectionService.java): `src/main/java/mcp/server/zap/core/service/protection/McpAbuseProtectionService.java`
- [Audit and Metrics](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/observability/ObservabilityService.java): `src/main/java/mcp/server/zap/core/observability/ObservabilityService.java`

### Engine and State

- [ZAP Engine Gateway](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/gateway/ZapEngineAdapter.java): `src/main/java/mcp/server/zap/core/gateway/ZapEngineAdapter.java`
- [Job Store](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/service/jobstore/ScanJobStore.java): `src/main/java/mcp/server/zap/core/service/jobstore/ScanJobStore.java`
- [History Store](https://github.com/dtkmn/mcp-zap-server/blob/main/src/main/java/mcp/server/zap/core/history/ScanHistoryStore.java): `src/main/java/mcp/server/zap/core/history/ScanHistoryStore.java`

### Other components

- **MCP Client**

## Connections

- MCP Client → MCP Server: invokes tools (evidence: `README.md`)
- MCP Server → Guided Tool Catalog: exposes catalog
- Guided Tool Catalog → Scan Job Queue: queues scans
- Guided Tool Catalog → Findings: requests findings (evidence: `README.md`)
- Guided Tool Catalog → Reports: requests reports (evidence: `README.md`)
- Guided Tool Catalog → Scan History: requests history (evidence: `README.md`)
- Guided Tool Catalog → API Imports: imports APIs (evidence: `README.md`)
- Guided Tool Catalog → Passive Analysis: requests analysis (evidence: `README.md`)
- Guided Tool Catalog → Guided Auth Setup: sets up auth (evidence: `README.md`)
- Scan Job Queue → Scan Job State: manages jobs (evidence: `src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java`)
- Scan Job Queue → Job Store: persists jobs (evidence: `src/main/java/mcp/server/zap/core/service/ScanJobQueueService.java`)
- Scan Job Queue → ZAP Engine Gateway: dispatches scans
- Guided Tool Catalog → Active Scans: starts scans (evidence: `README.md`)
- Guided Tool Catalog → Spider Scans: starts scans (evidence: `README.md`)
- Guided Tool Catalog → AJAX and Client Spiders: starts scans (evidence: `README.md`)
- Scan History → History Store: stores entries (evidence: `src/main/java/mcp/server/zap/core/history/ScanHistoryLedgerService.java`)
- MCP Server → Authentication: authenticates requests (evidence: `README.md`)
- MCP Server → Tool Authorization: checks tool scopes (evidence: `README.md`)
- MCP Server → Runtime Policy: enforces policy (evidence: `README.md`)
- MCP Server → Abuse Protection: applies guardrails (evidence: `README.md`)
- MCP Server → Audit and Metrics: records audit events (evidence: `README.md`)
- Findings → ZAP Engine Gateway: reads findings
- Reports → ZAP Engine Gateway: generates reports