mcp-odbc

Введение

В этом документе описывается настройка и использование универсального сервера ODBC для Model Context Protocol (MCP), называемого сервером mcp-odbc . Он был разработан для предоставления Большим языковым моделям прозрачного доступа к доступным ODBC источникам данных через Имя источника данных, настроенное для определенного ODBC-коннектора (также называемого драйвером ODBC).

Реализация сервера

Этот MCP Server для ODBC представляет собой небольшой слой TypeScript, построенный поверх node-odbc . Он направляет вызовы локальному диспетчеру драйверов ODBC хост-системы через node.js (в частности, используя npx для TypeScript).

Настройка и предварительные условия операционной среды

Хотя примеры, которые следуют ниже, ориентированы на Virtuoso ODBC Connector, это руководство также будет работать с другими ODBC Connector. Мы настоятельно рекомендуем вносить вклад в код и отправлять демонстрационные примеры использования, связанные с другими системами управления базами данных (СУБД), для включения в этот проект.

Ключевые компоненты системы

1. Проверьте версию node.js Если она не ниже 21.1.0 , обновите или установите явно с помощью:
   nvm install v21.1.0
2. Установите компоненты MCP с помощью:
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv
3. Установите версию nvm с помощью:
   nvm alias default 21.1.0

Установка

1. Бегать
   git clone https://github.com/OpenLinkSoftware/mcp-odbc-server.git
2. Изменить каталог
   cd mcp-odbc-server
3. Бегать
   npm init -y
4. Бегать
   npm install @modelcontextprotocol/sdk zod tsx odbc dotenv

Проверки среды выполнения unixODBC

1. Проверьте конфигурацию установки (т. е. расположение ключевых INI-файлов), выполнив:
   odbcinst -j
2. Выведите список доступных имен источников данных (DSN), выполнив команду:
   odbcinst -q -s

Переменные среды

В целях безопасности следует использовать файл .env , расположенный в том же каталоге, что и mcp-ser для установки привязок для имени источника данных ODBC ( ODBC_DSN ), пользователя ( ODBC_USER ), пароля ( ODBC_PWD ), ODBC INI ( ODBCINI ) и, если вы хотите использовать OpenLink AI Layer (OPAL) через ODBC, целевого API-ключа большой языковой модели (LLM) ( API_KEY ).

Использование

Инструменты

После успешной установки клиентским приложениям MCP будут доступны следующие инструменты.

Обзор

Подробное описание

• get_schemas
  • Извлечь и вернуть список всех имен схем из подключенной базы данных.
  • Входные параметры:
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает массив строк JSON с именами схем.
• get_tables
  • Извлечь и вернуть список, содержащий информацию о таблицах в указанной схеме. Если схема не указана, используется схема соединения по умолчанию.
  • Входные параметры:
    • schema (строка, необязательно): Схема базы данных для фильтрации таблиц. По умолчанию используется соединение по умолчанию.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает строку JSON, содержащую информацию о таблице (например, TABLE_CAT , TABLE_SCHEM , TABLE_NAME , TABLE_TYPE ).
• filter_table_names
  • Фильтрует и возвращает информацию о таблицах, имена которых содержат определенную подстроку.
  • Входные параметры:
    • q (строка, обязательно): подстрока для поиска в именах таблиц.
    • schema (строка, необязательно): Схема базы данных для фильтрации таблиц. По умолчанию используется соединение по умолчанию.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает строку JSON, содержащую информацию для сопоставления таблиц.
• describe_table
  • Извлечение и возврат подробной информации о столбцах определенной таблицы.
  • Входные параметры:
    • schema (строка, обязательно): имя схемы базы данных, содержащей таблицу.
    • table (строка, обязательно): Имя таблицы, которую нужно описать.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает строку JSON, описывающую столбцы таблицы (например, COLUMN_NAME , TYPE_NAME , COLUMN_SIZE , IS_NULLABLE ).
• query_database
  • Выполнить стандартный SQL-запрос и вернуть результаты в формате JSON.
  • Входные параметры:
    • query (строка, обязательно): Строка SQL-запроса для выполнения.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результаты запроса в виде строки JSON.
• query_database_md
  • Выполнить стандартный SQL-запрос и вернуть результаты, отформатированные в виде таблицы Markdown.
  • Входные параметры:
    • query (строка, обязательно): Строка SQL-запроса для выполнения.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результаты запроса в виде строки таблицы Markdown.
• query_database_jsonl
  • Выполнить стандартный SQL-запрос и вернуть результаты в формате строк JSON (JSONL) (один объект JSON на строку).
  • Входные параметры:
    • query (строка, обязательно): Строка SQL-запроса для выполнения.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результаты запроса в виде строки JSONL.
• spasql_query
  • Выполнить запрос SPASQL (гибрид SQL/SPARQL) и получить результаты. Это специфическая функция Virtuoso.
  • Входные параметры:
    • query (строка, обязательно): строка запроса SPASQL.
    • max_rows (число, необязательно): Максимальное количество возвращаемых строк. По умолчанию 20 .
    • timeout (число, необязательно): Время ожидания запроса в миллисекундах. По умолчанию 30000 , т.е. 30 секунд.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результат вызова базовой хранимой процедуры (например, Demo.demo.execute_spasql_query ).
• sparql_query
  • Выполнить запрос SPARQL и вернуть результаты. Это специфическая функция Virtuoso.
  • Входные параметры:
    • query (строка, обязательно): строка запроса SPARQL.
    • format (string, необязательно): Желаемый формат результата. По умолчанию 'json' .
    • timeout (число, необязательно): Время ожидания запроса в миллисекундах. По умолчанию 30000 , т.е. 30 секунд.
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результат вызова базовой функции (например, "UB".dba."sparqlQuery" ).
• virtuoso_support_ai
  • Использует функцию AI Assistant, специфичную для Virtuoso, передавая подсказку и необязательный ключ API. Это специфичная для Virtuoso функция.
  • Входные параметры:
    • prompt (строка, обязательно): текст подсказки для функции ИИ.
    • api_key (string, необязательно): API-ключ для службы AI. По умолчанию "none" .
    • user (строка, необязательно): Имя пользователя базы данных. По умолчанию "demo" .
    • password (строка, необязательно): Пароль базы данных. По умолчанию "demo" .
    • dsn (строка, необязательно): Имя источника данных ODBC. По умолчанию "Local Virtuoso" .
  • Возвращает результат вызова функции AI Support Assistant (например, DEMO.DBA.OAI_VIRTUOSO_SUPPORT_AI ).

Базовое тестирование установки и устранение неполадок

Инструмент инспектора MCP

Canonical MCP Inspector Tool Edition

1. Запустите инспектор из каталога/папки mcp-server с помощью следующей команды:
   ODBCINI=/Library/ODBC/odbc.ini npx -y @modelcontextprotocol/inspector npx tsx ./src/main.ts
2. Нажмите кнопку «Подключиться», затем нажмите вкладку «Инструменты», чтобы начать работу.

Издание инструмента OpenLink MCP Inspector

Это ответвление канонической версии, включающее исправление ошибки обработки JSON, связанной с использованием этого сервера MCP.

1. бегать
   git clone git@github.com:OpenLinkSoftware/inspector.git cd inspector
2. бегать
   npm run start
3. Введите следующее значение в поле ввода Arguments пользовательского интерфейса MCP Inspectors с http://localhost:6274
   tsx /path/to/mcp-odbc-server/src/main.ts
4. Нажмите кнопку Connect , чтобы инициализировать сеанс с назначенным сервером MCP.

Совместимость Apple Silicon (ARM64) с проблемами сервера MCP ODBC

Проблема конфликта узлов x86_64 и arm64

Возможно, используется версия node x86_64, а не arm64, но мост ODBC и сервер MCP являются компонентами на базе arm64.

Эту проблему можно решить, выполнив следующие действия:

1. Удалите версию node x86_64, выполнив:
   nvm uninstall 21.1.0
2. Выполните следующую команду, чтобы убедиться, что ваша текущая оболочка находится в режиме arm64:
   arch
   • если возвращается x86_64, выполните следующую команду, чтобы изменить активный режим:
     arch arm64
