# andrewwgordon/mcp-chinookdb-server architecture

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

- Interactive diagram: https://gitdiagram.com/andrewwgordon/mcp-chinookdb-server
- Repository: https://github.com/andrewwgordon/mcp-chinookdb-server

## Overview

##### Project type and purpose
- This is a small Python-based client/server tool set—specifically an MCP (Model Context Protocol) server exposing a local SQLite “Chinook” sample database plus a sample “Agno” agent client that drives it using an LLM.
- Purpose: Allow LLMs or interactive CLI clients to safely explore the Chinook database via standardized MCP resource endpoints and SQL-query tools.

##### File structure
- Top-level scripts:
- chinook_mcp_server.py – the MCP server implementation
- agno_test_client.py – a CLI agent client demonstrating LLM-driven queries
- Project metadata: pyproject.toml, uv.lock, .python-version – typical Python packaging and dependency files
- README.md – detailed overview, usage, architecture hints
- No separate “src” or “frontend/backend” directories; the architecture is captured by the two main processes.

##### Additional README insights
- Describes the MCP resource endpoints (schema://… and run_sql_query tool)
- Explains automatic database download/extraction, safe escaping, read-only SELECT enforcement
- Notes Agno agent’s use of OpenAI GPT-4 (or other LLMs) and REPL interface
- States STDIO transport by default

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Side
    subgraph "Client Side"
        User["User (CLI)"]:::client
        Agno["Agno Test Client"]:::client
    end

    %% External LLM and DB
    LLM["LLM Service\n(OpenAI API)"]:::external
    DB["Chinook SQLite Database"]:::external

    %% Server Side
    subgraph "Server Side"
        MCP["MCP Server"]:::server
        subgraph "Resources & Tools"
            Schema["Schema Endpoint"]:::server
            SQL["SQL Query Tool"]:::server
            Escape["Safe-Escaping Logic\n(SELECT only)"]:::server
        end
    end

    %% Project Configuration Files
    subgraph "Project Configurations"
        README["README.md"]:::external
        Pyproj["pyproject.toml"]:::external
        Lock["uv.lock"]:::external
        Pyver[".python-version"]:::external
    end

    %% Connections and Data Flows
    User -->|"1. Input NL Query"| Agno
    Agno -->|"2. Send Prompt"| LLM
    LLM -->|"3. Return Parsed Instructions"| Agno
    Agno -->|"4. Launch via STDIO"| MCP
    Agno -->|"5. MCP Request\n(schema or run_sql_query)"| MCP
    MCP -->|"6a. Handle schema"| Schema
    MCP -->|"6b. Handle run_sql_query"| SQL
    SQL -->|"7. Apply Safe-Escaping"| Escape
    Escape -->|"8. Read-Only SELECT"| DB
    MCP -->|"9. MCP Response"| Agno
    Agno -->|"10. Present Results"| User

    %% Click Events
    click Agno "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/agno_test_client.py"
    click MCP "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/chinook_mcp_server.py"
    click README "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/README.md"
    click Pyproj "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/pyproject.toml"
    click Lock "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/uv.lock"
    click Pyver "https://github.com/andrewwgordon/mcp-chinookdb-server/blob/main/.python-version"

    %% Styles
    classDef client fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef server fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
