pgops-mcp

Промышленный MCP-сервер, который даёт AI-агентам безопасный, аудируемый и экспертный контроль над реальной базой данных PostgreSQL и Docker-стеком вокруг неё — без shell-команд, без Python-скриптов, только инструменты.

Зачем

Существующие Postgres MCP-серверы — это тонкие обёртки над запросами: интроспекция + SELECT. Ни один не обрабатывает миграции с анализом влияния на блокировки, ни один не диагностирует производительность через EXPLAIN + pg_stat_statements, ни один не понимает контейнеризованное окружение, в котором живёт база данных. Агенты, работающие с базами данных сегодня, действуют вслепую и небезопасно.

pgops-mcp — это операционный мозг: интеллект схемы → защищённые запросы → движок миграций → диагностика производительности → осведомлённость об окружении, с архитектурой безопасности, которая делает каждое действие классифицируемым, подтверждаемым и аудируемым.

Related MCP server: PostgreSQL MCP Server

Поверхность инструментов (v0.1)

* Не регистрируются вообще, если сервер не запущен с --approval-mode, и даже тогда каждый вызов требует токен подтверждения. container.exec дополнительно применяет разрешённый список диагностических команд только для чтения — он не предоставляет shell. Docker-сокет эквивалентен root на хосте, поэтому по умолчанию доступ только для чтения.

Модель безопасности (ключевое отличие)

• Раздельные роли подключения только для чтения / чтения-записи; инструменты привязаны к нужной роли

• Классификация операторов перед выполнением — неограниченные DELETE/UPDATE блокируются

• Деструктивные действия требуют явных токенов подтверждения

• Каждый выполненный оператор попадает в append-only журнал аудита с временем и вердиктом

• Отмена вышедших из-под контроля запросов с многоуровневыми таймаутами

MCP-поверхность

Удалённый доступ и токены агентов

stdio не требует аутентификации — сервер является подпроцессом, который запускает ваш клиент, без открытого порта. HTTP требует, поэтому он отказывается запускаться без ключа:

pgops-mcp keygen                                    # RS256 keypair
pgops-mcp issue-token --subject my-agent            # read-only by default
pgops-mcp issue-token --subject deploy-bot --scope pgops:read --scope pgops:write
pgops-mcp scopes                                    # which scope each tool needs

pgops-mcp --transport http --public-key ~/.pgops/keys/pgops_public.pem

Сервер хранит только публичный ключ, поэтому он может проверять токены, но никогда не создавать их. Области (pgops:read / pgops:write / pgops:admin) соответствуют тем же уровням опасности, что и защитные механизмы, а инструмент без записи в области требует admin — отказ по умолчанию. Привязывается к loopback, если не указано иное.

Быстрый старт

uv sync
# point at your local Postgres in Docker:
export PGOPS_DSN="postgresql://user:pass@localhost:5432/mydb"
uv run pgops-mcp            # stdio transport for Claude Desktop / Cursor / VS Code

Добавьте в Claude Desktop:

{
  "mcpServers": {
    "pgops": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/pgops-mcp", "pgops-mcp"]
    }
  }
}

Документация

• docs/PRD.md — что и зачем, цели, не-цели

• docs/SPEC.md — поэтапная техническая спецификация с жёсткими воротами

• docs/ARCHITECTURE.md — системный дизайн + компромиссы

• docs/TOOLS.md — полный каталог инструментов со схемами и примерами

• docs/adr/ — записи архитектурных решений

• docs/flow.md — живой журнал прогресса

• docs/interview_prep.md — растущий Q&A для интервью

Статус

Фазы 0–6b завершены (319 тестов, каждый защитный механизм, вердикт и правило влияния на блокировки проверены на реальном Postgres через testcontainers — без моков — плюс сквозные наборы, управляющие сервером как реальным MCP-подпроцессом через stdio и как аутентифицированным HTTP-сервером).

migration.rollback намеренно остаётся открытым — см. docs/TOOLS.md.

Пример того, что migration.plan возвращает для изменения типа в таблице orders на 1,2 млн строк:

ALTER TABLE "orders" ALTER COLUMN "total_cents" TYPE bigint
  op=table_rewrite  risk=high  estimate=4800ms  confidence=medium
  why:   rewrites every row and rebuilds every index, holding AccessExclusiveLock
  SAFER: add a new column of the target type, backfill in batches, sync with a
         trigger, swap the names, then drop the old column

Быстрый старт dev-базы данных (порт хоста 5433, чтобы не конфликтовать с локальным Postgres на 5432):

docker compose up -d
export PGOPS_DSN="postgresql://pgops:pgops_dev@localhost:5433/pgops_demo"
uv run pgops-mcp --selfcheck