A Model Context Protocol (MCP) server for reading and analyzing Excel worksheets, featuring smart large-file handling and structured guidelines.
npm install fyaic-sheet-mcp基于 PowerShell 的工作表结构化阅读 MCP Server,用来帮助大模型安全、高效地阅读「按语义模块组织」的工作表文档。
``mermaid`
flowchart TD
subgraph 技能包
A[PowerShell脚本] --> B[Excel文件解析能力]
C[自然语言指令] --> D[学习复杂表格排布阅读方法]
B --> E[结构化数据提取]
D --> F[排版含义分析]
end
subgraph 功能层
E --> G[解析工作表]
F --> H[理解排版逻辑]
G --> I[梳理多页Sheet目录]
I --> J[反问用户确定读取哪一页Sheet]
end
subgraph 接口层
G --> K[list_xlsx_sheets工具]
H --> L[preview_xlsx_sheet工具]
J --> M[用户交互流程]
end
N[MCP客户端] --> K
N --> L
M --> N
本Skill与其他Excel MCP的关键区别在于:
- 脚本+自然语言指令:结合PowerShell脚本的技术实现与精心设计的自然语言指令,形成完整的工作表解析能力
- 复杂排版理解:能够处理工作表中的复杂排版,理解其中的逻辑结构
- 智能任务窄化:在表格页数庞大时,通过反问用户来窄化任务范围,提高分析效率
- 作用:列出指定工作表文件中的所有工作表(index + name),不读取单元格内容。$3
- 输入:{ path: string, sheet?: string[], maxRows?: number }
- 作用:按行数限制预览指定工作表的表头和前几行数据,返回 JSON 结构:
- sheetName:工作表名称
- rowCount / colCount
- header:表头行
- rows:从表头下一行开始的前 maxRows 行
- truncated:是否截断
> 注意:本 MCP Skill 同时内置了工作表的「读取能力」与
prompts/通用指令.md 中的核心语义指令,两者共同构成一个完整的 ODC 工作表解析能力。模型在调用其它工具前,应先通过 get_sheet_guideline 或等效方式加载并遵循这份通用指令。安装(源码方式)
前置条件:
- Node.js
- PowerShell(Windows 自带)
- 本机可访问工作表文件(.xlsx)
步骤:
`bash
克隆仓库
git clone https://github.com/fyaic/fyaic-sheet-mcp.git
cd fyaic-sheet-mcp安装依赖
npm install构建项目
npm run build
`$3
在开发模式下,建议指向本地构建的文件:`json
{
"mcpServers": {
"fyaic-sheet-local": {
"command": "node",
"args": [
"C:/absolute/path/to/fyaic-sheet-mcp/dist/index.js"
]
}
}
}
`工具使用流程
`mermaid
flowchart TD
A[用户/模型] --> B[调用 list_xlsx_sheets]
B --> C[获取工作表清单]
C --> D{表格页数是否庞大?}
D -- 是 --> E[反问用户窄化任务]
D -- 否 --> F[向用户确认需要阅读的sheet]
E --> F
F --> G[调用 preview_xlsx_sheet]
G --> H[获取结构化数据]
H --> I[分析复杂排版逻辑]
I --> J[按通用指令分析数据]
J --> K[生成结构化理解与总结]
K --> L[返回结果给用户]
`通用指令(阅读工作表的语义规则)
本项目内置的
prompts/通用指令.md 是技能逻辑的一部分,请务必在会话中作为 System / Instruction Prompt 提供给模型。要点包括:- 把表头行视为字段定义;从表头下一行开始,每一行是一条业务 entry。
- 表头之上的说明行属于「文档说明」,用于理解语义,不当作任务记录。
- 对每条记录,要给出「大阶段 → 子板块 → 任务」的完整路径。
- 对纵向合并单元格,视为上位类别标签,覆盖其下所有行。
- 空单元格要明确标注为「未填写 / 待定 / 未指定」,不要虚构内容。
- 如果存在外部链接但内容不可见,要在结论中显式注明分析基于「可见信息」。
建议的调用顺序
1. 调用
list_xlsx_sheets 拿到工作表清单。
2. 根据工作表数量和名称,判断表格是否庞大。
3. 如果表格庞大,反问用户以窄化任务范围。
4. 向用户确认需要阅读的 sheet。
5. 调用 preview_xlsx_sheet 获取结构化数据。
6. 分析复杂排版中的逻辑结构。
7. 按 prompts/通用指令.md` 的方法论,对数据做结构化理解与总结。