ggen MCP

电子表格MCP

     

用于电子表格分析和编辑的MCP服务器。专为LLM试剂设计的超薄、令牌高效的工具表面。

为什么？

将50000行电子表格转储到LLM上下文中是昂贵的，通常是不必要的。大多数电子表格任务都需要外科手术：找到一个区域，分析其结构，读取过滤后的切片。此服务器公开了允许代理使用的工具 发现→ 个人资料→ 提取 而不会在他们不需要的细胞上燃烧代币。

• 全力支持： .xlsx, .xlsm （通过 umya-spreadsheet)
• VBA源代码检查（可选）： .xlsm 通过 SPREADSHEET_MCP_VBA_ENABLED=true / --vba-enabled （解析嵌入式 xl/vbaProject.bin 通过 ovba)
• 仅限发现： .xls, .xlsb （枚举，未解析）

建筑

• LRU缓存 将最近访问的工作簿保存在内存中（可配置容量）
• 延迟表度量 每张表计算一次，跨工具重复使用
• 按需区域检测 跑步为 sheet_overview 并缓存为 region_id 查找(find_value, read_table, table_profile)

刀具表面

VBA支持（只读）

VBA工具包括 默认禁用。启用后，服务器可以从中提取和解析嵌入式VBA项目 .xlsm 文件和返回模块源代码。

通过以下方式启用：

• CLI： --vba-enabled
• 环境： SPREADSHEET_MCP_VBA_ENABLED=true

工具：

• vba_project_summary：列出模块+基本项目元数据
• vba_module_source：返回单个模块的分页源

笔记：

• 确实如此 不 执行宏；它只读取和返回文本。
• 响应的大小有限；通过模块源代码进行页面浏览。

写入和重新计算支持

编写工具允许“假设”分析：分叉工作簿、编辑单元格、通过LibreOffice重新计算公式，并对结果进行比较。为了安全起见，您可以为高保真回滚创建检查点，并显式应用预览（分阶段）更改。

启用写入工具

始终使用 :full 用于写入/重新计算功能的Docker镜像：

docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:full

Docker镜像包括LibreOffice，其中包含可靠重新计算所需的预配置宏。在Docker之外运行需要手动设置LibreOffice（宏信任、无头配置），不建议这样做。

写入工具

令牌高效写入工作流

find_formula分页

{
  "tool": "find_formula",
  "arguments": {
    "workbook_or_fork_id": "wb-23456789ab",
    "sheet_name": "Calc",
    "query": "SUM(",
    "include_context": false,
    "limit": 20,
    "offset": 0
  }
}

get_changeset摘要+过滤器

{
  "tool": "get_changeset",
  "arguments": {
    "fork_id": "fork-23456789abcd",
    "summary_only": true,
    "exclude_subtypes": ["recalc_result"],
    "limit": 200,
    "offset": 0
  }
}

Docker路径（导出+截图）

在Docker中运行时 --workspace-root /data 以及类似主机的挂载 -v /path/to/workbooks:/data:

• Fork工作文件位于 /tmp/mcp-forks 容器内部（在主机上不可见）。
• save_fork.target_path 已解决 workspace_root （Docker默认值： /data).

使用相对路径，如 out.xlsx （或 exports/out.xlsx)写回主机上已挂载的文件夹。

• screenshot_sheet 在下面写入PNG screenshots/ 在 workspace_root （Docker默认值： /data/screenshots/).

屏幕截图工具

screenshot_sheet 捕获矩形范围的视觉PNG，通过LibreOffice在 :full 图像。PNG会自动裁剪以删除页面空白，并保存在 screenshots/ 在工作空间中。注意：该工具返回a file:// 服务器文件系统上的URI；通过Docker运行时，将其视为容器路径，并在挂载的工作区文件夹下查找PNG（例如。 screenshots/.png).

论据：

• workbook_or_fork_id （必填；接受workbook_id或fork_id）
• sheet_name （必填）
• range （可选，默认 A1:M40)

