Metadata-Version: 2.4
Name: excel-mcp-server-fastmcp
Version: 1.13.0
Summary: Excel MCP Server based on FastMCP and openpyxl
Author-email: tangjian <406158101@qq.com>
Project-URL: Homepage, https://github.com/TangentDomain/excel-mcp-server
Project-URL: Repository, https://github.com/TangentDomain/excel-mcp-server
Project-URL: Issues, https://github.com/TangentDomain/excel-mcp-server/issues
Project-URL: PyPI, https://pypi.org/project/excel-mcp-server-fastmcp/
Keywords: mcp,excel,openpyxl,game-development,configuration,ai,fastmcp
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openpyxl<4.0.0,>=3.1.0
Requires-Dist: python-calamine>=0.3.0
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: xlcalculator<1.0.0,>=0.5.0
Requires-Dist: sqlglot<28.0.0,>=27.29.0
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.5.0; extra == "test"
Requires-Dist: pytest-timeout>=2.3.0; extra == "test"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio<1.0.0,>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov<7.0.0,>=6.2.1; extra == "dev"
Requires-Dist: pytest-mock<4.0.0,>=3.14.0; extra == "dev"
Requires-Dist: pytest-xdist<4.0.0,>=3.5.0; extra == "dev"
Requires-Dist: pytest-timeout<3.0.0,>=2.3.0; extra == "dev"
Requires-Dist: pytest-benchmark<5.0.0,>=4.0.0; extra == "dev"
Requires-Dist: coverage<8.0.0,>=7.10.4; extra == "dev"
Requires-Dist: psutil<6.0.0,>=5.9.0; extra == "dev"
Requires-Dist: memory-profiler<1.0.0,>=0.61.0; extra == "dev"
Requires-Dist: black<25.0.0,>=24.0.0; extra == "dev"
Requires-Dist: isort<6.0.0,>=5.13.0; extra == "dev"
Requires-Dist: flake8<8.0.0,>=7.0.0; extra == "dev"
Requires-Dist: mypy<2.0.0,>=1.10.0; extra == "dev"
Dynamic: license-file

[简体中文](README.md) | [English](README.en.md)

# 🎮 ExcelMCP: 让游戏策划用嘴说话的Excel神器

