attestation MCP server
Commit Nov 4, 2026Provides auditable research provenance, experiment ledgers, and symbolic math tools for scientists using local-first MCP tools.
Also known as mgoldey/attestation
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 4, 2026
- License
- MIT
What is attestation MCP?
attestation provides auditable research provenance, experiment ledgers, and symbolic math tools for scientists using local-first MCP tools.
Summary generated from the project's README
About attestation MCP server
Scientists who write research papers and manage experimental data can use this tool to maintain auditable provenance and local knowledge graphs. It functions as a local-first system that connects prose to evidence, ensuring that numbers in a draft match the original results files. The server provides 54 MCP tools categorized into surfaces like feed, provenance, knowledge, and symbolic math, allowing AI agents to interact with research data without any information leaving the machine.
Users can manage computational experiments through an experiment ledger that reads existing directories from W&B, MLflow, Sacred, DVC, or Hydra. This ledger ranks different arms of a sweep and provides caveats regarding statistical variance. While the provenance and ledger features run via pure local computation using Python 3.12+ and uv, advanced features like the personalized reading feed and knowledge graph require Ollama to run models locally. For those without a GPU, the system can connect to an OpenAI-compatible endpoint via the LLM_BASE_URL configuration.
What you can do with it
- 1Verify research claimsAn AI agent can check if a specific number in a markdown document is supported or contradicted by a local CSV or JSON results file.
- 2Rank experimental sweepsA developer can ask an agent to analyze experiment directories from MLflow or Hydra to find the best performing configuration.
- 3Manage research readingUsers can maintain a personalized science feed that uses cosine similarity to rank new papers from RSS or arXiv sources.
- 4Perform symbolic mathAn agent can execute mathematical derivations within a sandboxed environment to assist with scientific calculations.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ATTEST_DB
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemgoldey/attestation is public and reachablegithub.com/mgoldey/attestation ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-04github.com/mgoldey/attestation ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubattestation
attestation makes research provenance auditable and fully local, for any scientist who reads papers, keeps results files, and writes claims. It keeps a personalised science feed and a knowledge graph built from what you read; traces a number in your draft to the results file it came from and a citation key to your bibliography; and does symbolic derivations — all exposed to agents as MCP tools, with nothing leaving the machine. For computational work it adds an experiment ledger: it reads the runs you already have on disk (results files and W&B/MLflow/Sacred/DVC/Hydra directories) and ranks the arms of a sweep with caveats. The feed, provenance and symbolic tools assume nothing about your field; only the ledger assumes you run experiments.
Try it in 60 seconds
No model server, no ingest, no config — the run ledger and claim checker are
pure local computation over files that already exist. This uses the sweep in
examples/workspace:
git clone https://github.com/mgoldey/attestation ~/attestation && cd ~/attestation && uv sync
export ATTEST_DB=/tmp/attest-demo.db
uv run attest runs scan --root examples/workspace
uv run attest runs compare kdsweep
uv run attest claims examples/workspace/speech-distill/FINDINGS.md
Measured at 0.94s total with no LLM backend reachable at all. What it says:
kdsweep — ranked by val_loss (lower_is_better), all arms on librispeech-100h
winner: kdsweep_t4
caveat: the top two arms differ by 0.03 (1.4%) -- too close to call from
these numbers alone
caveat: each arm is a single run; no seed replication, so this ranking
cannot separate configuration from run-to-run variance
7 claim(s): 1 contradicted, 5 supported, 1 unsupported
1 malformed
attest claims exits 1 on a contradiction (so it can gate a commit), which is
why a && chain stops there.
Every tracker ranks arms. The second caveat — this ranking cannot separate
configuration from noise — is the part that earns its keep, and the
contradicted verdict is a number in a document that no longer matches the
artifact it came from.
What it does
Three things for every scientist, one for computational experiments, and one way to use all of them:
For every scientist
- The feed and knowledge graph rank a personalised reading list from cosine similarity plus click-trained terms, and derive a concept graph from the same tagging pass — no separate content pipeline. Any RSS/Atom source; arXiv is a default, not a requirement. See docs/guides/feed.md.
- Data and citation provenance check a number in your prose against
the results file that produced it — a JSON or CSV under
results/from any instrument, script or spreadsheet export, not only a training run — with one of five verdicts (supported,contradicted,unsupported,ambiguous,stale), and lint a citation key against your BibTeX or Zotero library. See docs/guides/claims-and-citations.md. - Symbolic derivations run in a sandboxed subprocess with a timeout and
memory cap, never
eval-ing input. Seesym.*in docs/guides/agents.md.
For computational experiments
- The experiment ledger reads runs from artifacts already on disk — no
instrumentation, no
log_metric()calls — and ranks the arms of a sweep with caveats rather than a silent verdict. Five tracker layouts (W&B, MLflow, Sacred, DVC, Hydra) are read as conventions of their own. This is the one part that assumes you run experiments — though a plainresults/file is read the same way, so the claim checker traces every number through it. See docs/guides/ledger.md.
From an agent
- All of the above are exposed as 54 MCP tools, restricted per session into
feed/provenance/knowledge/symbolicsurfaces. See docs/guides/agents.md and the repo's ownsrc/attestation/skills/(seven skills: one per agent surface plus setup, plus two write-side skills,attestation-recordandattestation-annotate).
Install
Two tiers. The run ledger and claim checker above need only Python 3.12+
and uv — no model, no download. The feed,
tagging, and knowledge graph additionally need Ollama
running locally; attest install then pulls ~7.8 GB of models
(gemma4:e2b-it-q4_K_M 7.2 GB + embeddinggemma 621 MB) and holds ~5.4 GB
resident while warm. Skip this tier entirely if you only want provenance.
uvx attestation install # from PyPI, nothing cloned; --check diagnoses only
No GPU? Point LLM_BASE_URL at an OpenAI-compatible endpoint; --check confirms
it answers. docs/guides/install.md: that tier,
prerequisites, and the manual steps attest install automates.
Chat with it from Discord
Once attest install has run and hermes-agent
is installed, the feed answers from a phone. Four steps, all outside this repo:
-
In the Discord Developer Portal create an application and a Bot, enable the Server Members and Message Content intents on the Bot page, and copy the token. Then
hermes gateway setup, pick Discord, and paste the token plus your own Discord user ID (not the bot's). -
Allowlist the feed surface for chat in
~/.hermes/config.yaml, so each turn carries 2 tool schemas instead of 131:mcp_servers: attestation-feed: {enabled: true} # attest install wrote the entry, disabled platform_toolsets: discord: [attestation-feed] # an MCP server here is an allowlist -
systemctl --user restart hermes-gateway, then invite the bot withhttps://discord.com/oauth2/authorize?client_id=<APP_ID>&scope=bot&permissions=274878286912and DM it "What are your recommendations today?"
Measured on gemma4:e2b over a GTX 1080: a turn dropped from 54-249s at 15-29k prompt tokens to 23-28s at ~5k. The other half of that saving is keeping the model resident, since a cold load alone was 30s. Full recipe, Telegram variant, and the keep-alive timer in docs/guides/agents.md.
Golden paths
A golden path is a directory under examples/ with a README in seven fixed
sections, a run.sh that runs those README commands verbatim, and its own
inputs on disk — tests/test_golden_paths.py runs every one whose
prerequisite is none and pins a line of its output, so the docs are what
the suite asserts. examples/README.md is the full catalogue, with a runtime
for each. Fourteen paths, grouped by prerequisite:
None — pure local computation:
agents/— the install doctor,attest emit's configs, one surface over stdiocitations/— a BibTeX library, a draft, one citation key that resolves nowheredvc/— a realdvc repropipeline, fourforeacharms rankedflows/— forty items scored, every MCP tool over stdio, four MLflow armshydra/— a real Hydra--multirunsweep, four arms rankedmlflow/— a real MLflow directory, four arms, one contradicted claimmodel-servers/—attest ingest/tagagainst an in-process stub servermolecular-ai/— a molecular-AI library generated from real papers, synced, searched, walked by citation edge, graphedranking/— twenty hand-built rows,rank.rank_rows's classifier-only AUC beside the blended-order AUCsacred/— a real SacredFileStorageObserverdirectory, four arms rankedtensorflow/— a real Keras/CSVLogger run, four learning-rate arms rankedwandb/— a real offline W&B run directory, four arms rankedworkspace/— the ledger and claim checker, three claims wrong on purpose
A model server at LLM_BASE_URL: every path above needs no model; this
one does, to score prompts against a running LLM.
prompt-evals/— the tagging prompt's dev score and the transfer gate
See examples/README.md for what each demonstrates, and demos/ for six
scripts that record these surfaces on video. The most thorough is flows/:
uv run --group examples python examples/flows/run_all.py --offline
examples/flows/README.md explains each flow;
examples/flows/RESULTS.md records what the live run measured.
Documentation
uv run --group docs mkdocs serve runs a browsable site over everything
below. The guides, one per question:
- docs/guides/install.md — set up with or without a model server
- docs/guides/agents.md — MCP tools, surfaces, the skill
- docs/guides/ledger.md — reading and ranking runs
- docs/guides/claims-and-citations.md — checking a draft
- docs/guides/feed.md — how ranking works
- docs/guides/evals.md — how prompts are measured
- docs/guides/testing.md — the gates and CI jobs
Plus docs/concepts.md for first-ten-minutes vocabulary, the
CLI reference (docs/reference/cli.md) and API reference under docs/, design
records under docs/superpowers/specs/, measurement lessons
(docs/measurement-lessons.md), CONTRIBUTING.md for the
gates and conventions, and CHANGELOG.md for what's landed.
Licence
MIT — see LICENSE.
attestation MCP questions
Do I need a model server to use the claim checker or run ledger?
No, the run ledger and claim checker are pure local computation over existing files and do not require a model server.
Can I use it without a GPU?
Yes, you can point the LLM_BASE_URL to an OpenAI-compatible endpoint if you do not have a GPU.