query-sanitizer-mcp
query-sanitizer-mcp
一个轻量级的 MCP 中间件,位于你的提示词和外部 LLM 之间,在任何数据离开你的机器之前自动对敏感数据进行脱敏处理。
[Your Prompt] → sanitize_query() → [Safe Prompt] → External LLM → [Response] → restore_response() → [You]v0.3.0 — 四阶段 DLP 流水线:正则表达式 → GLiNER NER → LLM 优化 → 后扫描检查。 100% 开源,100% 本地运行。已在 M4 MacBook 和 Google Colab T4 上测试。
为什么使用它
每当你将内部上下文粘贴到 Claude、ChatGPT 或任何云端 LLM 中时,你都有可能泄露:
员工姓名、电子邮件、电话号码
内部项目代号
基础设施详情(IP、主机名、数据库名称)
API 密钥和凭据
公司名称、交易金额、法律参考资料
此 MCP 服务器会拦截这些文本,使用类型化占位符(如 [ORG_NAME_1]、[PII_NAME_1] 等)替换敏感令牌,并在响应中恢复它们——这样你看到的是自然文本,而云端 LLM 永远看不到真实值。
Related MCP server: ai-security-gateway-mcp
工具
工具 | 描述 |
| 三阶段脱敏。返回安全文本 + |
| 将占位符换回原始值。 |
| 扫描 LLM 的响应,检查其是否生成或泄露了任何数据。 |
| 显示最近的脱敏历史记录。 |
检测流水线
第一阶段 — 正则表达式预处理(始终运行,无需模型)
针对结构化令牌的确定性模式。即使本地模型离线也能运行。
模式 | 类别 | 是否拦截? |
AWS 访问密钥 ( | CREDENTIAL | 是 — 已拦截 |
GitHub 令牌 ( | CREDENTIAL | 是 |
JWT ( | CREDENTIAL | 是 |
Slack 令牌 ( | CREDENTIAL | 是 |
| CREDENTIAL | 是 |
URL 中的密码 ( | CREDENTIAL | 是 |
电子邮件地址 | PII_NAME | 否 — 已恢复 |
电话号码 | PII_NAME | 否 |
社会安全号码 ( | PII_ID | 否 |
员工/工牌 ID ( | PII_ID | 否 |
RFC 1918 私有 IP | INFRA | 否 |
美元金额 | FINANCIAL | 否 |
配置定义的实体(组织名称、员工、代号、域名) | varies | 否 |
第二阶段 — LLM 优化(上下文相关,尽力而为)
捕获需要语义理解的实体:上下文中使用的组织名称、项目代号、GEO_INTERNAL 引用、LEGAL 条款、INTERNAL_URL 模式。如果本地模型不可用,将返回第一阶段的输出并附带明确警告。
第三阶段 — 后扫描置信度检查
在脱敏后的文本上运行高置信度正则表达式,以标记 LLM 可能遗漏的内容(例如模型未捕获到的 JWT)。在报告中显示为警告。
设置
选项 A — M4 MacBook(推荐)
技术栈: Ollama 0.19+ (MLX 后端,M4 上约 50 tok/s) + GLiNER NER (MPS,约 80ms/次调用)
# 1. Install Ollama and pull the recommended model
brew install ollama
ollama pull qwen2.5:3b # 2GB, fast + strong instruction following
ollama serve # Ollama 0.19+ uses MLX automatically on Apple Silicon
# 2. Clone and install with NER layer
git clone https://github.com/vidoluco/query-sanitizer-mcp
cd query-sanitizer-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[nlp]" # fastmcp + gliner (GLiNER NER layer)添加到 Claude Code (~/.claude/settings.json):
{
"mcpServers": {
"query-sanitizer": {
"command": "/path/to/query-sanitizer-mcp/.venv/bin/python",
"args": ["/path/to/query-sanitizer-mcp/server.py"],
"env": {
"SANITIZER_MODEL_NAME": "qwen2.5:3b",
"SANITIZER_GLINER_MODEL": "urchade/gliner_medium-v2.1"
}
}
}
}M4 的替代 LLM 模型(均通过 Ollama):
模型 | 大小 | M4 速度 | 适用场景 |
| 2 GB | ~50 tok/s | 默认 — 快速、准确 |
| 3 GB | ~40 tok/s | 强大的推理能力 |
| 2 GB | ~45 tok/s | 广泛通用 |
| 5 GB | ~30 tok/s | 更高准确度,需要更多内存 |
选项 B — Google Colab T4
技术栈: HuggingFace transformers (无需 Ollama) + GLiNER (CUDA)
# Cell 1 — install
!pip install "query-sanitizer-mcp[colab]" -q
# fastmcp + gliner + transformers + torch + accelerate
# Cell 2 — configure
import os
os.environ["SANITIZER_BACKEND"] = "hf"
os.environ["SANITIZER_HF_MODEL"] = "Qwen/Qwen2.5-3B-Instruct" # ~6GB, fits T4 16GB
os.environ["SANITIZER_GLINER_MODEL"] = "urchade/gliner_medium-v2.1"
os.environ["SANITIZER_LEDGER_DIR"] = "/content/sanitizer-ledger"
# Cell 3 — use directly (no MCP client needed in Colab)
import sys; sys.path.insert(0, ".")
from server import sanitize_query, restore_response, scan_response
result = sanitize_query("Send report to jane.doe@acme.com re: Project Phoenix")
print(result)首次运行会将
Qwen2.5-3B-Instruct(~6 GB) 和gliner_medium-v2.1(~500 MB) 下载到 Colab 缓存中。后续运行即时生效。
最小化设置(仅正则表达式,无需模型)
如果你想要零依赖操作(纯正则表达式,无 Ollama,无 GLiNER):
pip install fastmcp
SANITIZER_MODEL_RETRIES=0 python server.py凭据、电子邮件、社会安全号码、私有 IP 和财务金额仅通过正则表达式即可捕获。人员、组织名称和项目代号需要 GLiNER 或 LLM 层。
配置
创建 .sanitizer-ledger/config.json(或运行 python scripts/ledger.py init-config):
{
"org_names": ["Acme Corp", "Acme"],
"org_domains": ["acme-internal.net"],
"project_codenames": ["Phoenix", "Titan"],
"known_employees": ["Jane Smith", "Marcus Webb"],
"internal_ip_ranges": ["10.0.0.0/8"],
"custom_patterns": [
{"pattern": "JIRA-\\d{4,}", "category": "PROJECT_NAME", "description": "Jira tickets"}
],
"always_allow": ["Google Cloud", "Kubernetes", "BigQuery", "Terraform", "Docker"]
}配置定义的实体(org_names、known_employees 等)被连接到正则表达式预处理(用于确定性匹配)和 LLM 系统提示词(用于上下文变体)中。更改在下一次 sanitize_query 调用时生效 — 无需重启服务器。
环境变量
变量 | 默认值 | 描述 |
|
| 本地模型端点 |
|
| 模型名称 |
|
| 模型失败时的重试次数(2秒、4秒退避) |
|
| 账本目录路径 |
|
| 设置为 |
账本 CLI
python scripts/ledger.py list [N] # recent N entries
python scripts/ledger.py lookup <san_id> # full mapping for one entry
python scripts/ledger.py restore <san_id> <text> # restore from CLI
python scripts/ledger.py stats # aggregate stats by category and source
python scripts/ledger.py purge --older-than 30d # enforce retention policy
python scripts/ledger.py init-config # create starter config.json脱敏类别
类别 | 示例 | 严重性 |
| API 密钥、令牌、密码 | 严重 — 已拦截,永不恢复 |
| 内网 URL、暂存端点 | 严重 |
| 姓名、电子邮件、电话号码 | 高 |
| 社会安全号码、员工 ID、工牌号 | 高 |
| 公司/子公司名称 | 高 |
| 合同条款、案件编号 | 高 |
| 内部代号 | 中 |
| IP、主机名、数据库名称 | 中 |
| 收入、交易金额、预算 | 中 |
| 办公地点、建筑名称 | 低 |
安全模型
凭据永不存储 — 账本中写入的是
[BLOCKED]而不是原始值故障安全,而非故障开放 — 模型不可用时会触发正则表达式回退,绝不会明文透传
仅限本地推理 — 脱敏步骤不会向任何外部 API 发送数据
隐私模式 (
SANITIZER_LEDGER_STORE_ORIGINALS=false) — 原始值根本不会写入磁盘;恢复仅通过内存缓存,在同一服务器会话内有效
示例
查看 examples/ 获取完整的会话跟踪:
01_api_key_leak.md— AWS 凭据被正则表达式预处理拦截02_employee_pii.md— 包含姓名、电子邮件、员工 ID 的 HR 提示词 + 恢复03_internal_infra.md— 使用 Ollama 离线进行基础设施调试(正则表达式回退)
贡献
提交 Issue 或发送 PR。
下一步计划:
[ ] 从检测到的模式中自动建议配置条目
[ ] Claude Code 钩子集成(提示词前自动脱敏)
[ ] 置信度阈值配置
[ ] 批量/大规模脱敏模式
[ ] 代码块扫描(内联密钥、导入路径)
[ ] 账本静态加密
[ ] 用于账本审查的 Web UI
许可证
MIT
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
Detect and redact PII and secrets before text reaches an LLM, with reversible placeholders.
Find and redact leaked secrets, wallet keys and PII before an AI agent sends text.
Detect and redact PII and secrets (API keys, tokens) in text, HTML or PDF before it reaches an LLM.
Scan prompts for injection attacks, redact PII, and audit LLM SDK usage from any MCP client
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceSecurity middleware for LLM apps and AI agent pipelines. Detects prompt injection attacks (22 signatures, 7 languages) and anonymizes PII (17 entity types). Deterministic, sub-25ms, GDPR Art.30 compliant.-
- AlicenseAqualityDmaintenanceScans prompts for PII and masks or redacts sensitive data locally before sending to an LLM, supporting multiple anonymization modes.1MIT
- FlicenseAqualityDmaintenanceA data-loss-prevention (DLP) layer for AI agents that intercepts document reads, scans for sensitive data, and redacts or blocks it before it reaches the model, with audit logging.1-
- AlicenseAqualityBmaintenanceEnables safe interaction with cloud LLMs by redacting sensitive entities into reversible placeholders, enforcing deterministic egress policies with human approval, and rehydrating responses so real data never leaves the process.4MIT