pc2e-pii-shield

Un servidor seguro de Protocolo de Contexto de Modelo (MCP) de grado de producción que proporciona ejecución de consultas PostgreSQL de solo lectura con enmascaramiento automático, del lado del cliente y en el borde de Información de Identificación Personal (PII). Permite que los agentes de LLM (por ejemplo, Cursor, Cline, Claude Code) ejecuten consultas SQL en bases de datos garantizando el estricto cumplimiento del GDPR, PDPA y los principios de privacidad de datos.

Diseñado e ingenierizado como un producto de middleware de seguridad reutilizable, este servidor intercepta los resultados de las consultas a la base de datos para evitar la salida de datos sensibles.

Arquitectura Técnica

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

Componentes Principales

1. Interceptor de Auto-Enmascaramiento (masking.ts): Escanea dinámicamente los conjuntos de resultados SQL. Utiliza un enfoque híbrido: coincidencia de esquema de columnas (por ejemplo, campos que contengan name, email, phone) combinada con escaneo de contenido basado en expresiones regulares para detectar y enmascarar identificadores sensibles antes de que los datos salgan del servidor.

2. Caché de Pseudonimización (cache.ts): Una caché en memoria con respaldo TTL (predeterminado: 30 minutos) que asigna valores brutos a marcadores temporales (por ejemplo, __PERSON_A__, __EMAIL_1__). Esto permite la restauración bidireccional mientras previene el consumo ilimitado de memoria.

3. Guardia de Mutación a Nivel de AST (db.ts): Un validador estricto de expresiones regulares que intercepta las entradas SQL brutas. Bloquea cualquier comando que no sea SELECT y rechaza consultas que contengan palabras clave prohibidas como DROP, ALTER, DELETE, TRUNCATE, CREATE o GRANT, garantizando un límite estricto de solo lectura en la capa de aplicación.

4. Gestor de Sesiones Concurrentes (index.ts): A diferencia de las plantillas básicas de conexión única, este servidor mantiene un mapa activo de instancias de SSEServerTransport claveado por sessionId de conexión, permitiendo que múltiples desarrolladores o agentes remotos se conecten y transmitan simultáneamente sin colisiones de estado.

5. Endpoint de Telemetría y Métricas (/stats): Expone conteos de conexión, seguimiento de IPs de cliente únicas y estadísticas agregadas de ejecución de consultas para monitorear la instalación y el uso activo en tiempo real.

Related MCP server: PostgreSQL MCP Server

Modelo de Seguridad y Mitigación de Amenazas

• Conectividad de Base de Datos de Confianza Cero: Diseñada para prevenir la exposición de credenciales. La base de datos se ejecuta en una interfaz de red aislada solo con Tailscale (por ejemplo, 100.92.174.76), asegurando que el puerto de la base de datos nunca esté expuesto a Internet público.

• Transporte Cifrado y Seguridad de Clave API: El servidor está detrás de Nginx sobre HTTPS (puerto 443) utilizando certificados SSL comodín, aplicando una compuerta de autenticación segura de clave API (x-api-key) antes de reenviar las solicitudes.

• Ciclo de Vida en Memoria: Las asignaciones de pseudonimización se almacenan en memoria con TTL estrictos, sin dejar huellas persistentes en disco de la PII enmascarada.

Instalación y Despliegue

1. Configuración Previa del Entorno

Copia la plantilla de entorno:

cp .env.example .env

Configura tus credenciales de base de datos y genera una clave API segura dentro de .env.

2. Compilación Nativa

Asegúrate de que Node.js (v18+) esté instalado:

npm install
npm run build
npm start

3. Despliegue Contenerizado

Despliega usando Docker Compose:

docker compose up -d --build

Esto mapea el puerto del host 3088 al puerto interno 3000 del contenedor, ejecutando el servidor SSE automáticamente.

4. Ejecución Directa (NPX)

Puedes ejecutar el servidor al instante a través del transporte Stdio sin descargar el código manualmente:

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

O ejecutar el servidor a través del transporte SSE:

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

Integración con el Cliente

A. Integración Local con el Cliente (vía NPX sobre Stdio)

Configura tu cliente de IA local para lanzar el servidor directamente usando npx.

Claude Desktop (config.json)

Añade el siguiente bloque a tu ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %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 (Configuración → Funciones → MCP)

1. Haz clic en + Añadir nuevo servidor MCP.

2. Establece Nombre en pc2e-pii-shield.

3. Establece Tipo en command.

4. Establece Comando en:

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

VS Code (Cline / Roo Code)

Añade lo siguiente al JSON de configuración de tu cliente:

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

B. Integración Remota con el Cliente (vía HTTPS sobre SSE)

Si te estás conectando a un servidor alojado (por ejemplo, tu instancia NAS pública), conéctate a través de la URL de transporte SSE.

VS Code (Cline / Roo Code)

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

Cursor

1. Haz clic en + Añadir nuevo servidor MCP.

2. Establece Nombre en pc2e-pii-shield.

3. Establece Tipo en SSE.

4. Establece URL en:

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

Contexto del Proyecto y Líder Técnico

Este proyecto fue arquitecturado, construido y publicado como código abierto por Andrew Yeo.

Acerca del Arquitecto Principal

Andrew es Arquitecto de Sistemas Senior e Ingeniero de IA con sede en Singapur, y ofrece:

• 25 años de experiencia profesional en APAC, gestionando la entrega de programas, la incorporación de clientes y la gestión técnica de proveedores.

• Más de 16 años de arquitectura de sistemas y liderazgo tecnológico, diseñando e implementando infraestructuras empresariales robustas y plataformas de microservicios.

• Más de 2 años de ingeniería práctica dedicada en IA/ML, especializado en seguridad de IA, métricas de LLM y flujos de trabajo agénticos seguros.

Prueba de Trabajo Verificada

• Plataformas Cívicas Seguras: Arquitecturó e implementó MPS-Connect (una plataforma cívica de gestión de casos de circunscripción) y Case-Writer-Intelligence (CWI), integrando un motor de causalidad de 3 etapas con 7 compuertas de aprobación con intervención humana, reduciendo el tiempo de triaje de documentos en un 40%.

• Metrología y Pruebas de IA: Diseñó el Portable Continuous Context Engine (PC2E), ejecutando una evaluación sistemática y empírica de 50,000 casos en seis proveedores de LLM para comparar la alineación y el cumplimiento de los modelos.

• Enfoque Técnico: Experto en CI/CD y DevSecOps (GitHub Actions, Docker), implementaciones contenerizadas, topologías de red de confianza cero y orquestaciones SLM locales/de borde.