Skip to main content
Glama
securedact-mcp

securedact-mcp

SecuRedact MCP

PyPI Python License: Apache-2.0

SecuRedact는 AI 에이전트와 AI 워크플로우를 위한 로컬 우선(local-first) 개인정보 보호 및 보안 계층입니다. 데이터가 모델, 도구, 파일 또는 외부 대상에 도달하기 전에 개인 데이터/PII, GDPR 민감 정보, 자격 증명, API 키, 토큰, 비밀 및 민감한 파일과 같은 민감한 데이터를 감지하고 보호합니다.

SecuRedact MCP는 Apache-2.0 오픈소스 MCP 서버이자 재사용 가능한 Python 개인정보 보호 엔진입니다. 민감한 텍스트를 감지하고, 버전이 지정된 정책을 적용하며, 로컬에서 편집(redact)하고, 정화된 콘텐츠를 승인으로 표시하기 전에 잔여 출력을 검증합니다.

MCP 모드는 모든 프롬프트를 자동으로 가로채지 않습니다. 호스트는 도구를 호출하고 status == "ok"일 때만 sanitized_text를 보내야 합니다. 잘못 구성되었거나 악의적인 MCP 호스트는 일반적인 MCP 워크플로우를 우회할 수 있습니다. 공급자 네이티브 강제 훅(provider-native enforced hooks)은 별도의 통합 자산입니다. 지원되는 공급자가 프롬프트 수명 주기 경계에서 그러한 훅을 호출하면 일반 모델 처리 전에 동일한 결정적 결정을 적용할 수 있습니다. SecuRedact Enforced를 참조하세요.

SecuRedact가 필요한 이유

AI 에이전트는 점점 더 파일을 읽고, 도구를 호출하고, 외부 모델에 프롬프트를 보냅니다. 데이터를 먼저 확인하는 무언가가 없다면 PII, 자격 증명 및 민감한 문서가 노출됩니다. SecuRedact는 AI 워크플로우를 위한 개인정보 보호 및 보안 제어입니다:

  • 로컬 우선 — 모든 감지, 편집 및 정책 평가는 사용자 머신에서 실행됩니다. 기본적으로 네트워크 리스너, 원격 측정, 공급자 호출이 없습니다.

  • PII / GDPR 감지 — 이름, 이메일, IBAN, 식별자 및 특수 범주 데이터가 감지되어 가명화되거나 편집됩니다.

  • 비밀 및 자격 증명 보호 — API 키, 토큰 및 비밀번호가 감지되어 환경 밖으로 나가는 것이 차단됩니다.

  • 파일 시스템 보호 — 읽기는 경로 탐색/심볼릭 링크 이스케이프로부터 방어되며 .env와 같은 보호된 경로에서 차단됩니다.

  • AI 에이전트 개인정보 방화벽 — Claude Code 및 Gemini CLI에 대한 강제 훅은 프롬프트, 모델 호출 또는 도구 작업이 진행되기 전에 동일한 로컬 결정을 실행합니다.

  • 네트워크 / 이그레스 인식 — 외부 도구 호출이 (내부/외부/알 수 없음)으로 분류되어 정책이 승인을 요구하거나 이그레스를 차단할 수 있습니다.

SecuRedact는 민감한 데이터의 노출을 줄이는 데 도움이 됩니다. 이는 규정 준수를 보장하거나 모든 유출이 방지된다는 주장이 아닙니다. 제한 사항을 참조하세요.

Related MCP server: phi-redact-mcp

빠른 시작

PyPI에서 설치하고 안내식 설정을 실행합니다 (Windows):

py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

Linux / macOS:

python3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

몇 초 만에 텍스트 조각을 보호합니다 (결정적 전용 데모, 모델 불필요):

import os

os.environ["SECUREDACT_REQUIRE_FLAIR"] = "0"  # deterministic detectors only
from securedact_core import RedactionRequest, SecuredactEngine

engine = SecuredactEngine.from_environment()
result = engine.prepare(
    RedactionRequest(
        text="Contact alex@example.test, IBAN NL91ABNA0417164300",
        policy="strict_external_ai",
    )
)
print(result.status)  # "ok"
print(result.sanitized_text)  # "Contact [EMAIL_1], IBAN [IBAN_1]"

재현 가능한 합성 보안 데모: docs/distribution/security-demo.md.

안전한 기본 워크플로우

