de en es ja ko ru zh

pc2e-pii-shield

Name: pc2e-pii-shield
Author: thegeekybeng

by thegeekybeng

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

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

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.
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.
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.
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.
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)

Haz clic en + Añadir nuevo servidor MCP.
Establece Nombre en pc2e-pii-shield.
Establece Tipo en command.

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

Haz clic en + Añadir nuevo servidor MCP.
Establece Nombre en pc2e-pii-shield.
Establece Tipo en SSE.

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.

Available Tools

3 tools

add_to_rosterA

ParametersJSON Schema

Name	Required	Description	Default
`names`	Yes	An array of names to be dynamically added to the scanner roster.

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations are not provided, so the description carries the burden, but it is minimal. It clarifies the scope (local name-matching detection) but does not disclose behavioral traits such as whether the roster is persistent, how additions affect existing entries, or any potential side effects (e.g., deduplication). It goes beyond a simple 'Add' but lacks substantial behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that packs essential information: action, target, and purpose. It is front-loaded with the verb. No filler or redundant content. Five is appropriate for its brevity and efficiency.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple with one parameter and no output schema. The description covers the purpose and target, but lacks details about behavior (e.g., duplicates, confirmation) and does not mention return values. Given the low complexity, this is acceptable but not fully complete; a 3 is appropriate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (the parameter 'names' is documented as 'An array of names to be dynamically added to the scanner roster'). The description adds value by clarifying that the names are 'new' and for 'local name-matching detection', which enhances the schema's meaning. With full coverage, baseline is 3; the added specificity justifies a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Register new names to the active regex scan roster for local name-matching detection' clearly states the action (register names), the resource (active regex scan roster), and the purpose (local name-matching detection). It distinguishes from siblings (unmask_text, run_secure_query) by specifying the roster for name-matching, which is specific enough.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context (for local name-matching detection) but does not explicitly specify when to use this tool versus alternatives, nor any exclusions (e.g., when to prefer unmask_text). Sibling tools exist but are not referenced or contrasted. Adequate but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_secure_queryA

Execute a read-only SELECT database query. All PII values (names, emails, phones, NRIC/IDs) in the results will be automatically masked before being returned.

ParametersJSON Schema

Name	Required	Description	Default
`sql_query`	Yes	The read-only SQL SELECT query to run (e.g. SELECT name, email FROM contacts LIMIT 5)

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden, and it does so well by disclosing: (1) the operation is read-only, and (2) all PII values in results will be automatically masked. This gives the agent critical behavioral expectations (e.g., don't expect unmasked PII in results). It does not cover edge cases like error handling or large result pagination, but for the information provided, this is a strong disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences (33 words) with a clear action-first structure. Front-loads the primary purpose ('Execute a read-only SELECT database query') and follows with the key behavioral differentiator (PII masking). Every word contributes meaning; no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple 1-parameter tool with no output schema, the description covers all essential aspects: the operation, the constraint on input, and a key output transformation (masking). Additional details like error messages for invalid queries or rate limiting would be nice but are not critical for this complexity, and the behavioral notes alone elevate it above the norm.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds value by qualifying the query as 'read-only' and emphasizing the PII masking behavior, which affects result processing semantics beyond what the schema example shows. It could have gone further by specifying what happens with non-SELECT input (error vs. rejection).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Execute a read-only SELECT database query') with a specific verb and resource, and the PII masking note explains what makes it 'secure.' This effectively differentiates it from sibling tools (unmask_text, add_to__roster) by making clear this is the querying tool that returns masked data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use this tool (read-only data retrieval) but does not explicitly state alternatives or exclusions (e.g., 'for write operations use X'). The sibling tools could offer more context, but no explicit comparison is provided. The read-only and SELECT constraints give some usage guardrails.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

unmask_textA

Restore the original raw PII values in a text payload by replacing placeholders (e.g. PERSON_A, EMAIL_1) with their original values cached during this session.

ParametersJSON Schema

Name	Required	Description	Default
`masked_text`	Yes	The text containing placeholders to be restored.

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

