MCP Sheet Parser

# 用户指南 ## 1. 简介 本指南旨在帮助用户了解并有效使用 MCP Sheet Parser。MCP Sheet Parser 是一个通过模型上下文协议（MCP）运行的服务，它允许您通过自然语言指令，让 AI 代理帮助您完成对电子表格文件的读取、分析、转换和修改。 ## 2. 核心概念 - **AI 代理**: 指的是您正在交互的智能助手，例如 Claude。 - **MCP 客户端**: AI 代理运行的环境，例如 Claude Desktop 或 Cursor IDE。 - **MCP 服务器**: 本项目，一个在后台运行的程序，负责实际处理您的文件。 - **工具 (Tool)**: 服务器提供给 AI 代理使用的具体功能，例如 `parse_sheet`。 您的所有操作都将通过向 AI 代理发送指令来完成。代理会决定调用哪个工具来执行您的请求。 ## 3. 基础操作 ### 3.1 解析电子表格 (`parse_sheet`) 这是最基础也是最常用的功能。它让 AI 代理能够“读取”和“理解”您的表格文件。 **使用场景**: - 查看表格内容。 - 对数据进行初步分析。 - 为后续的数据修改做准备。 **如何使用**: 您可以直接向 AI 代理发出指令。 - **查看文件概览**: > "请解析一下 `/Users/name/Documents/年度报告.xlsx` 这个文件。" AI 代理会调用 `parse_sheet` 工具，默认只返回文件的基本信息（如工作表名称、行数、列数）和前几行数据作为预览。这样做是为了节省处理时间和成本，避免一次性加载过多内容。 - **查看完整数据**: > "请读取 `/Users/name/Documents/年度报告.xlsx` 的所有数据。" 当您需要查看全部内容时，AI 代理会自动在调用工具时设置 `include_full_data` 参数为 `true`。 - **查看特定工作表**: > "请解析文件 `/path/to/data.xlsx` 中的'销售记录'工作表。" ### 3.2 转换为 HTML (`convert_to_html`) 此功能可以将您的电子表格文件转换为一个或多个 HTML 文件，方便在浏览器中查看。转换过程会尽可能保留原始的格式和样式。 **使用场景**: - 分享数据报告。 - 在网页中嵌入表格。 - 以更直观的方式查看带有复杂格式的表格。 **如何使用**: - **转换整个文件**: > "请将 `/path/to/report.xlsx` 转换成 HTML。" 服务器会为文件中的每一个工作表生成一个对应的 HTML 文件。 - **转换单个工作表**: > "请只转换 `/path/to/report.xlsx` 里的 'Q3 Summary' 工作表。" - **处理大文件（分页）**: > "请将 `/path/to/large_data.csv` 转换成 HTML，每页显示 50 行，我先看看第一页。" 对于包含大量数据的文件，您可以使用分页功能，避免生成的 HTML 文件过大。 ### 3.3 应用修改 (`apply_changes`) 这是数据处理闭环的最后一步。当 AI 代理根据您的指令在内存中修改了数据后，此功能可以将这些修改保存回原始文件中。 **使用场景**: - 批量更新数据。 - 清理或格式化数据。 - 基于计算结果修改表格。 **如何使用**: 这个过程通常是连续的。 1. **第一步：读取和分析** > "请读取 `/path/to/inventory.xlsx`，告诉我所有'铅笔'的库存量。" 2. **第二步：提出修改指令** > "好的，请将所有'铅笔'的库存量都增加 100。" 3. **第三步：确认保存** > "请保存修改。" 在第三步，AI 代理会调用 `apply_changes` 工具，将修改后的数据写回 `inventory.xlsx` 文件。为安全起见，服务器默认会创建一个原始文件的备份（例如 `inventory.xlsx.backup`）。 ## 4. 高级技巧 - **范围选择**: 当您只关心表格的特定区域时，可以使用范围选择来提高效率。 > "请解析 `/path/to/data.xlsx` 中 A1 到 D10 区域的数据。" - **样式信息**: 如果您需要分析表格的格式（例如，找出所有标红的单元格），可以要求代理在解析时包含样式信息。 > "请解析 `/path/to/styles.xlsx`，并告诉我单元格的颜色信息。" - **组合使用**: 您可以将多个操作组合在一个指令中。 > "请读取 `/path/to/sales.xlsx`，计算'总销售额'这一列的总和，然后将结果填入 G1 单元格，最后保存文件。" ## 5. 支持的文件格式 | 格式 | 读取 | 写入 | 样式支持 | 备注 | | :----- | :--- | :--- | :------- | :--------------------------------- | | .xlsx | ✅ | ✅ | 完整 | 推荐使用的主要格式。 | | .xlsm | ✅ | ✅ | 完整 | 宏代码本身不会被执行或保留。 | | .xls | ✅ | ✅ | 基础 | 支持有限，部分复杂样式可能丢失。 | | .xlsb | ✅ | ❌ | 基础 | 二进制格式，暂不支持写入。 | | .csv | ✅ | ✅ | 无 | 纯文本格式，不包含任何样式信息。 |