How xoniks/mcp-visualization-duckdb works
Main Components
a. Client Layer
• Claude Desktop (external client) – sends/receives MCP messages via stdin/stdout.
b. Protocol & Launcher Layer
• mcp_server.py – launcher script that sets up the environment and starts the MCP server.
• code/mcp_server/ – implements the MCP protocol: server.py (core server loop), handlers.py (message routing), tools.py/types.py (request definitions).
c. Application Core Layer
• code/main.py – application entrypoint, orchestrates startup, loads config, initializes sub‐systems.
d. Configuration Layer
• code/config/settings.py & config.yaml – layered config (env vars → YAML → CLI).
e. Database Layer
• code/database/manager.py – DatabaseManager wraps DuckDB connections.
• code/database/queries.py – predefined queries.
• data/mcp.duckdb & data/samples – persistent DuckDB file and sample CSVs.
f. LLM Layer
• code/llm/ollama_client.py – HTTP client to Ollama local LLM.
• code/llm/prompts.py – prompt templates.
• External Ollama service (http://localhost:11434).
g. Visualization Layer
• code/visualization/chart_generator.py – builds Plotly charts and HTML widgets.
• code/visualization/insights.py & chart_types.py – analysis and chart‐type definitions.
h. Utilities Layer
• code/utils/logger.py – logging.
• code/utils/validators.py – input & SQL‐injection protection.
i. Scripting & Testing
• scripts/create_sample_db.py – helper to generate sample data.
• tests/ – unit tests for database, LLM, and visualization modules.
Relationships & Data Flows
1. Claude Desktop → mcp_server.py: launches and pipes messages.
2. mcp_server.py → code/main: initializes configuration and spawns MCP server.
3. MCP server (code/mcp_server/server.py) listens for JSON requests from Claude.
4. Incoming request → handlers.py →
• DatabaseManager → DuckDB (queries or load CSV) → returns result.
• OllamaClient → Ollama service → returns LLM response.
• ChartGenerator → takes data + chart config → outputs HTML + insight text.
5. Handlers assemble the response → return to Claude Desktop over MCP protocol.
Architectural Patterns & Principles
• Layered architecture: protocol, application logic, adapters (DB, LLM, viz), utilities.
• Modular design: each folder is a single responsibility.
• Dependency injection via config module and environment variables.
• Security-first: validators sit between incoming request and DB.
• Extensibility: new chart types or LL models drop into respective folder.
Final Touches
– Add a note on environment configuration order (env vars → YAML → CLI).
– Optionally, show test harness outside the main flow (tests/ and scripts/).