Provides deployment-readiness harnesses for AI patterns like document QA and structured extraction using deterministic evaluation gates.
Also known as nickjlamb/groundwork, @pharmatools/groundwork
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.4.1
- Last commit
- Nov 9, 2026
- License
- —
What is Groundwork MCP?
Groundwork provides deployment-readiness harnesses for AI patterns like document QA and structured extraction using deterministic evaluation gates.
Summary generated from the project's README
About Groundwork MCP server
Groundwork provides deployment-readiness harnesses for developers building AI patterns like document QA and structured extraction. It functions as a scaffold for creating trustworthy systems by implementing deterministic evaluation gates that prevent fabrication and schema errors from reaching production. Instead of relying on LLM judges, it uses fixed checks to ensure consistency across runs.
Users can initialize specific archetypes using the groundwork init command to set up a full harness within their own repository. The system includes a redaction pre-step via Redacta to handle privacy locally and uses OpenGATE for evaluations. It is designed to run in CI environments using the check --ci command to fail builds when regressions occur. The server can be used locally via npm or connected to AI clients like Claude Desktop through an MCP server setup using npx.
Beyond safety, the tool provides cost profiling through the groundwork cost command to measure token usage and savings. It focuses on creating a reliable floor for AI reliability rather than providing a final safety certification.
What you can do with it
- 1Preventing AI fabrication in document QAA developer can use the grounding checks to ensure an AI does not provide ungrounded numbers or unanswerable answers from a document.
- 2Validating structured data extractionYou can verify that extracted fields match a specific schema and do not contain guessed values.
- 3Automating deployment gates in CIIntegrate the harness into a GitHub Action to stop any pull request that falls below a committed performance baseline.
Written from the project's README. Every use case is checked against a quote from it.
How to install Groundwork MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Groundwork MCP in Claude Code
$ claude mcp add groundwork -- npx -y @pharmatools/groundworkInstall Groundwork MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"groundwork": {
"command": "npx",
"args": [
"-y",
"@pharmatools/groundwork"
]
}
}
}Install Groundwork MCP in VS Code
.vscode/mcp.json
{
"servers": {
"groundwork": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@pharmatools/groundwork"
]
}
}
}Install Groundwork MCP in VS Code CLI
$ code --add-mcp '{"name":"groundwork","type":"stdio","command":"npx","args":["-y","@pharmatools/groundwork"]}'Install Groundwork MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"groundwork": {
"command": "npx",
"args": [
"-y",
"@pharmatools/groundwork"
]
}
}
}Install Groundwork MCP in Codex
$ codex mcp add groundwork -- npx -y @pharmatools/groundworkInstall Groundwork MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.groundwork] command = "npx" args = ["-y", "@pharmatools/groundwork"]
Install Groundwork MCP in Gemini CLI
$ gemini mcp add -s user groundwork npx -- -y @pharmatools/groundworkInstall Groundwork MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"groundwork": {
"command": "npx",
"args": [
"-y",
"@pharmatools/groundwork"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work · What to fix for more points
- Source repository linked and reachablenickjlamb/groundwork is public and reachablegithub.com/nickjlamb/groundwork ↗Pass
- Package names this repository as its source@pharmatools/groundwork names nickjlamb/groundwork as sourcenpmjs.com/package/@pharmatools/groundwork ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-11-09github.com/nickjlamb/groundwork ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @pharmatools/groundworkPass
- No critical advisory in the package or its dependencies101 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- 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 GitHubGroundwork
Deployment-readiness harnesses for AI deployment patterns.
Redaction · evals from your real failures · a CI gate that fails fabrication
Website · Getting started · Examples · Roadmap · Contributing · Changelog
You have a prototype: your documents, a model, useful output. What you don't have is the apparatus that makes it responsible to ship — a privacy pre-step, an evaluation built from your own failures, and a gate that stops a quiet prompt tweak from deploying a system that fabricates. That apparatus usually requires an ML engineer. Groundwork scaffolds it instead.
Groundwork's units are deployment patterns, not products — think Terraform modules for trustworthy AI deployments. groundwork init <archetype> scaffolds the whole harness for a pattern:
| Archetype | The pattern | Status |
|---|---|---|
document-qa |
documents → retrieval → grounded answers → human review | ✅ shipped |
extraction |
documents → structured fields → schema validation → human review | ✅ shipped |
| research synthesis | questions → evidence → synthesis → human review | planned — see the roadmap |
Every check is deterministic: same inputs, same result, every time — no LLM judge, and no API key for the checks themselves.
Quick start — 60 seconds, no API key
git clone https://github.com/nickjlamb/groundwork.git && cd groundwork
npm install && npm run build
npm run demo # document QA: the whole loop passes, fully offline
npm run demo:break # the system starts fabricating — watch the gate go red
✗ GROUNDING demo-savings: ungrounded number "14" — not in the provided context
✗ GROUNDING demo-unanswerable-appeals: unanswerable question — the answer did not abstain
The same loop for structured extraction:
npm run demo:extraction # documents → fields, every check green
npm run demo:extraction:break # a guessed date of birth, a dropped field — red, by name
✗ EXTRACTION demo-referral: SCHEMA: /referral_date must be string
✗ EXTRACTION demo-referral: FABRICATED field "date_of_birth": document does not state it (got "12 April 1988")
That red build is the product: a fabricated figure, a guessed field, or a failed abstention becomes a CI failure, not a user complaint.
Ready for your own system?
npm install -D @pharmatools/groundwork
npx groundwork init # document QA
npx groundwork init extraction # structured extraction
How it works
| You edit | Groundwork runs | The gate enforces |
|---|---|---|
adapter.mjs — one file: answer() for document QA, extract() for extraction |
Redaction pre-step (Redacta) — identifiers become labelled tokens locally, before anything is sent | check --baseline freezes a good run as the floor |
datasets/cases/*.json — gold cases from real questions and real documents, labelled by hand |
The archetype's eval (OpenGATE) — document QA: anchored facts · numbers trace to context · abstention. Extraction: schema validity · field accuracy vs gold · no fabricated fields | check --ci in the scaffolded GitHub Action fails any PR below it |
groundwork.config.json — archetype, redaction, eval, and gate settings |
Cost profiling — measured token usage, savings in leverage order (caching → batching → trimming → routing) | A human still reviews high-stakes outputs — the gate is a floor, not a certification |
For extraction, one schema choice does most of the safety work: nullability is the abstention contract. A field the system must always find is non-nullable; a field the document may not state is nullable, and the system returns null for it — unknown → null, never guessed. A guessed value in a null-gold field fails by name: FABRICATED field "date_of_birth": document does not state it.
Examples
| Example | What it shows | Run |
|---|---|---|
demo/ |
Document QA: the full loop on a tiny local system — and the gate catching fabrication by name. Zero network. | npm run demo / npm run demo:break |
demo-extraction/ |
Structured extraction: schema validation, field accuracy, and the gate naming a guessed date of birth and a dropped required field. Zero network. | npm run demo:extraction / npm run demo:extraction:break |
examples/claude-doc-qa/ |
A real Claude-backed system: answer-from-document-only prompting, prompt caching, key-gated evals, measured usage feeding groundwork cost — plus a mock API so the whole loop runs offline in CI. |
npm run example:mock (offline) / npm run example:check (live) |
examples/claude-extraction/ |
Claude filling a schema from fictional referral letters: unknown → null in the prompt contract, the schema as the cached prefix, and the gate catching a guessed date of birth — plus a mock API for offline CI. | npm run example:extraction:mock (offline) / npm run example:extraction:check (live) |
Commands
groundwork init [archetype] scaffold the harness for a pattern (document-qa, extraction)
groundwork check redaction self-test + the archetype's eval
groundwork check --baseline freeze this run as the regression floor
groundwork check --ci exit non-zero on failure or regression vs baseline
groundwork cost measured token usage + savings, in leverage order
Two ways to learn it: docs/GETTING-STARTED.md is the reference walkthrough (about half an hour), and the course covers the same ground as checkpoint-driven lessons — including the sabotage test, where you deliberately break your own system to prove the gate catches it, and a lesson on the extraction archetype. The scaffolded playbook (GROUNDWORK.md) lives inside your repo, where your team will actually read it.
Use from Claude
The same checks ship as an MCP server (groundwork-mcp, stdio) so Claude Code, Cowork, or Claude Desktop can run them conversationally — check_readiness on a repo, check_answer_grounding on a single answer, check_extraction on a single record (no repo needed), scaffold_harness, cost_summary:
{ "mcpServers": { "groundwork": { "command": "npx", "args": ["-y", "@pharmatools/groundwork", "mcp"] } } }
There's also an Agent Skill (skills/groundwork-readiness/) that teaches an agent to run the gate and report results honestly — including refusing to present a green check as a safety certification.
What Groundwork is not
Groundwork is a strong floor, not a guarantee. Deterministic checks catch the failures that can be caught deterministically; they cannot certify an AI system safe. For high-stakes outputs — anything touching health, money, legal standing, or safety — a human must review before the output reaches the person it affects. Extraction raises the stakes quietly: the record feeds decisions, so a wrong field is a wrong decision. The scaffolded playbook says this too, on purpose.
Project
- Status — two archetypes shipped (document QA, structured extraction) of a planned three. Depth before breadth: each pattern gets finished properly before the next starts. See the roadmap.
- Contributing — bug reports, gold-case patterns, and examples are especially welcome: CONTRIBUTING.md.
- Releases — tagged on GitHub, versions on npm, history in CHANGELOG.md.
- Built on — OpenGATE (evaluation) and Redacta (privacy), both open source.
Licence
MIT. Everything init scaffolds into your repo is MIT-0 — yours, no attribution needed.
Groundwork MCP questions
How do I add Groundwork MCP to Claude Code?
Run claude mcp add groundwork -- npx -y @pharmatools/groundwork in your terminal. Add --scope user to make it available in every project.
How do I add Groundwork MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does Groundwork require an API key for its checks?
No, the checks are deterministic and do not require an API key for the evaluation process itself.