obsify

민감한 파일의 원시 값이 모델의 컨텍스트에 들어가지 않도록 AI 어시스턴트가 작업할 수 있게 합니다.

obsify는 로컬에서 작동하는 결정론적 MCP 서버입니다. 프론티어 모델은 형태(shape) — 스키마, 합성 트윈, 마스킹된 피드백 — 에 대해 추론하고, 결정론적 로컬 코드는 실체(substance)를 다루며 마스킹되고 집계된 결과만 반환합니다. LLM 호출이 없고, 런타임에 네트워크도 없습니다: 탐지는 정규식 + 체크섬 + 사전 + Presidio의 로컬 NER을 사용합니다.

호주 엔터티 지원(ABN / ACN / TFN, 체크섬 검증)과 레이블 기반 라우팅 계층을 제공하여 "어시스턴트가 원시 데이터를 피해야 하는 시점"을 판단 호출이 아닌 결정론적이고 강제된 결정으로 만듭니다.

정직한 범위: run_on_real은 모델이 작성한 코드를 최선의 노력 로컬 샌드박스에서 실행하고 그 출력을 최선의 노력으로 마스킹합니다. 감옥이 아닙니다. 유출을 감당할 수 없는 항목에 사용하기 전에 SECURITY.md를 읽으십시오. 집계 결과를 반환합니다.

이유

기밀 문서를 호스팅된 LLM에 제공하면 실체가 경계를 벗어납니다. 일반적인 대답은 "LLM을 사용하지 마라" 또는 "제공자를 신뢰하라"입니다. obsify는 세 번째 경로를 취합니다 — 데이터로의 컴퓨팅(compute-to-data): 데이터를 모델로 가져오지 않고 코드를 데이터로 가져옵니다.

• 모델은 스프레드시트의 스키마를 보고, 행을 보지 않습니다.

• 모델은 합성 트윈(가짜 값, 실제 구조)에 대해 개발합니다.

• 모델의 분석 코드는 로컬에서 실행됩니다. 마스킹되고 집계된 출력만 반환됩니다.

프론티어 모델의 추론은 보존됩니다. 원시 값에 대한 눈만 제거됩니다.

Related MCP server: Cloakbox

도구

지원 문서: PDF (텍스트 + 표; 복잡한 표는 obsify[tables]를 통한 폴백), Excel .xlsx/.xlsm, Word .docx (문단 + 표). 읽을 수 없거나 지원되지 않는 파일은 명시적 메모/사각지대로 표시되며, 조용히 버려지지 않습니다. (OCR 없음 — 스캔/이미지 페이지는 저범위로 표시되며, 변환되지 않습니다.)

알려진 엔터티 마스킹 (선택 사항). 숨길 이름의 로컬 .obsify.entities 목록을 제공하면 scan_pii / redact_text가 결정론적으로 이를 잡아내며 — NER이 놓치는 접미사/약어 변형(BRIGHTWATER HLDGS P/L for Brightwater Holdings Pty Ltd)도 — KNOWN_ENTITY로 처리합니다. 목록은 로컬에 남아 모델의 컨텍스트에 절대 들어가지 않습니다. docs/known_entities.md 참조.

데모

공식 MCP Inspector를 사용하여 합성 데이터에 대해 다섯 가지 도구를 모두 실시간으로 시험해 보세요:

python -m obsify.make_corpus --out ./corpus_demo
npx @modelcontextprotocol/inspector obsify-mcp

./corpus_demo/ledger.xlsx에 대해 scan_pii를 호출하고 유형/개수/위치만 반환하고 값은 절대 반환하지 않는지 확인하세요. docs/verifying.md 참조.

사용해 보기 — 합성 코퍼스

세 가지 형식을 모두 포괄하는 가짜이지만 현실적인 코퍼스(모두 합성; ABN/ACN/TFN은 체크섬 검증됨)를 생성한 다음 도구를 가리키세요:

pip install "obsify[demo]"                 # reportlab, for the sample PDFs
python -m obsify.make_corpus --out ./corpus_demo

