pc2e-pii-shield

一个安全、生产级的 Model Context Protocol（MCP）服务器，提供只读 PostgreSQL 查询执行，并具备自动、客户端侧和边缘端的个人可识别信息（PII）脱敏能力。它允许 LLM 智能体（例如 Cursor、Cline、Claude Code）在数据库上执行 SQL 查询，同时确保严格符合 GDPR、PDPA 和数据隐私原则。

该服务器作为可复用的安全中间件产品进行设计与工程化实现，拦截数据库查询结果，以防止敏感数据外泄。

技术架构

flowchart TD
    Client["AI Agent / Client (Cursor/Cline)"]
    Proxy["Nginx Reverse Proxy"]
    App["pc2e-pii-shield (Express)"]
    DB["Postgres Database (Tailscale-Only)"]

    Client ==>|HTTPS / SSE Request| Proxy
    Proxy ==>|x-api-key Authentication| App
    App ==>|Regex Read-Only Validation| DB
    DB ==>|Raw SQL Results| App
    App ==>|PII Tokenization & Masking| Proxy
    Proxy ==>|Sanitized Event Stream| Client

核心组件

1. 自动脱敏拦截器（masking.ts）： 动态扫描 SQL 结果集。它采用混合方法：列模式匹配（例如，包含 name、email、phone 的字段）结合基于正则表达式的内容扫描，在数据离开服务器之前检测并脱敏敏感标识符。

2. 假名化缓存（cache.ts）： 一个内存中的、基于 TTL 的缓存（默认：30 分钟），将原始值映射到临时占位符（例如 __PERSON_A__、__EMAIL_1__）。这支持双向还原，同时防止无限制的内存消耗。

3. AST 级变更防护器（db.ts）： 一个严格的正则表达式验证器，用于拦截原始 SQL 输入。它阻止任何非 SELECT 命令，并拒绝包含 DROP、ALTER、DELETE、TRUNCATE、CREATE 或 GRANT 等禁止关键字的查询，从而在应用层确保严格的只读边界。

4. 并发会话管理器（index.ts）： 与基本的单连接模板不同，该服务器维护一个以连接 sessionId 为键的 SSEServerTransport 实例活动映射，允许多个远程开发人员或智能体并发连接和流式传输，而不会发生状态冲突。

5. 遥测与指标端点（/stats）： 公开连接计数、唯一客户端 IP 跟踪和聚合查询执行统计信息，以实时监控安装和活跃使用情况。

Related MCP server: PostgreSQL MCP Server

安全模型与威胁缓解

• 零信任数据库连接： 旨在防止凭据泄露。数据库运行在仅限 Tailscale 的隔离网络接口上（例如 100.92.174.76），确保数据库端口永远不会暴露到公共互联网。

• 加密传输与 API 密钥安全： 服务器由 Nginx 通过 HTTPS（端口 443）前置代理，并使用通配符 SSL 证书，在转发请求之前强制执行安全的 API 密钥身份验证门禁（x-api-key）。

• 内存生命周期： 假名化映射以严格的 TTL 存储在内存中，不会在磁盘上留下已脱敏 PII 的任何持久痕迹。

安装与部署

1. 前置环境设置

复制环境模板：

cp .env.example .env

在 .env 中配置您的数据库凭据并生成一个安全的 API 密钥。

2. 原生构建

确保已安装 Node.js（v18+）：

npm install
npm run build
npm start

3. 容器化部署

使用 Docker Compose 部署：

docker compose up -d --build

此配置将主机端口 3088 映射到容器内部端口 3000，自动运行 SSE 服务器。

4. 直接执行（NPX）

您可以立即通过 Stdio 传输运行服务器，无需手动下载代码：

npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"

或者通过 SSE 传输运行服务器：

npx -y mcp-pii-shield --sse --port 3000 --db-uri "postgresql://username:password@localhost:5432/your_database" --api-key "your_secret_key"

客户端集成

A. 本地客户端集成（通过 NPX 经 Stdio 传输）

配置您的本地 AI 客户端，使用 npx 直接启动服务器。

Claude Desktop（config.json）

将以下代码块添加到您的 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pii-shield",
        "--db-uri",
        "postgresql://username:password@localhost:5432/your_database"
      ]
    }
  }
}

Cursor（设置 → 功能 → MCP）

1. 单击 + 添加新的 MCP 服务器。

2. 将 名称 设置为 pc2e-pii-shield。

3. 将 类型 设置为 command。

4. 将 命令 设置为：

   npx -y mcp-pii-shield --db-uri "postgresql://username:password@localhost:5432/your_database"

VS Code（Cline / Roo Code）

将以下内容添加到您的客户端设置 JSON：

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-pii-shield",
        "--db-uri",
        "postgresql://username:password@localhost:5432/your_database"
      ]
    }
  }
}

B. 远程客户端集成（通过 HTTPS 经 SSE 传输）

如果您要连接到托管服务器（例如您的公共 NAS 实例），请通过 SSE 传输 URL 连接。

VS Code（Cline / Roo Code）

{
  "mcpServers": {
    "pc2e-pii-shield": {
      "sseUrl": "https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here"
    }
  }
}

Cursor

1. 单击 + 添加新的 MCP 服务器。

2. 将 名称 设置为 pc2e-pii-shield。

3. 将 类型 设置为 SSE。

4. 将 URL 设置为：

   https://pii-shield.thegeekybeng.com/sse?api_key=your_api_key_here

项目背景与技术负责人

本项目由 Andrew Yeo 架构、构建并开源。

关于首席架构师

Andrew 是常驻新加坡的高级系统架构师和 AI 工程师，具备：

• 25 年专业经验，覆盖亚太地区，管理项目交付、客户引导和技术供应商管理。

• 16 年以上系统架构和技术领导经验，设计并部署了稳健的企业基础设施和微服务平台。

• 2 年以上专注的 AI/ML 实操工程经验，专精于 AI 安全、LLM 指标和安全智能体工作流。

已验证的工作成果

• 安全公民服务平台： 架构并部署了 MPS-Connect（公民选区个案处理平台）和 Case-Writer-Intelligence（CWI），集成了 3 阶段因果引擎和 7 个人工在环审批关卡，将文档分拣时间减少了 40%。

• AI 度量与测试： 设计了 Portable Continuous Context Engine（PC2E），运行了一项跨六个 LLM 提供商的 50,000 个案例的系统性实证评估，以对模型对齐和合规性进行基准测试。

• 技术专长： 精通 CI/CD 与 DevSecOps（GitHub Actions、Docker）、容器化部署、零信任网络拓扑以及本地/边缘 SLM 编排。