assurance-mcp

Coverage and staleness checks as MCP tools — arithmetic only, read-only inside folders you grant.

Install

pip install assurance-mcp
# or: pip install assurance   # every tool

{
  "mcpServers": {
    "assurance": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "assurance_mcp.server", "--root", "/absolute/path/to/your/reports"]
    }
  }
}

--root is required for folder tools (repeat for more roots, or set ASSURANCE_MCP_ROOTS). A filesystem root (/, C:\) is refused. Restart the client after editing the config.

Quick start

Five tools. Real output from check_set_coverage (no folder needed):

complete: false · read 2 of 4
"2 of 4 documents this question spans — not in the retrieved set: amendment-2.md, amendment-3.md"
unexpected: ["globex/msa.md"]

That is what this call returns:

from assurance_mcp.checks import check_set_coverage

result = check_set_coverage(
    expected=["msa.md", "amendment-1.md", "amendment-2.md", "amendment-3.md"],
    found=["msa.md", "amendment-1.md", "globex/msa.md"],
    scope="documents this question spans",
    where="the retrieved set",
)
assert result["complete"] is False
assert result["read"] == 2
assert "amendment-2.md" in result["summary"]

What it checks

tool	answers	needs `--root`
`check_set_coverage_tool`	did any two sets cover each other?	no
`check_retrieval_coverage_tool`	did retrieval hit every document the question spans?	no
`check_coverage_tool`	which periods are in this folder?	yes
`check_staleness_tool`	do figures still match a source you name?	yes
`list_dated_files_tool`	which periods does this folder hold?	yes

In CI

The MCP server itself is not a CI gate. Use assurance check / assurance diff from assurance-cli for exit codes:

exit	means
`0`	checked clean (or not asked to fail)
`1`	gap or unverifiable
`2`	could not run

Limits

expected is never inferred. You name the denominator.
CSV/TSV only for profiling — no XLSX dependency here.
Staleness needs recorded facts, or the answer is uncheckable.
No writes, no network. A model cannot widen --root.
Folder tools refuse until --root (or ASSURANCE_MCP_ROOTS) is set.

See the root README and CHANGELOG.md.

Release files for assurance-mcp 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for assurance-mcp 0.5.1
File	Size	Uploaded
assurance_mcp-0.5.1.tar.gz	25.0 kB	Sep 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for assurance-mcp 0.5.1
File	Interpreter	ABI	Platform	Reset
assurance_mcp-0.5.1-py3-none-any.whl 16.5 kB Sep 24, 2026	Python 3	none	any	Details

Total release size: 41.5 kB

Release files / assurance_mcp-0.5.1.tar.gz

Download URL	assurance_mcp-0.5.1.tar.gz
Size	25.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`605e187efb3c2cb55f8848af1dc8ede2f2a0e8c5c3dc80206062a416a30301b8`
BLAKE2b-256 checksum How to use checksums	`afb9c630adeccc56c3aafb31e2ebc548add893b21db419253ba6347dcddb67e6`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/i-ops-hq/assurance
Publishing commit: github.com/i-ops-hq/assurance/tree/551db6a28cea20c75a1e6a7390469d0251dd7bb7

Workflow

Publishing configuration: github.com/i-ops-hq/assurance/blob/551db6a28cea20c75a1e6a7390469d0251dd7bb7/.github/workflows/publish.yml
Publishing logs: github.com/i-ops-hq/assurance/actions/runs/36051671630/attempts/1

Artifact

Subject: assurance_mcp-0.5.1.tar.gz
SHA-256 checksum: 605e187efb3c2cb55f8848af1dc8ede2f2a0e8c5c3dc80206062a416a30301b8 Verifying attestations

Release files / assurance_mcp-0.5.1-py3-none-any.whl

Download URL	assurance_mcp-0.5.1-py3-none-any.whl
Size	16.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d53bbf0205d5929634f08ecc8b737db3c816f8339e1047014ae9e8191efb0b31`
BLAKE2b-256 checksum How to use checksums	`c9a005fc2e24f88ee01f8914fad782330547ff0ba57a8d525741d9833fe19ebd`
Upload date	Sep 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/i-ops-hq/assurance
Publishing commit: github.com/i-ops-hq/assurance/tree/551db6a28cea20c75a1e6a7390469d0251dd7bb7

Workflow

Publishing configuration: github.com/i-ops-hq/assurance/blob/551db6a28cea20c75a1e6a7390469d0251dd7bb7/.github/workflows/publish.yml
Publishing logs: github.com/i-ops-hq/assurance/actions/runs/36051671630/attempts/1

Artifact

Subject: assurance_mcp-0.5.1-py3-none-any.whl
SHA-256 checksum: d53bbf0205d5929634f08ecc8b737db3c816f8339e1047014ae9e8191efb0b31 Verifying attestations