How eth-ivia-lab/vacp works
VACP is an in-app protocol that lets AI agents inspect visual-analytics capabilities and state, then invoke semantic actions that update the interface. The repository supplies protocol/runtime primitives, visualization-provider adapters, agent transports, and debugging tools; it also includes a separate agent-evaluation suite. The graph emphasizes the documented agent-to-visualization workflow and sampled evaluation flow. Some provider and UI wiring is unsampled, so unsupported implementation-level connections are omitted.
Main entry points: cli.ts Arena CLI · create-runtime-bridge.ts Runtime Bridge · main.py MCP Server Entry · server.py MCP Tools
Components 20
Protocol Runtime
- Protocol Contract
packages/lib/protocol/core/src/schema.ts - Runtime Bridge
packages/lib/protocol/gateway/src/runtime/create-runtime-bridge.ts - DOM Snapshot
packages/lib/protocol/gateway/src/dom-snapshot.ts - DuckDB Client
packages/lib/protocol/duckdb/src/client.ts
Visualization Providers
- Vega-Lite Adapter
packages/lib/providers/vega-lite/src/duckdb-handle.ts - vgplot Actions
packages/lib/providers/vgplot/src/actions.ts
Agent Transports
- Agent Client
packages/lib/transports/agent-client/src/create-llm-model.ts - MCP Server Entry
packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py - MCP Tools
packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py - Browser Bridge Client
packages/lib/transports/mcp-server/src/vacp_mcp_server/bridge.py - Browser Control
packages/lib/transports/mcp-server/src/vacp_mcp_server/browser.py
Developer Tooling
- Debug Overlay
packages/lib/tooling/debug-ui/src/overlay/debug-ui-view.tsx - Analytics Runtime
packages/lib/tooling/analytics/src/runtime.ts
Evaluation Suite
- Arena CLI
packages/lib/evaluation/agent-arena/src/cli.ts - Scenario Runner
packages/lib/evaluation/agent-arena/src/runner/run.ts - Session Export
packages/lib/evaluation/agent-arena/src/logs/export-session.ts - Run Analysis
packages/lib/evaluation/agent-arena/src/analyze/analyze-run.ts - Report Generation
packages/lib/evaluation/agent-arena/src/report/render-html.ts - Plain MCP Runtime
packages/lib/evaluation/plain-mcp/src/plain_mcp/runtime.py
Other components
- AI Agent
Connections 14
- AI Agent → Protocol Contract: uses contract
README.md - AI Agent → Runtime Bridge: reads state
README.md - AI Agent → Runtime Bridge: executes actions
README.md - Runtime Bridge → DOM Snapshot: snapshots DOM
packages/lib/protocol/gateway/src/dom-snapshot.ts - Vega-Lite Adapter → DuckDB Client: uses queries
packages/lib/providers/vega-lite/src/duckdb-handle.ts - vgplot Actions → DuckDB Client: uses selection
packages/lib/providers/vgplot/src/actions.ts - MCP Server Entry → MCP Tools: creates server
packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py - MCP Tools → Browser Bridge Client: calls bridge
packages/lib/transports/mcp-server/src/vacp_mcp_server/server.py - MCP Server Entry → Browser Control: controls browser
packages/lib/transports/mcp-server/src/vacp_mcp_server/main.py - Arena CLI → Scenario Runner: starts runs
packages/lib/evaluation/agent-arena/src/cli.ts - Arena CLI → Session Export: exports sessions
packages/lib/evaluation/agent-arena/src/cli.ts - Arena CLI → Run Analysis: analyzes runs
packages/lib/evaluation/agent-arena/src/cli.ts - Run Analysis → Report Generation: feeds analysis
- Plain MCP Runtime → Browser Control: uses browser
packages/lib/evaluation/plain-mcp/src/plain_mcp/main.py