일반적인 외부 AI 준비에는 prepare_for_external_ai를 사용하세요:

{
  "text": "Contact alex@example.test",
  "policy": "strict_external_ai",
  "language": "auto",
  "response_mode": "minimal"
}

승인된 응답:

{
  "schema_version": "1",
  "status": "ok",
  "sanitized_text": "Contact [EMAIL_1]",
  "counts": {"email": 1},
  "policy": "strict_external_ai",
  "policy_version": 1,
  "policy_digest": "...",
  "reason_codes": []
}

review_required 및 blocked 응답에는 승인된 sanitized_text가 절대 포함되지 않습니다. 최소 응답에는 restore_capable이 명시적으로 선택되지 않는 한 원본 텍스트, 원시 엔터티 값, 매핑, 예외 본문, 스택 추적, 모델 경로 또는 복원 핸들이 포함되지 않습니다.

아키텍처 및 신뢰 경계

flowchart LR
    H["MCP host"] --> M["Securedact MCP"]
    M --> D["deterministic detectors"]
    M --> C["contextual detectors"]
    D --> P["policy engine"]
    C --> P
    P --> R["redactor"]
    R --> V["residual validator"]
    V --> O["approved sanitized output"]
    O --> W["host-controlled downstream workflow"]
    H -. "host may bypass MCP" .-> W

서버에는 공급자 클라이언트, OpenAI 호환 프록시, 리버스 프록시, 웹사이트, 데스크톱 챗봇, 공급자 자격 증명 또는 공급자별 전달이 없습니다. ADR 0001 및 위협 모델을 참조하세요.

도구

도구

의도된 용도

민감한 응답 동작

prepare_for_external_ai

권장되는 완전한 안전 워크플로우

기본적으로 최소

analyze_text

하위 수준 로컬 분석/검토

최소; review의 오프셋; 활성화된 디버그 모드에서만 원시 값

redact_text

하위 수준 호환성 작업

기본적으로 최소; 명시적 legacy 모드는 민감하며 더 이상 사용되지 않음

restore_text

로컬 불투명 세션 사용

기본적으로 일회용; 직접 매핑은 명시적 신뢰 레거시 모드 필요

create_safe_copy

구성된 단일 루트 아래에 승인된 .txt/.md 콘텐츠 작성

매핑이나 절대 경로를 반환하지 않음

securedact_read_file

로컬 파일을 안전하게 읽고 정화된 텍스트만 반환

읽기 전에 보호된 경로 차단; 탐색/심볼릭 링크/바이너리 거부; 기본적으로 minimal

응답 모드는 minimal, review, debug 및 restore_capable입니다. 디버그는 프로세스가 SECUREDACT_ENABLE_DEBUG_RESPONSES=1로 시작되지 않는 한 비활성화됩니다. MCP 요청으로는 활성화할 수 없습니다. 메모리 내 복원 세션은 암호화 난수 핸들, 제한된 용량, 만료, 동시성 보호 및 일회용 소비를 사용합니다. 프로세스 종료 시 모든 세션이 삭제됩니다.

MCP 도구, 응답 개인정보 보호 및 복원 세션을 참조하세요.

설치

Python >=3.12,<3.13이 지원됩니다.

PyPI에서 일반 설치를 하려면:

py -3.12 -m pip install "securedact-mcp[ml]"
securedact-mcp setup

Linux 또는 macOS에서는 python3.12 -m pip install "securedact-mcp[ml]"를 사용하세요. python이 이미 지원되는 3.12 환경을 선택하는 경우 python -m pip install "securedact-mcp[ml]"도 적절합니다.

setup은 패키지, Python 및 ML 종속성을 확인하고, 로컬 모델 상태를 검사하며, 기존 동의 기반 모델 설치 프로그램을 제공하고, 기존 오프라인 검증기를 실행하며, 해당 호스트가 감지되면 패키지된 Claude Code 및 Gemini CLI 통합을 제공합니다. 공급자의 공식 플러그인/확장 명령을 사용하며 다시 실행해도 안전합니다. 사용자가 모델 설정을 명시적으로 선택하고 기존 업스트림 프롬프트를 수락하지 않는 한 공급자 모델 API를 호출하거나, 공급자 신뢰를 자동으로 수락하거나, 컨텍스트 모델을 다운로드하지 않습니다.

고급 또는 무인 작업을 위한 수동 모델 명령은 계속 사용할 수 있습니다:

