Yxcel

Yuan + Excel · 把 Excel 交给 AI Agent，问一句话，拿回答案 + 一张新表格。

Yxcel 是一个 MCP（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
• 容错处理：空列名自动生成、重名列去重、全空行过滤

安装

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

接入 MCP

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

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

使用示例

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

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

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

开发

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