# mcp-data-summary

A learning project for building an MCP server with the official [Python SDK](https://github.com/modelcontextprotocol/python-sdk).

The server lets an LLM produce a visual summary report from CSV datasets without ever loading raw data into the model's context. It simulates a REST API (fake GET/POST), exposes data schemas as MCP Resources, provides chart and document generation as MCP Tools, and guides the whole workflow with an MCP Prompt.

---

## What it demonstrates

| MCP concept | File | What it does |
|---|---|---|
| **Resources** | `resources/datasets.py` | Expose dataset schemas via fake GET endpoints |
| **Tools** | `tools/chart_tools.py` | Generate bar, line, histogram, pie charts, dataset subset |
| **Tools** | `tools/stats_tools.py` | Descriptive stats + correlation matrix + scatter plot |
| **Tools** | `tools/document_tools.py` | Build HTML report + export PDF via fake POST |
| **Prompts** | `prompts/summary_prompt.py` | 7-step guided workflow for the LLM |
| **Fake API** | `api/fake_client.py` | Simulated REST client backed by local CSV and JSON files |
| **Schemas** | `api/schemas.py` | Pydantic models for all API responses |

---

## How it works

The LLM never sees raw tabular data. Instead it follows this pipeline:

```
GET /datasets                 → discover available datasets
GET /datasets/{name}          → inspect a plot-friendly schema (columns, dtypes, sample values)
tool: get_summary_statistics  → understand distributions and correlations
tool: generate_*_chart        → produce PNG charts saved to output/ and feedbacks to understand the charts
tool: build_html_report       → render a Jinja2 HTML report from the chart paths
tool: export_pdf_report       → convert HTML to PDF and POST it back to the fake API
```

---

## Project structure

```
mcp-data-summary/
├── data/                              # Sample CSV files and JSON dataset descriptions (auto-discovered)
│   ├── descriptions.json
│   ├── sales.csv
│   └── users.csv
├── output/                            # Generated charts, HTML and PDF reports
├── scripts/
│   └── run_pipeline.py                # End-to-end pipeline runner (no LLM needed)
├── tests/
│   ├── conftest.py                    # Shared pytest fixtures
│   ├── test_fake_client.py            # Unit tests for the API layer
│   ├── test_chart_tools.py            # Tests for all chart tools
│   └── test_stats_and_docs.py         # Tests for stats tool + HTML builder
├── src/
│   └── mcp_data_summary/
│       ├── server.py                  # Entry point — wires everything together
│       ├── api/
│       │   ├── fake_client.py         # Simulates GET /datasets and POST /reports
|       |   ├── json_encoder.py        # Custom JSON encoder
│       │   └── schemas.py             # Pydantic models for API responses
│       ├── resources/
│       │   └── datasets.py            # MCP Resources: dataset list + schema
│       ├── tools/
│       │   ├── chart_tools.py         # Bar, line, histogram, pie chart tools
│       │   ├── stats_tools.py         # Summary statistics + scatter plot
│       │   └── document_tools.py      # HTML report builder + PDF exporter
│       └── prompts/
│           └── summary_prompt.py      # Guided 7-step workflow prompt
└── pyproject.toml
```

---

## Quick start

### 1. Install uv

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Install dependencies

```bash
uv sync
```

### 3. Verify everything works (no LLM required)

Run the pipeline script — it simulates the full LLM workflow end-to-end:

```bash
uv run python scripts/run_pipeline.py

# Restrict to a single dataset
uv run python scripts/run_pipeline.py --datasets sales
```

Charts and a report will appear in `output/`.

### 4. Run the test suite

```bash
uv run pytest
```

### 5. Open the MCP Inspector (browser-based debug UI)

```bash
uv run mcp dev src/mcp_data_summary/server.py
```

This lets you browse Resources, call Tools manually, and inspect request/response payloads

### 6. Example - Connect to Claude Desktop

Add this block to your `claude_desktop_config.json`
(`~/Library/Application Support/Claude/` on macOS, `%APPDATA%\Claude\` on Windows):

```json
{
  "mcpServers": {
    "data-summary": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/mcp-data-summary",
        "run", "mcp-data-summary"
      ]
    }
  }
}
```

Restart Claude Desktop, then load the `data_summary_workflow` prompt. The LLM will discover datasets, inspect schemas, generate charts, and produce a PDF report autonomously.

---

## Available tools

| Tool | Input | Output |
|---|---|---|
| `get_summary_statistics` | dataset name | JSON with `describe` + `correlation` |
| `generate_bar_chart` | dataset, x/y columns, optional `group_by` | PNG path and chart data |
| `generate_line_chart` | dataset, x/y columns, optional `group_by` | PNG path and chart data |
| `generate_histogram` | dataset, column, bins | PNG path and chart data |
| `generate_pie_chart` | dataset, category + value columns | PNG path and chart data |
| `generate_scatter_plot` | dataset, x/y columns, optional `color_by` | PNG path and chart data |
| `build_subset_dataset` | dataset, filters | Subset name, path and schema |
| `build_html_report` | title, chart paths, captions, summary | HTML path |
| `export_pdf_report` | HTML path, report name | JSON with pdf path + report_id |

---

## Available resources

| URI | Returns |
|---|---|
| `datasets://list` | JSON array of available dataset names |
| `datasets://{name}/schema` | Plot-friendly schema: columns, dtypes, n_unique, sample values |

---

## Adding your own CSV

Drop any `.csv` file into `data/`. The server auto-discovers it on startup. Add a description in `data/descriptions.json`:

```python
{
    "your_file": "Description the LLM will see when reading the schema.",
}
```

Date columns are auto-detected if their name contains `"date"`.

---

## System dependencies for PDF export

WeasyPrint (used by `export_pdf_report`) requires Cairo and Pango to be installed at the OS level. The HTML report and all charts work without them.

```bash
# Ubuntu / Debian
sudo apt install libpango-1.0-0 libcairo2 libpangocairo-1.0-0

# macOS
brew install pango cairo

# Windows — follow the WeasyPrint install guide:
# https://doc.courtbouillon.org/weasyprint/stable/first_steps.html
```

---

## Next steps

- Support multi-dataset joins before charting
- Introduce a simple auth token to the fake API layer
- Stream chart generation progress back to the client using MCP notifications