umbryn-mcp

LLMに届く前にテキストからPII/PHIをマスキングするMCPサーバー — セルフホスト、フェイルクローズ、HIPAA対応。

規制対象領域でLLMやエージェントのパイプラインを構築しているチームには、ペイロードがモデルプロバイダーのインフラに入る前にPHI/PIIを取り除く、クリーンでドロップイン可能な手段がありません。umbryn-mcp はその境界です。redact、restore、detect という3つのMCPツールを提供し、機密値を元に戻せるプレースホルダーに置き換え、あなたが管理するインフラ内で完全に実行され、検出があいまいな場合はデータを漏らさずにリクエストをブロックします。

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 を呼び出して結果を復元してください。ラウンドトリップはバイト単位で正確で、プロパティベースのテストによって実証されています。

存在理由

PHI/PIIマスキングのMCP領域は実在しますが、十分に整備されていません。既存の選択肢は、HIPAA固有の検出機能を持たない薄いPresidioラッパーであり、さらに重要なことに、検出失敗がリクエストをブロックして生データを黙って通すことを防ぐ保証がありません。そのため、チームは自前の境界を実装するか、生データをプロバイダーに送信してBAA（ビジネスアソシエイト契約）に頼るという、実際のコンプライアンスインシデントを引き起こす設計時の誤りに陥ります。

作られた理由: MCPは急速に主流化しました。Claude、Cursor、ChatGPT、そして何千ものサーバーに第一級のサポートが組み込まれる一方、PHI/PIIマスキングの領域は、ほとんどメンテナンスされていない複数のラッパーだけが残されていました。このプロジェクトは、単一の誠実で監査可能な円い、フェイルクローズの境界を提供し、依存するマスキングロジックをブラックボックスではなく完全に検査可能な形にすることで、そのギャップを埋めます。

Related MCP server: MCP Presidio

特徴

• 3つのツール、1つの境界 — redact（→ マスキング済みテキスト + 元に戻せる token_map）、restore（→ 元のテキスト）、detect（→ 検出エリアのみで変更なし）。

• 構造上のフェイルクローズ — 検出エラーが発生した場合、またはいずれかの検出結果が信頼度しきい値を下回った場合、呼び出しは型付きエラーを返します。不確実さは実行を停止します。検出できた部分だけマスキングして残りを通過させるということはしません。

• HIPAA対応検出 — チェックサム検証済みのNPIとDEA、位置情報型のMedicare MBI、コンテキストを使ったMRN、CLIラボIDに加え、標準的なPII（メール、電話、SSN、クレジットカード、IBAN、IP、URL）。

• ゼロエグレス、セルフホスト — デフォルトエンジンは純粋な正規表現+チェックサムで、**ネットワーク呼び出しも重い依存関係もありません。**Pythonが動く場所ならどこにでもインストールできます。

• 任意のMLアップグレード — pip install "umbryn-mcp[presidio]" を実行するだけで、PERSON/LOCATION のNERをためのMicrosoft Presidio と spaCy が自動で追加されます。

• 元に戻せて決定的 — 衝突のない型付きプレースホルダーにより、restore(redact(x)) == x が任意の入力に対して保証されます。同じ入力+設定なら常に同じ出力になります。

使用すべき場合（そして使用すべきでない場合）

umbryn-mcp を使うべき場合:

• 医療、臨床、財務、またはユーザー生成テキストをサードパーティのLLM APIに送信し、そのプロバイダーのインフラやログにPHI/PIIを残さない必要がある場合。

• 規制領域でAIエージェントまたはMCPのパイプラインを構築していて、ワンツコールで差し込むことができサニタイズ境界が必要な場合。

• 後続のステップが機能するように、復元して化できるマスキングが必要な場合: redact → モデルへ送信 → restore。

• 方が行で監査できるセルフホストのゼロエグレスな検出器を必要する場合。

• 電子メールや名前だけでなく、HIPAA固有の識別子（NPI、DEA、Medicare MBI、MRN、CLIA）が必要な場合。

それ以外のケースでは別の方法を選ぶべき:

• 不可逆的な非識別化/匿名化（トークン化、k-匿名化）が必要 – ここのマスキングは仕様として元に戻せます。

• テキスト以外のデータ（画像、音声、PDF、データベース行）をマスキングする必要がある場合 — 対象はテキストのみです。

• 認定されたコンプライアンス製品を求めています — これは1つの技術的制御であって、コンプライアンスプログラム全体ではありません（【【どこー-----【「ドキュメント」と正直な限界]参照）。

• 透過プロキシとして、リクエスト経路内のすべてを自動マスキングしたい場合 — v1は明示的なツール呼び出しです。プロキシモードはロードマップにあります。

• 100%の再現性を保証が必要な場合 — このプロジェクトを含め、検出器はそれを保証できません。

クイックスタート（< 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 コアが設定された検出エンジンを実行し、重なりを決定論的に解決し、フェイルクローズのしきい値チェックを適用して、検出されたスパンを復元可能な型付きプレースホルダーに置き換えます。あなたが実行している境界の外に送信されるのは、マスキング済みテキストだけです。

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 → モデル → restore で、token_mapは開下手元に置きます。

