umbryn-mcp

MCP-сервер, который удаляет PII/PHI из текста до того, как он попадёт в LLM — самохостинг, fail-closed и с учётом HIPAA.

Команды, строящие LLM- и агентные пайплайны в регулируемых областях, не имеют чистого, готового способа удалить PHI/PII из полезной нагрузки до того, как она пересечёт границу инфраструктуры провайдера модели. umbryn-mcp — это та самая граница: три MCP-инструмента — redact, restore, detect — которые заменяют чувствительные значения обратимыми плейсхолдерами, работают полностью внутри вашей инфраструктуры и блокируют запрос, если обнаружение неопределённо, вместо утечки данных.

redact("Patient MRN: 1234567, provider NPI 1234567893, ssn 078-05-1120, john.doe@example.com")

  redacted_text  (safe to send to the model):
    "Patient MRN: [MEDICAL_RECORD_NUMBER_1], provider NPI [NPI_1], ssn [US_SSN_1], [EMAIL_ADDRESS_1]"

  token_map      (kept local, never sent to the model):
    [MEDICAL_RECORD_NUMBER_1] → 1234567
    [NPI_1]                   → 1234567893
    [US_SSN_1]                → 078-05-1120
    [EMAIL_ADDRESS_1]         → john.doe@example.com

Отправьте отредактированный текст модели; храните token_map локально; затем вызовите restore, чтобы восстановить результат. Обратные преобразования побайтово точны и подтверждены property-based тестами.

Зачем это существует

Ниша MCP-редактирования PHI/PII реальна, но недостаточно обслуживается — существующие варианты представляют собой тонкие обёртки над Presidio без специфического для HIPAA обнаружения и, что критично, без гарантии, что сбой обнаружения заблокирует запрос, а не молча пропустит необработанные данные. Поэтому команды либо создают собственную границу, либо отправляют чувствительные данные провайдеру и полагаются на BAA, чтобы это покрыть — ошибка на этапе проектирования, которая приводит к реальным инцидентам с комплаенсом.

Почему это было создано: MCP быстро стал мейнстримом — теперь он первоклассный в Claude, Cursor и ChatGPT, среди тысяч серверов — но уголок редактирования PHI/PII остался на несколько неподдерживаемых обёрток. Это заполняет пробел единой честной, проверяемой, fail-closed границей, оставаясь открытым исходным кодом, чтобы логика редактирования, от которой вы зависите, была полностью инспектируемой, а не чёрным ящиком.

Related MCP server: pii-anonymizer

Возможности

• Три инструмента, одна граница — redact (→ очищенный текст + обратимая карта токенов), restore (→ оригинал), detect (→ найденные сущности, без изменений).

• Fail-closed по построению — если обнаружение выдаёт ошибку или любое обнаружение опускается ниже порога уверенности, вызов возвращает типизированную ошибку. Неопределённость блокирует; никогда не редактирует то, что может, и не пропускает остальное.

• Обнаружение с учётом HIPAA — NPI и DEA с проверкой контрольной суммы, Medicare MBI с типизацией позиций, MRN с привязкой к контексту, лабораторные ID CLIA, плюс стандартные PII (email, телефон, SSN, кредитные карты, IBAN, IP, URL).

• Нулевой исходящий трафик, самохостинг — движок по умолчанию — чистый regex + контрольные суммы, без сетевых вызовов и без тяжёлых зависимостей. Устанавливается везде, где есть Python.

• Опциональное ML-обновление — pip install "umbryn-mcp[presidio]" добавляет Microsoft Presidio + spaCy для NER PERSON/LOCATION прозрачно.

• Обратимо и детерминированно — защищённые от коллизий типизированные плейсхолдеры делают restore(redact(x)) == x для произвольного ввода; одинаковый ввод + конфигурация всегда дают одинаковый вывод.

Когда использовать (а когда нет)

Используйте umbryn-mcp, когда:

• Вы отправляете медицинский, клинический, финансовый или пользовательский текст в сторонний LLM API и нужно держать PHI/PII вне инфраструктуры и логов этого провайдера.

• Вы строите агентный или MCP-пайплайн в регулируемой области и хотите готовую границу очистки, которую подключаете одним вызовом инструмента.

• Вам нужна обратимая редакция, чтобы последующие шаги работали: redact → отправить модели → restore.

• Вы хотите самохостинговый, без исходящего трафика детектор, который можно аудитировать построчно.

• Вам нужны специфические для HIPAA идентификаторы (NPI, DEA, Medicare MBI, MRN, CLIA), а не только имена и email.

Используйте что-то другое, когда:

• Вам нужна необратимая деидентификация / анонимизация (токенизация, k-анонимность) — здесь редакция обратима по замыслу.

• Вам нужно редактировать не текстовые данные (изображения, аудио, PDF, строки БД) — область применения — текст.

• Вы хотите сертифицированный комплаенс-продукт — это один технический контроль, а не программа комплаенса (см. Область применения и честные ограничения).

