# saisharan0103/excel-mcp-server_v2 architecture

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

- Interactive diagram: https://gitdiagram.com/saisharan0103/excel-mcp-server_v2
- Repository: https://github.com/saisharan0103/excel-mcp-server_v2

## Overview

##### Project Type & Purpose
- This is an open-source, Python-based MCP (Model Context Protocol) server.
- It exposes Excel-manipulation tools over two transports:
– stdio (stdin/stdout) for local, tool-embedded usage
– SSE (HTTP Server-Sent Events) for remote/HTTP usage
- Clients (AI agents or other MCP-aware tools) issue commands (create/read/modify Excel files) and receive structured responses.

##### File Structure
- Top-level: build scripts, CI/CD (.github/workflows), packaging (pyproject.toml), documentation (README.md, TOOLS.md), assets (logo).
- src/excel_mcp/: core Python package subdivided into:
– __main__.py: CLI entrypoint (“excel-mcp-server”)
– server.py: transport & MCP request dispatcher
– data.py, workbook.py, sheet.py, cell_utils.py: core data structures & helpers
– formatting.py, chart.py, pivot.py, calculations.py: domain logic modules
– validation.py, exceptions.py: input validation & error handling

##### README Insights
- Describes two transport modes (stdio vs. SSE)
- Environment variables: EXCEL_FILES_PATH (where files live), FASTMCP_PORT (SSE port)
- Usage patterns: invoked via “uvx excel-mcp-server <transport>” or via HTTP URL

##### Main Components & Their Interactions
a. Client(s): AI agent or MCP-aware tool
b. Transport Layer:
– StdioTransport: reads commands from stdin, writes responses to stdout
– SSETransport: HTTP endpoints (FastMCP over SSE)
c. MCP Server (server.py):
– Parses MCP requests → routes to tool handlers
d. Tool Handlers / Domain Modules:
– Workbook Management (workbook.py)
– Worksheet & Range Utilities (sheet.py, cell_utils.py)
– Data I/O (data.py)
– Formatting & Styles (formatting.py)
– Charts & Visualizations (chart.py)
– Pivot Tables (pivot.py)
– Calculations (calculations.py)
– Validation & Exceptions (validation.py, exceptions.py)
e. File System / Storage: reads/writes .xlsx files in EXCEL_FILES_PATH or client-supplied paths
f. Configuration & Runtime:
– Environment variables
– Python runtime & dependencies (pyproject.toml)
g. CI/CD & Packaging: GitHub Actions → publish to PyPI

##### Architectural Patterns & Design Principles
- Modular separation by domain (each Excel feature in its own module)
- Clear transport-handler-domain layering (akin to MVC: Transport → Controller (server.py) → Model (domain modules))
- Environment-driven configuration for portability (12-factor style)
- Single microservice exposing two interchangeable transport modes

##### How to Represent This
– Use a layered layout, top→down or left→right:
1. Clients (left)
2. Transports (next)
3. MCP Server / Dispatcher
4. Domain Modules
5. File System / Storage (right or bottom)
6. Config & Env (annotated)
- From Client → Transport
- From Transport → Server Dispatcher
- from Dispatcher → Domain Modules (each call flows to the appropriate module)
- From Domain Modules → File System (read/write)
– Indicate the packaging/CI path (GitHub → PyPI) in a corner or as an external pipeline for completeness

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["AI Client / MCP Tool"]:::external

    %% CLI Entry Point
    CLI["CLI Entry Point (__main__.py)"]:::internal

    %% Transports
    STDIO["stdio Transport"]:::internal
    SSE["SSE Transport (HTTP)"]:::internal

    %% Server Dispatcher
    Server["MCP Server / Dispatcher (server.py)"]:::internal

    %% Domain Modules
    subgraph "Domain Modules"
        Workbook["Workbook Management"]:::internal
        Sheet["Worksheet Utilities"]:::internal
        CellUtils["Cell Utilities"]:::internal
        DataIO["Data I/O"]:::internal
        Formatting["Formatting & Styles"]:::internal
        Chart["Charts & Visualizations"]:::internal
        Pivot["Pivot Tables"]:::internal
        Calculations["Calculations"]:::internal
        Validation["Validation"]:::internal
        Exceptions["Exceptions"]:::internal
    end

    %% File System / Storage
    FileSystem["File System (.xlsx Storage)"]:::external

    %% Configuration & Environment
    Env["Env Vars (EXCEL_FILES_PATH, FASTMCP_PORT)"]:::config

    %% CI/CD & Packaging
    subgraph "CI/CD & Packaging"
        Packaging["pyproject.toml"]:::config
        CICD["GitHub Actions (.github/workflows/publish.yml)"]:::external
        Build["Build Script (build.sh)"]:::external
        Docs["Documentation (README.md, TOOLS.md)"]:::external
        Assets["Assets (logo, etc.)"]:::external
    end

    %% Flows
    Client -->|requests| STDIO
    Client -->|requests| SSE
    CLI -->|starts| STDIO
    CLI -->|starts| SSE
    STDIO -->|MCP Request| Server
    SSE -->|MCP Request| Server
    Server -->|dispatch| Workbook
    Server -->|dispatch| Sheet
    Server -->|dispatch| CellUtils
    Server -->|dispatch| DataIO
    Server -->|dispatch| Formatting
    Server -->|dispatch| Chart
    Server -->|dispatch| Pivot
    Server -->|dispatch| Calculations
    Server -->|dispatch| Validation
    Server -->|dispatch| Exceptions
    Workbook -->|read/write| FileSystem
    Sheet -->|read/write| FileSystem
    CellUtils -->|read/write| FileSystem
    DataIO -->|read/write| FileSystem
    Formatting -->|read/write| FileSystem
    Chart -->|read/write| FileSystem
    Pivot -->|read/write| FileSystem
    Calculations -->|read/write| FileSystem
    Validation -->|handles errors| Exceptions
    Server -->|uses| Env

    %% Click Events
    click CLI "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/__main__.py"
    click Server "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/server.py"
    click Workbook "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/workbook.py"
    click Sheet "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/sheet.py"
    click CellUtils "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/cell_utils.py"
    click DataIO "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/data.py"
    click Formatting "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/formatting.py"
    click Chart "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/chart.py"
    click Pivot "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/pivot.py"
    click Calculations "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/calculations.py"
    click Validation "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/validation.py"
    click Exceptions "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/src/excel_mcp/exceptions.py"
    click Packaging "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/pyproject.toml"
    click CICD "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/.github/workflows/publish.yml"
    click Build "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/build.sh"
    click Docs "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/README.md"
    click Docs "https://github.com/saisharan0103/excel-mcp-server_v2/blob/main/TOOLS.md"
    click Assets "https://github.com/saisharan0103/excel-mcp-server_v2/tree/main/assets"

    %% Styles
    classDef external fill:#a2fca2,stroke:#333,stroke-width:1px
    classDef internal fill:#c2dfff,stroke:#333,stroke-width:1px
    classDef config fill:#e0e0e0,stroke:#333,stroke-width:1px
```
