Введение

В этом документе описывается настройка и использование универсального сервера 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

• Скринкаст по использованию базового редактора курсоров