mcp-devdb

Безопасный MCP-сервер только для чтения для локальных баз данных разработки. Программным агентам постоянно нужно видеть вашу базу разработки — схему, примеры данных, планы запросов, размеры таблиц — но наивный коннектор к базе данных дает им полный доступ на запись. mcp-devdb — это защищенная альтернатива: сервер Model Context Protocol, который предоставляет инструменты интроспекции за укрепленным SQL-шлюзом только для чтения, маскированием столбцов, ограничениями результатов и посессионным бюджетом запросов.

Бэкенды в v1: PostgreSQL (через postgres) и SQLite (через better-sqlite3). Интерфейс адаптера нейтрален к движку, поэтому MySQL можно добавить позже.

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

1. Создайте mcp-devdb.json рядом с местом, где будет запускаться сервер (см. mcp-devdb.example.json):

{
  "databases": {
    "app": { "url": "postgres://dev:dev@localhost:5432/app_development" },
    "cache": { "url": "sqlite:./data/cache.db" }
  }
}

2. Запустите его:

npx mcp-devdb --config ./mcp-devdb.json

Сервер общается по MCP через stdio; укажите вашему MCP-клиенту эту команду. Строки подключения находятся только в файле конфигурации или переменных окружения ("url": "env:MY_DB_URL", или резервный вариант MCP_DEVDB_URL без файла конфигурации) — модель никогда не может их предоставить.

Claude Code

claude mcp add devdb -- npx mcp-devdb --config /absolute/path/to/mcp-devdb.json

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "devdb": {
      "command": "npx",
      "args": ["mcp-devdb", "--config", "/absolute/path/to/mcp-devdb.json"]
    }
  }
}

Related MCP server: MCP PostgreSQL

Инструменты

database необязателен, когда настроена ровно одна база данных; при нескольких укажите нужную.

Конфигурация

mcp-devdb.json в рабочем каталоге или любой путь через --config:

{
  "databases": {
    "app": {
      "url": "postgres://dev:dev@localhost:5432/app_development",
      "allowTables": ["users", "orders", "public.events_*"],
      "denyTables": ["audit_log"]
    },
    "billing": { "url": "env:BILLING_DEV_DATABASE_URL" }
  },
  "maskPatterns": ["password", "secret", "token", "key", "hash", "ssn", "card"],
  "queryBudget": 100,
  "rowLimit": 200,
  "byteLimit": 262144,
  "statementTimeoutMs": 5000
}

• allowTables / denyTables — названия без учета регистра с подстановочными знаками *; правила, содержащие точку, соответствуют schema.table. Запрет имеет приоритет; непустой список разрешений является исключительным.

• maskPatterns — регулярные выражения без учета регистра, сопоставляемые с именами столбцов.

• Флаги CLI: --config <path>, --no-mask (отключить маскирование столбцов), --help, --version.

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

Полная модель угроз описана в SECURITY.md. Вкратце:

• Шлюз только для чтения: каждый оператор run_query/explain_query токенизируется (кавычки, экранирование E'...', комментарии, строки в долларовых кавычках) и должен начинаться с SELECT / WITH / EXPLAIN / SHOW / VALUES; многооператорный ввод и ключевые слова записи/DDL где-либо на верхнем уровне отклоняются — CTE, за которым следует INSERT, обнаруживается; SELECT 'DROP TABLE x' не является ложным срабатыванием.

• Принудительное применение на уровне движка: файлы SQLite открываются только для чтения; сеансы PostgreSQL работают с default_transaction_read_only=on, явными транзакциями BEGIN READ ONLY и тайм-аутами операторов.

• Маскирование столбцов включено по умолчанию (--no-mask для отказа), ограничения результатов и посессионный бюджет запросов (по умолчанию 100; при исчерпании вам сообщат о необходимости перезапустить сервер).

• Учетные данные никогда не попадают к модели: строки подключения поступают только из локального конфига/окружения и удаляются из каждого сообщения об ошибке.

Смоук-тест

scripts/verify-stdio.mjs создает временную базу данных SQLite, запускает node dist/cli.js и выполняет реальное рукопожатие MCP через stdio с помощью сырого JSON-RPC. Фактический вывод:

$ node scripts/verify-stdio.mjs
initialize -> mcp-devdb 0.1.0 (protocol 2025-06-18)
tools/list -> db_overview, describe_table, explain_query, list_tables, run_query, sample_rows
tools/call list_tables ->
{
  "database": "demo",
  "dialect": "sqlite",
  "tableCount": 2,
  "tables": [
    {
      "schema": null,
      "name": "orders",
      "type": "table",
      "rowEstimate": 3,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    },
    {
      "schema": null,
      "name": "users",
      "type": "table",
      "rowEstimate": 2,
      "sizeBytes": 4096,
      "sizePretty": "4.0 KiB"
    }
  ]
}
tools/call run_query "DROP TABLE users" -> isError=true
  Query rejected by read-only guard: Only read-only statements are allowed; the statement must start with one of: SELECT, WITH, EXPLAIN, SHOW, VALUES
SMOKE TEST PASSED

Ограничения

• MySQL пока нет. Интерфейс DbAdapter в src/adapters/types.ts — точка расширения.

• Только базы данных разработки. Шлюз блокирует запись на уровне SQL, но SELECT все равно может вызывать плохо помеченные функции или функции расширений с побочными эффектами (например, dblink, открывающий собственное соединение не только для чтения). Допустимо для баз данных разработки; никогда не направляйте это на продакшн. См. SECURITY.md.

• Шлюз консервативен: столбцы без кавычек, названные как запрещенные ключевые слова (например, столбец, буквально названный update), отклоняются — заключите их в кавычки ("update"), чтобы продолжить.

• SELECT ... FOR UPDATE отклоняется (он берет блокировки строк).

• Подсчет строк в SQLite использует COUNT(*); на огромных файлах list_tables может работать медленно.

Разработка

npm install
npm run lint && npm run typecheck && npm test && npm run build
node scripts/verify-stdio.mjs

Лицензия

MIT — Copyright (c) 2026 Aminyx