de en es ja ko ru zh

query-sanitizer-mcp

Name: query-sanitizer-mcp
Author: vidoluco

by vidoluco

Overview Schema Source Related Servers Discussions Admin

Python

Local

query-sanitizer-mcp

프롬프트와 외부 LLM 사이에 위치하여 데이터가 기기를 떠나기 전에 민감한 정보를 자동으로 삭제하는 경량 MCP 미들웨어입니다.

[Your Prompt] → sanitize_query() → [Safe Prompt] → External LLM → [Response] → restore_response() → [You]

v0.3.0 — 4단계 DLP 파이프라인: 정규식 → GLiNER NER → LLM 정제 → 사후 스캔 확인. 100% 오픈 소스, 100% 로컬 환경에서 실행됩니다. M4 MacBook 및 Google Colab T4에서 테스트되었습니다.

목적

내부 컨텍스트를 Claude, ChatGPT 또는 기타 클라우드 LLM에 붙여넣을 때마다 다음과 같은 정보가 유출될 위험이 있습니다:

직원 이름, 이메일, 전화번호
내부 프로젝트 코드명
인프라 세부 정보 (IP, 호스트 이름, DB 이름)
API 키 및 자격 증명
회사 이름, 거래 규모, 법적 참조

이 MCP 서버는 해당 텍스트를 가로채어 민감한 토큰을 유형별 자리 표시자([ORG_NAME_1], [PII_NAME_1] 등)로 대체하고, 응답에서 이를 복원합니다. 따라서 사용자는 자연스러운 텍스트를 보게 되며, 클라우드 LLM은 실제 값을 절대 볼 수 없습니다.

Related MCP server: zentric-protocol-mcp

도구

도구	설명
`sanitize_query(text)`	3단계 삭제. 안전한 텍스트 + `san_id` 반환.
`restore_response(text, san_id)`	자리 표시자를 원래 값으로 교체.
`scan_response(text)`	LLM 응답에서 생성되거나 유출되었을 수 있는 데이터를 스캔.
`view_ledger(last_n)`	최근 삭제 기록 표시.

탐지 파이프라인

1단계 — 정규식 사전 통과 (항상 실행, 모델 불필요)

구조화된 토큰을 위한 결정론적 패턴입니다. 로컬 모델이 오프라인일 때도 실행됩니다.

패턴	카테고리	차단 여부
AWS 액세스 키 (`AKIA…`)	CREDENTIAL	예 — 차단됨
GitHub 토큰 (`ghp_…`, `gho_…`)	CREDENTIAL	예
JWT (`eyJ…`)	CREDENTIAL	예
Slack 토큰 (`xox[baprs]-…`)	CREDENTIAL	예
`api_key = "…"` 스타일 할당	CREDENTIAL	예
URL 내 비밀번호 (`://user:pass@`)	CREDENTIAL	예
이메일 주소	PII_NAME	아니요 — 복원됨
전화번호	PII_NAME	아니요
SSN (`NNN-NN-NNNN`)	PII_ID	아니요
직원/배지 ID (`EMP-…`)	PII_ID	아니요
RFC 1918 사설 IP	INFRA	아니요
달러 금액	FINANCIAL	아니요
설정 정의 엔티티 (조직명, 직원, 코드명, 도메인)	다양함	아니요

2단계 — LLM 정제 (문맥 기반, 최선 노력)

문맥 내에서 사용되는 조직명, 프로젝트 코드명, GEO_INTERNAL 참조, LEGAL 용어, INTERNAL_URL 패턴 등 의미론적 이해가 필요한 엔티티를 포착합니다. 로컬 모델을 사용할 수 없는 경우, 명확한 경고와 함께 1단계 출력 결과가 반환됩니다.

3단계 — 사후 스캔 신뢰도 확인

삭제된 텍스트에 대해 높은 신뢰도의 정규식 패턴을 실행하여 LLM이 놓쳤을 수 있는 잠재적 데이터(예: 모델이 포착하지 못한 JWT)를 플래그 지정합니다. 보고서에 경고로 표시됩니다.

설정

옵션 A — M4 MacBook (권장)

스택: Ollama 0.19+ (MLX 백엔드, M4에서 약 50 tok/s) + GLiNER NER (MPS, 호출당 약 80ms)

# 1. Install Ollama and pull the recommended model
brew install ollama
ollama pull qwen2.5:3b   # 2GB, fast + strong instruction following
ollama serve             # Ollama 0.19+ uses MLX automatically on Apple Silicon

# 2. Clone and install with NER layer
git clone https://github.com/vidoluco/query-sanitizer-mcp
cd query-sanitizer-mcp
python3 -m venv .venv
.venv/bin/pip install -e ".[nlp]"   # fastmcp + gliner (GLiNER NER layer)

Claude Code에 추가 (~/.claude/settings.json):

