MCP Tool & Browser Execution Plane
The vg-mcp-orchestrator microservice provides a dual-plane execution engine running on Node.js 22 with headless Chromium, Puppeteer, Playwright, and programmatic container dispatch.
1. Dual-Plane Service Architecture
Inside vg-mcp-orchestrator, two isolated execution services operate concurrently:
| Plane | Logical Service | Primary Responsibilities |
|---|---|---|
| Plane 1: Security Tool & Puppeteer MCP Server | mcp-tool-server | Dispatches containerized security tools (nmap, nuclei, subfinder, ffuf, katana, testssl, gitleaks, sqlmap, wpscan, zap, trivy, metasploit, beef, set) via the scoped runtime proxy and performs headless Puppeteer web analysis. |
| Plane 2: Playwright Browser Automation Server | mcp-playwright-server | Provides deterministic headless Chromium DOM snapshots, interactive form testing, and visual verification for modern SPAs. |
2. Tool Execution Contract (POST /tools/execute)
When SecurityAgent or the direct Tool Execution API dispatches a tool run, the MCP server validates the tool identifier, normalizes target parameters, and executes the tool inside its dedicated sibling worker container:
Example Request Payload
{
"tool": "nuclei",
"params": {
"target": "https://target.example.com",
"scan_id": "scan_example_01",
"result_path": "<artifact_dir>/scan_example_01_nuclei.json"
}
}
Worker Mapping & Automatic Artifact Routing
Both synchronous execution (/tools/execute) and streaming execution (/tools/stream) automatically assign deterministic artifact paths whenever a scan_id is supplied:
| Tool Key | Target Worker Sandbox | Auto-Generated Artifact Format |
|---|---|---|
nmap | vg-worker-nmap | <scan_id>_nmap.xml |
nuclei | vg-worker-nuclei | <scan_id>_nuclei.json |
subfinder | vg-worker-subfinder | <scan_id>_subfinder.json |
ffuf | vg-worker-ffuf | <scan_id>_ffuf.json |
katana | vg-worker-katana | <scan_id>_katana.json |
testssl | vg-worker-testssl | <scan_id>_testssl.json |
gitleaks | vg-worker-gitleaks | <scan_id>_gitleaks.json |
wpscan | vg-worker-wpscan | <scan_id>_wpscan.json |
trivy | vg-worker-trivy | <scan_id>_trivy.json |
3. Demuxing Container Exec Streams
When attaching to a worker container exec stream, the container runtime multiplexes stdout (stream type 1) and stderr (stream type 2) frames with an 8-byte binary header ([stream_type, 0, 0, 0, size_b1, size_b2, size_b3, size_b4]).
The MCP server's stream demultiplexer strips these 8-byte frame headers in real time, enforces per-tool execution timeouts (300s–900s), and returns clean UTF-8 stdout and stderr buffers to the caller.