# xoniks/mcp-visualization-duckdb architecture

> Architecture diagram of the GitHub repository xoniks/mcp-visualization-duckdb, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xoniks/mcp-visualization-duckdb
- Repository: https://github.com/xoniks/mcp-visualization-duckdb

## Overview

##### 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/).

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        Claude["Claude Desktop"]:::external
    end

    %% Protocol & Launcher Layer
    subgraph "Protocol & Launcher Layer"
        Launcher["mcp_server.py"]:::internal
        subgraph "MCP Protocol (code/mcp_server)"
            Server["server.py"]:::internal
            Handlers["handlers.py"]:::internal
            Tools["tools.py"]:::internal
            Types["types.py"]:::internal
        end
    end

    %% Application Core Layer
    subgraph "Application Core Layer"
        Main["main.py"]:::internal
    end

    %% Configuration Layer
    subgraph "Configuration Layer"
        Settings["settings.py"]:::internal
        ConfigYAML["config.yaml"]:::internal
    end

    %% Database Layer
    subgraph "Database Layer"
        DBManager["manager.py"]:::internal
        Queries["queries.py"]:::internal
        DuckDB["DuckDB Storage"]:::data
        Samples["Sample CSVs"]:::data
    end

    %% LLM Layer
    subgraph "LLM Layer"
        OllamaClient["ollama_client.py"]:::internal
        Prompts["prompts.py"]:::internal
        OllamaService["Ollama Service"]:::external
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        ChartGen["chart_generator.py"]:::internal
        ChartTypes["chart_types.py"]:::internal
        Insights["insights.py"]:::internal
    end

    %% Utilities Layer
    subgraph "Utilities Layer"
        Logger["logger.py"]:::util
        Validators["validators.py"]:::util
    end

    %% Scripting & Testing
    subgraph "Scripting & Testing"
        Script["create_sample_db.py"]:::util
        DBTest["test_database.py"]:::test
        LLMTest["test_llm.py"]:::test
        VizTest["test_visualization.py"]:::test
    end

    %% Relationships
    Claude -->|"MCP messages"| Launcher
    Launcher -->|"starts"| Server
    Server -->|"routes"| Handlers
    Server -->|"MCP request"| Main
    Main -->|"loads config"| Settings
    Settings --> ConfigYAML
    Main -->|"uses"| DBManager
    DBManager --> Queries
    DBManager -->|"reads/writes"| DuckDB
    DBManager -->|"loads CSV"| Samples
    Main -->|"uses"| OllamaClient
    OllamaClient --> Prompts
    OllamaClient -->|"HTTP requests"| OllamaService
    Main -->|"uses"| ChartGen
    ChartGen --> ChartTypes
    ChartGen --> Insights
    Main -->|"uses"| Logger
    Main -->|"uses"| Validators
    Script --> Samples
    DBTest --> DBManager
    LLMTest --> OllamaClient
    VizTest --> ChartGen

    %% Click Events
    click Launcher "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/mcp_server.py"
    click Server "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/mcp_server/server.py"
    click Handlers "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/mcp_server/handlers.py"
    click Tools "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/mcp_server/tools.py"
    click Types "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/mcp_server/types.py"
    click Main "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/main.py"
    click Settings "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/config/settings.py"
    click ConfigYAML "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/config/config.yaml"
    click DBManager "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/database/manager.py"
    click Queries "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/database/queries.py"
    click DuckDB "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/data/mcp.duckdb"
    click Samples "https://github.com/xoniks/mcp-visualization-duckdb/tree/main/data/samples"
    click OllamaClient "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/llm/ollama_client.py"
    click Prompts "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/llm/prompts.py"
    click ChartGen "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/visualization/chart_generator.py"
    click ChartTypes "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/visualization/chart_types.py"
    click Insights "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/visualization/insights.py"
    click Logger "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/utils/logger.py"
    click Validators "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/code/utils/validators.py"
    click Script "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/scripts/create_sample_db.py"
    click DBTest "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/tests/test_database.py"
    click LLMTest "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/tests/test_llm.py"
    click VizTest "https://github.com/xoniks/mcp-visualization-duckdb/blob/main/tests/test_visualization.py"

    %% Styles
    classDef internal fill:#cfe2f3,stroke:#036;
    classDef data fill:#d9ead3,stroke:#387;
    classDef external fill:#fce5cd,stroke:#f60;
    classDef util fill:#fff2cc,stroke:#aa0;
    classDef test fill:#ead1dc,stroke:#a00;
```