다중 시트 Excel 원장(숫자 오탐 지뢰밭), PDF 위임장(산문 + 시산표), DOCX 감사 메모(문단 + 공급업체 표)를 작성합니다. 실제 데이터를 건드리지 않고 scan_pii / make_synthetic_twin을 시험해 보기에 좋습니다.

설치 및 MCP 서버로 실행

Python 3.11+ 필요. obsify는 stdio를 통해 MCP와 통신합니다 — 클라이언트가 로컬 하위 프로세스로 실행합니다. 원격으로 호스팅되지 않습니다. MCP 호환 클라이언트(Claude Desktop, Claude Code, Cursor, VS Code 등)에 등록하려면 해당 클라이언트의 설정에 블록 하나를 추가하세요.

권장 — uvx를 통한 제로 설치:

{ "mcpServers": { "obsify": { "command": "uvx", "args": ["obsify-mcp"] } } }

uvx는 PyPI에서 obsify를 가져와 요청 시 실행합니다 — 영구 설치 불필요. 첫 실행 시 obsify는 spaCy NER 모델(en_core_web_lg, ~560 MB)을 한 번 다운로드하여 캐시합니다. 이는 공개 모델을 가져오며 사용자 데이터를 보내지 않습니다(금지하려면 OBSIFY_AUTO_DOWNLOAD=0 설정하고 직접 모델 설치). 이후 실행은 즉시 이루어지며 완전히 오프라인입니다.

또는 설치 (pip / pipx):

pipx install obsify        # isolated, on PATH  (or: pip install obsify)

그런 다음 클라이언트를 설치된 명령어로 지정하세요:

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

클라이언트를 다시 시작하면 도구가 나타납니다. 선택적 추가 기능: obsify[tables] (camelot + Ghostscript를 통한 복잡한 표 PDF 폴백), obsify[compute] (pandas, run_on_real 코드 내에서 유용).

