umbryn-mcp

텍스트가 LLM에 도달하기 전에 PII/PHI를 자동으로 마스킹하는 MCP 서버 — 자체 호스팅, 실패 시 차단(fail-closed), HIPAA 인지.

규제 산업 분야에서 LLM 및 에이전트 파이프라인을 구축하는 팀에게는 페이로드가 모델 제공업체 인프라로 넘어가기 전에 PHI/PII를 제거할 수 있는 깔끔하고 즉시 사용 가능한 방법이 없습니다. umbryn-mcp가 바로 그 경계입니다. redact, restore, detect라는 세 가지 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

기능

• 세 가지 도구, 하나의 경계 — redact(→ 정리된 텍스트 + 되돌릴 수 있는 토큰 맵), restore(→ 원본), detect(→ 발견된 엔터티, 변경 없음).

• 구조적으로 실패 시 차단 — 감지 오류가 발생하거나 감지 결과가 신뢰 임계값 미만이면 호출이 형식화된 오류를 반환합니다. 불확실성은 차단합니다. 가능한 부분만 마스킹하고 나머지를 통과시키지 않습니다.

• HIPAA 인지 감지 — 체크섬 검증 NPI 및 DEA, 위치 유형 Medicare MBI, 컨텍스트 기반 MRN, CLIA 실험실 ID, 표준 PII(이메일, 전화번호, 주민등록번호, 신용카드, IBAN, IP, URL)를 지원합니다.

• 외부 전송 없음, 자체 호스팅 — 기본 엔진은 순수 정규식 + 체크섬으로 네트워크 호출이나 무거운 의존성이 없습니다. Python이 실행되는 어디에나 설치할 수 있습니다.

• 선택적 ML 업그레이드 — pip install "umbryn-mcp[presidio]"로 Microsoft Presidio + spaCy를 추가하여 PERSON/LOCATION NER을 투명하게 사용할 수 있습니다.

• 되돌릴 수 있고 결정적 — 충돌 없는 형식화된 플레이스홀더로 임의의 입력에 대해 restore(redact(x)) == x를 보장합니다. 동일한 입력과 구성은 항상 동일한 출력을 생성합니다.

언제 사용해야 하나요 (그리고 언제 사용하지 말아야 하나요)

다음과 같은 경우 umbryn-mcp를 사용하세요:

• 의료, 임상, 금융 또는 사용자 생성 텍스트를 타사 LLM API로 보내면서 해당 제공업체의 인프라와 로그에 PHI/PII가 노출되는 것을 방지해야 하는 경우.

• 규제 산업 분야에서 에이전트 또는 MCP 파이프라인을 구축하면서 한 번의 도구 호출로 연결할 수 있는 즉시 사용 가능한 마스킹 경계를 원하는 경우.

• 다운스트림 단계가 계속 작동하도록 되돌릴 수 있는 마스킹이 필요한 경우: redact → 모델에 전송 → restore.

• 한 줄 한 줄 감사할 수 있는 자체 호스팅, 외부 전송 없는 감지기를 원하는 경우.

• 이름과 이메일뿐만 아니라 HIPAA 특정 식별자(NPI, DEA, Medicare MBI, MRN, CLIA)가 필요한 경우.

다음과 같은 경우 다른 것을 사용하세요:

• 되돌릴 수 없는 비식별화/익명화(토큰화, k-익명성)가 필요한 경우 — 여기서의 마스킹은 설계상 되돌릴 수 있습니다.

• 텍스트가 아닌 데이터(이미지, 오디오, PDF, 데이터베이스 행)를 마스킹해야 하는 경우 — 범위는 텍스트입니다.

• 인증된 컴플라이언스 제품을 원하는 경우 — 이는 컴플라이언스 프로그램이 아닌 하나의 기술적 통제 수단입니다(범위 및 솔직한 한계 참조).

• 요청 경로의 모든 것을 자동으로 정리하는 투명한 프록시를 원하는 경우 — 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 → model → restore이며, 토큰 맵은 절대 외부로 유출되지 않습니다.

1. 모델 전에 정리. redact(user_text)를 호출하세요. LLM에는 redacted_text만 보내세요. token_map은 프로세스에 보관하고 원시 입력만큼 민감하게 취급하며 모델에 절대 전달하지 마세요.

2. 모델이 플레이스홀더로 작업하도록 하세요. 모델은 [NPI_1], [US_SSN_1] 등을 보고 추론하고 그대로 에코할 수 있는 의미상 중립적인 토큰으로 인식합니다.

3. 나중에 복원. restore(model_output, token_map)를 호출하여 모델 응답의 실제 값을 사용자나 데이터베이스에 도달하기 전에 다시 바꿔 넣으세요.

4. 차단 처리. redact가 [LOW_CONFIDENCE] 또는 [DETECTION_ERROR] 도구 오류를 반환하면 경계가 유출을 거부한 것입니다. 이를 표면화하고 입력을 강화하거나 위험을 낮추되 원시 텍스트를 계속 보내지 마세요.

파이프라인에서 신뢰하기 전에 대표적인(합성) 데이터로 detect(sample_text)를 호출하여 무엇이 감지되고 무엇이 감지되지 않는지 정확히 확인하고 아래 임계값을 위험 허용 수준에 맞게 조정하세요.

정확한 실패 시 차단

모든 redact 호출을 제어하는 두 가지 임계값이 있습니다.

• 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를 실행하는 것은 규정 준수 설계의 일부가 될 수 있지만, 인증, 보장, 또는 업무 제휴 계약(BAA), 위험 평가, 법률 자문을 대체하는 것은 아닙니다.

구체적으로, 이 프로젝트는 다음을 수행하지 않습니다: 100% 탐지를 보장하지 않으며(어떤 탐지기도 그럴 수 없음), 되돌릴 수 있는 삭제 이상의 비식별화를 수행하지 않으며, 비텍스트 데이터를 다루지 않으며, v1에서 투명 프록시 역할을 하지 않습니다(삭제는 직접 연결하는 명시적 도구 호출을 통해 이루어집니다). 완벽한 탐지기는 없습니다 — 의존하기 전에 자체 대표 데이터로 평가하십시오. 전체 경계, 가정, 잔여 위험은 docs/THREAT_MODEL.md를, 문제 보고는 SECURITY.md를 참조하십시오.

기여 방법

기여는 언제나 환영합니다 — 첫 오픈소스 PR을 만들기에 의도적으로 친근한 곳이며, 관리자는 빠르게 응답하려고 노력합니다.

가장 쉽고 가치 높은 기여: 새 식별자에 대한 탐지 인식기 추가(정규식 + 선택적 검증 숫자 검증기 + 테스트). add-a-recognizer 이슈 양식이 사양을 겸하며, CONTRIBUTING.md에서 여섯 단계를 안내합니다.

도움이 될 수 있는 다른 좋은 방법: 문서 개선, 테스트 케이스 또는 예제 클라이언트 구성 추가, 로드맵의 항목 선택. 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 팀이 만들었습니다.