Content
# SheetSpec
<!-- mcp-name: io.github.helloo1568/sheetspec -->
**English** | [简体中文](README.zh-CN.md)
[](https://github.com/helloo1568/SheetSpec/actions/workflows/test.yml)
[](https://pypi.org/project/sheetspec/)
[](https://pypi.org/project/sheetspec/)
[](LICENSE)
> **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
```
## 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](https://docs.astral.sh/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](docs/agent-integrations.md#codex),
[Claude Code](docs/agent-integrations.md#claude-code),
[Cursor](docs/agent-integrations.md#cursor), and
[OpenCode](docs/agent-integrations.md#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.
## How the Agent Gate works
```mermaid
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
```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](THIRD_PARTY_NOTICES.md).
- [Contributing](CONTRIBUTING.md)
- [Changelog](CHANGELOG.md)
- [Release process](docs/releasing.md)
- [Security policy](SECURITY.md)
```text
License: MIT
```