限制和行为：

• 每个屏幕截图的最大范围： 100行×30列。如果超过，该工具将失败，并建议使用平铺的子范围进行请求。
• 导出/裁剪后，像素保护会拒绝太大而无法可靠使用代理的图像（默认最大值 4096px 在一侧或 12英里 面积）。在拒绝时，该工具会返回较小范围的建议。
• 通过env变量覆盖像素保护： SPREADSHEET_MCP_MAX_PNG_DIM_PX, SPREADSHEET_MCP_MAX_PNG_AREA_PX.

看 docs/RECALC.md 了解架构细节。

示例

请求： 分析检测到的区域

{
  "tool": "table_profile",
  "arguments": {
    "workbook_id": "wb-23456789ab",
    "sheet_name": "Q1 Actuals",
    "region_id": 1,
    "sample_size": 10,
    "sample_mode": "distributed"
  }
}

答复：

{
  "sheet_name": "Q1 Actuals",
  "headers": ["Date", "Category", "Amount", "Notes"],
  "column_types": [
    {"name": "Date", "inferred_type": "date", "nulls": 0, "distinct": 87},
    {"name": "Category", "inferred_type": "text", "nulls": 2, "distinct": 12, "top_values": ["Payroll", "Marketing", "Infrastructure"]},
    {"name": "Amount", "inferred_type": "number", "nulls": 0, "min": 150.0, "max": 84500.0, "mean": 12847.32},
    {"name": "Notes", "inferred_type": "text", "nulls": 45, "distinct": 38}
  ],
  "row_count": 1247,
  "samples": [...]
}

代理现在知道列类型、基数和值分布，而无需读取1247行。

推荐的代理工作流程

1. list_workbooks → list_sheets → workbook_summary 用于定向
2. sheet_overview 得到 detected_regions （ids/界限/种类/置信度）
3. table_profile → read_table 随着 region_id，小 limit，以及 sample_mode (distributed 首选）
4. 使用 find_value （标签模式）或 range_values 用于有针对性的拉动
5. 保留 sheet_page 用于未知布局或计算器检查；更喜欢 compact/values_only
6. 保持有效载荷较小；页面/过滤器而非整页读取

区域检测

电子表格通常在一张表上包含多个逻辑表、参数块和输出区域。服务器会自动检测到这些：

证明优先代码生成（v2.1）

新：ggen v2.1介绍 证明优先编译器：加密收据、保护内核和默认预览工作流。

主要特点

• 默认预览：未经明确批准，不得写作(preview: false)
• 保护内核：发电前进行7次安全检查（G1-G7）

- G1：路径安全| G2：输出重叠| G3：模板编译 - G4：海龟解析| G5：SPARQL执行| G6：决定论| G7：界限

• 加密收据：用于审计合规性的SHA-256哈希（SOC2，ISO 27001）
• First Light报道：每个编译的1页标记/JSON摘要
• 收据验证：具有7个验证检查的独立工具（V1-V7）
• Jira集成：可选编译器阶段（dry_run/create/sync模式）
• 权利提供者：基于能力的许可（免费/付费/企业）

快速入门（先证明）

# Preview (default) - no writes
sync_ggen { workspace_root: "." }

# Review report
cat ./ggen.out/reports/latest.md

# Apply if satisfied
sync_ggen { workspace_root: ".", preview: false }

# Verify receipt (7 checks)
verify_receipt { receipt_path: "./ggen.out/receipts/latest.json" }

输出结构

./ggen.out/
├── reports/latest.md       # First Light Report (human-readable)
├── receipts/latest.json    # Cryptographic receipt (SHA-256 hashes)
└── diffs/latest.patch      # Unified diff (preview mode)

文档（v2.1）

• 证明优先编译器 （~2000 LOC）-完整指南
• 保护内核 （~900 LOC）-解释了7项安全检查
• First Light报告 （~800 LOC）-报告格式参考
• 收据验证 （~700 LOC）-7次验证检查
• 权利提供者 （~600 LOC）-许可证制度
• 迁移指南v2.1 （~1500 LOC）-v2.0→ v2.1升级

______________________________________________________________________

本体生成（ggen集成）

更新：此MCP服务器包括本体驱动的代码生成功能，由 根.从RDF本体、Zod模式或OpenAPI规范生成类型安全的Rust代码。

快速开始

# Validate RDF ontology
validate_ontology { ontology_path: "ontology/domain.ttl", strict_mode: true }

# Generate entity from Zod schema
generate_from_schema {
  schema_type: "zod",
  schema_content: "z.object({ id: z.string().uuid(), name: z.string() })",
  entity_name: "Product",
  features: ["serde", "validation", "builder"]
}

# Generate API from OpenAPI spec
generate_from_openapi {
  openapi_spec: "openapi/api.yaml",
  generation_target: "full",
  framework: "rmcp"
}

# Full ontology sync (13-step pipeline)
sync_ontology {
  ontology_path: "ontology/",
  audit_trail: true,
  validation_level: "strict"
}

可用工具

文档

• MCP工具使用指南 -完整的工具参考，包括模式和错误代码
• 工作流示例 -5个真实世界的工作流程和代码示例
• 验证指南 -4层验证，黄金文件测试

示例工作流程

// 1. Define schema
let schema = r#"z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  age: z.number().int().min(18)
})"#;

