Content
# Yxcel
> **Y**uan + Ex**cel** · Let AI Agent handle Excel, ask a question, get an answer + a new spreadsheet.
Yxcel is a [MCP](https://modelcontextprotocol.io) server that turns Excel files into queryable databases. After importing `.xlsx` / `.xls` files, AI Agents can use structured tool calls to filter, aggregate, group, and sort data, and automatically export the results into new Excel files - no SQL required, and no need for Agents to configure large models.
## Design Philosophy
Yxcel doesn't try to be a "brain" itself; it focuses on being a reliable "data layer". LLM orchestration, dialogue management, and inference decision-making are all left to external Agents, while Yxcel concentrates on parsing, storing, querying, and exporting Excel files.
```
┌─────────────┐ MCP (stdio) ┌──────────────────┐
│ Agent │ ◄──────────────► │ Yxcel │
│ │ tool calls: │ │
│ · LLM orchestration │ import_excel │ Intelligent Excel parsing │
│ · Dialogue management │ list_documents │ In-memory query engine │
│ · Inference decision-making │ query_data │ Result export .xlsx │
│ · Result presentation │ get_schema │ SQLite storage │
│ │ delete_document │ │
└─────────────┘ └──────────────────┘
```
## Workflow
```
Excel file ──import_excel──► SQLite (auto-parse header/type/trim tail)
│
Agent query ──query_data──► Query result + auto-exported .xlsx file
```
## Tool List
| Tool | Description |
|------|------|
| `import_excel` | Import Excel file. Auto-detect header row, infer column type (text/number/date), trim "total" rows. |
| `list_documents` | List all imported files and metadata (row count, sheet count, status, etc.). |
| `get_schema` | Get column definitions and sample data for each sheet. |
| `query_data` | Filter, aggregate, group, and sort - results auto-exported as `.xlsx`, return file path. |
| `delete_document` | Delete document and all data (cascade delete associated rows and physical files). |
### query_data Parameters
| Parameter | Type | Description |
|------|------|------|
| `document_id` | string | Document ID returned by `import_excel` |
| `sheet_name` | string | Sheet name to query |
| `filters` | array? | Filter conditions (AND logic), see operators below |
| `aggregations` | array? | Aggregation operations: `count` / `sum` / `avg` / `min` / `max` |
| `group_by` | string[]? | Group by columns |
| `order_by` | object? | Sort: `{ column, direction: "asc"|"desc" }` |
| `limit` | number? | Return row count limit |
**Filter Operators**: `=` `!=` `>` `<` `>=` `<=` `contains` `not_contains` `in` `not_in` `between` `is_null`
> Numeric column comparisons automatically remove thousand separators and compare by value, avoiding string traps like `"1500" < "200"`.
## Intelligent Parsing
Excel files are often irregular; Yxcel's parser handles real-world data:
- **Smart header scanning**: Score algorithm to locate the actual header row (Chinese field keywords score higher, pure numbers/repeated values score lower)
- **Column type inference**: Combine column name keywords and value distribution to determine text / number / date
- **Tail trimming**: Auto-remove "total"/"summary" rows
- **Date standardization**: Uniform formatting to `YYYY-MM-DD`
- **Error tolerance**: Auto-generate empty column names, deduplicate duplicate columns, filter out empty rows
## Installation
```bash
git clone https://github.com/Yuan-lai-ru-ci/Yxcel.git
cd Yxcel
npm install
npm run build
```
## MCP Integration
Add to your MCP configuration (`mcp.json`):
```json
{
"servers": {
"yxcel": {
"command": "npx",
"args": ["tsx", "path/to/yxcel/src/index.ts"],
"type": "stdio",
"enabled": true
}
}
}
```
## Usage Example
After import, Agents can combine and call:
> **User**: Analyze the quantity distribution of various entities in this community enterprise list
```jsonc
// Agent → query_data
{
"document_id": "48858d3f-...",
"sheet_name": "Enterprise and Individual List",
"group_by": ["Entity Type"],
"aggregations": [{ "function": "count", "column": "Serial Number", "alias": "Quantity" }]
}
// ← Return
// Individual: 480, Enterprise: 320
// Auto-export .../exports/...List_Enterprise_and_Individual_List_<timestamp>.xlsx
```
## Development
```bash
npm run dev # tsx watch (hot reload)
npm run build # tsc → dist/
npm start # Run once
```
## Tech Stack
- TypeScript (ESM)
- SQLite (better-sqlite3, WAL mode)
- MCP SDK (@modelcontextprotocol/sdk)
- Excel parsing and export (xlsx)
## License
MIT
