io.github.helloo1568/sheetspec MCP Server

The io.github.helloo1568/sheetspec MCP server provides contract testing and quality gates for spreadsheets created by AI agents. It is positioned around spreadsheet validation workflows, including Excel and XSLX-focused tooling concepts, using Python libraries such as openpyxl where applicable.

🛠️ Key Features

Contract testing for AI-generated spreadsheets
Quality gates for spreadsheet outputs
Spreadsheet validation for Excel/XLSX workflows

🚀 Use Cases

Validate spreadsheets produced by AI agents
Enforce data quality requirements in spreadsheet generation pipelines
Apply quality gate checks before accepting spreadsheet artifacts

⚡ Developer Benefits

Supports contract-testing and data-quality practices for spreadsheets
Enables structured validation expectations for excel and xlsx outputs
Fits MCP-based development workflows related to spreadsheet validation

⚠️ Limitations

Source data provides no details on available tools, configuration, or runtime behavior beyond the contract testing and quality gate scope.

SheetSpec

English | 简体中文

Catch spreadsheet delivery errors before an AI agent says "done."

SheetSpec validates .xlsx workbooks against reviewed, lockable acceptance contracts. It catches missing formulas, duplicate identifiers, wrong totals, invalid data types, and unauthorized template edits, then returns structured issues at worksheet, cell, or range level that an agent can repair.

It provides deterministic Excel/XLSX validation, contract testing, and quality gates for workbooks created or modified by AI agents. It is not another Excel chatbot or a silent auto-fixer.

text

user requirements -> reviewed contract -> locked acceptance target
-> agent creates or edits Excel -> SheetSpec validates independently
-> structured repair issues -> agent repairs and revalidates -> deliver after passing

SheetSpec Agent Gate demo

Why agents need an independent gate

An agent can create a workbook that opens successfully and looks plausible while still shipping hidden errors. Asking the same agent to "check its work" is useful, but it is not an independent acceptance test: the agent can overlook the same mistake, reinterpret the requirement, or change the target while repairing the file.

SheetSpec separates creation from acceptance:

Capability	Risk addressed
Reviewed contracts	Business requirements being guessed from workbook structure
Contract locks	Acceptance-target changes going undetected after work begins
Independent validation	"The file saved" being treated as "the task is correct"
Structured repair issues	Vague retries without a rule, worksheet, cell, expected value, or actual value
Protected baseline ranges	Unauthorized template value or formula changes going undetected

SheetSpec validates only the rules you declare. A passing result means the declared contract passed; it does not claim that every unstated business assumption is correct.

Try SheetSpec

SheetSpec requires Python >=3.11,<3.15. With uv, you can run it without installing it permanently.

1. Verify the CLI

bash

uvx sheetspec --version

Or install it with pip:

bash

pip install sheetspec

2. Run the included broken/fixed demo

bash

git clone --depth 1 https://github.com/helloo1568/SheetSpec.git
cd SheetSpec
uv sync
uv run python examples/create_demo.py

uv run sheetspec lock examples/sales-report.spec.yaml \
  --baseline examples/sales-report-template.xlsx \
  --output examples/sales-report.spec.lock.demo.json

uv run sheetspec check examples/sales-report-broken.xlsx \
  --spec examples/sales-report.spec.yaml \
  --lock examples/sales-report.spec.lock.demo.json \
  --format text

uv run sheetspec check examples/sales-report-fixed.xlsx \
  --spec examples/sales-report.spec.yaml \
  --lock examples/sales-report.spec.lock.demo.json \
  --format json

The broken workbook demonstrates missing month headers, duplicate orders, text stored as an amount, missing and inconsistent formulas, a wrong total, and protected-template changes. The fixed workbook passes the same locked contract. Its JSON summary includes:

json

{
  "status": "passed",
  "summary": {
    "checks": 12,
    "passed": 12,
    "warnings": 0,
    "errors": 0,
    "skipped": 0,
    "total_issues": 0
  }
}

3. Validate your own workbook

bash

uvx sheetspec inspect report.xlsx --format json
uvx sheetspec init report.xlsx --output report.spec.yaml
# Review report.spec.yaml before treating it as the acceptance target.
uvx sheetspec lock report.spec.yaml --output report.spec.lock.json
uvx sheetspec check report.xlsx \
  --spec report.spec.yaml \
  --lock report.spec.lock.json \
  --format json

init drafts checks from workbook structure; it does not infer your complete business intent. Review the contract before locking it.

Use it with your agent

Run SheetSpec as a local STDIO MCP server:

bash

uvx sheetspec mcp

Copy-paste setup instructions are available for Codex, Claude Code, Cursor, and OpenCode.

The recommended delivery loop is:

text

inspect -> draft/review -> lock -> create/edit -> validate
-> repair ERROR -> validate again -> deliver

MCP makes SheetSpec callable. The included Agent Skill defines when it should be called, and CI can enforce the same acceptance contract after the agent finishes.

Validation output agents can repair

Every issue uses a stable machine-readable shape:

