Content
# materials-semantic-mcp
An MCP server that gives agents **meaning, not access**: governed metric
definitions over a materials test lab, plus agent memory that can't enter
the system without a provenance label.
Built by a materials & clinical engineering manager who spent years running
V&V documentation, now applying the same discipline to agent systems. The
dataset is synthetic; the governance problems are real.
## The thesis
Give an agent your database and it will rediscover — differently each run —
what "first-pass yield" means, which joins are valid, and which numbers are
comparable. Give it a **semantic layer** and those meanings are defined
once, versioned, owned, and enforced. Agents don't need access to your
data. They need access to your definitions.
The same argument applies to what agents *learn*. Unlabeled model-generated
memory that becomes instruction is an **uncontrolled document** entering
your quality system. Here, every memory carries a provenance label — a
disposition record — and the write rules are enforced, not suggested.
## Architecture
```text
semantic/metrics.yaml ← definitions: formula, unit, grain, dimensions,
│ access rules, owner, lineage (SINGLE SOURCE OF TRUTH)
▼
src/semantic_layer.py ← interprets definitions (whitelist-validated at
│ load); computes metrics; rejects ungoverned
│ dimensions; withholds gated identities by role
▼
src/server.py (MCP) ← thin wiring: 5 agent tools, role injected by deployment
src/memory_admin.py ← operator CLI: the human gate (confirm/deprecate)
▲
src/memory.py ← provenance-labeled write-back (se10)
```
## Tool surface
| Tool | Contract |
|------|----------|
| `list_metrics` | Every governed metric with its definition — the menu is the documentation |
| `explain_metric` | Formula fields, source table, reviewed join path, definitions version |
| `query_metric` | Computes from the definition; disallowed dimensions rejected; gated dimensions withheld (aggregated away) below `engineering` role |
| `remember` | Agent writes require `observed` or `inferred` + a source; anything else is rejected |
| `recall` | Authority-ordered: authoritative > user-confirmed > observed > inferred; stale excluded by default |
Promotion and deprecation are deliberately absent from this table — see
"Where the human gate actually lives" below.
## Resources
Read-only views of the definitions — browse without calling a tool.
| Resource | Contract |
|----------|----------|
| `semantic://metrics` | Full text of `semantic/metrics.yaml`, the governed definitions |
| `semantic://metrics/{name}` | One metric's definition block; unknown names return error text |
## Provenance as disposition (the V&V translation)
| Label | Who establishes it | QMS analogue |
|-------|--------------------|--------------|
| `observed` | Agent, from direct evidence | Raw test record |
| `inferred` | Agent, by conclusion | Engineering judgment, unreviewed |
| `user-confirmed` | Human review | Reviewed & approved record |
| `authoritative` | Human designation | Controlled specification |
| *stale* (status, not label) | Time, via `sweep_stale` | Past review-by date |
Rules enforced at write time: agents may write `observed`/`inferred` only;
promotion requires a human; unlabeled writes are rejected; confirmed
memories never age out silently — humans deprecate them with a reason.
Memories also inherit the ACCESS ROLE of the session that wrote them, and
recall filters to at-or-below the caller's role — found live when a public
session recalled supplier-gated rates an engineering session had
remembered (se04 routing eval, 2026-07-09). Query-time masking means
nothing if gated data can round-trip through memory.
**Where the human gate actually lives.** Promotion (`confirm`) and
deprecation are NOT MCP tools — an agent-callable tool that stamps
"human" is a forgeable gate (found by adversarial review, 2026-07-09).
The agent-facing surface is exactly five tools: `list_metrics`,
`explain_metric`, `query_metric`, `remember`, `recall`. Promotions run
through the operator CLI and record who signed:
```bash
python src/memory_admin.py --memory-db data/memory.db list
python src/memory_admin.py --memory-db data/memory.db confirm 12 --by "Iver Olsen"
python src/memory_admin.py --memory-db data/memory.db deprecate 12 --reason "superseded"
```
## Quickstart
```bash
uv sync # or: pip install -e . --group dev
python src/generate_dataset.py --db data/lab.db # synthetic, seeded
python -m pytest tests/ -q # 58 tests (CI runs these on every push)
MCP_ROLE=engineering python src/server.py --db data/lab.db
```
Claude Desktop / Claude Code config:
```json
{
"mcpServers": {
"materials-semantic-layer": {
"command": "python",
"args": ["src/server.py", "--db", "data/lab.db"],
"cwd": "/path/to/materials-semantic-mcp",
"env": { "MCP_ROLE": "public" }
}
}
}
```
The role lives in the deployment environment, not the conversation — an
agent cannot talk its way into `engineering`.
## What the tests pin down
Metric math equals hand-written ground-truth SQL; populations honor their
`where` clauses (ESC-only, cracked-only); ungoverned dimensions and unknown
metrics reject; identity-gated dimensions are aggregated away for `public`
(one row, no per-supplier shape, no hidden ordering — masking labels is not
access control) and appear in full for
`engineering`; filter values are parameterized (injection-shaped input
returns zero rows, not a breach); provenance write rules, promotion gates,
supersede chains, and the stale sweep are all deterministic and covered.
## Data
Fully synthetic, generated by a seeded script shaped like a polymer test
lab: ESC (environmental stress cracking), wet-patch chemical exposure, and
tensile runs over resin batches from fictional suppliers — including one
problem supplier and one with sloppy paperwork, so governance questions
have answers worth finding. No real supplier, material, or employer data.
## Roadmap
- ~~Wire into the Materials RAG agent + 10-case routing eval~~ — done
(materials-rag branch `se04/semantic-mcp-wiring`; predictions grade as
honest declines until a validated prediction tool exists)
- Model-swap eval experiment: same tools, same gold sets, second lab's
model — publish the delta
- Blog: *The Semantic Layer for Agents* — definitions, not data
