# marlonluo2018/pandas-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/marlonluo2018/pandas-mcp-server
- Repository: https://github.com/marlonluo2018/pandas-mcp-server

## Overview

##### Project type and purpose
- This is a Python-based MCP (Model Context Protocol) server that exposes Pandas data-processing and Chart.js chart-generation functions over a stdio interface.
- Its primary use case is to let an MCP client load CSV metadata, execute arbitrary (but sandboxed) Pandas code, and produce interactive bar, pie, and line charts as standalone HTML files.

##### File structure
Top-level files and folders:
- server.py – entry point and MCP server loop
- requirements.txt – external libraries (pandas, chardet, MCP toolkit, etc.)
- metadata_test.py, test_charts.py – unit tests covering read_metadata and chart-generation functions
- templates/ – Chart.js HTML templates (barchart_template, piechart_template, linechart_template)
Patterns and conventions:
- Single-process, modular design: server.py dispatches to handler functions
- Templates folder holds static HTML with placeholders for dynamic data
- Tests mirror production modules for coverage and regression checking

##### README for additional insights
- Describes four core services:
– read_metadata: CSV introspection (auto-detect encoding/delimiter)
– run_pandas_code: sandboxed execution of user-supplied Pandas snippets
– bar_chart_to_html / pie_chart_to_html / line_chart_to_html: inject data into Chart.js templates, write HTML
- Workflow: MCP client → stdio → server.py → appropriate handler → JSON response (plus file‐path for charts)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Protocol / Transport Layer
    subgraph "Protocol / Transport Layer"
        direction TB
        client["MCP Client"]:::protocol
        transport["STDIO Transport\n(stdin/stdout JSON)"]:::protocol
    end
    client -->|"JSON Request"| transport
    transport -->|"JSON"| dispatcher

    %% Server Process and Core Modules
    subgraph "MCP Server Process"
        direction TB
        dispatcher["Dispatcher"]:::core
        metadata["Metadata Handler\n(read_metadata)"]:::core
        executor["Code Executor\n(run_pandas_code)\n[Sandbox Filter]"]:::core
        barGen["Bar Chart Generator\n(bar_chart_to_html)"]:::core
        pieGen["Pie Chart Generator\n(pie_chart_to_html)"]:::core
        lineGen["Line Chart Generator\n(line_chart_to_html)"]:::core
        template["Template Engine"]:::io
        fsIO["File System I/O\n(CSV Read / HTML Write)"]:::io
    end
    transport --> dispatcher
    dispatcher -->|"metadata"| metadata
    dispatcher -->|"code"| executor
    dispatcher -->|"bar chart"| barGen
    dispatcher -->|"pie chart"| pieGen
    dispatcher -->|"line chart"| lineGen
    metadata --> fsIO
    executor --> fsIO
    barGen --> template
    pieGen --> template
    lineGen --> template
    template --> fsIO
    fsIO -->|"HTML Response"| transport

    %% External Dependencies and Config
    subgraph "External Config & Dependencies"
        direction TB
        readme["Project Overview\n(README.md)"]:::external
        requirements["Dependencies List\n(requirements.txt)"]:::external
        pandas["pandas"]:::external
        chardet["chardet"]:::external
        mcpLib["MCP Framework"]:::external
        chartjs["Chart.js Templates"]:::external
    end
    requirements --> pandas
    requirements --> chardet
    requirements --> mcpLib
    template -.-> chartjs
    readme -.-> dispatcher

    %% Unit Tests
    subgraph "Unit Test Suite"
        direction TB
        testMeta["metadata_test.py"]:::test
        testCharts["test_charts.py"]:::test
    end
    testMeta --> metadata
    testCharts --> barGen
    testCharts --> pieGen
    testCharts --> lineGen

    %% Click Events
    click dispatcher "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click metadata "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click executor "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click barGen "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click pieGen "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click lineGen "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click template "https://github.com/marlonluo2018/pandas-mcp-server/tree/main/templates/"
    click fsIO "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/server.py"
    click testMeta "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/metadata_test.py"
    click testCharts "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/test_charts.py"
    click requirements "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/requirements.txt"
    click readme "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/README.md"
    click pandas "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/requirements.txt"
    click chardet "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/requirements.txt"
    click mcpLib "https://github.com/marlonluo2018/pandas-mcp-server/blob/main/requirements.txt"
    click chartjs "https://github.com/marlonluo2018/pandas-mcp-server/tree/main/templates/"

    %% Styles
    classDef protocol fill:#dddddd,stroke:#888888,stroke-width:1px
    classDef core fill:#bbdefb,stroke:#1976d2,stroke-width:1px
    classDef io fill:#c8e6c9,stroke:#388e3c,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#ef6c00,stroke-width:1px
    classDef test fill:#e1bee7,stroke:#8e24aa,stroke-width:1px
```