json

{
  "issue_code": "duplicate-value",
  "rule_id": "order-id-unique",
  "severity": "error",
  "sheet": "Raw Data",
  "cell": "A4",
  "range": null,
  "message": "发现重复值：SO-002",
  "expected": "unique",
  "actual": "SO-002",
  "suggestion": null,
  "related_cells": ["A3", "A4"]
}

Results are deterministically ordered and capped at 500 visible issues while preserving the total issue count.

SheetSpec validation report preview

How the Agent Gate works

flowchart LR
  A["Describe requirements"] --> B["Draft acceptance contract"]
  B --> C["Human reviews contract"]
  C --> D["Lock contract"]
  D --> E["Agent creates or edits Excel"]
  E --> F["Validate independently"]
  F -->|failed| G["Read structured issues and repair"]
  G --> F
  F -->|passed| H["Deliver workbook and report"]

The contract lock stores SHA-256 hashes for the normalized contract and optional baseline workbook. It detects changes; Git history, review, and CI remain the security boundary.

SheetSpec architecture

Contract example

yaml

version: "0.1"
name: Annual sales report acceptance
baseline: sales-report-template.xlsx

checks:
  - id: required-sheets
    type: required_sheets
    sheets: [Raw Data, Monthly Summary]

  - id: order-id-unique
    type: unique_values
    sheet: Raw Data
    range: A2:A500

  - id: amount-formulas
    type: formulas_required
    sheet: Raw Data
    range: F2:F500

  - id: annual-total
    type: total_equals_sum
    sheet: Monthly Summary
    total_cell: N2
    source_range: B2:M2
    tolerance: 0.01

  - id: protect-summary-header
    type: unchanged_ranges
    sheet: Monthly Summary
    ranges: [A1:N1]
    compare: both

Included rules

Rule	Purpose
`required_sheets`	Require worksheets
`required_columns`	Require exact column names
`required_cells`	Require non-empty cells or exact values
`no_blank_values`	Reject blank cells in a range
`unique_values`	Require unique values
`allowed_values`	Restrict values to an allowlist
`data_type`	Validate numbers, text, dates, booleans, or formulas
`formulas_required`	Require formulas
`formula_consistency`	Detect structural formula outliers
`total_equals_sum`	Compare a total with the numeric source range
`unchanged_ranges`	Protect baseline values and formulas

CLI reference

bash

sheetspec --version
sheetspec inspect report.xlsx --format json
sheetspec init report.xlsx --output report.spec.yaml
sheetspec lock report.spec.yaml --output report.spec.lock.json
sheetspec check report.xlsx --spec report.spec.yaml --lock report.spec.lock.json --format json
sheetspec diff before.xlsx after.xlsx --format json
sheetspec report report.xlsx --spec report.spec.yaml --output report.html
sheetspec mcp

Exit codes:

text

0  validation passed
1  one or more error-level rules failed
2  invalid file, contract, baseline, or lock
3  internal error

MCP reference

Generic configuration:

json

{
  "mcpServers": {
    "sheetspec": {
      "command": "uvx",
      "args": ["sheetspec", "mcp"]
    }
  }
}

Tools:

inspect_workbook
draft_workbook_spec
validate_workbook
compare_workbooks
generate_validation_report

The test suite launches a real STDIO subprocess, initializes an MCP client session, lists all tools, and calls workbook inspection and validation end to end.

Agent Skill

Install skills/sheetspec/ in the agent's skill directory. The skill instructs the agent not to change the contract merely to pass validation, edit the workbook during validation, claim formula results were verified when cached values are missing, or claim delivery success while error-level issues remain. Contract locks and CI provide the enforceable checks around that workflow.

Technical boundaries

.xlsx workbooks are read-only; SheetSpec does not modify the source workbook.
openpyxl does not recalculate arbitrary Excel formulas.
Complex external formulas, VBA, Power Query, and pivot-table semantics are outside the v0.1 scope.
passed means all declared checks passed, not that the entire business model is universally correct.
Workbooks above 50 MB and rules covering more than 100,000 cells are rejected.
Results expose at most 500 visible issues while preserving the total issue count.

Roadmap

0.2: optional LibreOffice recalculation, JUnit/SARIF output, and rule plugins;
0.3: more templates, interactive MCP reports, and constrained repair helpers;
long term: a standard quality gate for spreadsheet-producing agents.

Open source

SheetSpec uses an original validation engine and depends on openpyxl, Pydantic, PyYAML, Typer, Jinja2, and the MCP Python SDK. See THIRD_PARTY_NOTICES.md.

text

License: MIT

io.github.helloo1568/sheetspec MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

SheetSpec

Why agents need an independent gate

Try SheetSpec

1. Verify the CLI

2. Run the included broken/fixed demo

3. Validate your own workbook

Use it with your agent

Validation output agents can repair

How the Agent Gate works

Contract example

Included rules

CLI reference

MCP reference

Agent Skill

Technical boundaries

Roadmap

Open source

Install