securedact-mcp install
securedact-mcp models verify
securedact-mcp

마지막 명령은 로컬 stdio 서버를 시작합니다. 표준 출력은 MCP 프로토콜 메시지용으로 예약되어 있습니다. securedact-mcp setup --non-interactive는 업스트림 수락을 암시하거나 새 공급자를 구성하지 않고 상태를 보고합니다. 대상 대화형 공급자 설정에는 --host claude, --host gemini 또는 --host all을 사용하세요.

개발자/소스 설치

대신 검토된 소스 체크아웃에서 작업하려면:

git clone https://github.com/GigantesHJI/securedact-mcp.git
cd securedact-mcp
python -m pip install ".[ml]"
securedact-mcp setup

저장소나 휠에는 모델 체크포인트가 포함되어 있지 않으며 시작 시 다운로드하지 않습니다. Securedact는 이러한 모델 가중치를 재배포하지 않습니다. 업스트림 모델 가중치는 자체 라이선스를 유지하며 Apache-2.0으로 재라이선스되지 않습니다. 모델 설치 및 타사 라이선스를 참조하세요.

결정적 전용 로컬 개발은 명시적으로 선택해야 합니다:

$env:SECUREDACT_REQUIRE_FLAIR = "0"
securedact-mcp

프로덕션은 기본적으로 컨텍스트 기능을 요구하며 구성된 모델이 없거나, 로드 중이거나, 손상되었거나, 사용할 수 없는 경우 폐쇄적으로 실패합니다.

호스트 패키지

테스트된 구성 자산과 안전한 워크플로우 지침은 Codex, Cursor 및 Windsurf용 integrations/ 아래에 있습니다. 자동화된 MCP 클라이언트 하네스는 서버 시작, 도구 목록, 호출, 최소 응답 형태, stdout 무결성 및 종료를 검증합니다. 실제 호스트가 모든 프롬프트에 대해 도구를 호출한다는 것을 증명하지는 않습니다. 호환성 증거를 참조하세요.

저장소는 또한 Gemini CLI 확장 루트입니다: gemini extensions install https://github.com/GigantesHJI/securedact-mcp로 훅을 설치할 수 있습니다. 해당 경로가 해석되려면 gemini-cli-extension 토픽과 태그 트리에 루트 매니페스트가 포함된 릴리스가 필요합니다. pip install "securedact-mcp[ml]" 및 로컬 모델 없이는 설치된 훅이 아무것도 강제하지 않습니다. SecuRedact Enforced를 참조하세요.

정책 및 Python API

내장 정책에는 default, strict_external_ai, gdpr, identifiers_only 및 review_all_contextual이 포함됩니다. 호환성 정책은 계속 사용할 수 있습니다. 로컬 조직 정책 파일은 제어된 정책 디렉토리에서만 로드되며, 엄격한 선언적 스키마를 사용하고, 폐쇄 실패 불변식을 비활성화할 수 없습니다. 알 수 없거나, 중복되거나, 크기가 초과되거나, 잘못된 형식이거나, 심볼릭 링크된 정책은 폐쇄적으로 실패합니다.

from securedact_core import RedactionRequest, SecuredactEngine

engine = SecuredactEngine.from_environment()
result = engine.prepare(
    RedactionRequest(
        text="Contact alex@example.test",
        policy="strict_external_ai",
    )
)

from_environment()는 컨텍스트 모델 요구 사항을 유지합니다. 독립형 결정적 개발에는 SECUREDACT_REQUIRE_FLAIR=0이 필요합니다. 애플리케이션은 테스트된 감지기 구현을 주입할 수도 있습니다. 공개 API 및 정책을 참조하세요.

재현 가능한 개발

커밋된 uv.lock은 Python 3.12에 대한 런타임, ML, 개발, 벤치마크 및 보안 엑스트라를 해결합니다.

uv sync --frozen --extra dev --extra benchmark
uv run python scripts\verify.py

테스트, 이슈, 스크린샷, 픽스처 또는 풀 리퀘스트에 실제 개인 정보, 개인 문서, 자격 증명, 고객 로그 또는 모델 가중치를 사용하지 마십시오. CONTRIBUTING.md를 참조하세요.

평가 및 성능

uv run python -m securedact_eval quality --mode deterministic --gate `
  --thresholds benchmarks\thresholds.json `
  --baseline benchmarks\baselines\quality-deterministic.json
