本地工作簿mcp

Name: 本地工作簿mcp
Author: McFuzzySquirrel

作者：McFuzzySquirrel5 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

通过代码探索想法：一次实验一个项目

关于这些项目

我所有的项目都只有一个主要目的：通过实验学习。每个仓库都是我在提出问题时的结果：

“这可能吗？”
“我想知道……”

有时它们是尝试解决我遇到的实际问题，其他时候只是我跟随好奇心深入研究。
这是我学习游乐场，一个测试想法、尝试新事物并通过实践学习的空间。

我在这里分享它们，以防它们能帮助或启发其他人。
因此，请期待一些项目会显得杂乱无章，而另一些则结构良好，所有这些都是正在进行的学习的真实反映。

您可以自由地使用、修改或构建这里提供的任何内容。

那么，让我们开始吧：

Excel本地MCP

本地模型上下文协议服务器和CLI工具，用于分析Excel工作簿的对话。使用自然语言与您的电子表格进行对话——提问、搜索数据、预览表格，并在不离开终端或浏览器的情况下切换工作簿。

🚀 当前状态： 正在进行中。CLI工具已稳定并经过测试。Web界面功能正常但需要验证测试。两者共享同一个强大的后端（MCP + 语义内核）。

截图

CLI代理

CLI截图

Web聊天UI

📸 截图即将推出

Web界面具有干净的Blazor界面，包括：

上传工作簿的文件上传功能

聊天风格的对话界面

正确的HTML表格渲染

侧边栏中的建议查询

对话历史记录

功能

✅ 语义内核CLI代理 - 使用Spectre.Console驱动的漂亮终端UI
✅ 调试日志 - 查看LLM调用的确切工具及其时间
✅ 工作簿切换 - 加载不同的工作簿而不需重启
✅ MCP服务器 - 符合标准的模型上下文协议服务器
✅ 示例工作簿 - 真实的测试数据（项目、员工、预算）
✅ 本地优先 - 所有内容都在您的机器上运行，数据不会离开设备
✅ 跨平台 - 通过.NET 9支持Windows、Linux、macOS

快速入门： 跳转到入门指南以在3分钟内运行。

这存在的原因

保持电子表格私密性。 许多团队无法将财务或受监管的Excel文件上传到托管服务。在本地运行MCP服务器可以让代理在不离开设备的情况下分析数据。
将Excel带入MCP生态系统。 大多数现有的MCP工具专注于文本文档或REST API。这个项目填补了空白，将工作簿结构转换为任何符合标准的客户端可以使用的MCP工具/资源。
启用代理自动化。 通过一致的工作表、表格和行模式，代理可以回答自然语言问题，生成摘要，并触发依赖于电子表格上下文的下游工作流。

使用案例

“预算工作簿中有哪些标签和表格，谁拥有每一个？”
“查找所有引用供应商X且余额逾期的工作表中的行。”
“预览季度奖项表格的前20行，并将其发送给同事。”
“结合本地CRM MCP服务器，让代理可以将电子表格导出与实时系统数据进行对账。”

未来增强

查看不断发展的路线图docs/FutureFeatures.md。即将推出的亮点：

支持过滤范围预览（例如，公式与值，透视表扩展）。
实现写回工具以更新单元格、添加工作表或标注发现。
暴露分析，如值分布、异常检测或图表生成。
添加WebSocket/HTTP传输，以便服务器可以在中继或容器编排平台后面运行。

组件

核心后端（稳定）

src/ExcelMcp.Server – 标准IO JSON-RPC MCP服务器，索引工作簿
src/ExcelMcp.Contracts – 共享数据合约
src/ExcelMcp.Client – 命令行MCP客户端工具

用户界面（正在开发中）

CLI代理（推荐 - 已充分测试 ✅）

src/ExcelMcp.SkAgent – 具有AS/400风格终端界面的语义内核CLI代理
- ✅ 调试日志显示工具调用
- ✅ 无需重启即可切换工作簿
- ✅ 彩色输出
- ✅ 适用于任何工作簿（无假设）
- ✅ 在Windows、Linux（树莓派）上进行了测试

Web聊天（功能正常 - 需要验证 ⚠️）

