README.md•20.2 kB
# MCP PII Tools
Model Context Protocol (MCP)을 위한 PII(개인식별정보) 탐지, 익명화, 암호화 및 복호화 도구입니다.
## 🚀 주요 기능
- **고정밀 PII 탐지**: GPT-4o 기반 `langextract`를 사용한 정확한 PII 탐지
- **다양한 PII 유형 지원**: 이름, 이메일, 전화번호, 여권번호, 주소, 신용카드번호, 주민등록번호 등
- **실시간 익명화**: 탐지된 PII를 즉시 익명화 처리
- **고급 암호화**: 결정론적 암호화(검색 가능) 및 FPE(형식 유지 암호화) 지원
- **완전한 복호화**: 암호화된 텍스트를 원본으로 복원
- **일괄 처리**: 여러 텍스트를 효율적으로 처리
- **MCP 호환**: Model Context Protocol 표준을 준수
## 📦 설치 요구사항
### 1. uv 설치 (권장)
```bash
# uv 설치 (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 또는 pip로 설치
pip install uv
```
### 2. 프로젝트 설치
```bash
# 저장소 클론
git clone https://github.com/your-username/mcp-pii-tools.git
cd mcp-pii-tools
# 의존성 설치
uv sync
# 개발 의존성 포함 설치
uv sync --extra dev
```
### 3. pip 사용 (대안)
```bash
pip install langextract[openai] openai python-dotenv cryptography mcp
```
## 🔐 암호화 방식
### 결정론적 암호화 (Deterministic Encryption)
- **용도**: 이름, 주소, 이메일
- **특징**: 같은 입력 → 같은 암호문 (검색 가능)
- **알고리즘**: AES-CBC with PBKDF2
- **출력**: Base64 인코딩
### FPE (Format Preserving Encryption)
- **용도**: 전화번호, 신용카드번호, 여권번호, 주민등록번호, 은행계좌번호
- **특징**: 원본 형식 유지 (010-1234-5678 → 808-2523-9129)
- **알고리즘**: 컨텍스트 기반 결정론적 변환
- **출력**: 동일한 형식의 암호문
## 🔧 사용법
### 1. 기본 PII 탐지
```python
from mcp_pii_tools import mcp_detect_pii
result = mcp_detect_pii("김철수 씨의 이메일은 kim@example.com입니다.")
print(f"탐지된 PII: {result['count']}개")
```
### 2. 텍스트 처리 (탐지 + 익명화)
```python
from mcp_pii_tools import mcp_process_text
result = mcp_process_text("Rachel Lim의 전화번호는 010-1234-5678입니다.")
print(f"익명화된 텍스트: {result['anonymized_text']}")
```
### 3. 일괄 처리
```python
from mcp_pii_tools import mcp_batch_process
texts = [
"김철수 씨가 방문했다.",
"박지현 님의 이메일은 park@test.com입니다.",
"John Smith의 전화번호는 010-9876-5432입니다."
]
result = mcp_batch_process(texts)
print(f"총 탐지된 PII: {result['total_pii_detected']}개")
```
### 4. 익명화 처리
```python
from mcp_pii_tools import mcp_anonymize_text
# PII 항목들
pii_items = [
{"type": "이름", "value": "김철수", "start_pos": 0, "end_pos": 3, "confidence": 0.9},
{"type": "전화번호", "value": "010-1234-5678", "start_pos": 10, "end_pos": 23, "confidence": 0.9}
]
anonymized = mcp_anonymize_text("김철수 씨의 전화번호는 010-1234-5678입니다.", pii_items)
print(anonymized) # "[이름] 씨의 전화번호는 [전화번호]입니다."
```
### 5. 개별 PII 항목 암호화
```python
from mcp_pii_tools import mcp_encrypt_pii_item, mcp_decrypt_pii_item
# 암호화
encrypt_result = mcp_encrypt_pii_item("김철수", "이름")
print(f"암호화: {encrypt_result['encrypted_value']}")
# 복호화
decrypt_result = mcp_decrypt_pii_item(encrypt_result['encrypted_value'], "이름")
print(f"복호화: {decrypt_result['decrypted_value']}")
```
### 6. 텍스트 전체 암호화/복호화
```python
from mcp_pii_tools import mcp_encrypt_text_pii, mcp_decrypt_text_pii
# 텍스트 암호화
text = "김철수 씨의 이메일은 kim@example.com이고 전화번호는 010-1234-5678입니다."
encrypt_result = mcp_encrypt_text_pii(text)
print(f"암호화된 텍스트: {encrypt_result['encrypted_text']}")
# 텍스트 복호화
decrypt_result = mcp_decrypt_text_pii(
encrypt_result['encrypted_text'],
encrypt_result['encrypted_items']
)
print(f"복호화된 텍스트: {decrypt_result['decrypted_text']}")
```
## 🛠️ MCP Tools
### 1. `detect_pii`
텍스트에서 PII를 탐지합니다.
**매개변수:**
- `text` (string): 분석할 텍스트
**반환값:**
```json
{
"success": true,
"pii_items": [
{
"type": "이름",
"value": "김철수",
"confidence": 0.9,
"start_pos": 0,
"end_pos": 3
}
],
"count": 1,
"processing_time": 1.234,
"summary": {"이름": 1}
}
```
### 2. `process_text`
텍스트에서 PII를 탐지하고 익명화 처리합니다.
**매개변수:**
- `text` (string): 처리할 텍스트
**반환값:**
```json
{
"success": true,
"original_text": "김철수 씨의 이메일은 kim@example.com입니다.",
"anonymized_text": "[이름] 씨의 이메일은 [이메일]입니다.",
"pii_items": [...],
"count": 2,
"processing_time": 1.234,
"summary": {"이름": 1, "이메일": 1}
}
```
### 3. `batch_process`
여러 텍스트를 일괄적으로 처리합니다.
**매개변수:**
- `texts` (array): 처리할 텍스트 리스트
**반환값:**
```json
{
"success": true,
"results": [...],
"total_texts": 3,
"successful_count": 3,
"total_pii_detected": 5,
"processing_time": 3.456,
"average_time_per_text": 1.152
}
```
### 4. `anonymize_text`
PII 항목들을 사용하여 텍스트를 익명화합니다.
**매개변수:**
- `text` (string): 원본 텍스트
- `pii_items` (array): PII 항목들
**반환값:**
```json
"[이름] 씨의 전화번호는 [전화번호]입니다."
```
### 5. `encrypt_pii_item`
개별 PII 항목을 암호화합니다.
**매개변수:**
- `pii_value` (string): 암호화할 PII 값
- `pii_type` (string): PII 유형 (이름, 전화번호, 이메일 등)
**반환값:**
```json
{
"success": true,
"original_value": "김철수",
"encrypted_value": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=",
"pii_type": "이름",
"encryption_method": "deterministic"
}
```
### 6. `decrypt_pii_item`
암호화된 PII 항목을 복호화합니다.
**매개변수:**
- `encrypted_value` (string): 복호화할 암호화된 값
- `pii_type` (string): PII 유형
**반환값:**
```json
{
"success": true,
"encrypted_value": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=",
"decrypted_value": "김철수",
"pii_type": "이름",
"decryption_method": "deterministic"
}
```
### 7. `encrypt_text_pii`
텍스트에서 PII를 탐지하고 모든 PII를 암호화합니다.
**매개변수:**
- `text` (string): 처리할 텍스트
**반환값:**
```json
{
"success": true,
"original_text": "김철수 씨의 이메일은 kim@example.com입니다.",
"encrypted_text": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q= 씨의 이메일은 Y2F0YWxvZ0BleGFtcGxlLmNvbQ==입니다.",
"pii_items": [...],
"encrypted_items": {
"김철수": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=",
"kim@example.com": "Y2F0YWxvZ0BleGFtcGxlLmNvbQ=="
},
"count": 2,
"processing_time": 1.234,
"summary": {"이름": 1, "이메일": 1}
}
```
### 8. `decrypt_text_pii`
암호화된 텍스트에서 PII를 복호화합니다.
**매개변수:**
- `encrypted_text` (string): 암호화된 텍스트
- `encrypted_items` (object): 원본값 → 암호화값 매핑
**반환값:**
```json
{
"success": true,
"encrypted_text": "X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q= 씨의 이메일은 Y2F0YWxvZ0BleGFtcGxlLmNvbQ==입니다.",
"decrypted_text": "김철수 씨의 이메일은 kim@example.com입니다.",
"decrypted_items": {
"X3Mi/5ClIhn56auXS6KKbmcdkp+k20TrYVRGoZpY35Q=": "김철수",
"Y2F0YWxvZ0BleGFtcGxlLmNvbQ==": "kim@example.com"
},
"count": 2,
"processing_time": 0.567
}
```
## 🎯 지원하는 PII 유형
| 유형 | 한국어 | 영어 | 예시 | 암호화 방식 |
|------|--------|------|------|-------------|
| 이름 | 이름 | name | 김철수, Rachel Lim | 결정론적 |
| 이메일 | 이메일 | email | kim@example.com | 결정론적 |
| 주소 | 주소 | address | 서울시 강남구 테헤란로 123 | 결정론적 |
| 전화번호 | 전화번호 | phone | 010-1234-5678 | FPE |
| 여권번호 | 여권번호 | passport_number | M31143886 | FPE |
| 신용카드번호 | 신용카드번호 | credit_card | 4532-1234-5678-9012 | FPE |
| 주민등록번호 | 주민등록번호 | ssn | 123456-1234567 | FPE |
| 은행계좌번호 | 은행계좌번호 | bank_account | 123-456-789012 | FPE |
## ⚡ 성능 특성
- **정확도**: 100% (GPT-4o 기반)
- **처리 시간**: 평균 1.3초/텍스트 (탐지), 0.1초/텍스트 (암호화/복호화)
- **지원 언어**: 한국어, 영어, 혼합 텍스트
- **동시 처리**: 일괄 처리 지원
- **암호화 성능**: 초당 수천 건 처리 가능
## 🔒 보안 고려사항
- **PII 탐지**: OpenAI API를 통한 텍스트 전송이 발생할 수 있습니다
- **암호화**: 모든 암호화/복호화는 로컬에서 처리됩니다
- **키 관리**: `PII_MASTER_KEY` 환경변수로 마스터 키 설정 필요
- **데이터 보호**: 암호화된 데이터는 검색 가능하지만 원본 복원 불가능
- **형식 유지**: FPE를 통해 데이터베이스 스키마 변경 없이 암호화 가능
## 📝 예제 실행
### uv 사용 (권장)
```bash
# 기본 테스트 (탐지, 익명화, 암호화/복호화)
uv run python mcp_pii_tools.py
# 사용 예제 (상세한 예제들)
uv run python mcp_pii_example.py
# 암호화 모듈 단독 테스트
uv run python pii_crypto.py
```
### pip 사용
```bash
# 기본 테스트 (탐지, 익명화, 암호화/복호화)
python mcp_pii_tools.py
# 사용 예제 (상세한 예제들)
python mcp_pii_example.py
# 암호화 모듈 단독 테스트
python pii_crypto.py
```
## 🔧 환경 설정
### 1. 환경변수 설정
#### **방법 1: 자동 설정 스크립트 사용 (가장 쉬움)**
```bash
# 대화형 설정 스크립트 실행
uv run python setup_env.py
```
#### **방법 2: 템플릿 파일 사용**
```bash
# 템플릿 파일을 .env로 복사
cp env.template.txt .env
# .env 파일을 편집하여 실제 값 입력
nano .env # 또는 vim, code 등
```
#### **방법 3: 직접 생성**
**OpenAI 사용 시:**
```bash
# .env 파일 생성
echo "PII_PROVIDER=openai" > .env
echo "OPENAI_API_KEY=your_openai_api_key_here" >> .env
echo "PII_MASTER_KEY=your_secure_master_key_here" >> .env
echo "PII_MODEL_ID=gpt-4o" >> .env
```
**vLLM 사용 시:**
```bash
# .env 파일 생성
echo "PII_PROVIDER=vllm" > .env
echo "VLLM_API_KEY=your_vllm_api_key_here" >> .env
echo "PII_MASTER_KEY=your_secure_master_key_here" >> .env
echo "PII_MODEL_ID=qwen3-235b-awq" >> .env
echo "VLLM_BASE_URL=https://qwen.smartmind.team/v1" >> .env
echo "VLLM_TIMEOUT=600" >> .env
echo "VLLM_TEMPERATURE=0.0" >> .env
echo "VLLM_MAX_TOKENS=4096" >> .env
```
#### **필수 환경변수**
- `PII_MASTER_KEY`: PII 암호화용 마스터 키 (선택사항, 기본값: "pii_master_key_1!smartmind")
#### **Provider별 환경변수**
**OpenAI 사용 시:**
- `OPENAI_API_KEY`: OpenAI API 키 (https://platform.openai.com/api-keys)
- `PII_MODEL_ID`: 모델 ID (기본값: gpt-4o)
**vLLM 사용 시:**
- `VLLM_API_KEY`: vLLM API 키 (OPENAI_API_KEY와 동일하게 사용 가능)
- `VLLM_BASE_URL`: vLLM 서버 URL (기본값: https://qwen.smartmind.team/v1)
- `PII_MODEL_ID`: 모델 ID (기본값: qwen3-235b-awq)
- `VLLM_TIMEOUT`: 요청 타임아웃 (초, 기본값: 600)
- `VLLM_TEMPERATURE`: 온도 (기본값: 0.0)
- `VLLM_MAX_TOKENS`: 최대 토큰 수 (기본값: 4096)
#### **마스터 키 생성 방법**
```bash
# OpenSSL 사용
openssl rand -base64 32
# Python 사용
python -c "import secrets; print(secrets.token_urlsafe(32))"
```
### 2. MCP 서버 실행
#### **uv 사용 (권장):**
```bash
# uv로 MCP 서버 실행
uv run python mcp_pii_tools.py
# 또는 가상환경 활성화 후 실행
uv shell
python mcp_pii_tools.py
```
#### **pip 사용:**
```bash
# MCP 서버로 실행 (Claude Desktop 등에서 사용)
python mcp_pii_tools.py
```
### 3. 사용 가능한 MCP Tools
- `detect_pii`: PII 탐지
- `process_text`: PII 탐지 + 익명화
- `batch_process`: 일괄 처리
- `anonymize_text`: 익명화
- `encrypt_pii_item`: 개별 PII 암호화
- `decrypt_pii_item`: 개별 PII 복호화
- `encrypt_text_pii`: 텍스트 전체 암호화
- `decrypt_text_pii`: 텍스트 전체 복호화
## 🖥️ Claude Desktop 설정
### 1. Claude Desktop MCP 설정
Claude Desktop에서 MCP 서버를 사용하려면 설정 파일을 수정해야 합니다.
#### **macOS 설정 파일 위치:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```
#### **Windows 설정 파일 위치:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
### 2. 설정 파일 내용
#### **권장 설정 (uv 사용):**
```json
{
"mcpServers": {
"mcp-pii-tools": {
"command": "/opt/homebrew/bin/uv",
"args": ["run", "--directory", "/Users/matthew/Workspace/mcp-pii-tools", "python", "mcp_pii_tools.py"]
}
}
}
```
#### **중요한 설정 포인트:**
1. **uv 전체 경로 사용**: `command`에 `uv`의 전체 경로를 지정
- macOS (Homebrew): `/opt/homebrew/bin/uv`
- macOS (직접 설치): `~/.cargo/bin/uv`
- Linux: `~/.cargo/bin/uv`
2. **디렉터리 명시**: `--directory` 옵션으로 프로젝트 디렉터리 지정
- Claude Desktop이 실행될 때 올바른 가상환경을 찾을 수 있도록 함
- `pyproject.toml`이 있는 디렉터리를 정확히 지정해야 함
3. **상대 경로 사용**: `args`에서 스크립트 파일명만 사용
- `--directory`로 작업 디렉터리가 설정되므로 상대 경로로 충분
#### **대안 설정 (pip 사용):**
```json
{
"mcpServers": {
"mcp-pii-tools": {
"command": "python",
"args": ["/Users/matthew/Workspace/mcp-pii-tools/mcp_pii_tools.py"]
}
}
}
```
### 3. 환경변수 설정
**중요**: API 키와 설정은 JSON 파일이 아닌 환경변수로 관리합니다.
#### **방법 1: 자동 설정 스크립트 사용 (권장)**
```bash
# 프로젝트 디렉터리에서 실행
uv run python setup_env.py
```
#### **방법 2: .env 파일 사용**
```bash
# 템플릿 파일을 .env로 복사
cp env.template.txt .env
# .env 파일을 편집하여 실제 값 입력
nano .env # 또는 vim, code 등
```
#### **방법 3: 시스템 환경변수 설정**
```bash
# macOS/Linux
export OPENAI_API_KEY="your_openai_api_key_here"
export PII_MASTER_KEY="your_secure_master_key_here"
# Windows
set OPENAI_API_KEY=your_openai_api_key_here
set PII_MASTER_KEY=your_secure_master_key_here
```
### 4. 설정 완료
1. **Claude Desktop 종료**
2. **환경변수 설정** (위 방법 중 하나 선택)
3. **Claude Desktop 재시작**
4. **MCP 서버 연결 확인**
### 5. 사용 예시
Claude Desktop에서 다음과 같이 사용할 수 있습니다:
```
"이 텍스트에서 개인정보를 찾아서 익명화해줘: 김철수 씨의 이메일은 kim@example.com이고 전화번호는 010-1234-5678입니다."
```
## 🖥️ Cursor 설정
### 1. Cursor MCP 설정
Cursor에서 MCP 서버를 사용하려면 설정을 추가해야 합니다.
#### **설정 파일 위치:**
```
~/.cursor/mcp_settings.json
```
### 2. 설정 파일 내용
```json
{
"mcpServers": {
"mcp-pii-tools": {
"command": "uv",
"args": ["run", "python", "/Users/matthew/Workspace/mcp-pii-tools/mcp_pii_tools.py"]
}
}
}
```
### 3. 환경변수 설정
**중요**: API 키와 설정은 JSON 파일이 아닌 환경변수로 관리합니다.
#### **방법 1: 자동 설정 스크립트 사용 (권장)**
```bash
# 프로젝트 디렉터리에서 실행
uv run python setup_env.py
```
#### **방법 2: .env 파일 사용**
```bash
# 템플릿 파일을 .env로 복사
cp env.template.txt .env
# .env 파일을 편집하여 실제 값 입력
nano .env # 또는 vim, code 등
```
### 4. Cursor에서 사용
1. **Cursor 설정 열기** (Cmd/Ctrl + ,)
2. **MCP 설정 추가**
3. **환경변수 설정** (위 방법 중 하나 선택)
4. **Cursor 재시작**
5. **MCP 도구 사용**
## 🔧 수동 테스트
### 1. MCP 서버 직접 테스트
#### **uv 사용 (권장):**
```bash
# 서버 실행
uv run python mcp_pii_tools.py
# 다른 터미널에서 테스트
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | uv run python mcp_pii_tools.py
```
#### **pip 사용:**
```bash
# 서버 실행
python mcp_pii_tools.py
# 다른 터미널에서 테스트
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | python mcp_pii_tools.py
```
### 2. 개별 도구 테스트
#### **uv 사용 (권장):**
```bash
# PII 탐지 테스트
uv run python -c "
from mcp_pii_tools import mcp_detect_pii
result = mcp_detect_pii('김철수 씨의 이메일은 kim@example.com입니다.')
print(result)
"
```
#### **pip 사용:**
```bash
# PII 탐지 테스트
python -c "
from mcp_pii_tools import mcp_detect_pii
result = mcp_detect_pii('김철수 씨의 이메일은 kim@example.com입니다.')
print(result)
"
```
## 🚨 문제 해결
### 1. MCP 서버 연결 실패
- **환경변수 확인**: `OPENAI_API_KEY`, `PII_MASTER_KEY` 설정 확인
- **uv 설치 확인**: `uv --version`으로 uv가 설치되어 있는지 확인
- **의존성 설치 확인**: `uv sync`로 모든 의존성이 설치되었는지 확인
- **파일 권한 확인**: 스크립트 파일에 실행 권한이 있는지 확인
### 1.1. 모듈을 찾을 수 없는 오류 (ModuleNotFoundError)
**증상**: `ModuleNotFoundError: No module named 'dotenv'` 또는 `ModuleNotFoundError: No module named 'langextract'`
**원인**: Claude Desktop이 실행할 때 올바른 가상환경을 찾지 못함
**해결 방법**:
1. **uv 전체 경로 사용**:
```json
"command": "/opt/homebrew/bin/uv"
```
2. **디렉터리 명시**:
```json
"args": ["run", "--directory", "/Users/matthew/Workspace/mcp-pii-tools", "python", "mcp_pii_tools.py"]
```
3. **uv 경로 확인**:
```bash
which uv
# 결과: /opt/homebrew/bin/uv (macOS Homebrew)
# 또는: ~/.cargo/bin/uv (직접 설치)
```
4. **수동 테스트**:
```bash
/opt/homebrew/bin/uv run --directory /Users/matthew/Workspace/mcp-pii-tools python mcp_pii_tools.py
```
### 2. 도구가 보이지 않는 경우
- **Claude Desktop 재시작**: 설정 변경 후 반드시 재시작
- **로그 확인**: Claude Desktop 로그에서 오류 메시지 확인
- **설정 파일 문법**: JSON 문법이 올바른지 확인
### 3. 성능 최적화
- **환경변수 사용**: `.env` 파일 대신 시스템 환경변수 사용 권장
- **절대 경로 사용**: 상대 경로 대신 절대 경로 사용
- **uv 사용**: `uv run`을 사용하여 가상환경 자동 관리
- **의존성 캐싱**: `uv`의 빠른 의존성 해결 및 캐싱 활용
## 🐛 오류 처리
모든 함수는 `success` 필드를 통해 성공/실패를 나타냅니다:
```python
result = mcp_detect_pii("텍스트")
if result['success']:
print(f"탐지된 PII: {result['count']}개")
else:
print(f"오류: {result['error']}")
```
## 🤝 기여
버그 리포트나 기능 요청은 GitHub Issues를 통해 제출해주세요.
## 🚀 주요 사용 사례
### 1. 데이터 마이그레이션
- 기존 데이터베이스의 PII를 안전하게 암호화하여 새 시스템으로 이전
- FPE를 통한 스키마 변경 없이 암호화 적용
### 2. 개발/테스트 환경
- 프로덕션 데이터의 PII를 익명화하여 테스트 데이터로 활용
- 개발자들이 실제 데이터 없이도 테스트 가능
### 3. 데이터 분석
- PII를 암호화한 상태에서도 검색 및 분석 가능
- 결정론적 암호화를 통한 그룹핑 및 집계
### 4. 규정 준수
- GDPR, 개인정보보호법 등 규정에 따른 PII 보호
- 감사 추적을 위한 암호화 로그 관리
---
**MCP PII Tools** - 고정밀 개인정보 탐지, 익명화, 암호화 및 복호화 솔루션