oracle-mcp

Только чтение сервер базы данных Oracle для Model Context Protocol. Он позволяет ИИ-агентам (Claude Desktop, Claude Code, Cursor, VS Code agents, OpenAI Agents, …) безопасно просматривать большие устаревшие схемы Oracle — тысячи таблиц, сотни пакетов, представления, синонимы, триггеры, последовательности и исходный код PL/SQL — ни разу не изменяя данные.

Он спроектирован как автономный модуль, который работает вместе с существующим "Engineering MCP" (GitLab / Redmine / Taiga / ERPNext): один агент, несколько MCP-серверов.

Модель безопасности в одной строке: сервер выполняет только SELECT и чтение словаря данных, каждое имя объекта передается как переменная привязки, произвольный SQL проверяется защитным механизмом только для чтения, а учетной записи базы данных должны быть выданы права только на чтение. Защита в глубину, а не единый шлюз.

Содержание

• Возможности

• Требования

• Установка

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

• Подключение к агенту

• Архитектура

• Справочник инструментов

• Вопросы безопасности

• Примеры

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

• Устранение неполадок

Related MCP server: safe-sql-mcp

Возможности

• 24 целенаправленных инструмента, охватывающих поиск, описание, DDL, исходный код, зависимости, индексы, ограничения, триггеры, синонимы, статистику, недопустимые объекты и защищенное выполнение SELECT.

• Только чтение по построению — SQL-защита, которая отклоняет все, кроме одного, SELECT / WITH … SELECT без комментариев.

• Везде переменные привязки — имена объектов и ключевые слова никогда не вставляются в SQL.

• Ограниченно и безопасно — жесткий предел строк (по умолчанию 1000), тайм-аут на оператор, очистка ResultSet.

• Пул соединений с прозрачным переподключением (толстый режим / Oracle Instant Client).

• Структурированное журналирование в stderr (метка времени, инструмент, затраченное время, строки, схема, SQL) — никогда секреты.

• Типизированная таксономия ошибок — соединение / проверка / недопустимый SQL / права / не найдено / тайм-аут / oracle.

• Строгая типизация (TypeScript strict) и тестирование (48 модульных тестов для защиты и помощников).

Требования

• Node.js ≥ 18

• Oracle Instant Client установлен и доступен в путях поиска библиотек (в этой сборке используется толстый режим oracledb).

  • Windows: папка Instant Client в PATH.

  • Linux/macOS: в LD_LIBRARY_PATH / DYLD_LIBRARY_PATH или установите ORACLE_CLIENT_LIB_DIR.

• Сетевой доступ к базе данных и учетная запись Oracle только для чтения (см. Безопасность).

Установка

git clone <your-repo>/oracle-mcp.git
cd oracle-mcp
npm install
npm run build          # compiles src/ → dist/

Проверка без базы данных:

npm test               # 48 unit tests (SQL guard, identifiers, formatting)

Проверка на реальной базе данных (только чтение):

ORACLE_USER=... ORACLE_PASSWORD=... ORACLE_CONNECT_STRING=host:port/service \
  npx tsx scripts/integration-check.ts

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

Конфигурация задается через переменные окружения. Сервер автоматически загружает файл .env из своего собственного каталога пакета (скопируйте .env.example → .env), поэтому секреты хранятся рядом с сервером и не попадают в конфигурацию агента. Конфигурация проверяется при запуске; сервер быстро завершается с понятным сообщением без секретов, если чего-то не хватает.

Базы данных (одна или несколько)

Сервер может проверять несколько баз данных Oracle одновременно. Каждый инструмент принимает необязательный аргумент database; если он опущен, используется база по умолчанию.

Одна база данных:

ORACLE_USER="readonly_user"
ORACLE_PASSWORD="change_me"
ORACLE_CONNECT_STRING="host:port/service"

Несколько баз данных — перечислите имена, затем укажите переменные для каждого имени с префиксом ORACLE_<ИМЯ>_ (имя в верхнем регистре, неалфавитно-цифровые символы → _):

ORACLE_DATABASES=tcil,sbi_eforex,ybl
ORACLE_DEFAULT_DATABASE=tcil
ORACLE_TCIL_USER="…"        ORACLE_TCIL_PASSWORD="…"        ORACLE_TCIL_CONNECT_STRING="host:port/service"
ORACLE_SBI_EFOREX_USER="…"  ORACLE_SBI_EFOREX_PASSWORD="…"  ORACLE_SBI_EFOREX_CONNECT_STRING="host:port/service"
ORACLE_YBL_USER="…"         ORACLE_YBL_PASSWORD="…"         ORACLE_YBL_CONNECT_STRING="host:port/service"