{
  "mcpServers": {
    "query-sanitizer": {
      "command": "/path/to/query-sanitizer-mcp/.venv/bin/python",
      "args": ["/path/to/query-sanitizer-mcp/server.py"],
      "env": {
        "SANITIZER_MODEL_NAME": "qwen2.5:3b",
        "SANITIZER_GLINER_MODEL": "urchade/gliner_medium-v2.1"
      }
    }
  }
}

M4용 대체 LLM 모델 (모두 Ollama 경유):

모델	크기	M4 속도	용도
`qwen2.5:3b`	2 GB	~50 tok/s	기본 — 빠르고 정확함
`phi4-mini`	3 GB	~40 tok/s	강력한 추론
`llama3.2:3b`	2 GB	~45 tok/s	광범위한 일반 용도
`qwen2.5:7b`	5 GB	~30 tok/s	더 높은 정확도, 더 많은 RAM 필요

옵션 B — Google Colab T4

스택: HuggingFace transformers (Ollama 불필요) + GLiNER (CUDA)

# Cell 1 — install
!pip install "query-sanitizer-mcp[colab]" -q
# fastmcp + gliner + transformers + torch + accelerate

# Cell 2 — configure
import os
os.environ["SANITIZER_BACKEND"]    = "hf"
os.environ["SANITIZER_HF_MODEL"]   = "Qwen/Qwen2.5-3B-Instruct"  # ~6GB, fits T4 16GB
os.environ["SANITIZER_GLINER_MODEL"] = "urchade/gliner_medium-v2.1"
os.environ["SANITIZER_LEDGER_DIR"] = "/content/sanitizer-ledger"

# Cell 3 — use directly (no MCP client needed in Colab)
import sys; sys.path.insert(0, ".")
from server import sanitize_query, restore_response, scan_response

result = sanitize_query("Send report to jane.doe@acme.com re: Project Phoenix")
print(result)

첫 실행 시 Qwen2.5-3B-Instruct (~6 GB)와 gliner_medium-v2.1 (~500 MB)을 Colab 캐시로 다운로드합니다. 이후 실행은 즉시 이루어집니다.

최소 설정 (정규식 전용, 모델 불필요)

의존성 없는 운영(순수 정규식, Ollama 및 GLiNER 미사용)을 원할 경우:

pip install fastmcp
SANITIZER_MODEL_RETRIES=0 python server.py

자격 증명, 이메일, SSN, 사설 IP 및 금융 금액은 정규식만으로 포착됩니다. 사람, 조직명, 프로젝트 코드명은 GLiNER 또는 LLM 계층이 필요합니다.

구성

.sanitizer-ledger/config.json을 생성하거나 python scripts/ledger.py init-config를 실행하세요:

{
  "org_names": ["Acme Corp", "Acme"],
  "org_domains": ["acme-internal.net"],
  "project_codenames": ["Phoenix", "Titan"],
  "known_employees": ["Jane Smith", "Marcus Webb"],
  "internal_ip_ranges": ["10.0.0.0/8"],
  "custom_patterns": [
    {"pattern": "JIRA-\\d{4,}", "category": "PROJECT_NAME", "description": "Jira tickets"}
  ],
  "always_allow": ["Google Cloud", "Kubernetes", "BigQuery", "Terraform", "Docker"]
}

설정으로 정의된 엔티티(org_names, known_employees 등)는 정규식 사전 통과(결정론적 매칭용)와 LLM 시스템 프롬프트(문맥 변형용) 모두에 연결됩니다. 변경 사항은 다음 sanitize_query 호출 시 적용되며 서버 재시작은 필요하지 않습니다.

환경 변수

변수	기본값	설명
`SANITIZER_MODEL_URL`	`http://localhost:11434/v1/chat/completions`	로컬 모델 엔드포인트
`SANITIZER_MODEL_NAME`	`llama3.2`	모델 이름
`SANITIZER_MODEL_RETRIES`	`2`	모델 실패 시 재시도 횟수 (2s, 4s 백오프)
`SANITIZER_LEDGER_DIR`	`.sanitizer-ledger/`	기록 디렉토리 경로
`SANITIZER_LEDGER_STORE_ORIGINALS`	`true`	`false`로 설정 시 원본 값을 저장하지 않음 (GDPR 모드 — 복원은 동일 세션 내에서만 작동)

Ledger CLI

python scripts/ledger.py list [N]                # recent N entries
python scripts/ledger.py lookup <san_id>         # full mapping for one entry
python scripts/ledger.py restore <san_id> <text> # restore from CLI
python scripts/ledger.py stats                   # aggregate stats by category and source
python scripts/ledger.py purge --older-than 30d  # enforce retention policy
python scripts/ledger.py init-config             # create starter config.json

삭제 카테고리