There are no annotations, so the description must convey behavior. It mentions the session-cached values but does not disclose what happens if the cache is missing, whether the operation is reversible, or any side effects (e.g., does it mutate input or return a new string?). It provides some context but lacks critical behavioral details for a tool with no annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that front-loads the core action and provides examples. It contains no redundant or tangential information, making it optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with one parameter and no output schema, the description covers the main mechanism but omits the return value and potential error conditions (e.g., missing cache entries). While the session dependency is mentioned, a mention of expected output or failure handling would enhance completeness. Still, it is adequate for a simple tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides a basic description of 'masked_text.' The tool description adds value by giving concrete examples of placeholder formats and explaining that they are replaced with original values. This goes beyond the schema's simple definition, enriching parameter understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: restoring original PII values by replacing placeholders like __PERSON_A__ and __EMAIL_1__ with cached values. It uses a specific verb and resource, making it unmistakable. Although siblings are unrelated, the purpose is distinct and well-defined.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It implies usage context by mentioning 'cached during this session,' which tells the agent when the tool is applicable (after a prior masking operation). It does not explicitly list alternatives or exclusions, but given the unrelated siblings, this is not a significant gap. The context is clear enough for selecting this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv1.0.0Aug 21, 2026
- First observedadd_to_roster
- First observedrun_secure_query
- First observedunmask_text

Deploy Server

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

TDQS

A3.9/5.0

Scored 2026-08-21 00:10 across 3 tools

Disambiguation5/5

Each tool addresses a distinct concern: one unmask text, one manage the name roster, and one execute queries with automatic masking. There is no overlap that would cause an agent to misselect.

Naming Consistency4/5

Most tools follow a verb_noun pattern (unmask_text, run_secure_query), but add_to_roster breaks the pattern with an intervening preposition. This is a minor deviation and the intent remains clear.

Tool Count4/5

Three tools is a reasonable, focused set for a PII-shielding server. It is slightly lean but each tool serves a clear purpose without unnecessary bloat.

Completeness3/5

The core masking lifecycle is covered—query masking, unmasking, and roster management—but obvious gaps exist: no tool for masking non-query text, no roster removal or listing, and no way to manage the cached placeholders beyond unmasking. These gaps could force workarounds.

Maintenance

ActivitySlowing

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

AgentSQL
io.github.cuipengdba
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Databases Security
13
DB Query Guard MCP
com.clauxel.dbqueryguard
Paid remote MCP for governed database query review, SQL simulation, approvals, and audits.
Databases Security
2
PGAuditor
com.mcpgatepro
Hosted MCP server for PostgreSQL diagnostics: slow queries, missing indexes, connection pressure.
Databases Monitoring Observability
1
Draxlr AOAuth
com.draxlr.api
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
Data Visualization Databases Search
1

Related MCP Servers

PostgreSQL Read-Only MCP
Databases Security
currentspace
F
license
Not graded
quality
D
maintenance
A secure MCP server that enables querying PostgreSQL databases through an SSH tunnel with enforced read-only access, connection pooling, and comprehensive data exploration tools.
Updated a year ago (2025-07-08 01:21 UTC)
-
PostgreSQL MCP Server
Databases Developer Tools
datdeboer
A
license
Not graded
quality
D
maintenance
A production-ready MCP server that enables safe, read-only SQL SELECT queries against PostgreSQL databases with built-in security validation. It features connection pooling, automatic row limits, and structured logging to ensure secure and reliable database interactions.
Updated 8 months ago (2026-02-16 17:44 UTC)
31 npm
ISC
mcp-postgres
Databases Developer Tools
gbfeliped
A
license
Not graded
quality
D
maintenance
Read-only PostgreSQL MCP server that enables running SELECT queries, listing tables and schemas, and describing columns, with built-in protection against writes and malicious SQL attacks.
Updated 4 months ago (2026-06-18 14:32 UTC)
476 npm
MIT
postgres-mcp-readonly
Databases Developer Tools
mahin1995
A
license
A
quality
D
maintenance
A secure, read-only PostgreSQL MCP server that provides safe database introspection and querying capabilities.
Updated 5 months ago (2026-05-04 16:20 UTC)
14
19 npm
MIT

pc2e-pii-shield

Arquitectura Técnica

Componentes Principales

Modelo de Seguridad y Mitigación de Amenazas

Instalación y Despliegue

1. Configuración Previa del Entorno

2. Compilación Nativa

3. Despliegue Contenerizado

4. Ejecución Directa (NPX)

Integración con el Cliente

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

Claude Desktop (config.json)

Cursor (Configuración → Funciones → MCP)

VS Code (Cline / Roo Code)

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

VS Code (Cline / Roo Code)

Cursor

Contexto del Proyecto y Líder Técnico

Acerca del Arquitecto Principal

Prueba de Trabajo Verificada

Available Tools

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Claude Desktop (`config.json`)