// 2. Preview generation
preview_generation {
  generation_config: {
    tool: "generate_from_schema",
    arguments: { schema_content: schema, entity_name: "User" }
  },
  show_diffs: true
}

// 3. Generate code
generate_from_schema {
  schema_type: "zod",
  schema_content: schema,
  entity_name: "User",
  features: ["serde", "validation", "builder"]
}

// 4. Use generated code
use crate::generated::user::{User, UserBuilder};
let user = UserBuilder::new()
    .id(Uuid::new_v4())
    .email("alice@example.com")
    .age(25)
    .build()?;

跑吧 完整示例:

cargo run --example ontology_generation_example

主要特点

• 4层验证：输入防护装置→ SHACL→ 质量门→ 运行时安全
• 确定性的：相同的输入→ 始终保持相同的输出（SHA-256已验证）
• 审计跟踪：生产部署的加密收据
• 预览模式：应用更改前的安全试运行
• 金文件测试：用于回归检测的快照测试

1. 沟槽检测 --扫描分隔内容块的空行/空列
2. 递归拆分 --沿探测到的排水沟细分大面积区域
3. 边界修剪 --删除稀疏边以收紧边界
4. 标头检测 --标识标题行（包括多行合并的标题）
5. 分类 --为每个地区添加标签： data, parameters, outputs, calculator, metadata
6. 信心评分 --标题清晰、结构良好的区域得分更高

区域按工作表缓存。工具如 read_table 接受a region_id 读取范围，而无需手动指定范围。

快速开始

Docker（推荐）

发布了两种图像变体：

# Read-only (slim image)
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:latest

# Read-only + VBA tools enabled
docker run -v /path/to/workbooks:/data -p 8079:8079 -e SPREADSHEET_MCP_VBA_ENABLED=true ghcr.io/psu3d0/spreadsheet-mcp:latest

# With write/recalc support (full image)
docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:full

货物安装

# Read-only
cargo install spreadsheet-mcp
spreadsheet-mcp --workspace-root /path/to/workbooks

# Enable VBA tools
SPREADSHEET_MCP_VBA_ENABLED=true spreadsheet-mcp --workspace-root /path/to/workbooks

注： 对于写入/重新计算功能，请使用 :full Docker镜像而不是cargo安装。Docker镜像包括具有所需宏配置的LibreOffice。

从源代码构建

cargo run --release -- --workspace-root /path/to/workbooks

默认传输：HTTP流 127.0.0.1:8079终结点： POST /mcp.

使用 --transport stdio 对于CLI管道。

MCP客户端配置

克劳德代码/克劳德桌面

