# MCP Data Service · MCP 数据服务

> Expose data query + insights + SQL as an MCP Server — plug into Claude Desktop, Cursor, or any MCP client in 30 seconds.
> 把「数据查询 + 自动洞察 + SQL」包装成 MCP 标准工具，Claude Desktop / Cursor 即插即用——给任意 AI Agent 装上数据能力，30 秒接入。

[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)
[![CI](https://github.com/lengzhanbao/mcp-data-service/actions/workflows/ci.yml/badge.svg)](https://github.com/lengzhanbao/mcp-data-service/actions)

---

**English** · [中文](#中文)

## English

### What is this?

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that turns a data table into callable tools for any AI agent. **No LLM API** — pandas + SQLite locally.

- **v0.2.0**: 11 tools + 2 resources + 2 prompts · CSV/SQLite · pagination · read-only SQL · health check · Docker

### Tools (11)

| Tool | What it does |
|------|--------------|
| `query_video_stats(metric, rule, condition, source, page, page_size, columns)` | Query: TOP/BOTTOM/AVG/SUM/by-date + filter + pagination + column select |
| `data_insights(source)` | Auto insights: overview + anomaly (1.5σ) + recommendations |
| `list_columns(source)` | List columns & dtypes |
| `list_sources()` | List configured sources |
| `refresh_sources()` | Clear cache |
| `get_schema(source)` | Detailed schema: dtype/nulls/mean/min/max/samples |
| `preview_data(source, page, page_size, condition)` | Paginated preview with filter |
| `aggregate_stats(source, group_by, metric, agg, condition)` | Group-by agg (mean/sum/count/min/max/median) |
| `correlation_analysis(source, columns)` | Pearson correlation matrix |
| `sql_query(sql, source)` | Read-only SELECT/WITH over DataFrame or SQLite file |
| `health_check()` | Health: sources/rows/cols/tools |

### Resources (2)

| URI | What |
|-----|------|
| `data://{source}/preview` | First 5 rows |
| `data://{source}/schema` | Schema JSON (rows + dtypes) |

### Prompts (2)

| Prompt | What |
|--------|------|
| `analyze_video_data(source)` | 6-step full analysis guide |
| `anomaly_drilldown(source, metric)` | Anomaly drill-down guide |

### Quick Start

```bash
pip install -r requirements.txt
pip install -e .[dotenv]           # or pipx install -e .[dotenv]
LOG_LEVEL=DEBUG python server.py --verbose --health  # 详细日志
python tests/test_server.py        # direct + MCP handshake (tools/resources/prompts)
python server.py --health          # health check
python server.py                   # stdio (clients launch it)
```

### Connect from Claude Desktop / Cursor

```json
{ "mcpServers": { "data-service": { "command": "python", "args": ["/absolute/path/to/mcp-data-service/server.py"] } } }
```

### Multiple sources (CSV + SQLite)

```bash
DATA_SOURCES="default=./data/video_stats.csv,archive=./data/archive.db" python server.py
# SQLite auto-detected by .db/.sqlite; table video_stats or first table is used
```

### Docker

```bash
docker build -t mcp-data-service .
docker run -i --rm -v ./data:/app/data:ro mcp-data-service --health
docker compose up
```

---

## 中文

### 这是什么？

一个 [MCP](https://modelcontextprotocol.io) Server：把一张数据表变成任何 AI Agent 可调用的工具。**不依赖 LLM API**——pandas + SQLite 本地计算。

- **v0.2.0**：11 工具 + 2 资源 + 2 提示 · 支持 CSV/SQLite · 分页 · 只读 SQL · 健康自检 · Docker

### 工具清单（11）

| 工具 | 作用 |
|------|------|
| `query_video_stats(metric, rule, condition, source, page, page_size, columns)` | 按指标查询：TOP/BOTTOM/平均值/总和/按日期 + 过滤 + 分页 + 选列 |
| `data_insights(source)` | 自动洞察：总览 + 异常（1.5σ）+ 建议 |
| `list_columns(source)` | 列出列名与类型 |
| `list_sources()` / `refresh_sources()` | 多源列表 / 清缓存 |
| `get_schema(source)` | 详细 Schema + 统计摘要 |
| `preview_data(source, page, page_size, condition)` | 分页预览 + 条件过滤 |
| `aggregate_stats(source, group_by, metric, agg, condition)` | 分组聚合 mean/sum/count/min/max/median |
| `correlation_analysis(source, columns)` | 相关性矩阵 |
| `sql_query(sql, source)` | 只读 SELECT/WITH（内存 DataFrame 或 SQLite 文件） |
| `health_check()` | 健康自检 |

### 资源与提示

- 资源：`data://{source}/preview` 预览、`data://{source}/schema` JSON
- 提示：`analyze_video_data` 全流程引导、`anomaly_drilldown` 异常下探

### 快速开始

```bash
pip install -r requirements.txt
pip install -e .[dotenv]       # 或 pipx install -e .[dotenv]
LOG_LEVEL=DEBUG python server.py --verbose --health  # 详细日志
python tests/test_server.py    # 直调 + MCP 握手
python server.py --health      # 自检
python server.py               # stdio（客户端自动拉起）
```

### 多数据源（CSV + SQLite）

```bash
DATA_SOURCES="default=./data/video_stats.csv,archive=./data/archive.db" python server.py
# .db/.sqlite 自动走 SQLite，表名为 video_stats 或首表
```

### Docker

```bash
docker build -t mcp-data-service .
docker compose up
```

---

## License

MIT © lengzhanbao