内容
# 受管的MCP
在模型上下文协议上运行的治理。
`受管`的协作者 — **理解者**、**校准器**、**导航器** — 作为MCP服务器公开。任何具有MCP能力的客户端（Claude或基于Claude构建的平台）都在两个关键点挂载治理：**输入** 和 **交接点**。每个决策都会留下一个 **所有权、可审计的证据记录** 作为副产品 — 不是通过约定，而是因为服务器在没有写入记录的情况下无法运行。
这是实际体现：你不将治理附加到一个系统上，而是发布它，它会前往任何需要它的地方。
## 接口
**工具** （模型控制的动作）
- `understand(action, context, principal)` — 读取意图、范围、敏感性和后果类别。在拥有主体下打开证据记录。
- `calibrate(decision_id, model_confidence)` — 该置信度是否足以应对 **此后果**？不是一个固定的阈值：校准器跟踪每个后果类别过去的决策结果，并通过在线 **可靠性** 估计来折扣声明的置信度，然后与下限进行比较。对于一个类别，其置信度仅为80%值得信赖，其声明的0.85会下降到实际的0.69。如果没有历史记录，可靠性为1.0，因此它完全归结为一个固定的下限 — 一个严格的概括，而不是一个替代品。每次调整都记录在证据中，因此校准本身是可审计的。（这是一个具有收缩的可靠性加权估计器，而不是一个经过训练的校准器；它依赖于通过 `Calibrator.observe()` 馈送的已解决结果，而该标记本身就是一个难题。）
- `navigate(decision_id)` — 交接点：`proceed`、`gate` 或 `block`，以及触发的确切规则。
**资源** （只读数据）
- `governance://policy` — 版本化的规则集，作为可审计的工件。
- `governance://evidence/{decision_id}` — 一个决策的完整记录：输入、每个工具的结果、路由、时间戳和拥有主体。这是承保人的只读视图。
**提示**
- `escalation_review(decision_id)` — 网关呈现给责任人类的内容：证据，然后 *"你会为此结果签上你的名字吗？"*
## 运行演示（无依赖）
```bash
python examples/walkthrough.py
```
**第一幕** — 三个决策，三个路由：
| 动作 | 类别 | 置信度 | 路由 |
|---|---|---|---|
| 读取Q3摘要，草拟内部笔记 | 可逆 | 0.88 | **继续** |
| 将250,000美元转移到外部账户 | 不可逆 | 0.99 | **网关** |
| 批量修改客户PII记录 | 有界 | 0.79 | **阻止** |
**第二幕** — 校准学习。相同的动作在相同的声明置信度下，由于代理机构建立了业绩记录，因此被不同地判断：
| 通过 | 可靠性 | 有效置信度 | 下限 | 路由 |
|---|---|---|---|---|
| 冷启动（无历史记录） | 1.00 | 0.85 | 0.80 | **继续** |
| 40次过度自信的结果后 | 0.81 | 0.69 | 0.80 | **阻止** |
请求的本身没有变化 — 系统对该置信度的信任度发生了变化，证据记录显示了确切的原因。 这次转变是值得关注的。
## 运行MCP服务器
```bash
pip install "mcp[cli]"
python -m governed_mcp.server # 标准输入/输出传输
```
要在Claude Code / 桌面应用程序中挂载它，请将其添加为MCP服务器（标准输入/输出，命令 `python -m governed_mcp.server`）。然后要求Claude通过 `understand` → `calibrate` → `navigate` 运行一个动作，并读取 `governance://evidence/{id}`。
## 设计原则
接口强制执行两件事，而不是交给学科：
1. **每个工具调用都写入证据。** 决策不能在静默中进行。
2. **`principal` 是打开决策的必要条件。** "部署代理的人拥有结果" 在机械上被捕获 — 记录始终回答 *谁拥有这个*。
## 替换真实的 `governed`
这里的协作者是接口的透明替身。真正的深度在于您的库的内部 — 后果分类器、校准阈值、策略引擎。替换 `governed_mcp/coworkers.py` 中的 `Understander.read`、`Calibrator.check` 和 `Navigator.route`；服务器、资源、提示和证据存储保持不变。MCP层故意很薄 — 它证明的观点是您知道在代理系统中 **哪里** 附加治理。
## 测试
```bash
python tests/test_governance.py # 不需要pytest；pytest也适用
```
断言治理工具必须正确获得的决策：路由与后果匹配，敏感范围提高下限，每个步骤都在主体下写入证据，当过度自信累积时，校准会翻转判决。
## 布局
```
governed-mcp/
├── governed_mcp/
│ ├── policy.py # 后果带、分类、校准下限
│ ├── coworkers.py # Understander, Calibrator（可靠性加权）, Navigator
│ ├── evidence.py # EvidenceStore, Decision, 所有权记录
│ └── server.py # FastMCP: 3个工具，2个资源，1个提示
├── policy.yaml # 可编辑的规则集（如果存在pyyaml，则覆盖默认）
├── examples/
│ └── walkthrough.py # 可运行、无依赖的演示（第一幕 + 第二幕）
├── tests/
│ └── test_governance.py
├── requirements.txt
└── pyproject.toml
```