Пулы создаются лениво для каждой базы данных — настройка десяти ничего не стоит, пока они не запрашиваются. Заключайте пароли в двойные кавычки, чтобы $/# воспринимались буквально.

Совет по строке подключения: для PDB используйте форму имени службы хост:порт/служба. Более старая форма хост:порт:SID не является Easy Connect — преобразуйте ее (…:порт/служба) или используйте псевдоним tnsnames.

Общие настройки

Подключение к агенту

oracle-mcp работает по MCP через stdio. Добавьте его рядом с вашим Engineering MCP.

Claude Desktop / Claude Code (claude_desktop_config.json / .mcp.json) — здесь нет секретов; сервер читает свой собственный .env:

{
  "mcpServers": {
    "engineering": { "command": "node", "args": ["/path/to/mcp-erpnext/src/index.js"] },
    "oracle": {
      "command": "node",
      "args": ["/path/to/oracle-mcp/dist/index.js"],
      "cwd": "/path/to/oracle-mcp"
    }
  }
}

Учетные данные хранятся в oracle-mcp/.env (в gitignore), а не в конфигурации агента. Размещение Oracle на собственном сервере (а не объединение с JS Engineering MCP) изолирует критичную для безопасности поверхность базы данных и позволяет предоставлять/развертывать ее независимо.