1. モデルの前でスクラブ。 redact(user_text) を呼びます。LLMには redacted_text だけを渡します。token_map はプロセス内に保持し、元の入力と同じように機密扱いにしてください。モデに入れさえてはなりません。

2. モデルにプレースホルダーを扱わせる。 モデルには [NPI_1]、[US_SSN_1] などが表示されます — 考えられる中立的なトークンで、推論してそのままエコーバックできます。

3. 後で復元する。 restore(model_output, token_map) を呼び出して、モデルの応答がユーザーやそのDBに届く前に、実際の値に戻します。

4. ブロックの処理。 redact が [LOW_CONFIDENCE] や [DETECTION_ERROR] を返した場合、境界がデータ漏出を防いだことになります。そのエラーを可視化し、入力を厳しくするかリスクを下げるかを実行し、でも生テキストを先のまま送らないでください。

パイプラインでその境界を本番でどう使うかは、まず代表的な（サンプルの）データで detect(sample_text) を呼び、何が検出されて何がされないかを確認し、しきい値（下記）を許容可能なリスクに合わせてチューニングしてください。

フェイルクローズの正確な動作

すべての redact 呼び出しは2つのしきい値を制御します:

• detection_floor (デフォルト 0.35) — 感度の境界。これを下回るシグナルはノイズとして扱われます。

• min_confidence (デフォルト 0.5) — 信頼しきい値。

検出はフロアは超えたものの**min_confidence未満**のとき、その呼び出しはフェイルクローズモードになります。確かな部分だけを置き換えて不確実な部分を通すのではなく、[LOW_CONFIDENCE] エラーが返ります。エンジンの処理がエラーになったときは [DETECTION_ERROR] が返ります。いずれのエラーでもマスキング済みテキストを返しません。 両方のしきい値は設定可能です。

設定

すべて任意です。まともなデフォルトなので、設定ゼロで動作します。クライアントの env ブロックで設定します。

設定ファイル

フラットな環境変数に収まらない設定は、UMBRYN_CONFIG で JSON ファイルを指定します。上記の値は環境変数がファイル設定より優先されるので、ファイルを共通のベースにして起動時だけをチューニングできます。ファイルが不正（JSONフォルト、未知のしきい値、コンパイルできない正規表現）の場合、静かにで落ちるのではなく、起動時にフェイルクローズします。

{
  // 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 にあります。

エンティティカバレッジ

ベンチマーク

検出品質は主張ではなく測定されています。以下の数値は、デフォルト（依存関係ゼロ）エンジンを 合成評価コーパス に対して実行した結果です — 200 件の生成ドキュメント、約 1,800 のラベル付きスパン、チェックサムに失敗する類似文字列をディストラクタとして織り込み、精度を正直に保っています。python eval/run_eval.py --markdown で再現できます。

\* = HIPAA 関連識別子であり、CI 品質ゲートの対象です。ゲート対象セットの合計: 精度 0.99、再現率 1.00。 再現率が 0.90 未満または精度が 0.80 未満に低下すると、ゲートはビルドを失敗させます。（NPI の 12 件の誤検出は、たまたま Luhn/80840 チェックディジットを通過する類似の 10 桁の数字です — 意図的な、過剰編集に偏るフェイルセーフなバイアスです。）

これらは、クリーンな書式と近くのコンテキスト語を備えた合成の最良条件です。実際のテキストはもっと乱雑です。 これは回帰のガードレールであり、健全性チェックとして扱ってください。保証ではありません — 常に独自の代表的なデータで評価してください。

スコープと正直な限界

このツールは、ある境界で PHI/PII の露出を減らします。システムを「HIPAA 準拠」にするものではありません。 準拠は、システムと組織全体の特性です — そのポリシー、契約、アクセス制御、監査体制、そして人々 — 単一のライブラリの特性ではありません。umbryn-mcp を実行することは、準拠した設計の一部になり得ますが、認証でも、保証でも、ビジネスアソシエイト契約、リスク評価、または法律相談の代わりでもありません。

具体的には、このプロジェクトは以下を行いません: 100% の検出を保証する（どの検出器もそうではありません）、可逆的なマスキングを超えた非識別化、非テキストデータのカバー、v1 での透過プロキシとしての動作（マスキングは、配線する明示的なツール呼び出しによるものです）。完璧な検出器はありません — 依存する前に、自分の代表データで評価してください。完全な境界、前提、および残存リスクについては docs/THREAT_MODEL.md を、問題の報告については SECURITY.md を参照してください。

貢献方法

貢献は大歓迎です — ここは意図的に、初めてのオープンソース PR を出すのに親しみやすい場所であり、メンテナーは迅速に応答しようと努めています。

最も簡単で価値の高い貢献: 新しい識別子の検出認識器（正規表現 + オプションのチェックディジットバリデータ + テスト）を追加することです。add-a-recognizer イシューフォーム は仕様を兼ねており、CONTRIBUTING.md が 6 つのステップを説明しています。

その他の良い貢献方法: ドキュメントの改善、テストケースやクライアント設定例の追加、または ロードマップ から何かを選ぶことです。good first issues を閲覧するか、提案するためにイシューを開いてください。

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 の背後にあるチームによって構築されています。