uv run python -m securedact_eval performance --mode deterministic

버전이 지정된 합성 코퍼스는 정확 및 완화된 스팬 정밀도, 재현율, F1, 거짓 양성 및 거짓 음성 비율, 엔터티/언어/도메인/분할별 결과, 동작/카테고리 정확도 및 부트스트랩 재현율 구간을 보고합니다. 진짜 음성은 토큰 수준 안전이 아닌 문서 수준의 부정적 예입니다. GDPR 관련 스위트는 감지 평가이지 법적 규정 준수 인증이 아닙니다. 실제 Flair 및 GPU 벤치마크는 명시적으로 구성된 로컬 모델이 필요하며 일반 CI가 아닙니다. 벤치마킹을 참조하세요.

벤치마크 프레임워크는 로컬 데이터 계층과 대규모 프로필을 문서화합니다. 마이그레이션 계획은 향후 추출 경계를 정의합니다. GitHub가 저장소 단계를 실행하기 전에 실패한 경우 CI 문제 해결 결정 트리를 사용하세요. 로컬 성공은 필수 GitHub 검사를 대체하지 않습니다.

보안 및 제한 사항

  • 애플리케이션 코드는 프롬프트, 발견 사항, 매핑, 복원 핸들, 비밀, 모델 입력 또는 복원된 출력을 기록하지 않습니다.

  • 결정적 및 컨텍스트 감지는 새롭거나, 모호하거나, 적대적인 공개를 놓칠 수 있습니다. 상호 참조 및 보편적 난독화 저항은 주장되지 않습니다.

  • 검토 오프셋을 사용하면 원본 입력이 있는 신뢰할 수 있는 로컬 클라이언트가 값을 재구성할 수 있습니다. 검토 응답을 로컬에 유지하세요.

  • 호스트 동작 및 다운스트림 공급자 동작은 신뢰 경계 밖에 있습니다.

  • 파일에 문서화된 저장소 보안 설정은 여전히 관리자 확인이 필요합니다.

취약점은 SECURITY.md를 사용하여 비공개로 보고하세요. 공개 이슈에 취약점 세부 정보나 실제 데이터를 넣지 마십시오.

라이선스

원본 저장소 소스 및 문서는 Apache License 2.0에 따라 라이선스가 부여됩니다. 저작권 귀속은 NOTICE에 기록되어 있습니다. 타사 종속성 및 모델 가중치는 자체 라이선스를 유지합니다.

Available Tools

6 tools
analyze_textA
Read-onlyIdempotent

Inspect text locally and report detected sensitive content without producing sanitized output.

Use this when you need to understand what PII, secrets, or credentials are present (counts, entity types, and, with review/debug modes, positions) but do not need redacted text for transmission. The original text is not modified and no sanitized representation is returned. For a policy-approved, ready-to-send result use prepare_for_external_ai; for a sanitized file use create_safe_copy; for reversing a prior local session use restore_text.

Returns a JSON object with 'status' ('ok', 'review_required', or 'blocked'), 'policy', 'policy_version', 'policy_digest', 'counts' (entity-type tallies), and, when response_mode is 'review' or 'debug', a 'findings' list. 'debug' additionally returns 'debug_details'.

Inputs: text (required), policy, response_mode. Returns: object

create_safe_copyA

Sanitize text locally and write the approved result to a new file in the Safe Copies directory.

Use this when you need a sanitized on-disk copy (for storage, handoff, or archival) rather than an in-memory sanitized string. For the sanitized text only, use prepare_for_external_ai; for inspection-only use analyze_text; for reversing a prior session use restore_text.

Side effects: a new file is written to the directory set by SECUREDACT_SAFE_COPY_DIR. The supplied 'content' is not modified and no existing file is overwritten. The filename must be a bare '.txt' or '.md' basename (no path separators or directory traversal). The operation blocks and reports 'blocked' if the directory is unconfigured, the filename is invalid, or policy blocks the content.

Returns a JSON object with 'status' ('ok' or 'blocked'), 'filename', and 'counts'.

Inputs: content (required), filename (required), policy. Returns: object

prepare_for_external_aiA
Read-onlyIdempotent

Use this before sending user-supplied or potentially sensitive text to an external AI service.