• Вы хотите прозрачный прокси, который автоматически очищает всё в пути запроса — v1 — явные вызовы инструментов; режим прокси в дорожной карте.

• Вам требуется гарантированный 100% recall — ни один детектор, включая этот, не может этого обещать.

Быстрый старт (< 60 секунд)

pip install umbryn-mcp        # zero heavy deps; runs immediately

Затем зарегистрируйте его в вашем MCP-клиенте.

Claude Desktop / Claude Code (claude_desktop_config.json или claude mcp add umbryn-mcp -- umbryn-mcp):

{
  "mcpServers": {
    "umbryn-mcp": {
      "command": "umbryn-mcp"
    }
  }
}

Cursor (.cursor/mcp.json) и VS Code используют ту же форму — см. examples/ для готовых к вставке конфигов.

Хотите также обнаружение имён/адресов?

pip install "umbryn-mcp[presidio]"
python -m spacy download en_core_web_lg

Сервер автоматически обнаруживает Presidio и обновляется — изменений конфигурации не требуется. (Установите UMBRYN_ENGINE=regex, чтобы принудительно использовать движок без зависимостей, или =presidio, чтобы требовать ML-движок.)

Как это работает

Вызов инструмента приходит через stdio; ядро Redactor запускает настроенный движок обнаружения, детерминированно разрешает перекрытия, применяет проверку порога fail-closed и заменяет обнаруженные диапазоны обратимыми типизированными плейсхолдерами. Только очищенный текст должен покидать границу, которую вы запускаете.

flowchart LR
    A[MCP client<br/>Claude · Cursor · agent] -- redact / restore / detect --> B[umbryn-mcp<br/>stdio server]
    B --> C[Redactor core<br/>fail-closed · reversible]
    C --> D{Detection engine}
    D -->|default, zero deps| E[Regex + checksums]
    D -->|optional| F[Presidio + spaCy NER]
    C -. scrubbed text .-> A
    A -- scrubbed text only --> G[(LLM / downstream)]

Ядро Redactor зависит только от небольшого интерфейса DetectionEngine — никогда напрямую от Presidio или MCP. Необработанные данные и движок обнаружения остаются внутри границы, которую вы запускаете; только очищенный текст покидает её. См. docs/ARCHITECTURE.md и docs/THREAT_MODEL.md.

Инструменты

redact(text) → { redacted_text, token_map, entities }

Заменяет обнаруженные PHI/PII типизированными плейсхолдерами, например [NPI_1]. token_map сопоставляет каждый плейсхолдер с его исходным значением — храните его локально; никогда не отправляйте модели. entities перечисляет, что было отредактировано (тип/диапазон/оценка) для аудита.

restore(redacted_text, token_map) → { text }

Обращает редактирование, восстанавливая исходный текст точно. Безопасно вызывать на выходе модели, который всё ещё содержит плейсхолдеры.

detect(text) → { entities, count }

Сообщает найденные сущности — тип, диапазон, уверенность — без изменения текста. В отличие от redact, он показывает низкоуверенные совпадения, а не блокирует, чтобы вы могли проверить покрытие перед доверием границе в пайплайне.

Как использовать (реальный пайплайн)

Паттерн — redact → model → restore, при этом карта токенов никогда не покидает вашу сторону:

1. Очистите перед моделью. Вызовите redact(user_text). Отправьте только redacted_text в LLM. Держите token_map в своём процессе — обращайтесь с ним так же чувствительно, как с исходным вводом, и никогда не передавайте модели.

2. Пусть модель работает с плейсхолдерами. Она видит [NPI_1], [US_SSN_1] и т.д. — семантически нейтральные токены, о которых она может рассуждать и которые может повторять.

3. Восстановите после. Вызовите restore(model_output, token_map), чтобы подставить реальные значения обратно в ответ модели, прежде чем он достигнет вашего пользователя или базы данных.

4. Обработайте блокировку. Если redact возвращает ошибку инструмента [LOW_CONFIDENCE] или [DETECTION_ERROR], граница отказалась пропустить утечку — сообщите об этом, ужесточите ввод или снизьте риск, но не отправляйте необработанный текст дальше.

Прежде чем доверять пайплайну, вызовите detect(sample_text) на репрезентативных (синтетических) данных, чтобы увидеть, что именно ловится, а что нет, и настройте пороги (ниже) под свой уровень риска.

Fail-closed, точно

Два порога управляют каждым вызовом redact:

• detection_floor (по умолчанию 0.35) — граница чувствительности. Сигналы ниже неё считаются шумом.

• min_confidence (по умолчанию 0.5) — порог доверия.

Любой кандидат, переживший пол, но набравший ниже min_confidence, переводит вызов в режим fail-closed: он возвращает ошибку [LOW_CONFIDENCE], а не редактирует уверенные диапазоны и пропускает неопределённый. Ошибки движка возвращают [DETECTION_ERROR]. При любой ошибке отредактированный текст не возвращается. Оба порога настраиваются (см. ниже).

Конфигурация

