内容
# 材料语义MCP
一个MCP服务器，为代理提供**意义，而非访问权限**：在材料测试实验室中，受管辖的指标
定义，以及代理内存，代理内存如果没有来源标签，则无法进入系统。
由一位材料和临床工程经理构建，他曾花费数年时间运行V&V文档，现在将同样的规范应用于代理系统。数据集是合成的；治理问题是真实的。
## 论文
给代理你的数据库，它将重新发现——每次运行都不同——什么是“首次通过率”，哪些连接是有效的，哪些数字是可比较的。给它一个**语义层**，那些含义被定义一次，版本控制，拥有并强制执行。代理不需要访问你的数据。他们需要访问你的定义。
同样的论点适用于代理**学习**的内容。未标记的模型生成的内存成为指令，是一个**不受控制的文档**，进入你的质量系统。在这里，每个内存都带有来源标签——一个处置记录——并且写入规则被强制执行，而不是建议。
## 架构
```text
semantic/metrics.yaml ← 定义：公式，单位，粒度，维度，
│ 访问规则，所有者，血统（单一真实来源）
▼
src/semantic_layer.py ← 解释定义（加载时进行白名单验证）；计算指标；拒绝不受管辖
│ 的维度；按角色隐藏受控身份
▼
src/server.py (MCP) ← 薄线路：5个代理工具，部署时注入角色
src/memory_admin.py ← 操作员CLI：人类网关（确认/废弃）
▲
src/memory.py ← 带来源标签的写回（se10）
```
## 工具表面
| 工具 | 契约 |
|------|----------|
| `list_metrics` | 每个受管辖的指标及其定义——菜单即文档 |
| `explain_metric` | 公式字段，源表，审查连接路径，定义版本 |
| `query_metric` | 根据定义计算；拒绝不允许的维度；隐藏维度在`engineering`角色以下被聚合 |
| `remember` | 代理写入需要`observed`或`inferred`+源；否则拒绝 |
| `recall` | 权威排序：权威 > 用户确认 > 观察 > 推断；默认排除过期 |
提升和废弃在该表中故意省略——参见下面的“人类网关实际位置”。
## 资源
定义的只读视图——浏览无需调用工具。
| 资源 | 契约 |
|----------|----------|
| `semantic://metrics` | `semantic/metrics.yaml`的全文，受管辖的定义 |
| `semantic://metrics/{name}` | 指标的定义块；未知名称返回错误文本 |
## 来源作为处置（V&V转换）
| 标签 | 谁建立它 | QMS类似物 |
|-------|--------------------|--------------|
| `observed` | 代理，从直接证据 | 原始测试记录 |
| `inferred` | 代理，通过结论 | 工程判断，未审查 |
| `user-confirmed` | 人类审查 | 审查和批准的记录 |
| `authoritative` | 人类指定 | 受控规范 |
| *过期*（状态，非标签） | 时间，通过`sweep_stale` | 过去审查日期 |
写入时强制执行规则：代理只能写入`observed`/`inferred`；提升需要人类；未标记的写入被拒绝；确认的内存不会默默地过期——人类会用原因废弃它们。内存还会继承写入会话的访问角色，并且回忆过滤到调用者的角色或以下——当公共会话回忆供应商控制的费率时，工程会话会发现（se04路由评估，2026-07-09）。查询时屏蔽意味着如果受控数据可以绕过内存，则没有任何意义。
**人类网关实际位置**。 提升（`confirm`）和废弃不是MCP工具——一个代理可调用的工具，盖上“人类”戳记，是一个可伪造的网关（通过对抗性审查发现，2026-07-09）。面向代理的界面恰好有五个工具：`list_metrics`，`explain_metric`，`query_metric`，`remember`，`recall`。提升通过操作员CLI运行，并记录谁签署：
```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"
```
## 快速入门
```bash
uv sync # 或：pip install -e . --group dev
python src/generate_dataset.py --db data/lab.db # 合成，种子
python -m pytest tests/ -q # 58个测试（CI每次推送都运行这些）
MCP_ROLE=engineering python src/server.py --db data/lab.db
```
Claude Desktop / Claude Code 配置：
```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" }
}
}
}
```
角色存在于部署环境中，而不是对话中——代理无法通过对话进入`engineering`。
## 测试确定内容
指标数学等于手写的基准SQL；群体遵守其`where`子句（仅ESC，裂开）；不受管辖的维度指标和未知指标拒绝；身份控制的维度根据`public`（一行，无供应商特定形状，无隐藏排序——屏蔽标签不是访问控制）被聚合，并为`engineering`完全显示；过滤值参数化（注入形输入返回零行，而不是违规）；来源写入规则，提升门控，替代链和过期扫描都是确定性的，并被覆盖。
## 数据
完全合成，由种子脚本生成，类似于聚合物测试实验室：ESC（环境应力裂纹），湿斑化学物质暴露，以及来自虚构供应商的树脂批次的拉伸运行——包括一个问题供应商和一个有粗糙文档的供应商，因此治理问题有值得查找的答案。没有真正的供应商，材料或雇主数据。
## 路线图
- ~~连接到材料RAG代理 + 10案例路由评估~~ — 完成
（材料-rag分支`se04/semantic-mcp-wiring`；预测评级为诚实的拒绝，直到存在有效的预测工具）
- 模型交换评估实验：相同的工具，相同的金牌集，第二个实验室的模型——发布差异
- 博客：*代理的语义层* — 定义，而不是数据