SecuRedact inspects and sanitizes the text locally and returns the policy-approved representation; this tool does not transmit the text externally. It is the recommended default for outbound AI workflows. Use analyze_text for inspection-only classifications, redact_text for the lower-level compatibility path, create_safe_copy when a sanitized file is required, and restore_text only to reverse a prior local session in a trusted context.

Returns a JSON object with 'status' ('ok', 'review_required', or 'blocked'), 'sanitized_text' (present only when approved), 'counts', 'policy', and optionally 'restoration_session' (when response_mode is 'restore_capable').

Inputs: text (required), policy, language, response_mode. Returns: object

redact_textA
Read-onlyIdempotent

Direct/lower-level redaction entry point; prefer prepare_for_external_ai for normal outbound workflows.

In its normal modes this performs the same local sanitization as prepare_for_external_ai and returns the approved result, so most agents should call prepare_for_external_ai instead. Use redact_text when you specifically need this lower-level compatibility path, or the 'legacy' mode for local review of raw redaction internals. The 'legacy' mode returns potentially sensitive local-review details and is never selected by default.

Returns, for normal modes, the same approved result as prepare_for_external_ai (status, sanitized_text, counts). For 'legacy' mode it returns a result with deprecation_code 'legacy_sensitive_response' containing local-review redaction data.

Inputs: text (required), policy, response_mode. Returns: object

restore_textA

Reverse a prior SecuRedact protection step in a trusted, local-only context.

Use this ONLY after you previously received a restoration_session from SecuRedact (for example from prepare_for_external_ai with response_mode 'restore_capable') and now need to reconstruct the original text locally for trusted review. Restoration can reveal the original sensitive values (PII, secrets, credentials); it is a trusted-local operation, not a step to prepare data for external transmission. Never call it to sanitize or prepare text for an external AI; for that use prepare_for_external_ai. Never call it on text you did not previously protect with SecuRedact.

Security boundary: all processing is local and nothing leaves the machine. The 'mapping' form requires trusted_local_review=true and exposes raw originals, so its output must never be transmitted. Returns a JSON object with 'status' ('ok' or 'blocked'), 'restored_text' (present only on success), and 'reason_codes' describing any failure.

Inputs: text (required), mapping, restoration_session, trusted_local_review. Returns: object

securedact_read_fileA
Read-onlyIdempotent

Safely read a local file and return only its sanitized (PII/secrets removed) text.

Use this when you must ingest a local file's contents for use with an external AI but want path-traversal, size, and binary defenses plus sanitization applied first. If the content is already in memory, use prepare_for_external_ai; for a sanitized file on disk, use create_safe_copy.

Side effects: reads a file from local disk and never transmits it. Sensitive paths and escapes are blocked before any file content is read. The returned 'sanitized_text' is safe to forward.

Returns a JSON object with 'status' ('ok' or 'blocked'), 'path', and 'sanitized_text' (present only when approved).

Inputs: path (required), policy, max_bytes. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Most tools have clearly distinct outputs (in-memory text, file write, file read, inspection, restoration), but prepare_for_external_ai and redact_text perform identical sanitization in normal modes, with redact_text explicitly deferring to prepare_for_external_ai. This creates a potential misselection point despite the helpful cross-references.

    Naming Consistency4/5

    The majority of tools follow a clean verb_noun pattern (analyze_text, redact_text, restore_text, create_safe_copy). prepare_for_external_ai and securedact_read_file deviate with a prepositional phrase and a brand prefix, but the overall naming remains readable and predictable.

    Tool Count5/5

    Six tools is well within the ideal scope for a focused sanitization server. Each tool maps to a distinct workflow step, and none feel extraneous enough to bloat the surface.

    Completeness4/5

    The set covers the core lifecycle: inspection, in-memory sanitization, safe file output, safe file input, and session restoration. Minor gaps exist around policy management and the redundant redact_text path, but there are no critical dead ends for the stated purpose.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that redacts PII/PHI from text before it ever reaches an LLM — self-hosted, fail-closed, and HIPAA-aware.
      3
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      MCP server providing on-prem PII detection and anonymization tools (scan and is_sensitive) for AI agents, ensuring data stays local.
      4
      MIT
    • F
      license
      A
      quality
      B
      maintenance
      MCP server for local, verifiable PDF redaction. Enables AI agents to find sensitive regions, locate text, redact PDFs on-device, verify redaction and tamper-evidence seals, and generate PDFs—without uploading confidential documents.
      8
      365 npm
      -