src/ExcelMcp.ChatWeb – ASP.NET Blazor Server Web UI
- ✅ 浏览器聊天界面
- ✅ 文件上传功能
- ✅ HTML表格渲染
- ✅ 无关工作簿的提示
- ✅ 在Linux ARM64上构建
- ⏳ 需要手动验证测试（参见WEB-CHAT-ROADMAP.md）

文档

docs/UserGuide.md – 包含设置、工作流程和故障排除的详细指南
docs/FutureFeatures.md – 路线图和未来增强
docs/SkAgentQuickStart.md – CLI代理快速入门指南
docs/WebChatImprovements.md – Web聊天的技术细节
test-data/README.md – 示例工作簿和测试指南
GETTING-BACK-ON-TRACK.md – 开发状态和下一步计划

预备条件

.NET SDK 9.0+
PowerShell 7+（Windows/macOS/Linux）用于打包脚本
本地.xlsx工作簿以供分析

构建与测试

dotnet build
dotnet test

快速入门

语义内核CLI代理（推荐）

SK代理提供了一个经典的AS/400风格终端界面，带有对话式AI、调试日志和工作簿切换：

# 1. 启动本地LLM服务器（例如，LM Studio在端口1234上）

# 2. 创建示例工作簿（可选）
pwsh -File scripts/create-sample-workbooks.ps1

# 3. 运行代理
dotnet run --project src/ExcelMcp.SkAgent -- --workbook "test-data/ProjectTracking.xlsx"

# 4. 与您的工作簿对话：
> 这个工作簿中有哪些表格？
> 显示所有高优先级任务
> 加载test-data/EmployeeDirectory.xlsx
> 谁在工程部门工作？
> 退出

功能：

✅ 绿色彩色终端UI
✅ 调试日志显示工具调用
✅ 切换工作簿而不需重启（加载，打开，切换命令）
✅ 不区分大小写的搜索
✅ 适用于本地LLMs（LM Studio，Ollama）或OpenAI

参见： docs/SkAgentQuickStart.md 以获取详细指南。

Web聊天（用于测试 - 支持Linux/树莓派）

Web聊天提供了一个基于浏览器的界面。目前功能正常但需要验证测试。

# Linux/树莓派（推荐）
./run-chatweb.sh
# 在http://localhost:5001上打开

# Windows（开发）
dotnet run --project src/ExcelMcp.ChatWeb
# 在http://localhost:5000上打开

已经实现的功能：

✅ 浏览器聊天界面
✅ 文件上传功能
✅ HTML表格渲染（固定于11月1日）
✅ 无关工作簿的提示（从CLI学习）
✅ 对话历史记录
✅ 在树莓派OS（ARM64）上运行

需要测试的功能：

⏳ 手动验证（加载，查询，验证结果）
⏳ 错误处理场景
⏳ 性能基准测试
⏳ 跨浏览器兼容性

参见：

WEB-CHAT-ROADMAP.md - 测试检查清单及路线图
GETTING-BACK-ON-TRACK.md - 当前状态及下一步计划
docs/WebChatImprovements.md - 技术细节

MCP服务器和CLI客户端

用于直接MCP协议交互或编程访问：

# 使用CLI客户端（首次运行时提示工作簿路径）
dotnet run --project src/ExcelMcp.Client -- 列表
dotnet run --project src/ExcelMcp.Client -- 搜索 "产品名称"
dotnet run --project src/ExcelMcp.Client -- 预览 销售 --行数 10

直接运行MCP服务器

用于与其他MCP兼容客户端集成：

# 直接运行stdio MCP服务器
dotnet run --project src/ExcelMcp.Server -- --workbook "D:/Data/sample.xlsx"

示例mcp.json用于VS Code

{
  "servers": {
    "excel-workbook-mcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/src/ExcelMcp.Server/bin/Debug/net9.0/ExcelMcp.Server.exe",
      "args": [
        "--workbook",
        "${input:excel-workbook-path}"
      ]
    }
  },
  "inputs": [
    {
      "id": "excel-workbook-path",
      "type": "promptString",
      "description": "要加载的Excel工作簿的完整路径",
      "default": "D:/Downloads/sampledata.xlsx"
    }
  ]
}

打包

将每个组件打包为独立的单文件可执行程序：

pwsh -File scripts/package-server.ps1   # MCP服务器
pwsh -File scripts/package-client.ps1   # CLI客户端
pwsh -File scripts/package-skagent.ps1  # CLI代理（推荐 - 已充分测试 ✅）
pwsh -File scripts/package-chatweb.ps1  # Web聊天（功能正常 - 需要测试 ⚠️）

