内容
# 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
