Groundwork
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Groundwork
Your product evidence, in your repo, written by your own agent.
Groundwork lets Claude Code (or any MCP agent) keep customer insights, hypotheses, experiments, findings and requirements as linked Markdown files in a groundwork/ folder. Every requirement traces back to the findings, experiments and customer quotes behind it.
insight ──▶ hypothesis ──▶ experiment ──▶ finding ──▶ requirement
"I gave up "Guided import pilot, 10 "activation "Guided CSV
after 20 will lift accounts: 61% vs 38%" import"
minutes" activation" validated"No account, no API keys, no server. Your agent does the thinking. Groundwork checks the data, keeps links valid and computes experiment verdicts.
Plain files. Read them, diff them, review them in pull requests, and keep them as long as you like.
Traceability. Ask "why are we building this?" and get the full evidence chain, or check it in CI with
groundwork validate.
Quickstart (2 minutes)
Claude Code
In your project folder:
claude mcp add groundwork -- npx -y groundwork-mcpOr install the plugin, which adds the MCP server and a skill that teaches Claude when to use it:
/plugin marketplace add IdeatorlabsAB/groundwork
/plugin install groundwork@groundworkCodex
codex mcp add groundwork -- npx -y groundwork-mcpOr add it to ~/.codex/config.toml by hand:
[mcp_servers.groundwork]
command = "npx"
args = ["-y", "groundwork-mcp"]To teach Codex when to use it, copy the skill into your repo:
mkdir -p .agents/skills/groundwork
curl -fsSL https://raw.githubusercontent.com/IdeatorlabsAB/groundwork/main/skills/groundwork/SKILL.md -o .agents/skills/groundwork/SKILL.mdStart codex in your project folder, so Groundwork finds the project.
Then
Talk to your agent as you normally would:
Here are my notes from three customer interviews. Log the pains as insights.
Draft a hypothesis from the onboarding insights, with a success metric.
The pilot finished: activation went from 38% to 61%, support tickets stayed at 11 a week. Record it and write up the finding.
Why are we building the guided import?
Groundwork writes files like groundwork/insights/INS-0001-setup-takes-too-long.md. Commit them like any other file.
Related MCP server: accreta
The CLI
npx -p groundwork-mcp groundwork init # create groundwork/config.yml
npx -p groundwork-mcp groundwork validate # check every item and link; exits 1 on errors
npx -p groundwork-mcp groundwork trace REQ-0002
npx -p groundwork-mcp groundwork list hypothesis
npx -p groundwork-mcp groundwork import --to <web app> # see "Groundwork for teams"trace shows the chain behind an item (from examples/acme):
REQ-0002 Guided CSV import (solution, approved)
├─ finding FND-0001 Guided import lifts activation
│ ├─ experiment EXP-0001 Guided import pilot (completed, validated)
│ │ └─ hypothesis HYP-0001 Guided import (validated)
│ │ ├─ insight INS-0001 Setup takes too long
│ │ └─ insight INS-0002 Import errors are unclear
│ ├─ hypothesis HYP-0001 Guided import (validated) (shown above)
│ └─ insight INS-0001 Setup takes too long (shown above)
└─ requirement REQ-0001 Get set up without help (stakeholder, draft)
└─ finding FND-0001 Guided import lifts activation (shown above)Run validate in CI to block pull requests with broken links:
# .github/workflows/groundwork.yml
on: pull_request
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: npx -y -p groundwork-mcp groundwork validateSetup
groundwork/config.yml holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off. Agents can also add product areas and products themselves, with add_product_areas and add_products; people are always added by hand:
name: Acme
productAreas:
- { id: onboarding, label: Onboarding }
products: [Acme app]
people:
- { id: sam, name: Sam, role: owner, email: sam@acme.example }Groundwork finds the project by looking for groundwork/config.yml in the current folder and the folders above it. Set GROUNDWORK_DIR to point somewhere else, and GROUNDWORK_USER to choose who you're acting as.
The full format, every field and the rules are in SPEC.md. See examples/acme for a sample project.
Tools
Read | Write | Lifecycle |
|
|
|
|
|
|
|
|
|
|
| |
|
| |
|
| |
| ||
|
Privacy
Insights hold what customers said, and these files usually end up in git. Groundwork tells agents to record a role ("Finance manager") and an optional reference ("P07"), never names or contact details. Check quotes before you commit them, and keep the repo private if they're sensitive.
Groundwork for teams
The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal. It's a separate, paid product; this project is and stays open source.
To move a project into it, create an agent token in the web app (Settings → Connect an agent), then:
export GROUNDWORK_TOKEN=gw_…
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-run # see what would happen
npx -p groundwork-mcp groundwork import --to https://your-groundwork-appEvery item keeps its links, and its original id (INS-0001) is stored with it. Running the import again skips items already there (--overwrite replaces them). Afterwards groundwork/config.yml says migrated:, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server. For Codex, run codex mcp remove groundwork and add this to ~/.codex/config.toml:
[mcp_servers.groundwork]
url = "https://your-groundwork-app/api/mcp"
bearer_token_env_var = "GROUNDWORK_TOKEN"Contributing
Issues and pull requests are welcome. See CONTRIBUTING.md.
Licence
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Team docs served to AI agents over MCP - search, Markdown reads, version pinning, read audit.
Hosted markdown project wikis your team's AI assistants read, search, and update over MCP.
Public read-only MCP for products, frameworks, guides, methodology, and blog metadata.
Your product team's shared strategic memory — an MCP server your AI tools reason over.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn MCP server that gives LLM agents structured, safe, and traceable access to engineering project documentation stored in Markdown/Git repositories, enabling management of requirements, decisions, tests, tasks, and impact analysis.14MIT
- AlicenseNot gradedqualityBmaintenanceMCP server that enables AI agents to search, fetch, and analyze a self-maintaining markdown knowledge base with provenance, drift detection, and canonical definitions.1MIT
- FlicenseAqualityDmaintenanceProvides coding agents with a shared, Markdown-based engineering knowledge base to search, capture, create, and update internal conventions, API details, infrastructure configs, and development setup via lightweight MCP tools.6-
- AlicenseNot gradedqualityBmaintenanceEnables MCP agents to maintain durable, evidence-aware project knowledge, retrieve precise excerpts on demand, and track decisions, conflicts, and revisions across sessions.1Apache 2.0