每个脚本发布到dist/<rid>/<AppName>，带有特定平台的启动助手（.ps1，.sh，.bat）。

推荐用户： 从package-skagent.ps1（CLI代理）开始，因为它已经经过了充分测试。

对于开发者： Web聊天在Linux/树莓派上运行，但在广泛使用之前需要验证测试。参见WEB-CHAT-ROADMAP.md以获取测试检查清单。

根据需要传递-Runtime（例如，linux-x64，linux-arm64）或-SkipZip。

与代理集成

指向打包的服务器或使用CLI/web应用启动器来协商工作簿/服务器路径。所有工具（excel-list-structure，excel-search，excel-preview-table）和资源（excel:// URI）遵循MCP规范，因此它们可以与OpenAI代理、MCP桥接器或任何兼容的编排器一起使用。

致谢

使用了这些出色的开源项目：

Spectre.Console - 提供美观、多彩的CLI界面和丰富的格式化
语义内核 - Microsoft的LLM编排框架
ClosedXML - 不依赖Office的Excel文件操作
模型上下文协议 - Anthropic的AI到工具通信标准

特别感谢Spectre.Console团队使终端应用程序变得美丽！🎨

入门指南

1. 构建项目

dotnet build
dotnet test

2. 创建示例工作簿

pwsh -File scripts/create-sample-workbooks.ps1

这将在test-data/中创建三个测试工作簿：

ProjectTracking.xlsx - 任务、项目、时间日志
EmployeeDirectory.xlsx - 员工和部门数据
BudgetTracker.xlsx - 收入和支出跟踪

参见test-data/README.md以获取详细信息和示例查询。

3. 运行语义内核代理

# 使用本地LLM（推荐：LM Studio，Ollama）
dotnet run --project src/ExcelMcp.SkAgent -- --workbook test-data/ProjectTracking.xlsx

# 或设置环境变量
$env:LLM_BASE_URL = "http://localhost:1234/v1"
$env:LLM_MODEL_ID = "local-model"
$env:EXCEL_MCP_WORKBOOK = "test-data/ProjectTracking.xlsx"
dotnet run --project src/ExcelMcp.SkAgent

4. 尝试一下

> 哪些任务是高优先级？
> 显示所有工程部门的员工
> 加载test-data/BudgetTracker.xlsx
> 总收入是多少？
> 帮助

关键功能探索：

🔧 调试日志 - 查看LLM调用的确切工具
🔄 工作簿切换 - 使用加载，打开或切换命令
🎨 彩色输出 - 绿色横幅，彩色消息
📊 示例工作簿 - 包含真实测试数据

文档

用户指南 - 完整的设置和工作流程指南
SK代理快速入门 - CLI代理教程
调试日志 - 了解工具调用
示例工作簿 - 测试数据参考
未来功能 - 计划增强

故障排除

常见问题及解决方案：

LLM未调用工具/编造数据：

参见docs/SkAgentTroubleshooting.md
尝试更好的模型：gpt-4，phi-4，llama-3.1-8b-instruct
检查调试日志：⚠️ 未调用任何工具表示模型问题

搜索返回无结果：

已修复！空字符串错误已解决
搜索默认不区分大小写
调试日志显示：caseSensitive=False

计算错误：

模型限制 - 本地模型可能难以进行数学计算
调试日志显示工具调用但计算不正确
使用GPT-4进行准确计算

参见docs/UserGuide.md以获取详细的流程示例、环境变量和故障排除笔记。

致谢

该项目依赖于出色的ClosedXML库（https://github.com/ClosedXML/ClosedXML），作为其核心引擎，用于读取和写入Excel工作簿（.xlsx文件）。 ClosedXML建立在OpenXML SDK之上，提供了简洁直观的API，使得此MCP服务器能够在不需要Microsoft Excel或任何COM自动化的情况下与Excel数据进行交互。

通过此MCP服务器公开的所有工作簿操作，如读取行、写入单元格值或添加数据，内部均由ClosedXML驱动。

非常感谢ClosedXML维护者和贡献者的持续工作，他们为.NET生态系统中最可靠和面向开发者的Excel库之一做出了贡献。您的项目使得像这样的工具能够在轻量级环境中跨平台运行成为可能。