[![PyPI](https://img.shields.io/pypi/v/excel-mcp-server-fastmcp.svg)](https://pypi.org/project/excel-mcp-server-fastmcp/v1.9.1)
[![CI](https://github.com/TangentDomain/excel-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/TangentDomain/excel-mcp-server/actions/workflows/ci.yml)
![Tests](https://img.shields.io/badge/tests-968-brightgreen.svg)
![Tools](https://img.shields.io/badge/tools-52-green.svg)
![GitHub stars](https://img.shields.io/github/stars/TangentDomain/excel-mcp-server?style=social&label=Stars)

> **🚀 游戏策划必备：用中文/SQL直接操作Excel，告别手动VBA！**
> 
> 🎯 **自然语言** → "把技能攻击力全部加10%"  
> 🔧 **SQL查询** → "SELECT * FROM skills WHERE class='法师'"  
> ⚡ **智能操作** → 自动跨表JOIN、批量修改、版本管理

---

## 🚀 最新更新 (v1.9.1)

### ⚡ 性能大升级
- **整体性能提升 10.3x**：核心查询路径全面优化，大数据量场景响应速度质的飞跃

### ✨ 窗口函数全家桶（新增7个）
- **窗口聚合函数**：`AVG() OVER` / `SUM() OVER` / `MIN() OVER` / `MAX() OVER` / `COUNT() OVER`
- **NTH_VALUE**：取窗口中第 N 行的值（如「每个职业伤害排名第2的技能」）
- **GROUP_CONCAT**：行合并为字符串（如「列出每个职业的所有技能名」）
- **UPDATE 支持窗口函数**：批量修改也能用窗口计算（如「按伤害排名分批调整数值」）

### 📊 完整窗口函数清单（17个）
| 函数 | 说明 | 示例 |
|------|------|------|
| ROW_NUMBER | 行号 | 每行唯一编号 |
| RANK / DENSE_RANK | 排名 | 处理并列名次 |
| NTILE | 分桶 | 均分为 N 组 |
| PERCENT_RANK / CUME_DIST | 百分比/累积分布 | 统计分布位置 |
| LAG / LEAD | 前后行取值 | 同比/环比分析 |
| FIRST_VALUE / LAST_VALUE | 首尾值 | 分组极值 |
| NTH_VALUE | 第N行值 | 自定义排名取值 |
| AVG/SUM/MIN/MAX/COUNT | 窗口聚合 | 分组统计 |
| GROUP_CONCAT | 字符合并 | 列表拼接 |

### 🔧 其他改进
- **行号支持**：`_ROW_NUMBER_` 虚拟列，SELECT 和 UPDATE 都可用
- **IN/NOT IN 修复**：UPDATE 的 IN 子句静默失败问题已修复
- **写入增强**：列名匹配失败自动降级到传统 openpyxl 路径

### 🎮 游戏场景支持
- **技能系统**：CTE查询、平衡分析、批量调整、排名统计
- **装备管理**：套装计算、稀有度分类、评分系统、属性聚合
- **怪物配置**：AI行为配置、属性缩放、掉落管理、分组统计
- **关卡设计**：进度统计、难度配置、活动管理、数据透视

---

[📖 完整更新日志](docs/CHANGELOG.md) | [🎯 贡献指南](docs/CONTRIBUTING.md)

---

## 🎯 一句话介绍

> **"我要把技能攻击力全部加10%,装备按稀有度排序,找出法师职业所有技能"**

**🎯 不写代码！不学公式！用中文直接命令Excel，智能完成游戏配置管理！**

---

## 🚀 快速开始(1分钟)

> 💡 **🔥 急用命令？** → [📋 30秒快速参考](docs/tutorials/QUICK_REFERENCE.md)

### 🔥 一键安装，即刻使用！

#### 🎯 推荐:uvx(最简单,无安装)
```bash
# Mac/Linux 一行命令
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

使用:
```bash
uvx excel-mcp-server-fastmcp
```

#### 📦 传统:pip
```bash
pip install excel-mcp-server-fastmcp
```

> 💡 国内用户:`pip install excel-mcp-server-fastmcp -i https://pypi.tuna.tsinghua.edu.cn/simple`

### 🔗 AI 客户端配置(1分钟)

#### Cursor（推荐）
- 设置 → MCP → Add Server
- Name: `excelmcp`
- Command: `uvx`
- Args: `"excel-mcp-server-fastmcp"`

#### Claude Code
```bash
# 在项目中添加MCP服务器
claude mcp add excelmcp -- uvx excel-mcp-server-fastmcp
```

#### 其他客户端
- Cherry Studio / VSCode + Continue: 同样配置
- OpenClaw: 内置支持，无需配置

### ✅ 验证成功
在 AI 客户端说:"帮我读取技能表测试一下"
看到 Excel 数据?🎉 **配置完成!**

---

## 🎮 游戏开发场景演示 (所见即所得！)

### 🎯 策划日常工作示例
> 🎯 **真实案例**: 以下所有操作都已通过41个MCP工具验证  
> 🎮 **支持游戏**: RPG、MMO、卡牌、塔防、射击、策略等各类游戏  
> ⚡ **性能表现**: 支持10万+数据批量处理，响应时间 <1秒

```bash
# 🗣️ 用中文直接命令Excel (无需编程!)
"帮我把技能表里所有法师技能攻击力加 20%"
"找出装备表中价格超过 1000 的史诗装备" 
"把技能表和职业表关联,统计每个职业的技能数量"
"复制技能表到新文件,命名为技能备份_v2.xlsx"
```

### 🔢 数值策划任务
```bash
# 数据分析
"计算每个职业的平均攻击力和防御力"
"找出攻击力最高的前 10 个技能"
"批量调整所有技能冷却时间,乘以 0.8"
"生成角色属性平衡报告"
```

### 🏗️ 关卡策划需求
```bash
# 关卡配置
"读取关卡配置表,找出所有可收集道具"
"批量修改怪物掉落概率,稀有物品提升 50%"
"生成关卡进度统计报表"
```

---

## 📊 核心功能对比

### 游戏开发专用对比

| 场景 | ExcelMCP | 传统 Excel | ChatGPT | Python pandas |
|------|----------|------------|---------|----------------|
| **学习成本** | 🟢 0(直接说人话) | 🔴 需要公式学习 | 🟡 需要详细描述 | 🔴 需要编程基础 |
| **跨表操作** | 🟢 自动 JOIN | 🔴 复杂 VLOOKUP | 🔴 不支持 | 🟡 需要代码实现 |
| **批量修改** | 🟢 一条指令搞定 | 🔴 手动操作 | 🟡 需要详细描述 | 🟡 需要循环处理 |
| **错误处理** | 🟢 智能提示 | 🔴 容易出错 | 🟡 依赖 AI 能力 | 🔴 需要异常处理 |
| **游戏优化** | 🟢 专属优化 | 🔴 通用功能 | 🔴 不专业 | 🟡 需要游戏知识 |
| **响应速度** | 🟢 < 3秒 | 🟢 即时 | 🟡 10-30秒 | 🟢 3-10秒 |
| **数据规模** | 🟢 10万行×1000列 | 🟢 无限制 | 🔴 有限制 | 🟢 内存限制 |

### 优势场景分析

#### 🎮 ExcelMCP 最适合
- **游戏策划**:数值调整、配置管理、平衡分析
- **独立开发者**:快速原型、配置迭代、多人协作
- **数据分析师**:游戏数据分析、用户行为统计
- **运营人员**:活动配置、道具管理、版本对比

#### 🔧 传统 Excel 最适合
- **复杂公式计算**:财务报表、科学计算
- **可视化图表**:动态图表、复杂报表
- **宏自动化**:复杂业务流程自动化

#### 💡 ChatGPT 最适合
- **文本处理**:文案生成、翻译、总结
- **代码编写**:程序开发、算法设计
- **创意内容**:游戏设计、故事创作

#### 🐍 Python pandas 最适合
- **大数据处理**:百万级行数据处理
- **机器学习**:数据建模、算法训练
- **自动化脚本**:复杂数据处理流水线

---

## 🛠️ 支持的游戏类型

| 游戏类型 | 支持场景 | 特色功能 |
|----------|----------|----------|
| **RPG** | 技能系统、装备套装、属性成长 | CTE 查询、装备加成计算 |
| **MMO** | 大数据量配置、版本管理 | 流式写入、缓存优化 |
| **卡牌** | 卡牌效果、概率计算 | 条件格式、数据验证 |
| **策略** | 单位配置、战斗计算 | 跨文件 JOIN、批量操作 |
| **休闲** | 关卡配置、道具管理 | 简单查询、快速修改 |

---

## 📱 手机端看这里（简化功能对比）

| 使用场景 | ExcelMCP | 传统方式 |
|----------|----------|----------|
| **策划想调数值** | 直接说"加攻击力" | 手动改100个单元格 |
| **跨表统计** | "关联表统计" | VLOOKUP+公式 |
| **找问题数据** | "找出异常值" | 人工肉眼排查 |
| **批量修改** | "批量更新" | 复制粘贴重复操作 |

> 💡 **一句话总结**：你用自然语言说需求，ExcelMCP帮你搞定Excel操作

---

## 💡 使用技巧

### 🎯 高效指令示例
```bash
# 数据分析
"分析技能平衡性,找出伤害过高的技能"
"计算装备套装加成效果,按总价排序"
"统计怪物掉落,找出最值钱的掉落"

# 批量操作
"批量修改所有武器耐久度 +20%"
"复制装备表到不同品质分类"
"生成职业配装推荐"

# 版本管理
"比较技能表新旧版本差异"
```

### 🚀 一键复制(即用即改)

#### 技能表分析
```bash
"读取技能表,找出所有冷却时间小于3秒的技能,按伤害排序"
```

#### 装备批量优化
```bash
"给所有史诗级装备攻击力+15%,防御+10%"
"找出总评分超过80的装备,按评分降序排列"
```

#### 怪物AI配置
```bash
"修改所有Boss级怪物血量+50%,伤害+30%"
"统计不同类型怪物的平均属性,生成平衡报告"
```

#### 关卡配置管理
```bash
"批量更新关卡难度参数,第5关难度+20%"
"生成各关卡完成率统计报表,标记完成率低于50%的关卡"
```

### 🔢 行号定位更新（高级用法）

当表中存在**重复记录**，无法通过字段值唯一确定要更新的行时，可使用 `_ROW_NUMBER_` 虚拟列精确定位：

```sql
-- 按行号列表更新（最常用）
UPDATE LootList SET PropType = '主武器' WHERE _ROW_NUMBER_ IN (11, 21, 36)

-- 按单个行号更新
UPDATE 数据表 SET 状态 = '已处理' WHERE _ROW_NUMBER_ = 5

-- 按行号范围更新
UPDATE 数据表 SET 值 = 100 WHERE _ROW_NUMBER_ BETWEEN 10 AND 50
```

> ⚠️ **注意**：`_ROW_NUMBER_` 在 **SELECT 查询和 UPDATE 的 WHERE 条件**中都可用。不能用于 SET 赋值。行号从1开始计数，对应Excel的数据行（不含表头）。

---

## 🎮 现在试试！3分钟体验ExcelMCP神奇功能

### 🚀 新手体验（3秒上手！）
```bash
# 💡 就这么说就行：
"读取我的技能表，显示前5个技能"
# 🎯 没错！用中文直接命令Excel，就这么简单！
```

### 📊 快速分析体验（展示真实力！）
```bash
# 🎯 试试这个复杂查询（一条命令搞定）：
"把技能表和职业表关联，找出法师职业所有技能并按攻击力排序"
"分析技能表，找出攻击力最高的3个技能"
```

### 🔧 批量操作体验
```bash
# 复制这句测试批量修改：
"给所有法师技能的冷却时间减少20%"
```

### 🎯 结果对比
- ✅ 成功：看到Excel数据被正确读取和修改
- ❌ 失败：检查Excel文件是否关闭、文件路径是否正确
"创建配置文件备份"
"回滚到指定版本"
```

### 🚀 性能优化
- **大文件**:使用流式写入,支持 10万+ 行数据
- **复杂查询**:自动索引优化,响应 < 3 秒
- **内存占用**:典型文件 < 100MB
- **支持格式**:.xlsx、.xlsm、.xlsb

---

## 📚 文档资源

### 📖 快速上手
- [📋 快速参考指南](docs/tutorials/QUICK_REFERENCE.md) - 30秒找到你需要命令（新！）
- [互动式教程](docs/tutorials/INTERACTIVE_TUTORIAL.md) - 分模块游戏配置实战教程（新！）
- [基础教程](docs/api/README-gaming.md) - 游戏开发入门指南
- [性能优化](docs/api/README-performance.md) - 大文件处理技巧
- [SQL 参考](docs/api/README-sql.md) - 高级查询语法

### 🎮 示例代码
- [游戏开发示例](examples/README.md) - 完整技能系统、装备管理案例
- [批量操作示例](examples/进阶操作/) - 数据批处理、版本对比
- [实战案例](examples/实战案例/) - 完整游戏数值平衡方案

---

## 🔧 故障排除

### ❌ 常见问题

**Python 版本问题**
```bash
python --version  # 需要 3.10+
# 升级:https://www.python.org/downloads/
```

**网络问题**
```bash
# 国内镜像源
pip install -i https://pypi.tuna.tsinghua.edu.cn/simple excel-mcp-server-fastmcp
```

**配置错误**
- 检查 JSON 格式是否正确
- 重启 AI 客户端
- 验证 uvx:`uvx --version`

### 🆘 获取帮助
```bash
# 命令行帮助
excel-mcp-server-fastmcp --help

# 项目文档
https://github.com/TangentDomain/excel-mcp-server

# 提交问题
GitHub Issues → 使用 Bug 报告模板
```

---

## 📈 技术规格

- **响应速度**:小文件 < 1秒,大文件 < 3秒
- **数据规模**:10万行 × 1000列
- **工具数量**:52 个游戏专用工具
- **内存占用**:< 100MB(典型文件)
- **支持格式**:.xlsx、.xlsm、.xlsb

---

## 🤝 参与贡献

### 🌟 给个 Star 吧!
如果这个工具对你有帮助,请点亮 ⭐ Star
- 🔍 **发现工具**:帮助更多游戏开发者找到我们
- 🔔 **获取更新**:Star 后第一时间收到功能更新
- 🎮 **推动生态**:每一个 Star 都是我们改进的动力

### 💪 如何贡献
- 🐛 **报告 Bug**:使用 [Issue 模板](https://github.com/TangentDomain/excel-mcp-server/issues/new)
- 💡 **功能建议**:欢迎提出游戏开发新需求
- 📚 **改进文档**:让其他开发者更容易上手
- 💻 **提交代码**:查看 [贡献指南](docs/CONTRIBUTING.md)

---

## 📄 许可证

[MIT License](LICENSE) - 开源友好,可商用

---

## 🎉 致谢

感谢所有贡献者和游戏开发者社区!特别感谢:
- 游戏策划和数值策划的宝贵反馈
- 测试用户提供的真实使用场景
- 开发者社区的代码贡献

---

## 🔧 常见问题与解决

### 🚨 90%常见问题（必看）

#### 1. MCP连接失败
```
问题：AI客户端说"工具不可用"
解决：
1. 检查uv是否安装：uv --version
2. 重新安装：uvx excel-mcp-server-fastmcp --force-reinstall
3. 重启AI客户端
```

#### 2. Excel文件读取失败
```
问题：提示"无法打开Excel文件"
解决：
1. 文件路径要完整：/Users/xxx/Desktop/技能表.xlsx（不要~/Desktop）
2. 确认文件是.xlsx格式（不支持.xls/.csv）
3. 文件没有被Excel软件打开
```

#### 3. 数据格式错误
```
问题：修改数据后显示异常
解决：
1. 检查是否有合并单元格（建议取消合并）
2. 确保数值列是纯数字，不要混入文本
3. 日期格式要统一（建议用YYYY-MM-DD）
```

#### 4. 大文件卡顿
```
问题：10万行以上文件处理慢
解决：
1. 分批处理："先读取前1000行测试"
2. 用WHERE过滤："只处理攻击力>100的技能"
3. 关闭其他占用内存的程序
```

#### 5. 中文乱码
```
问题：中文显示为问号或乱码
解决：
1. 确保Excel文件保存为UTF-8编码
2. 检查系统语言设置
3. 使用英文列名避免编码问题
```

### 🛠️ 快速自查清单
遇到问题时，按顺序检查：
1. ✅ Excel文件是否关闭？
2. ✅ 文件路径是否完整？
3. ✅ 文件格式是.xlsx？
4. ✅ MCP配置是否正确？
5. ✅ uvx命令是否可用？

### 💡 快速诊断

#### 大文件处理优化
```bash
# 大文件(10万行以上)处理技巧:
"使用流式读取,避免内存溢出"
"分批次处理数据,每次处理1万行"
"关闭Excel自动计算,提升处理速度"
```

#### 数据格式问题
```bash
# 数字变文本问题:
"将文本格式的数字转换为数值格式"
"检查单元格格式,设置为常规或数值"
```

#### 跨表关联失败
```bash
# JOIN查询失败:
"检查关联字段的数据类型是否一致"
"确认关联值在两个表中都存在"
"使用模糊匹配查找可能的不一致"
```

### ⚡ 性能优化建议

#### 🎯 最佳实践
- **小文件**(<1万行):直接处理,无需特殊优化
- **中文件**(1-10万行):启用流式处理,批量操作
- **大文件**(>10万行):分块处理,避免全量加载

#### 💾 内存管理
```bash
# 大文件处理优化:
"处理后及时清理内存,避免内存泄漏"
"使用分页查询,每次只加载部分数据"
"关闭不必要的Excel功能,减少内存占用"
```

#### 🔄 批量操作优化
```bash
# 高效批量操作:
"批量插入时使用流式写入,性能提升80%"
"批量更新时按行批量,减少IO次数"
"复杂查询先筛选再处理,减少数据量"
```

### 🆘 获取帮助

1. **查看日志**:检查 `.excel_mcp_logs/` 目录下的错误日志
2. **简化问题**:先用小文件测试,复现问题后再处理大文件
3. **版本确认**:运行 `excel-mcp-server-fastmcp --version` 确认版本
4. **提交Issue**:[GitHub Issues](https://github.com/TangentDomain/excel-mcp-server/issues/new)

---

**用 AI 重新定义游戏开发配置管理!** 🚀
