Skip to main content
Glama
deenesjakoruzh
vidoluco

query-sanitizer-mcp

by vidoluco
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

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: zentric-protocol-mcp

工具

工具

描述

sanitize_query(text)

三阶段脱敏。返回安全文本 + san_id。

restore_response(text, san_id)

将占位符换回原始值。

scan_response(text)

扫描 LLM 的响应，检查其是否生成或泄露了任何数据。

view_ledger(last_n)

显示最近的脱敏历史记录。

检测流水线

第一阶段 — 正则表达式预处理（始终运行，无需模型）

针对结构化令牌的确定性模式。即使本地模型离线也能运行。

模式

类别

是否拦截？

AWS 访问密钥 (AKIA…)

CREDENTIAL

是 — 已拦截

GitHub 令牌 (ghp_…, gho_…)

CREDENTIAL

是

JWT (eyJ…)

CREDENTIAL

是

Slack 令牌 (xox[baprs]-…)

CREDENTIAL

是

api_key = "…" 风格的赋值

CREDENTIAL

是

URL 中的密码 (://user:pass@)

CREDENTIAL

是

电子邮件地址

PII_NAME

否 — 已恢复

电话号码

PII_NAME

否

社会安全号码 (NNN-NN-NNNN)

PII_ID

否

员工/工牌 ID (EMP-…)

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 速度

适用场景

qwen2.5:3b

2 GB

~50 tok/s

默认 — 快速、准确

phi4-mini

3 GB

~40 tok/s

强大的推理能力

llama3.2:3b

2 GB

~45 tok/s

广泛通用

qwen2.5:7b

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 调用时生效 — 无需重启服务器。

环境变量

变量

默认值

描述

SANITIZER_MODEL_URL

http://localhost:11434/v1/chat/completions

本地模型端点

SANITIZER_MODEL_NAME

llama3.2

模型名称

SANITIZER_MODEL_RETRIES

2

模型失败时的重试次数（2秒、4秒退避）

SANITIZER_LEDGER_DIR

.sanitizer-ledger/

账本目录路径

SANITIZER_LEDGER_STORE_ORIGINALS

true

设置为 false 可停止在磁盘存储原始值（GDPR 模式 — 恢复仅在同一会话内有效）

账本 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

脱敏类别

类别

示例

严重性

CREDENTIAL

API 密钥、令牌、密码

严重 — 已拦截，永不恢复

INTERNAL_URL

内网 URL、暂存端点

严重

PII_NAME

姓名、电子邮件、电话号码

高

PII_ID

社会安全号码、员工 ID、工牌号

高

ORG_NAME

公司/子公司名称

高

LEGAL

合同条款、案件编号

高

PROJECT_NAME

内部代号

中

INFRA

IP、主机名、数据库名称

中

FINANCIAL

收入、交易金额、预算

中

GEO_INTERNAL

办公地点、建筑名称

低

安全模型

  • 凭据永不存储 — 账本中写入的是 [BLOCKED] 而不是原始值

  • 故障安全，而非故障开放 — 模型不可用时会触发正则表达式回退，绝不会明文透传

  • 仅限本地推理 — 脱敏步骤不会向任何外部 API 发送数据

  • 隐私模式 (SANITIZER_LEDGER_STORE_ORIGINALS=false) — 原始值根本不会写入磁盘；恢复仅通过内存缓存，在同一服务器会话内有效

示例

查看 examples/ 获取完整的会话跟踪：

  1. 01_api_key_leak.md — AWS 凭据被正则表达式预处理拦截

  2. 02_employee_pii.md — 包含姓名、电子邮件、员工 ID 的 HR 提示词 + 恢复

  3. 03_internal_infra.md — 使用 Ollama 离线进行基础设施调试（正则表达式回退）

贡献

提交 Issue 或发送 PR。

下一步计划：

  • [ ] 从检测到的模式中自动建议配置条目

  • [ ] Claude Code 钩子集成（提示词前自动脱敏）

  • [ ] 置信度阈值配置

  • [ ] 批量/大规模脱敏模式

  • [ ] 代码块扫描（内联密钥、导入路径）

  • [ ] 账本静态加密

  • [ ] 用于账本审查的 Web UI

许可证

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers