dbmole-mcp/docs/superpowers/specs/2026-06-11-dbmole-mcp-design.md

# dbmole-mcp — дизайн

MCP-сервер (stdio) для работы с PostgreSQL и MySQL через именованные подключения.
Решаемая боль: фиксированные env-конфиги требуют перезапуска харнеса при каждом
изменении настроек. dbmole хранит подключения персистентно и позволяет управлять
ими тулзами в рантайме, без перезапуска. Переносимость — npm-пакет и Docker-образ.

## Стек

- TypeScript, ESM, Node >= 20
- `@modelcontextprotocol/sdk` — McpServer + StdioServerTransport
- `zod` — схемы входов тулзов и валидация конфигов
- `pg` — драйвер PostgreSQL, `mysql2` — драйвер MySQL
- `ssh2` — SSH-туннели (pure JS, не требует ssh-бинаря в Docker)
- `tsup` — сборка bin с shebang
- Biome — линт и формат: indent 4 пробела, `semicolons: asNeeded`,
  `quoteStyle: single`; функции — `const fn = () => {}` где возможно
- `vitest` + `@vitest/coverage-v8` — тесты, `testcontainers` — интеграционные

## Каскад источников подключений

Выше — приоритетнее при совпадении имён:

1. env `DBMOLE_CONNECTIONS` — JSON-массив конфигов, readonly в рантайме
2. конфиг-файл: `--config <path>` или env `DBMOLE_CONFIG` (путь),
   формат `{ "connections": [...] }`, readonly в рантайме
3. персистентный стор `~/.config/dbmole/connections.json`
   (права 0600, путь переопределяется env `DBMOLE_STORE`) —
   мутируется тулзами add/update/remove_connection

Правила:

- Стор перечитывается при каждом обращении (resolve, list, mutate) — без
  кеширования файла. Несколько одновременных инстансов dbmole видят изменения
  друг друга сразу.
- Запись стора атомарная: tmp-файл + rename. Перед каждой мутацией — re-read
  (read-modify-write), последняя запись побеждает.
- У каждого подключения в выдаче `list_connections` есть `source: env | config | store`.
- `update/remove_connection` по записи из env/config → ошибка с указанием источника.
- `add_connection` с именем, занятым любым слоем, → ошибка (никаких теневых записей).

## Схема подключения

```ts
{
    name: string                // [a-zA-Z0-9_-]+, уникально в рамках слоя
    type: 'postgres' | 'mysql'
    host: string
    port?: number               // default: 5432 (pg) / 3306 (mysql)
    user: string
    password?: string
    database?: string           // дефолтная БД для тулзов без явного database
    readonly?: boolean          // default: false
    ssh?: {
        host: string
        port?: number           // default: 22
        user: string
        password?: string
        privateKey?: string     // inline PEM
        privateKeyPath?: string // путь, '~' разворачивается
        passphrase?: string
        agent?: boolean         // использовать SSH_AUTH_SOCK
    }
}
```

Валидация zod на всех входах: и тулзовых, и из env/файлов. Ошибка в одном
конфиге из источника не валит сервер — битая запись скипается с warning в stderr.

## Runtime-архитектура

```
src/
  index.ts          — entry: argv/env, wire-up, stdio transport, shutdown
  server.ts         — McpServer, регистрация тулзов
  config/
    types.ts        — zod-схемы ConnectionConfig, SshConfig
    sources.ts      — чтение env-слоя и config-файла
    store.ts        — персистентный стор: атомарные read/write, 0600
    registry.ts     — мердж каскада, CRUD store-слоя, resolve(name) → {config, source, hash}
  net/
    tunnel.ts       — SshTunnel: ssh2-клиент + локальный TCP-форвард
  db/
    driver.ts       — интерфейс Driver
    postgres.ts     — pg-реализация
    mysql.ts        — mysql2-реализация
    manager.ts      — ConnectionManager: кеш name → {tunnel?, driver, hash}
  tools/
    connections.ts  — list/add/update/remove/test_connection
    query.ts        — execute_sql
    schema.ts       — list_databases, list_tables, describe_table
  format.ts         — приведение результатов, rowLimit, truncation
```

- **registry** — единственная точка чтения конфигов. `resolve(name)` возвращает
  конфиг, источник и стабильный hash (canonical JSON) конфига.
- **manager** — ленивая инициализация: при первом запросе к подключению
  поднимает туннель (если есть `ssh`) и создаёт драйвер. Если hash конфига
  изменился со времени кеширования — dispose старого (пулы + туннель)
  и пересоздание. Это даёт hot-reload настроек без перезапуска.
- **tunnel** — локальный TCP-сервер на `127.0.0.1:0` (эфемерный порт), каждое
  входящее соединение форвардится через `ssh2` `forwardOut` на целевые
  db host:port. Драйвер подключается к локальному endpoint.
- **driver** — интерфейс: `query`, `listDatabases`, `listTables`,
  `describeTable`, `dispose`. Внутри — map пулов per database
  (пул на пару connection+database), max 4 соединения на пул.
- Shutdown: SIGINT/SIGTERM/закрытие stdin → dispose всех драйверов и туннелей.

## Readonly

Серверное принуждение, не SQL-парсинг. На каждом новом коннекте пула:

- pg: `SET default_transaction_read_only = on`
- mysql: `SET SESSION TRANSACTION READ ONLY`

Блокирует DML и DDL на стороне движка. Обходится только явным `SET` в SQL —
для агентского сценария приемлемо (защита от случайной записи, не от злого умысла).

## Тулзы

Все входы — zod. Параметр `database` опционален везде, где есть, —
fallback на `database` подключения; если нет ни того ни другого → ошибка.

| Тулза | Вход | Выход |
|---|---|---|
| `list_connections` | — | `[{name, type, host, port, database, readonly, source, ssh: boolean}]`, без секретов |
| `add_connection` | полный конфиг | ok + запись в стор |
| `update_connection` | `name` + partial-конфиг | ok, патч store-записи, инвалидация кеша manager; явный `null` в поле удаляет опциональное поле (напр. `ssh: null`) |
| `remove_connection` | `name` | ok, удаление из стора, dispose ресурсов |
| `test_connection` | `name` | connect + `SELECT 1`: версия сервера, latency ms |
| `execute_sql` | `connection, sql, params?, database?, rowLimit?` | SELECT: `{columns, rows, rowCount, truncated}`; DML: `{rowCount, lastInsertId?}` |
| `list_databases` | `connection` | имена + размер в байтах |
| `list_tables` | `connection, database?, schema?` | `[{schema, name, rowEstimate}]` (mysql: schema = database) |
| `describe_table` | `connection, table, database?, schema?` | колонки (тип, nullable, default), PK, индексы, FK |

- `params` — позиционные (`$1` для pg, `?` для mysql), передаются драйверу
  как параметризованный запрос.
- `rowLimit`: default 100, max 1000. При срезе `truncated: true`.
- Один SQL-стейтмент на вызов: `multipleStatements` выключен у mysql2,
  у pg параметризованные запросы и так single-statement. Меньше сюрпризов.
- Ошибки — структурный текст: `[pg 42P01] relation "x" does not exist` + detail/hint
  у pg. «Connection not found» перечисляет доступные имена — агент сам чинится.
- Системные БД скрыты в `list_databases` (template0/1; mysql, sys,
  performance_schema, information_schema).

## Дистрибуция

- npm: package `dbmole-mcp`, `bin: { "dbmole-mcp": "dist/index.js" }`.
  Подключение: `{ "command": "npx", "args": ["-y", "dbmole-mcp"] }`
- Docker: `node:22-alpine`, multi-stage build,
  `docker run -i --rm -v dbmole-store:/root/.config/dbmole dbmole-mcp`
- README: оба способа + формат env/config + примеры `.mcp.json`

## Тестирование

- **Unit** (моки, без сети): мердж каскада и приоритеты, атомарность стора
  и права 0600, zod-валидация (вкл. скип битых записей), форматирование
  результатов и truncation, tool-хендлеры с мок-manager, lifecycle туннеля
  с мок-ssh2, инвалидация по hash.
- **Интеграция** (testcontainers, требуется Docker): реальные postgres и mysql
  контейнеры — полный флоу add_connection → execute_sql → list/describe →
  readonly-enforcement (запись падает с ошибкой движка); sshd-контейнер →
  e2e туннель до pg за SSH.
- Coverage-пороги в vitest config: >= 90% lines/functions.
- CI-разделение: `npm run test:unit` (быстрые) / `npm run test:int` (docker).

## Вне скоупа (YAGNI)

- Другие движки (sqlite, mssql) — интерфейс Driver оставляет дверь открытой
- Шифрование стора (плейнтекст 0600, как ~/.pgpass)
- HTTP/SSE транспорт
- Idle-таймауты туннелей и пулов (dispose по shutdown и инвалидации достаточно)
- Миграции формата стора