AI导哈

数据可视化报告生成服务

一个利用MCP协议构建的服务器，通过Python SDK实现从CSV数据集生成可视化摘要报告，无需将原始数据加载到LLM上下文中。

  • by Geyo33
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Geyo33/mcp-learning-project

使用说明

mcp数据摘要

与官方合作构建MCP服务器的学习项目 开发包.

服务器允许LLM从CSV数据集生成可视化摘要报告，而无需将原始数据加载到模型的上下文中。它模拟REST API（假GET/POST），将数据模式公开为MCP资源，将图表和文档生成提供为MCP工具，并通过MCP提示指导整个工作流程。

它展示了什么

MCP概念 文件 它的作用
资源 resources/datasets.py 通过伪造的GET端点公开数据集架构
工具 tools/chart_tools.py 生成条形图、折线图、直方图、饼图、数据集子集
工具 tools/stats_tools.py 描述性统计+相关矩阵+散点图
工具 tools/document_tools.py 构建HTML报告+通过假POST导出PDF
提示 prompts/summary_prompt.py LLM的7步指导工作流程
假冒API api/fake_client.py 由本地CSV和JSON文件支持的模拟REST客户端
模式 api/schemas.py 所有API响应的冗余模型

运作原理

LLM永远不会看到原始表格数据。相反，它遵循以下流程：

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

项目结构

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

快速启动

1.安装uv

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

2.安装依赖项

uv sync

3.验证一切正常（不需要LLM）

运行管道脚本——它端到端模拟完整的LLM工作流：

uv run python scripts/run_pipeline.py

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

图表和报告将出现在 output/.

4.运行测试套件

uv run pytest

5.打开MCP检查器（基于浏览器的调试UI）

uv run mcp dev src/mcp_data_summary/server.py

这使您可以浏览资源、手动调用工具和检查请求/响应有效负载

6.示例-连接到克劳德桌面

将此块添加到您的 claude_desktop_config.json (~/Library/Application Support/Claude/ 在macOS上， %APPDATA%\Claude\ 在Windows上）：

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

重新启动Claude Desktop，然后加载 data_summary_workflow 提示。LLM将自主发现数据集、检查模式、生成图表并生成PDF报告。

可用工具

工具 输入 输出
get_summary_statistics 数据集名称 JSON describe + correlation
generate_bar_chart 数据集，x/y列，可选 group_by PNG路径和图表数据
generate_line_chart 数据集，x/y列，可选 group_by PNG路径和图表数据
generate_histogram 数据集、列、箱 PNG路径和图表数据
generate_pie_chart 数据集、类别+值列 PNG路径和图表数据
generate_scatter_plot 数据集，x/y列，可选 color_by PNG路径和图表数据
build_subset_dataset 数据集、过滤器 子集名称、路径和架构
build_html_report 标题、图表路径、标题、摘要 HTML路径
export_pdf_report HTML路径，报告名称 JSON，pdf路径+report_id

可用资源

URI 返回
datasets://list 可用数据集名称的JSON数组
datasets://{name}/schema 绘图友好模式：列、数据类型、n_unique、示例值

添加自己的CSV

放下任何 .csv 归档 data/。服务器在启动时会自动发现它。在中添加描述 data/descriptions.json:

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

如果日期列的名称包含 "date".

PDF导出的系统依赖关系

WeasyPrint（由使用 export_pdf_report)要求在操作系统级别安装Cairo和Pango。HTML报告和所有图表都可以在没有它们的情况下工作。

# 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

下一步

  • 支持在绘制图表之前进行多数据集连接
  • 向伪造的API层引入一个简单的auth令牌
  • 使用MCP通知将流图生成进度反馈给客户端

相关 MCP