Mcp Proxy For Pii Pseudo Anonymization

MCP Conceal

一个 MCP 代理，会在数据到达 Claude、ChatGPT 或 Gemini 等外部 AI 提供商之前，对个人身份信息（PII）进行假名化。

sequenceDiagram
    participant C as AI Client (Claude)
    participant P as MCP Conceal
    participant S as Your MCP Server
    
    C->>P: Request
    P->>S: Request
    S->>P: Response with PII
    P->>P: PII Detection
    P->>P: Pseudo-Anonymization
    P->>P: Consistent Mapping
    P->>C: Sanitized Response

MCP Conceal 采用假名化而非删除的方式，以保留 AI 分析所需的语义含义和数据关系。例如：[email protected] 会变为 [email protected]，在保护敏感信息的同时保留其结构。

安装

下载预构建二进制文件

1. 访问 发布页面
2. 下载适用于你平台的二进制文件：

平台	二进制文件
Linux x64	mcp-server-conceal-linux-amd64
macOS Intel	mcp-server-conceal-macos-amd64
macOS Apple Silicon	mcp-server-conceal-macos-aarch64
Windows x64	mcp-server-conceal-windows-amd64.exe

3. 添加可执行权限：chmod +x mcp-server-conceal-*（Linux/macOS）
4. 添加到 PATH：
   • Linux/macOS：mv mcp-server-conceal-* /usr/local/bin/mcp-server-conceal
   • Windows：将其移至 PATH 中的目录，或将当前目录添加到 PATH

从源代码构建

git clone https://github.com/gbrigandi/mcp-server-conceal
cd mcp-server-conceal
cargo build --release

二进制文件位置：target/release/mcp-server-conceal

快速入门

前置条件

安装 Ollama，以使用基于大模型的 PII 检测：

1. 安装 Ollama：ollama.ai
2. 拉取模型：ollama pull llama3.2:3b
3. 验证：curl http://localhost:11434/api/version

基本用法

创建一个最简的 mcp-server-conceal.toml：

[detection]
mode = "regex_llm"

[llm]
model = "llama3.2:3b"
endpoint = "http://localhost:11434"

有关所有可用选项，请参阅配置部分。

以代理模式运行：

mcp-server-conceal \
  --target-command python3 \
  --target-args "my-mcp-server.py" \
  --config mcp-server-conceal.toml

配置

完整配置参考：

[detection]
mode = "regex_llm"                # Detection strategy: regex, llm, regex_llm
enabled = true                    
confidence_threshold = 0.8        # Detection confidence threshold (0.0-1.0)

[detection.patterns]
email = "\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}\\b"
phone = "\\b(?:\\+?1[-\\.\\s]?)?(?:\\(?[0-9]{3}\\)?[-\\.\\s]?)?[0-9]{3}[-\\.\\s]?[0-9]{4}\\b"
ssn = "\\b\\d{3}-\\d{2}-\\d{4}\\b"
credit_card = "\\b\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}[-\\s]?\\d{4}\\b"
ip_address = "\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b"
url = "https?://[^\\s/$.?#].[^\\s]*"

[faker]
locale = "en_US"                  # Locale for generating realistic fake PII data
seed = 12345                      # Seed ensures consistent anonymization across restarts
consistency = true                # Same real PII always maps to same fake data

[mapping]
database_path = "mappings.db"     # SQLite database storing real-to-fake mappings
retention_days = 90               # Delete old mappings after N days

[llm]
model = "llama3.2:3b"             # Ollama model for PII detection
endpoint = "http://localhost:11434"
timeout_seconds = 180
prompt_template = "default"       # Template for PII detection prompts

[llm_cache]
enabled = true                    # Cache LLM detection results for performance
database_path = "llm_cache.db"
max_text_length = 2000

配置指南

检测设置：

• confidence_threshold：较低的值（0.6）可以捕获更多 PII，但会增加误报。较高的值（0.9）更加精确，但可能漏掉部分 PII。
• mode：根据延迟与准确度的要求进行选择（参见下方的检测模式）

Faker 设置：

• locale：使用 "en_US" 表示美国姓名和地址，使用 "en_GB" 表示英国姓名和地址，以此类推。此设置会影响生成的虚假数据的真实性
• seed：在各部署环境中保持一致，以确保相同的真实数据映射为相同的虚假数据
• consistency：始终保持为 true，以维持数据关系

映射设置：