Архитектура

                        ┌──────────────────────────────────────────────┐
   AI agent  ──stdio──▶ │  index.ts  (McpServer, StdioServerTransport)  │
   (Claude/Cursor/…)    └───────────────┬──────────────────────────────┘
                                        │ registers 24 tools
                        ┌───────────────▼───────────────┐
                        │  tools/oracle/*                │  runSelect · executionPlan · ddl
                        │  (thin handlers, zod schemas)  │  · 20 declarative metadata tools
                        └───────┬───────────────┬────────┘
              guarded SQL       │               │  built SQL + binds
                    ┌───────────▼──────┐   ┌─────▼─────────────────────┐
                    │ validation/      │   │ oracle/client.ts          │
                    │ sqlGuard.ts      │   │  • timeout (callTimeout)  │
                    │ (fail-closed)    │   │  • row cap + truncation   │
                    └──────────────────┘   │  • ResultSet cleanup      │
                                           │  • error → taxonomy       │
                                           └─────┬─────────────────────┘
                                                 │ pooled connection
                                           ┌─────▼───────────────┐
                                           │ oracle/pool.ts       │  thick init · pool · reconnect
                                           └─────┬───────────────┘
                                                 ▼
                                        Oracle DB  (ALL_* dictionary + DBMS_METADATA/DBMS_XPLAN)

  cross-cutting:  config/env.ts (zod-validated)   logging/logger.ts (stderr, redacted)
                  errors.ts (typed taxonomy)       utils/ (identifiers, formatting)

Структура папок

oracle-mcp/
├── src/
│   ├── index.ts               # server bootstrap + graceful shutdown
│   ├── config/env.ts          # env loading & validation (zod)
│   ├── logging/logger.ts      # structured stderr logger (+ SQL redaction)
│   ├── errors.ts              # OracleMcpError + Oracle→taxonomy mapping
│   ├── types/index.ts         # shared types
│   ├── validation/sqlGuard.ts # read-only SQL guard  ◀── security core
│   ├── utils/
│   │   ├── identifiers.ts      # name validation, LIKE-pattern escaping
│   │   └── format.ts           # Markdown tables / code blocks
│   ├── oracle/
│   │   ├── pool.ts             # thick init, pool lifecycle, reconnect
│   │   └── client.ts           # the single query choke-point
│   └── tools/oracle/
│       ├── context.ts          # tool type + registration wrapper
│       ├── runSelect.ts        # oracle_run_select (guarded)
│       ├── executionPlan.ts    # oracle_show_execution_plan
│       ├── ddl.ts              # oracle_get_object_ddl / oracle_get_view
│       ├── metadataTools.ts    # 20 declarative dictionary tools
│       └── index.ts            # catalogue + registerOracleTools()
├── tests/                     # vitest unit tests
├── scripts/integration-check.ts
└── .env.example

Почему такой выбор

• Автономный пакет TypeScript, а не часть JS Engineering MCP — изолирует чувствительную к безопасности поверхность, позволяет использовать строго типизированную сборку и независимое развертывание/права.

• Толстый режим — выбран для этого развертывания (присутствует Instant Client); обеспечивает максимально широкий набор функций драйвера. Тонкий режим позволил бы убрать зависимость от клиента, если это необходимо.

• Декларативные инструменты метаданных — 20 инструментов словаря используют одну безопасную форму (фиксированный SQL + привязки + формат), поэтому добавление инструмента занимает несколько строк, а свойства безопасности единообразны.

• Единая точка входа OracleClient — каждый запрос проходит через нее, поэтому тайм-аут, лимит строк, очистка, сопоставление ошибок и журналирование выполняются ровно в одном месте.

Справочник инструментов

Все инструменты имеют префикс oracle_. Инструменты, ограниченные владельцем, принимают необязательный schema; поисковые инструменты принимают необязательный limit (ограничен ORACLE_MAX_ROWS). Имена могут быть указаны как OBJECT или SCHEMA.OBJECT.

Как общие вопросы сопоставляются с инструментами

Вопросы безопасности

Уровни защиты (эшелонированная оборона):

1. Учётная запись только для чтения (основная стена). Предоставьте пользователю подключения только CREATE SESSION + SELECT на объектах (или ролях), которые он должен просматривать, а также SELECT_CATALOG_ROLE для словаря данных. MCP должен быть неспособен выполнять запись независимо от любых ошибок выше по стеку.

2. SQL-защита (validation/sqlGuard.ts) для единственного свободного инструмента (oracle_run_select) — она отказывает по умолчанию и отклоняет:

   • всё, что не является одиночным SELECT / WITH … SELECT;

   • INSERT/UPDATE/DELETE/MERGE/…, все DDL, GRANT/REVOKE, COMMIT/ROLLBACK;

   • PL/SQL-блоки (BEGIN/DECLARE), CALL, EXECUTE [IMMEDIATE], SELECT … INTO, FOR UPDATE;

   • опасные пакеты (DBMS_SQL, DBMS_SCHEDULER, DBMS_JOB, UTL_FILE, UTL_HTTP, …);

   • точки с запятой / множественные инструкции и все комментарии/подсказки (hints) (классический вектор обхода);

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

3. Переменные связывания (bind variables) для каждого имени объекта / ключевого слова в 23 инструментах работы с метаданными — пользовательский ввод является значением, а никогда не текстом SQL. Идентификаторы дополнительно проверяются на соответствие строгому набору символов.

4. Ограничения — жёсткий лимит строк (ORACLE_MAX_ROWS), callTimeout на инструкцию, очистка ResultSet.

5. Никакой утечки секретов — пароли никогда не логируются; логи идут только в stderr (stdout является каналом MCP); SQL в логах усекается по длине.

Примечания

• oracle_show_execution_plan выполняет EXPLAIN PLAN, который записывает данные в сессионную глобальную временную таблицу PLAN_TABLE. Это временные служебные метаданные, автоматически отбрасываемые и доступные даже учётным записям только для чтения — никакие производственные данные не читаются и не записываются.

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

Примеры

Agent: "Describe mfx_entity_master."
 → oracle_describe_table { table_name: "MFX_ENTITY_MASTER" }

Agent: "Find every procedure that references mfx_transaction."
 → oracle_search_source { keyword: "mfx_transaction", object_type: "PACKAGE BODY" }

Agent: "Show the body of MFX_GET_MARGIN."
 → oracle_get_package_body { package_name: "MFX_GET_MARGIN" }

Agent: "What foreign keys does mfx_transaction have?"
 → oracle_get_constraints { table_name: "MFX_TRANSACTION" }

Agent: "Explain: SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7"
 → oracle_show_execution_plan { sql: "SELECT * FROM mfx_transaction WHERE trans_date > SYSDATE - 7" }

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

npm test            # unit: SQL guard (accept/reject matrix), identifiers, LIKE escaping
npm run typecheck   # tsc --noEmit
npx tsx scripts/integration-check.ts   # live smoke test (needs a DB; read-only)

Модульные тесты намеренно сосредоточены на защитном механизме (security guard) — на наборе принимаемых конструкций (SELECT/CTE, литералы, содержащие запрещённые слова, экранированные кавычки, идентификаторы, похожие на ключевые слова) и наборе отклоняемых (DML/DDL, точки с запятой, комментарии/подсказки, PL/SQL, опасные пакеты, q'…', превышение размера, нестроковые значения).

Устранение неполадок

Лицензия

MIT.