Всё опционально; разумные значения по умолчанию означают, что он работает без конфигурации. Задаётся через блок env клиента.

Файл конфигурации

Для настроек, которые не умещаются в плоскую переменную окружения, укажите UMBRYN_CONFIG на JSON-файл. Переменные окружения по-прежнему имеют приоритет над файлом для скалярных значений выше, так что вы можете поставить один файл и подстраивать под каждый запуск. Некорректный файл (плохой JSON, неизвестный порог, некомпилируемый regex) приводит к закрытому сбою при запуске, а не к молчаливой деградации.

{
  // Per-entity trust thresholds override min_confidence for that type.
  "entity_thresholds": { "PHONE_NUMBER": 0.7, "IP_ADDRESS": 0.9 },

  // Entity types to drop entirely — never detected, never redacted.
  // (A privacy trade-off you're opting into: a disabled type can leak.)
  "disabled_entities": ["URL"],

  // Your own recognizers, no fork required. `validator` names a built-in
  // check-digit function (luhn, npi, dea, iban, nhs) — config supplies data,
  // never code.
  "recognizers": [
    {
      "entity_type": "EMPLOYEE_ID",
      "regex": "\\bEMP-\\d{6}\\b",
      "base_score": 0.85,
      "context": ["employee", "badge"],
      "context_required": false
    }
  ],

  "audit_log": true
}

Готовый к копированию пример находится в examples/umbryn_config.json.

Покрытие сущностей

Benchmark

Качество обнаружения измеряется, а не декларируется. Числа ниже получены на движке по умолчанию (без зависимостей) при оценке на синтетическом оценочном корпусе — 200 сгенерированных документов, ~1800 размеченных фрагментов, с похожими на настоящие идентификаторы значениями, не проходящими контрольную сумму, вкраплёнными как дистракторы для честной оценки точности. Воспроизвести их можно командой python eval/run_eval.py --markdown.

\* = идентификатор, значимый для HIPAA, подлежащий контролю качества CI. Совокупно по контролируемому набору: точность 0.99, полнота 1.00. Сборка не проходит контроль, если полнота падает ниже 0.90 или точность ниже 0.80. (12 ложных срабатываний NPI — это похожие 10-значные числа, которые проходят контрольную цифру Luhn/80840 — намеренный отказоустойчивый уклон в сторону избыточного редактирования.)

Это синтетические, наилучшие условия с чистой разметкой и окружающими контекстными словами; реальные тексты более запутанные. Относитесь к этому как к защитному барьеру регрессий и проверке здравомыслия, а не как к гарантии — всегда оценивайте на своих репрезентативных данных.

Область применения и честные ограничения

Этот инструмент снижает раскрытие PHI/PII на одной границе. Он не делает систему «соответствующей HIPAA». Соответствие — это свойство всей системы и организации — её политик, контрактов, контроля доступа, аудиторской позиции и людей, — а не какой-то отдельной библиотеки. Запуск umbryn-mcp может быть частью соответствующей архитектуры, но это не сертификация, не гарантия и не замена Соглашению с деловым партнёром, оценке рисков или юридической консультации.

Конкретно, этот проект не: гарантирует 100% обнаружение (ни один детектор не гарантирует), не деидентифицирует за пределами обратимой редакции, не охватывает нетекстовые данные и не действует как прозрачный прокси в v1 (редакция выполняется через явные вызовы инструментов, которые вы подключаете). Ни один детектор не идеален — оценивайте на своих репрезентативных данных, прежде чем полагаться на него. Полные границы, допущения и остаточные риски см. в docs/THREAT_MODEL.md, а о проблемах сообщайте в SECURITY.md.

Как внести вклад

Вклад очень приветствуется — это намеренно дружелюбное место для вашего первого PR в open-source, и мейнтейнер старается отвечать быстро.

Самый лёгкий ценный вклад: добавьте распознаватель для нового идентификатора (regex + опциональный валидатор контрольной цифры + тест). Форма issue add-a-recognizer одновременно служит спецификацией, а CONTRIBUTING.md описывает шесть шагов.

Другие хорошие способы помочь: улучшить документацию, добавить тестовые примеры или примеры конфигураций клиентов, или взять что-то из дорожной карты. Просмотрите хорошие первые задачи или откройте issue, чтобы предложить что-то своё.

git clone https://github.com/Rinava/umbryn-mcp && cd umbryn-mcp
pip install -e ".[dev]"
pytest                 # fast invariant suite (Presidio faked, sub-second)
ruff check . && mypy src/umbryn_mcp
python eval/run_eval.py

Полное руководство — настройка разработки, соглашения и правило «никаких реальных PHI в фикстурах» — находится в CONTRIBUTING.md. Внося вклад, вы соглашаетесь, что ваша работа лицензируется по MIT.

Лицензия

MIT — соответствует Presidio и максимизирует повторное использование. Создано с помощью Microsoft Presidio (опционально) и MCP Python SDK.

umbryn-mcp создан командой, стоящей за Kenda.