fyaic-sheet-mcp

基于 PowerShell 的工作表结构化阅读 MCP Server，用来帮助大模型安全、高效地阅读「按语义模块组织」的工作表文档。

项目架构

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脚本的技术实现与精心设计的自然语言指令，形成完整的工作表解析能力
• 复杂排版理解：能够处理工作表中的复杂排版，理解其中的逻辑结构
• 智能任务窄化：在表格页数庞大时，通过反问用户来窄化任务范围，提高分析效率

提供的工具

list_xlsx_sheets

• 输入：{ path: string }
• 作用：列出指定工作表文件中的所有工作表（index + name），不读取单元格内容。

preview_xlsx_sheet

• 输入：{ 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）

步骤：

# 克隆仓库
git clone https://github.com/fyaic/fyaic-sheet-mcp.git
cd fyaic-sheet-mcp

# 安装依赖
npm install

# 构建项目
npm run build

3. 本地调试配置

在开发模式下，建议指向本地构建的文件：

{
  "mcpServers": {
    "fyaic-sheet-local": {
      "command": "node",
      "args": [
        "C:/absolute/path/to/fyaic-sheet-mcp/dist/index.js"
      ]
    }
  }
}

工具使用流程

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 的方法论，对数据做结构化理解与总结。

核心功能特点

1. 解析工作表

• 通过PowerShell脚本安全、高效地读取Excel文件
• 提取结构化数据，包括表头、行数据等
• 处理不同类型的Excel文件格式

2. 理解复杂排版逻辑

• 基于自然语言指令的语义理解
• 分析合并单元格、层级结构等复杂排版
• 识别业务逻辑和数据关系

3. 处理庞大表格

• 当表格页数庞大时，智能判断处理方式
• 通过反问用户来窄化任务范围
• 提高分析效率和准确性