query-sanitizer-mcp

Легковесное MCP-промежуточное ПО, которое располагается между вашими промптами и внешними LLM, автоматически удаляя конфиденциальные данные до того, как они покинут ваш компьютер.

[Your Prompt] → sanitize_query() → [Safe Prompt] → External LLM → [Response] → restore_response() → [You]

v0.3.0 — Четырехэтапный DLP-конвейер: regex → 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

Инструменты

Конвейер обнаружения

Этап 1 — Предварительная проверка через Regex (всегда выполняется, модель не требуется)

Детерминированные шаблоны для структурированных токенов. Работает, даже когда локальная модель отключена.

Этап 2 — Уточнение LLM (контекстное, «лучшее из возможного»)

Выявляет сущности, требующие семантического понимания: названия организаций, используемые в контексте, кодовые имена проектов, ссылки GEO_INTERNAL, юридические термины, шаблоны INTERNAL_URL. Если локальная модель недоступна, возвращается результат Этапа 1 с четким предупреждением.

Этап 3 — Проверка достоверности после сканирования

Запускает высокоточные regex-шаблоны по очищенному тексту, чтобы пометить потенциальные пропуски LLM (например, JWT, который модель не заметила). Отображается как предупреждение в отчете.

Установка

Вариант А — M4 MacBook (рекомендуется)

Стек: Ollama 0.19+ (бэкенд MLX, ~50 ток/с на M4) + GLiNER NER (MPS, ~80 мс/вызов)

# 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"
      }
    }
  }
}

Альтернативные LLM-модели для M4 (все через Ollama):

Вариант 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 ГБ) и gliner_medium-v2.1 (~500 МБ) в кэш Colab. Последующие запуски происходят мгновенно.

Минимальная установка (только regex, модели не нужны)

Если вы хотите работу без зависимостей (чистый regex, без Ollama, без GLiNER):

pip install fastmcp
SANITIZER_MODEL_RETRIES=0 python server.py

Учетные данные, электронные письма, SSN, частные IP-адреса и финансовые суммы определяются только с помощью regex. Люди, названия организаций и кодовые имена проектов требуют 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 и т. д.) встроены как в предварительную проверку regex (для детерминированного сопоставления), так и в системный промпт LLM (для контекстных вариантов). Изменения вступают в силу при следующем вызове sanitize_query — перезапуск сервера не требуется.

Переменные окружения

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

Категории удаления

Модель безопасности

• Учетные данные никогда не сохраняются — в журнал записывается [BLOCKED] вместо оригинального значения

• Отказоустойчивость, а не отказ с открытием — недоступность модели вызывает откат к regex, никогда не пропускает открытый текст

• Только локальный вывод — никакие данные не отправляются на внешний API для этапа очистки

• Режим конфиденциальности (SANITIZER_LEDGER_STORE_ORIGINALS=false) — оригиналы вообще не записываются на диск; восстановление работает только в рамках одной сессии сервера через кэш в памяти

Примеры

Смотрите examples/ для полных трассировок сессий:

1. 01_api_key_leak.md — Учетные данные AWS заблокированы предварительной проверкой regex

2. 02_employee_pii.md — HR-промпт с именами, электронными письмами, ID сотрудников + восстановление

3. 03_internal_infra.md — Отладка инфраструктуры с офлайн-Ollama (откат к regex)

Участие в разработке

Откройте issue или отправьте PR.

Идеи для следующего шага:

• [ ] Автоматическое предложение записей конфигурации на основе обнаруженных шаблонов

• [ ] Интеграция хука Claude Code (автоматическая очистка перед промптом)

• [ ] Настройка порога достоверности

• [ ] Режим пакетной/массовой очистки

• [ ] Сканирование блоков кода (встроенные секреты, пути импорта)

• [ ] Шифрование журнала в покое

• [ ] Веб-интерфейс для просмотра журнала

Лицензия

MIT