PATH 문제 (서버 연결 실패의 #1 원인): command는 클라이언트가 보는 PATH에서 확인 가능해야 합니다. GUI 클라이언트는 가상 환경의 PATH를 공유하지 않을 수 있습니다. 해결책: uvx/pipx 사용 (전역적으로 확인 가능), 또는 절대 경로 제공 — "/path/to/.venv/bin/obsify-mcp" (macOS/Linux) 또는 "C:\path\to\.venv\Scripts\obsify-mcp.exe" (Windows).

이 저장소에서 (PyPI에 올리기 전):

pip install "git+https://github.com/Formative-Sum41/obsify.git"   # gets `obsify-mcp` + `obsify`

라우팅 계층 — 결정론적, 판단 호출이 아님

"도와주지만 기밀 파일을 읽지 마세요"의 어려운 부분은 보호 시점을 결정하는 것입니다. obsify는 그 결정을 모델에서 환경으로 옮깁니다:

1. .obsify.json — 경로를 분류하는 레이블 매니페스트 (public / confidential / restricted).

2. obsify.guard (python -m obsify.guard로 실행) — 레이블이 지정된 파일의 직접 읽기를 차단(종료 코드 2)하고 어시스턴트를 scan_pii / make_synthetic_twin / run_on_real로 리디렉션하는 PreToolUse 가드.

3. 관례 (CLAUDE.md에 있음) — 어시스턴트가 가드에 도달하기 전에 obsify를 선호하도록 함.

한 명령으로 설정:

obsify init [--dir PATH] [--with-claude-md]

obsify init은 비파괴적으로 설계되었습니다 — 정확히 하나의 파일을 소유하고 나머지에 대한 스니펫을 제공합니다:

• .obsify.json — obsify가 소유; init이 작성함 (--force 없이 덮어쓰지 않음).

• .claude/settings.json — 사용자 파일: init은 PreToolUse 훅 블록을 출력하여 붙여넣도록 하며, 직접 편집하지 않음 (코드를 실행하므로 등록은 사용자 결정).

• CLAUDE.md — 사용자 파일: 관례는 옵트인. 기본적으로 출력; --with-claude-md는 마커로 감싸진 멱등 블록을 추가하여 사용자 콘텐츠를 덮어쓰지 않음.

전체 관례: docs/obsify_routing.md.

탐지 정밀도 유지 방법

• 체크섬 검증 식별자. ABN/ACN/TFN 후보는 정규식으로 제안되고 공식 체크섬으로 확인되므로, 임의의 숫자가 식별자로 보고되지 않습니다.

• 컨텍스트 필요 ID. 레이블 단어("TFN", "ABN", "BSB", …)가 근처에 있을 때만 숫자가 ABN/ACN/TFN으로 허용됩니다 — 이는 숫자 원장에서 순차 저널 ID 오탐 홍수를 차단합니다.

• 문자 없는 / 숫자 포함 NER 억제. 순수 숫자, 금액, 날짜 및 영숫자 코드는 이름/조직으로 플래그되지 않습니다. 실제 이름, 이메일 및 주소(문자를 포함)는 영향을 받지 않습니다. 검증된 문자 없는 PII는 예외로 유지: 체크섬 ID(ABN/ACN/TFN/Medicare), Luhn 카드, 유효 IP, BSB 인접 계좌, 전화(컨텍스트 또는 전화 형태를 통해) — 소수점은 여전히 금액을 표시하며 전화가 아닙니다.

측정된 정확도

obsify는 점수 평가 하네스(eval/ — 레이블이 지정된 합성 코퍼스 + 정답 키 + 배송되는 탐지기에 대한 스코어러, 추가로 독립적인 제3자 교차 확인)를 제공합니다. 합성 코퍼스에 대한 헤드라인: 예상 탐지 항목에 대해 100% 재현율, 숫자 FP-고문 시트(그룹화된 숫자 가드 포함)에서 0 오탐, 맥락 게이트 ID가 올바르게 억제됨. Microsoft presidio-research에 대한 독립 교차 확인: EMAIL/IBAN 100%, PERSON 94%.

하네스는 그 가치를 입증했습니다 — 실제 결함을 발견했고, 이후 수정되었습니다: 신용 카드와 전화번호가 숫자 노이즈 필터에 의해 조용히 억제되고 있었음(이제 체크섬 검증/전화 형태를 통해 예외 처리됨), Medicare, IP, 생년월일, 호주 여권 및 운전면허증에는 인식기가 없었음(이제 추가됨, 체크섬 또는 컨텍스트 게이트). 전체 방법, 숫자 및 남은 문서화된 격차(SWIFT/BIC, 생년월일이 아닌 날짜): eval/README.md.

테스트

pip install -e ".[dev]"
pytest tests/            # or run any file directly: python tests/test_obsify.py

12개 스위트(73개 테스트), Linux + Windows / Python 3.11 + 3.12에서 CI 실행:

• mcp-protocol — 실제 서버를 stdio로 실행하고 MCP와 통신(Claude와 같은 클라이언트가 사용하는 동일한 경로): 다섯 도구 모두 유효한 스키마로 등록되고 호출이 JSON-RPC를 통해 왕복하는지 확인 — scan_pii가 형태만, 종단 간 반환하는지 포함.

• checksums — 외부에 게시된 ABN/ACN/TFN 작업 예제(유효 및 손상)에 고정되어 생성기↔검증기 순환성을 깨뜨림.

• obsify / twin / redaction — 개인정보 보호 불변성: 형태만 출력, 누출 없는 트윈, 실패-폐쇄 자체 점검.

• precision — 오탐 억제기가 숫자 원장 노이즈를 죽이면서 실제 이름을 유지하는지.

• routing — 가드의 차단/허용 분류 및 obsify init의 비파괴 계약.

• corpus — 합성 PDF+Excel+DOCX 코퍼스 종단 간: 형식별 탐지, DOCX 문단+표 추출, 모든 형식에서 형태만 출력.

• evaluation — 회귀 게이트로서 점수 하네스(재현율, 억제, FP-고문, 격차).

• robustness — 우아한 저하: 손상/초대형/빈/중첩/지원되지 않는 입력이 절대 충돌하지 않고 항상 메모로 표시됨.

• model / variants — 첫 실행 모델 자동 다운로드 로직; verify_value_free 뒤의 변형 정규화.

대화형 검증(MCP Inspector) 및 라이브 클라이언트 최종 점검은 docs/verifying.md 참조.

라이선스

MIT — LICENSE 참조.