SheetSpec

<!-- mcp-name: io.github.helloo1568/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.

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

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

uvx sheetspec --version

Or install it with pip:

pip install sheetspec

2. Run the included broken/fixed demo

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:

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

3. Validate your own workbook

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:

uvx sheetspec mcp

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

The recommended delivery loop is:

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:

{
  "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.

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.

Contract example

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

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:

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:

{
  "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.

• Contributing
• Changelog
• Release process
• Security policy

License: MIT