增添 ~/.claude.json 或项目 .mcp.json:

只读（细长图像）：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio"]
    }
  }
}

启用只读+VBA工具：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio", "--vba-enabled"]
    }
  }
}

使用写入/重新计算（完整图像）：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/path/to/workbooks:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
    }
  }
}

二进制（无Docker）：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

光标/VS代码

只读（细长图像）：

{
  "mcp.servers": {
    "spreadsheet": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest", "--transport", "stdio"]
    }
  }
}

使用写入/重新计算（完整图像）：

{
  "mcp.servers": {
    "spreadsheet": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "${workspaceFolder}:/data", "ghcr.io/psu3d0/spreadsheet-mcp:latest-full", "--transport", "stdio", "--recalc-enabled"]
    }
  }
}

二进制（无Docker）：

{
  "mcp.servers": {
    "spreadsheet": {
      "command": "spreadsheet-mcp",
      "args": ["--workspace-root", "${workspaceFolder}", "--transport", "stdio"]
    }
  }
}

HTTP模式

docker run -v /path/to/workbooks:/data -p 8079:8079 ghcr.io/psu3d0/spreadsheet-mcp:latest

通过连接 POST http://localhost:8079/mcp.

本地开发

要在不重建Docker的情况下测试本地更改：

cargo build --release

然后将MCP客户端指向二进制文件：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "/path/to/spreadsheet-mcp/target/release/spreadsheet-mcp",
      "args": ["--workspace-root", "/path/to/workbooks", "--transport", "stdio"]
    }
  }
}

配置

演出

• LRU工作簿缓存 --最近打开的工作簿保留在内存中；当容量超过时，最老的被驱逐
• 懒惰的指标 --首次访问时计算的表度量，缓存以供后续调用
• 按需区域检测 --继续运行 sheet_overview （或 region_id 查找），然后缓存
• 采样模式 — distributed 采样跨行均匀读取，无需加载所有内容
• 输出上限 — sheet_overview 默认情况下截断区域/标题；使用工具参数请求更多
• 紧凑格式 — values_only 和 compact 输出模式减少响应大小

测试

运行测试

# Run all tests
cargo test

# Run specific test suite
cargo test --test sparql_injection_tests

# Run with all features
cargo test --all-features

代码覆盖率

我们针对特定类别的目标保持高代码覆盖率：

在本地生成覆盖率报告

# Install cargo-llvm-cov
cargo install cargo-llvm-cov

# Generate HTML coverage report
./scripts/coverage.sh --html --open

# Generate LCOV for CI
./scripts/coverage.sh --lcov

# Check coverage thresholds
./scripts/coverage.sh --check

覆盖率报告在CI中自动生成，并在拉取请求时作为工件提供。

有关详细的保险范围文档，请参阅 docs/CODE_COVERAGE.md.

手动测试

# Basic functionality test
cargo test

涵盖：区域检测、区域范围工具、， read_table 边缘案例（合并的标题、过滤器、大工作表）、工作簿摘要。

本地MCP测试

要使用MCP客户端（Claude Code、Cursor等）测试本地更改，请使用在每次调用时重建Docker映像的辅助脚本：

{
  "mcpServers": {
    "spreadsheet": {
      "command": "./scripts/local-docker-mcp.sh"
    }
  }
}

集 WORKSPACE_ROOT 要覆盖默认测试目录，请执行以下操作：

WORKSPACE_ROOT=/path/to/workbooks ./scripts/local-docker-mcp.sh

这确保您始终根据最新的代码更改进行测试，而无需手动重建映像。

行为与限制

• 默认情况下为只读；写入/重新计算功能需要 --recalc-enabled 或 :full 图像
• XLSX支持写入; .xls/.xlsb 是只读的
• 内存缓存荣誉有限 cache_capacity
• 更喜欢区域范围的读取和采样，以提高令牌/延迟效率
• screenshot_sheet 需要写入/重新计算支持，每张图像最多100×30个单元格（有拆分建议）。