3. Установите версию arm64 node , выполнив:
   nvm install 21.1.0

Несовместимость уровня моста узла с ODBC

При попытке использовать Model Context Protocol (MCP) ODBC Server на машинах Apple Silicon вы можете столкнуться с ошибками несоответствия архитектуры. Они возникают из-за того, что собственный модуль Node.js ODBC ( odbc.node ) скомпилирован для архитектуры ARM64, но загружается версия среды выполнения unixODBC на базе x86_64.

Типичное сообщение об ошибке:

Эту проблему можно решить, выполнив следующие шаги:

1. Убедитесь, что ваш Node.js работает в режиме ARM64:
   node -p "process.arch" # Should output: `arm64`
2. Установите unixODBC для ARM64:
   # Verify Homebrew is running in ARM64 mode which brew # Should point to /opt/homebrew/bin/brew # Remove existing unixODBC brew uninstall --force unixodbc # Install ARM64 version arch -arm64 brew install unixodbc
3. Пересоберите модуль Node.js ODBC для ARM64:
   # Navigate to your project cd /path/to/mcp-odbc-server # Remove existing module rm -rf node_modules/odbc # Set architecture environment variable export npm_config_arch=arm64 # Reinstall with force build npm install odbc --build-from-source
4. Убедитесь, что модуль теперь ARM64:
   file node_modules/odbc/lib/bindings/napi-v8/odbc.node # Should show "arm64" instead of "x86_64"

Ключевые моменты

• И unixODBC, и модуль Node.js ODBC должны быть совместимы с ARM64.
• Использование переменных окружения ( export npm_config_arch=arm64 ) более надежно, чем команды npm config.
• Всегда проверяйте архитектуру с помощью команды file или node -p "process.arch"
• При использовании Homebrew на Apple Silicon команды можно префиксировать с помощью arch -arm64 чтобы принудительно использовать двоичные файлы ARM64.

Использование приложения MCP

Конфигурация рабочего стола Клода

Путь к этому файлу конфигурации: ~{username}/Library/Application Support/Claude/claude_desktop_config.json .

Использование рабочего стола Клода

1. Запустите приложение.
2. Примените конфигурацию (см. выше) через Настройки | Интерфейс разработчика.
3. Убедитесь, что у вас есть работающее ODBC-соединение с именем источника данных (DSN).
4. Представить приглашение на выполнение запроса, например,
   Execute the following query: SELECT TOP * from Demo..Customers

Конфигурация Cline (расширение Visual Studio)

Путь к этому файлу конфигурации: ~{username}/Library/Application\ Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Использование Cline (расширение Visual Studio)

1. Используйте Shift+Command+P, чтобы открыть палитру команд.
2. Введите: Cline .
3. Выберите: Cline View, чтобы открыть пользовательский интерфейс Cline на боковой панели VSCode.
4. Используйте значок с четырьмя квадратами для доступа к пользовательскому интерфейсу для установки и настройки серверов MCP.
5. Примените конфигурацию Клайна (см. выше).
6. Вернитесь в основной пользовательский интерфейс расширения и запустите новую задачу, запросив обработку следующего запроса:
   "Execute the following query: SELECT TOP 5 * from Demo..Customers"

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

Используйте шестеренку настроек, чтобы открыть меню конфигурации, которое включает пункт меню MCP для регистрации и настройки mcp servers .

Использование курсора

1. Используйте комбинацию клавиш Command + I или Control + I , чтобы открыть интерфейс чата.
2. Выберите Agent в раскрывающемся списке в левом нижнем углу пользовательского интерфейса, где по умолчанию установлено Ask .
3. Введите приглашение, определяющее использование mcp-server for odbc используя шаблон: @odbc {rest-of-prompt} .
4. Нажмите «Принять», чтобы выполнить запрос.

Связанный

• Скринкаст использования MCP Inspector
• Скринкаст по использованию базового Claude Desktop
• Скринкаст по использованию базового расширения Cline Visual Studio Code
• Скринкаст по использованию базового редактора курсоров