• retention_days：在数据一致性与存储之间取得平衡。较短的期限（30 天）可以减少存储空间，但可能导致重复数据的匿名化结果不一致
• database_path：在生产环境中使用绝对路径，以避免数据库位置问题

检测模式

根据性能要求和数据复杂度选择检测策略：

RegexLlm（默认）

最适合生产环境——兼顾速度与准确度：

• 阶段 1：通过快速正则表达式匹配捕获常见模式（电子邮件、电话、SSN）
• 阶段 2：大模型分析剩余文本，检测复杂的 PII
• 适用场景：需要全面检测，同时要求性能合理
• 性能：每个请求约 100–500 毫秒，具体取决于文本大小
• 配置：mode = "regex_llm"

仅 Regex

最适合高吞吐量、对延迟敏感的应用：

• 仅使用模式匹配，不进行 AI 分析
• 适用场景：PII 模式定义明确，且要求响应时间低于 10 毫秒
• 权衡：可能漏掉上下文型 PII，例如“我的账号是 ABC123”
• 配置：mode = "regex"

仅 LLM

最适合复杂的非结构化数据：

• AI 驱动的检测能够捕获细微的 PII 模式
• 适用场景：准确度比速度更重要
• 性能：每个请求约 200–1000 毫秒
• 配置：mode = "llm"

高级用法

Claude Desktop 集成

配置 Claude Desktop 以代理 MCP 服务：

{
  "mcpServers": {
    "database": {
      "command": "mcp-server-conceal",
      "args": [
        "--target-command", "python3",
        "--target-args", "database-server.py --host localhost",
        "--config", "/path/to/mcp-server-conceal.toml"
      ],
      "env": {
        "DATABASE_URL": "postgresql://localhost/mydb"
      }
    }
  }
}

自定义大模型提示词

为特定领域自定义检测提示词：

模板位置：

• Linux：~/.local/share/mcp-server-conceal/prompts/
• macOS：~/Library/Application Support/com.mcp-server-conceal.mcp-server-conceal/prompts/
• Windows：%LOCALAPPDATA%\\com.mcp-server-conceal\\mcp-server-conceal\\data\\prompts\\

用法：

1. 运行一次 MCP Conceal，在 prompts 目录中自动生成 default.md：

   mcp-server-conceal --target-command echo --target-args "test" --config mcp-server-conceal.toml
   

2. 复制：cp default.md healthcare.md
3. 编辑模板，为特定领域添加 PII 模式
4. 配置：prompt_template = "healthcare"

环境变量

向目标进程传递环境变量：

mcp-server-conceal \
  --target-command node \
  --target-args "server.js" \
  --target-cwd "/path/to/server" \
  --target-env "DATABASE_URL=postgresql://localhost/mydb" \
  --target-env "API_KEY=secret123" \
  --config mcp-server-conceal.toml

故障排除

启用调试日志：

RUST_LOG=debug mcp-server-conceal \
  --target-command python3 \
  --target-args server.py \
  --config mcp-server-conceal.toml

常见问题：

• 配置中的正则表达式模式无效
• Ollama 连接问题
• 数据库文件权限
• 缺少提示词模板

安全

**映射数据库：**包含敏感的真实信息到虚假信息的映射。请设置适当的文件权限以确保安全。

**大模型集成：**使用基于大模型的检测模式时，请在可信基础设施上运行 Ollama。

贡献

欢迎贡献！按照以下步骤开始：

开发环境设置

前置条件：

• 安装 Rust：https://rustup.rs/
• 最低支持的 Rust 版本：1.70+

1. 克隆并设置：

   git clone https://github.com/gbrigandi/mcp-server-conceal
   cd mcp-server-conceal
   

2. 以开发模式构建：

   cargo build
   cargo test
   

3. 安装开发工具：

   rustup component add clippy rustfmt
   

4. 启用调试日志运行：

   RUST_LOG=debug cargo run -- --target-command cat --target-args test.txt --config mcp-server-conceal.toml
   

测试

• 单元测试：cargo test
• 集成测试：cargo test --test integration_test
• 代码检查：cargo clippy
• 格式化：cargo fmt

提交更改

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature-name
3. 进行更改并添加测试
4. 确保所有测试通过：cargo test
5. 格式化代码：cargo fmt
6. 提交 pull request，并附上清晰的说明

许可证

MIT 许可证——详情请参阅 LICENSE 文件。