# Yxcel

> **Y**uan + Ex**cel** · 把 Excel 交给 AI Agent，问一句话，拿回答案 + 一张新表格。

Yxcel 是一个 [MCP](https://modelcontextprotocol.io)（Model Context Protocol）服务器，它把 Excel 文件变成可查询的数据库。导入 `.xlsx` / `.xls` 文件后，AI Agent 就能通过结构化工具调用对数据做筛选、聚合、分组、排序，并自动把结果导出成新的 Excel 文件——不需要写一行 SQL，也不需要 Agent 自己配大模型。

## 设计理念

Yxcel 不自己做"大脑"，它只做可靠的"数据层"。LLM 编排、对话管理、推理决策全部交给外部 Agent，Yxcel 专注于把 Excel 解析、存储、查询、导出这几件事做到位。

```
┌─────────────┐     MCP (stdio)     ┌──────────────────┐
│   Agent      │ ◄──────────────►  │      Yxcel        │
│             │  tool calls:        │                   │
│ · LLM 编排   │  import_excel       │  智能 Excel 解析   │
│ · 对话管理   │  list_documents     │  内存查询引擎      │
│ · 推理决策   │  query_data         │  结果导出 .xlsx    │
│ · 结果呈现   │  get_schema         │  SQLite 存储       │
│             │  delete_document    │                   │
└─────────────┘                    └──────────────────┘
```

## 工作流程

```
Excel 文件 ──import_excel──► SQLite（自动解析表头/类型/裁剪表尾）
                                    │
   Agent 提问 ──query_data──► 查询结果 + 自动导出的 .xlsx 文件
```

## 工具一览

| 工具 | 说明 |
|------|------|
| `import_excel` | 导入 Excel 文件。自动识别表头行、推断列类型（text/number/date）、裁剪"合计/总计"表尾行。 |
| `list_documents` | 列出所有已导入文件及元数据（行数、表数、状态等）。 |
| `get_schema` | 获取某个文档的列定义和每个 sheet 的前 5 行样本数据。 |
| `query_data` | 筛选、聚合、分组、排序——结果自动导出为 `.xlsx`，返回文件路径。 |
| `delete_document` | 删除文档及其全部数据（级联删除关联行与物理文件）。 |

### query_data 参数

| 参数 | 类型 | 说明 |
|------|------|------|
| `document_id` | string | 由 `import_excel` 返回的文档 ID |
| `sheet_name` | string | 要查询的工作表名 |
| `filters` | array? | 过滤条件（AND 逻辑），见下方操作符 |
| `aggregations` | array? | 聚合操作：`count` / `sum` / `avg` / `min` / `max` |
| `group_by` | string[]? | 分组列 |
| `order_by` | object? | 排序：`{ column, direction: "asc"\|"desc" }` |
| `limit` | number? | 返回行数上限 |

**过滤操作符**：`=` `!=` `>` `<` `>=` `<=` `contains` `not_contains` `in` `not_in` `between` `is_null`

> 数字列比较自动去除千分位逗号并按数值大小比较，避免 `"1500" < "200"` 这类字符串陷阱。

## 智能解析

Excel 文件往往不规整，Yxcel 的解析器针对真实数据做了处理：

- **智能表头扫描**：在前 5 行中用评分算法定位真正的表头行（中文字段关键词加分、纯数字/重复值减分）
- **列类型推断**：结合列名关键词和值分布投票判定 text / number / date
- **表尾裁剪**：自动剔除"合计/总计/小计/平均/汇总"行
- **日期标准化**：统一格式化为 `YYYY-MM-DD`
- **容错处理**：空列名自动生成、重名列去重、全空行过滤

## 安装

```bash
git clone https://github.com/Yuan-lai-ru-ci/Yxcel.git
cd Yxcel
npm install
npm run build
```

## 接入 MCP

在你的 MCP 配置（`mcp.json`）中加入：

```json
{
  "servers": {
    "yxcel": {
      "command": "npx",
      "args": ["tsx", "path/to/yxcel/src/index.ts"],
      "type": "stdio",
      "enabled": true
    }
  }
}
```

## 使用示例

导入后，Agent 可以这样组合调用：

> **用户**：分析这份社区企业名单里各类主体的数量分布

```jsonc
// Agent → query_data
{
  "document_id": "48858d3f-...",
  "sheet_name": "企业及个体户名单",
  "group_by": ["主体类型"],
  "aggregations": [{ "function": "count", "column": "序号", "alias": "数量" }]
}
// ← 返回
// 个体工商户: 480, 企业: 320
// 并自动导出 .../exports/...名单_企业及个体户名单_<时间戳>.xlsx
```

## 开发

```bash
npm run dev      # tsx watch（热重载）
npm run build    # tsc → dist/
npm start        # 运行一次
```

## 技术栈

- TypeScript（ESM）
- SQLite（better-sqlite3，WAL 模式）
- MCP SDK（@modelcontextprotocol/sdk）
- Excel 解析与导出（xlsx）

## License

MIT