内容
保密性 MCP
一款保密服务器，能将敏感的名称、代号和标识符从代理的输出中剔除。
您在 YAML 文件中定义受保护的内容；服务器提供工具，从代理读取的文件中编辑受保护的实体，并在返回代理的输出之前检查是否存在泄密。
## 理念
在企业科技领域，我发现处理法律协议和敏感信息在 AI 开发的背景下可能很棘手。我相信，未来我们将看到更多具体的标准和工具，用于控制各方及其相关代理之间信息流的控制。这个存储库是该理念的一个实现，主要作为 MCP，同时附带一个预提交钩子。
有时，您希望您的代理使用客户敏感或内部信息，但要确保这些信息不会泄露到输出中。这对于编写文档或面向公众的文档很有用，特别是在较大的相互关联的组织中，内部背景非常有帮助。
我们可以将三个主要参与者——代理、开发人员和终端用户/读者——与文档交互的方式分为以下几类：
| 案例 | 代理 | 开发人员 | 读者 | 名称 | 如何强制执行 | 示例 |
|------|:-----:|:---:|:------:|------|-------------------|---------|
| 1 | ✓ | ✓ | ✓ | 公共 | 不需要任何措施 | 来自公共规范的文档 |
| 2 | ✓ | ✓ | ✗ | 工作上下文 | 代理看到真实信息，但其输出在返回前被清除 | 案例研究：客户的真实姓名在上下文中，发布为“财富 500 强客户” |
| 3 | ✗ | ✓✗ | 机密盲 | 代理只看到占位符；真实值在代理外部被替换回 | 运行手册使用 `$DB_PASSWORD`；开发人员持有真实凭证 |
| 4 | ✓ | ✗ | ✗ | 开发人员盲上下文 | 数据所有者（而非开发人员）控制访问；服务器持有数据，因此开发人员从未看到原始上下文 | 合规代理读取工资，起草匿名报告 |
| 5 | ✗ | ✓ | ✓ | 内部路由 | 敏感部分由人员/服务器添加到仅限内部的目的地，代理从未触及 | 详细信息仅在内部 wiki 中；代理从未看到它 |
| 6 | ✗ | ✗ | ✓ | 转录 | 服务器在代理完成后将值直接插入到完成的文件中 | 生成的合同中的每个收件人的许可证密钥 |
| 7 | ✓ | ✗ | ✓ | 用户私有 | 代理为单个用户读取和写入；操作员在合同上被屏蔽（无日志/训练） | 代理读取用户的医疗数据，并向同一用户报告 |
| 8 | ✗ | ✗ | ✗ | 退化 | 不适用 | 数据不发挥作用 |
**此 MCP 针对案例 2 和 3。_output` / ` 涵盖案例 2（代理看到真实信息，清除）；`read_clean` 涵盖案例 3（代理仅看到占位符）。两者生活在同一服务器中，因此单个配置可以涵盖两种工作流程。
## 功能
- **`read_clean`** — 代理读取具有受保护实体的文件，这些实体被占位符替换；机密永远其上下文。
- **`verify_output`** / **`verify_file`** — 在代理发送其响应之前，扫描文本或文件中的受保护实体。
- 不区分大小写的匹配，自动扩展常见代码形状的变体（`client-one`、`client_one`、`ClientOne`、`clientone`）。
- spaCy 命名实体识别捕获 ORG / GPE / PRODUCT 范围，并根据捆绑的 + 用户可扩展的进行过滤。
- 启动验证。
- CLI（`ity verify`）和 git 预提交钩子，用于非代理工作流程。
## 安装
需要 [uv](https://github.com/astral-sh/uv)。
```bash
git clone https://github.com/Otto-Cline/confidentiality-mcp.git
cd confidentiality-mcp
uv sync
uv tool install .
```
`uv sync` 设置开发环境（由 MCP 服务器使用）。`uv tool install .` 将 `confidentiality` CLI 放在您的 PATH 中。
## 配置
现成的配置位于 [`examples/configs/`](examples/configs/) — 复制一个并适配。或者从头创建 `configs/protected.yaml`：
```yaml
protected:
- entity: "Client One"
granularity: concept # identifier | concept
output_mode: anonymize # anonymize | omit
placeholder: "the client" # optional, used by read_clean
allowlist:
- lucille # names spa ignore
on_violation: reprompt # reprompt | report
preverification: enabled # enabled | disabled
default_placeholder: "<<redacted>>"
nlp_model: en_core_web_sm # or en_core_web_lg
```
### 字段
| 字段 | 值 | 效果 |
|---|---|---|
| `protected[].entity` | 字符串 | 要保护的文字文本 |
| `protected[].granularity` | `identifier` \| `concept` | `identifier` 运行文字 + 变体匹配；`concept` 为相关实体添加 spaCy NER 传递 |
| `protected[].output_mode` | `anonymize` \| `omit` | 代理应如何重写泄密 |
| `protected[].placeholder` | 字符串 | 此实体的读取时间替代 |
| `allowlist[]` | 字符串列表 | 要排除的 NER 标记名称（与内置列表合并） |
| `on_violation` | `reprompt` \| `report` | `reprompt`：代理静默重写并重新验证。`report`：代理显示违规列表并停止。 |
| `preverification` | `enabled` \| `disabled` | `read_clean` 工具是否注册 |
| `default_placeholder` | 字符串 | 没有 `placeholder` 的条目的备用 |
| `nlp_model` | spaCy 模型名称 | NER 的模型（`en_core_web_sm` 随软件包附带） |
## 连接到 Claude Code
```bash
claude mcp add confidentiality-mcp -- \
uv --directory /absolute/path/to/confidentiality-mcp run \
python -m confidentiality.server \
--config /absolute/path/to/confidentiality-mcp/configs/protected.yaml
```
开始会话；`/mcp` 显示 `confidentiality-mcp` 已连接。
## 工具
### `read_clean(path)`
返回位于 `path` 的文件，其中每个受保护的实体（及其变体）都被配置的占位符替换。没有匹配的文件将保持不变。
### `verify_output(text)`
扫描 `text` 并返回：
```json
{
"violations": [{"entity": "...", "match": "...", " [start, end], ...}],
"suspicious_entities": [{"text": "...", "label": "PERSON", ...}],
"action": "reprompt"
}
```
`violations确认的文字匹配suspicious_entities NER 标记的范围，代理应审查（仅在至少存在一个 `concept` 条目时填充）。`action` 反映配置的 `on_violation` 模式。
### `verify_file(path)`
与 `verify_output` 相同，但从磁盘读取；用于大型草稿以避免通过工具调用发送文件正文。向响应中添加一个 `path键。
## CLI
```bash
confidentialityconfig protected.yaml file.md
confidentiality verify --show-suspicious file.md
confidentiality verify --quiet file.md
```
配置解析：`--config` → `$CONFIDENTIALITY_CONFIG` → `./protected.yaml`。
退出代码：`0` clean，`1` 违规，`2` 配置错误。
## 预提交钩子
```yaml
# .pre-commit-config.yaml
repos:
- repo: local
hooks:
- confidentiality-verify
: 保密性检查
entry: confidentiality verify --config /absolute/path/to/protected.yaml
language: system
files: '.+'
```
然后 `pre-commit install`。
## 程序 API
```python
from confidentiality import (
verify_text, verify_path,
obfuscate_text, obfuscate_path,
load_config,
)
```
## 示例
- [`examples/configs/`](examples/configs/) — 两个主要工作流（最小、案例 2 输出清除、案例 3 读取时间）的启动配置。
- [`examples/case-study/`](examples/case-study/) — 一个完整的案例研究，包含一个虚构的工程简报、一个匹配的配置和一个要馈送到 Claude提示。
## 开发
```bash
uv sync
uv run pytest
uv tool install --editable . # live source for CLI iteration
```
## 故障排除
- `confidentiality: found` — 运行 tool update-shell`。
- 服务器无法启动 — 将相同的配置通过 `confidentiality verify --config <path> some-file，查看 lint 错误。
nlp_model` — 使用 `uv runm spacy download < 安装其他 spaCy 模型。