카테고리	예시	심각도
`CREDENTIAL`	API 키, 토큰, 비밀번호	치명적 — 차단됨, 절대 복원 안 됨
`INTERNAL_URL`	인트라넷 URL, 스테이징 엔드포인트	치명적
`PII_NAME`	이름, 이메일, 전화번호	높음
`PII_ID`	SSN, 직원 ID, 배지 번호	높음
`ORG_NAME`	회사/자회사 이름	높음
`LEGAL`	계약 조건, 사건 번호	높음
`PROJECT_NAME`	내부 코드명	중간
`INFRA`	IP, 호스트 이름, DB 이름	중간
`FINANCIAL`	수익, 거래 규모, 예산	중간
`GEO_INTERNAL`	사무실 위치, 건물 이름	낮음

보안 모델

자격 증명은 절대 저장되지 않음 — 원본 값 대신 [BLOCKED]가 기록됨
Fail-safe, not fail-open — 모델을 사용할 수 없는 경우 정규식 폴백이 트리거되며, 일반 텍스트가 그대로 통과되지 않음
로컬 추론 전용 — 삭제 단계를 위해 외부 API로 전송되는 데이터 없음
개인정보 보호 모드 (SANITIZER_LEDGER_STORE_ORIGINALS=false) — 원본이 디스크에 전혀 기록되지 않음; 복원은 메모리 내 캐시를 통해 동일한 서버 세션 내에서만 작동

예시

전체 세션 추적은 examples/를 참조하세요:

01_api_key_leak.md — 정규식 사전 통과에 의해 차단된 AWS 자격 증명
02_employee_pii.md — 이름, 이메일, 직원 ID가 포함된 HR 프롬프트 + 복원
03_internal_infra.md — Ollama 오프라인 상태에서의 인프라 디버깅 (정규식 폴백)

기여

이슈를 열거나 PR을 보내주세요.

향후 계획 아이디어:

[ ] 탐지된 패턴에서 설정 항목 자동 제안
[ ] Claude Code 훅 통합 (프롬프트 전 자동 삭제)
[ ] 신뢰도 임계값 설정
[ ] 일괄/대량 삭제 모드
[ ] 코드 블록 스캔 (인라인 비밀값, import 경로)
[ ] 저장 시 기록 암호화
[ ] 기록 검토를 위한 웹 UI

라이선스

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessResponsive

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

redact
com.eleyed
Redact PII from text before it reaches a model. Nothing stored, no third-party AI.
Security Legal & Compliance
1
boundaryai
ai.boundaryai
Deterministic runtime safety for AI agents: scan PII, gate tool actions, verify LLM output.
Security AI & Machine Learning Agent Orchestration
2
sigma-gate A
io.github.spektre-labs
Deterministic trust gate for AI output: leaked-secret, prompt-injection & PII in one call.
Security AI & Machine Learning
2
agent-prompt-injection-firewall-mcp
io.github.CSOAI-ORG
The WAF for agents. Pattern-based + heuristic firewall scans prompts, RAG documents, tool argume...
Security AI & Machine Learning
2

Related MCP Servers

mcp-redact
Security Developer Tools Command Line
nine710
A
license
Not graded
quality
D
maintenance
Local-first CLI and MCP server for redacting sensitive text before sharing logs, configs, and errors with AI tools.
Updated 5 months ago (2026-05-01 08:08 UTC)
MIT
zentric-protocol-mcpofficial
Security AI & Machine Learning
ZentricProtocol
F
license
Not graded
quality
D
maintenance
Security middleware for LLM apps and AI agent pipelines. Detects prompt injection attacks (22 signatures, 7 languages) and anonymizes PII (17 entity types). Deterministic, sub-25ms, GDPR Art.30 compliant.
Updated 3 months ago (2026-06-09 23:13 UTC)
-
classifinder-mcpofficial
Security AI & Machine Learning
ClassiFinder
A
license
A
quality
B
maintenance
Enables AI agents to scan text for leaked secrets and prompt injection markers, and redact them before reaching an LLM.
Updated a month ago (2026-08-19 00:52 UTC)
2
1
MIT
ai-security-gateway-mcp
Security AI & Machine Learning
dceptev-byte
A
license
A
quality
D
maintenance
Scans prompts for PII and masks or redacts sensitive data locally before sending to an LLM, supporting multiple anonymization modes.
Updated 6 months ago (2026-03-23 12:40 UTC)
1
MIT

query-sanitizer-mcp

목적

도구

탐지 파이프라인

1단계 — 정규식 사전 통과 (항상 실행, 모델 불필요)

2단계 — LLM 정제 (문맥 기반, 최선 노력)

3단계 — 사후 스캔 신뢰도 확인

설정

옵션 A — M4 MacBook (권장)

옵션 B — Google Colab T4

최소 설정 (정규식 전용, 모델 불필요)

구성

환경 변수

Ledger CLI

삭제 카테고리

보안 모델

예시

기여

라이선스

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

mcp-redact

zentric-protocol-mcpofficial

classifinder-mcpofficial

ai-security-gateway-mcp