pc2e-pii-shield

Безопасный MCP-сервер производственного уровня, обеспечивающий выполнение SQL-запросов только для чтения с автоматической маскировкой персональных данных (PII) на стороне клиента и на границе сети. Он позволяет LLM-агентам (например, Cursor, Cline, Claude Code) выполнять SQL-запросы к базам данных, гарантируя строгое соответствие требованиям GDPR, PDPA и принципам защиты данных.

Спроектирован и разработан как переиспользуемый продукт класса security-промежуточного слоя: сервер перехватывает результаты запросов к базе данных, предотвращая несанкционированную утечку чувствительных данных.

Техническая архитектура

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) в сочетании с контентным сканированием на основе регулярных выражений для обнаружения и маскировки чувствительных идентификаторов до того, как данные покинут сервер.

2. Кэш псевдонимизации (cache.ts): In-memory кэш с TTL (по умолчанию 30 минут), который сопоставляет исходные значения с временными плейсхолдерами (например, __PERSON_A__, __EMAIL_1__). Это позволяет выполнять двунаправленное восстановление данных, предотвращая при этом неограниченное потребление памяти.

3. Защита на уровне AST (db.ts): Строгий валидатор, перехватывающий исходные SQL-запросы. Блокирует любые команды, отличные от SELECT, и отклоняет запросы, содержащие запрещённые ключевые слова, такие как DROP, ALTER, DELETE, TRUNCATE, CREATE или GRANT, обеспечивая строгую границу только для чтения на уровне приложения.

4. Менеджер конкурентных сессий (index.ts): В отличие от простых шаблонов с одним подключением, этот сервер поддерживает активную карту экземпляров SSEServerTransport, ключом в которой является sessionId подключения, что позволяет нескольким удалённым разработчикам или агентам подключаться и работать в потоковом режиме одновременно без конфликтов состояния.

5. Endpoint телеметрии и метрик (/stats): Предоставляет данные о количестве подключений, отслеживании уникальных IP-адресов клиентов и агрегированную статистику выполнения запросов для мониторинга установки и активности в реальном времени.

Related MCP server: PostgreSQL MCP Server

Модель безопасности и смягчение угроз

• Подключение к базе данных с нулевым доверием: Разработано для предотвращения раскрытия учётных данных. База данных работает в изолированной сетевой среде только через Tailscale (например, 100.92.174.76), что гарантирует, что порт базы данных никогда не будет доступен из публичного интернета.

• Шифрованный транспорт и защита API-ключей: Сервер работает за Nginx по HTTPS (порт 443) с использованием wildcard SSL-сертификатов, обеспечивая обязательную аутентификацию через API-ключ (x-api-key) перед передачей запросов.

• Жизненный цикл в памяти: Сопоставления псевдонимизации хранятся в памяти со строгими TTL, не оставляя постоянных следов на диске для замаскированных PII-данных.

Установка и развёртывание

1. Предварительная настройка окружения

Скопируйте шаблон файла окружения:

cp .env.example .env

Настройте учётные данные базы данных и сгенерируйте безопасный API-ключ в файле .env.

2. Сборка вручную (Native Build)

Убедитесь, что установлен 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 (Settings → Features → MCP)

1. Нажмите + Add New MCP Server.

2. В поле Name укажите pc2e-pii-shield.

3. В поле Type выберите command.

4. В поле Command укажите:

   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), используйте URL 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. Нажмите + Add New MCP Server.

2. В поле Name укажите pc2e-pii-shield.

3. В поле Type выберите SSE.

4. В поле URL укажите:

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

Контекст проекта и технический руководитель

Этот проект был спроектирован, разработан и опубликован в открытом доступе Эндрю Йео (Andrew Yeo).

О техническом руководителе

Эндрю — старший системный архитектор и AI-инженер из Сингапура, предлагающий:

• 25+ лет профессионального опыта в Азиатско-Тихоокеанском регионе: управление программами, онбординг клиентов и управление техническими вендорами.

• 16+ лет в системной архитектуре и технологическом лидерстве: проектирование и развёртывание корпоративной инфраструктуры и микросервисных платформ.

• 2+ года практической инженерии в области AI/ML: специализация на безопасности ИИ, метриках LLM и безопасных агентных рабочих процессах.

Подтверждённые проекты (Proof-of-Work)

• Безопасные гражданские платформы: Спроектировал и развернул MPS-Connect (платформа для работы с обращениями избирателей) и Case-Writer-Intelligence (CWI), интегрировав 3-ступенчатый механизм каузального анализа с 7 этапами утверждения с участием человека, что сократило время обработки документов на 40%.

• AI-метрология и тестирование: Разработал Portable Continuous Context Engine (PC2E) — систему, выполняющую систематическую эмпирическую оценку 50 000 сценариев на шести LLM-провайдерах для бенчмаркинга согласованности моделей и соответствия требованиям.

• Техническая специализация: Эксперт в CI/CD и DevSecOps (GitHub Actions, Docker), контейнерных развёртываниях, сетевых топологиях с нулевым доверием и оркестрации локальных/периферийных SLM-моделей.