Copyright (c) 2025, Software Tree

ORMCP Server - Beta

Сервер Model Context Protocol (MCP) для подключения ваших AI-приложений к реляционным базам данных

ORMCP Server позволяет AI-LLM и MCP-клиентам легко обмениваться объектно-ориентированными данными (в формате JSON) с любой реляционной базой данных, используя стандартный протокол MCP.

ORMCP Server делает ваши реляционные данные готовыми к работе с AI.

⚠️ Уведомление о бета-версии

ORMCP Server в настоящее время находится в статусе Beta, и мы предоставляем ранний доступ пользователям, которые хотят проверить программное обеспечение, оставить отзыв и помочь нам гарантировать, что продукт соответствует самым высоким стандартам качества. Эта бета-версия не предназначена для коммерческого использования и предоставляется только для целей тестирования.

Related MCP server: io.github.ralfbecher/orionbelt-analytics

📋 Содержание

• Что такое MCP?

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

• Как это работает

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

• Руководства для конкретных платформ — 🍎 macOS · 🪟 Windows · 🐧 Linux

• Установка

• Настройка микросервиса Gilhari

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

• Запуск сервера

• Конфигурация MCP-клиента

• Примеры использования

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

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

• Разработка

• Участие в разработке

• Лицензия

• Поддержка и ресурсы

Что такое MCP?

Model Context Protocol (MCP) — это открытый стандарт, который обеспечивает унифицированный способ взаимодействия AI-моделей с внешними инструментами и источниками данных. Он стандартизирует обмен данными и упрощает интеграцию LLM в сложные рабочие процессы без создания собственных API-интеграций под каждый вариант использования.

Подробнее на Официальном сайте MCP.

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

• ✅ Стандартизированный интерфейс: Полное соответствие спецификации Model Context Protocol (MCP)

• 🌐 Агностичность к баз данных: Работает с любой базой данных, поддерживающей JDBC (например, PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)

• ↔️ Двунаправленный поток данных: Плавная связь между AI и базой данных с возможностью работы только в режиме READONLY

• 🔄 Объектно-реляционное отображение (ORM): Операции с JSON-объектами (CRUD) прозорно и корректно отображаются на реляционные данные

• 🔒 Безопасный доступ к данным: Операции, специфичные для доменной модели, способствуют защите данных

• 🧾 Декларативная ORM-спецификация: Интуитивная, ненавязчивая и гибкая спецификация ORM, основанная на простой грамматике

• 🕸️ Поддержка сложного моделирования объектов: Включая отношения «один к одному», «один ко многим» и «многие ко многим», а также путь-выражения

• 🖇️ Гибкие запросы: Глубокие и поверхностные запросы, различного рода операционные директивы, аналогичные возможностям GraphQL, для уточнения формы и объёма возвращаемых объектов

• 🚀 Высокооптимизированный и легковесный движок отображения: Пул соединений, подготовленные выражения (Prepared Statements), оптимизированные SQL-запросы, минимальное количество обращений к базе данных, кэширование метаданных

• 🔌 Совместимость с существующими данными и базами данных: Работает с существующими схемами и данными в любой SQLatabase общей базы; не требует идиативного типа данных JSON

• 📚 Подробная документация: Детальное руководство пользователя, файлы README, документация по API, примеров приложений

• ☁️ Без привязки к облачному провайдеру: Развертывание в любом месте благодаря поддержке Docker

• ⚡ Высокая производительность: Построен на архитектуре микросервисов Gilhari и оптимизированном ORM-движке

• 🛡️ Надёжная обработка ошибок: Чёткие сообщения об ошибках и механизмы восстановления

• 📈 Масштабируемость: Эффективное выполнение множества параллельных запросов; масштабируемое развертывание с помощью Docker

Как это работает

+---------------------+         +----------------------+         +-------------------------+
| AI App / LLM Client | <--->   |     ORMCP Server     | <--->   |   Relational Database   |
| (MCP-compliant tool)|         |    (MCP + Gilhari)   |         | (Postgres, MySQL, etc.) |
+---------------------+         +----------------------+         +-------------------------+
         |                                |                                 |
         |  JSON (via MCP Tools)          |                                 |
         |------------------------------->|                                 |
         |                                |   ORM + JDBC                    |
         |                                |-------------------------------->|
         |                                |                                 |
         |     JSON result (MCP format)   |                                 |
         |<-------------------------------|                                 |

Важно: AI-приложение (LLM-клиент) преобразует естественный язык в вызовы MCP-инструментов. Затем ORMCP Server преобразует эти вызовы MCP в вызовы REST API к библетной базе данных.

ORMCP Server выполняет роль моста между современными AI-приложениями и реляционными базами данных через:

• Протокол MCP: Стандартизированная связь между AI и инструментами

• Gilhari: Слой компьютерной интеграции с реляционными базами данных через ORM и JDBC

• JSON-отображение: Прозрачное объектно-реляционное отображение

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

Новичок в ORMCP? Переходите прямо к руководству, которое подходит под вашу платформу, чтобы быстро настроить работу: 🍎 macOS · 🪟 Windows · 🐧 Linux

Разделы ниже охватывают все платформы вместе, как полный справочник.

Три простых шага для использования ORMCP

1. Очертите область ваших данных

• Определите лёгкие объектные модели для конкретных данных

• Напишите декларативную ORM-спецификацию для этих моделей в текстовом файле, используя простую грамматику (JDX)

2. Создайте собственный микросервис на базе Gilhari

• Добавьте модели, ORM-спецификацию и JDBC-драйвер в файл Dockerfile

• Соберите Docker-образ Gilhari

3. Запустите с помощью ORMCP

• Подключите ORMCP к микросервису Gilhari

• Запустите микросервис Gilhari, затем ORMCP

• Взаимодействуйте с выбранными реляционными данными интуитивно-объектно-ориентированным способом с помощью AI-агента или MCP-клиента

Подробный быстрый старт

Предварительные требования

• Python 3.12+

• Docker (для микросервиса Gilhari)

• JDBC-драйвер для вашей целевой базы данных

1. Установите ORMCP Server

Руководство для вашей платформы с пошаговыми инструкциями по установке: macOS · Windows · Linux

ORMCP Server доступен на публичном PyPI. Для его установки не нужны аккаунт, токен или запрос на бета-доступ:

pip install ormcp-server

# Verify installation
pip show ormcp-server

📌 Пользователи Linux/Mac: Современные дистрибутивы Linux и macOS могут требовать наличия виртуального окружения. Если вы получаете ошибки "externally-managed-environment", смотрите руководство по вашей платформе или руководство по устранению неполадок.

# Create virtual environment (recommended on Linux/Mac)
python3 -m venv .venv

# Activate — Linux/Mac:
source .venv/bin/activate
# Activate — Windows (Command Prompt):
.venv\Scripts\activate
# Activate — Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install
pip install ormcp-server

Если у вас есть существующий токен Gemfury из более ранней бета-установки, он больше не будет работать — доступ через Gemfury прекращён. Используйте pip install ormcp-server, который будет брать загрузку напрямую с публичного PyPI.

Если команда ormcp-server не найдена после установки:

Добавьте каталог с исполняемыми файлами Python в PATH. Подробности смотрите в вашем руководстве по платформе: macOS · Windows · Linux

2. Настройка микросервиса Gilhari

Подробную инструкцию настройки смотрите в разделе Настройка микросервиса Gilhari ниже.

Примечание: Полный рабочий пример доступен в отдельном репозитории: gilhari_example1

Для запуска примера:

ВАЖНО: Для сборки и запуска микросервиса Gilhari требуется Docker — Get Docker (Получить Docker), если он ещё не установлен на вашем компьютере

# Clone the example repository of a sample Gilhari microservice that deals with User type of objects
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Pull Gilhari Docker image
docker pull softwaretree/gilhari:latest

# Build a Docker image for the sample Gilhari microservice
./build.cmd  # On Windows
# or
./build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
./curlCommandsPopulate.cmd  # On Windows
# or
./curlCommandsPopulate.sh   # On Linux/Mac

3. Настройте переменные окружения

# Linux/Mac
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"

# Windows (Command Prompt)
set GILHARI_BASE_URL=http://localhost:80/gilhari/v1/
set MCP_SERVER_NAME=MyORMCPServer

# Windows (PowerShell)
$env:GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
$env:MCP_SERVER_NAME="MyORMCPServer"

4. Запустите ORMCP Server

ormcp-server

Если вы получаете ошибки "command not found", см., смотрите руководство для вашей платформы: macOS · Windows · Linux

# Or use Python directly (works on all platforms)
python -m ormcp_server

5. Подключите ваш AI-клиент

Для Claude Desktop добавьте в claude_desktop_config.json:

Вариант 1: Использование имени команды (requires PATH configured):

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Вариант 2: Использование полного пути (рекомендуется для Windows):

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "C:\\Users\\<YourUsername>\\AppData\\Roaming\\Python\\Python313\\Scripts\\ormcp-server.exe",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Чтобы найти ваш точный путь:

# Windows (PowerShell)
(Get-Command ormcp-server).Source

# Or use pip
pip show -f ormcp-server | findstr "Location"

# Linux/Mac
which ormcp-server

Готово! Ваш AI-клиент теперь может взаимодействовать с вашей базой данных, принимая естественный язык.

Примечание: Шаги 3 (Настройка переменных окружения) и 4 (Запуск ORMCP Server) не обязательны, если вы используете Claude Desktop в качестве клиента, потому что Claude Desktop автоматически запускает настроенный ORMCP-сервер в режиме STDIO.

Примеры использования

Запрос данных

AI-запрос: «Покажи мне всех пользователей с возрастом больше или равным 55»

Сгенерированный вызов MCP:

{
  "name": "query",
  "arguments": {
    "className": "User",
    "filter": "age >= 55",
    "maxObjects": -1,
    "deep": true
  }
}

Результат:

[
  {"id": 55, "name": "Mary55", "city": "Campbell", "state": "CA"},
  {"id": 56, "name": "Mike56", "city": "Boston", "state": "MA"}
]

Вставка данных

AI-запрос: «Добавь нового пользователя (id = 65) Джона Смита из Бостона, штат Массачусетс, с возрастом 65»

Сгенерированный вызов MCP:

{
  "name": "insert",
  "arguments": {
    "className": "User",
    "jsonObjects": [
      {
        "id": 65,
        "name": "John Smith",
        "city": "Boston",
        "state": "MA",
        "age": 65
      }
    ]
  }
}

Агрегация данных

AI-запрос: «Какой средний возраст пользователей в Калифорнии?»

Сгенерированный вызов MCP:

{
  "name": "getAggregate",
  "arguments": {
    "className": "User",
    "attributeName": "age",
    "aggregateType": "AVG",
    "filter": "state='CA'"
  }
}

Результат:

49

Настройка микросервиса Gilhari

ORMCP Server зависит от Gilhari — микросервисного фреймворка для интеграции JSON-данных с базами данных. Эту настройку необходимо завершить перед началом использования ORMCP-сервера.

IMPORTANT: Docker необходим для сборки и запуска микросервиса Gilhari — Get Docker if not already installed...

Установка Gilhari Software

1. Получите Docker-образ Gilhari:

   docker pull softwaretree/gilhari:latest

2. Установите SDK Gilhari:

   • Набор SDK для Gilhari software поставляется в пакете ORMCP server в папке Gilhari_SDK

   • Альтернативно, скачайте с: https://www.softwaretree.com/v1/products/gilhari/download-gilhari.php

   • SDK включает документацию (README, API Guides, Sample Apps) для облегчения работы с Gilhari software

Настройка собственного микросервиса Gilhari под ваше приложение

Выполните следующие шаги (подробно в документации SDK Gilhari):

1. Определите классы доменных моделей — Java-классы контейнера для ваших JSON-объектов

2. Создайте декларативную ORM-спецификацию — сопоставьте атрибуты JSON со схемой базы данных

3. Соберите Docker-образ микросервиса Gilhari под ваше приложение — включите доменные классы, ORM-спецификацию и JDBC-драйвер

4. **Запустите микросерви:

   docker run -p 80:8081 your-gilhari-service:1.0

Примечание: Полный рабочий пример доступен в отдельном репозитории: gilhari_example1. Этот пример демонстрирует микросервис Gilhari который управляет объектами User.

Быстрый старт с примером:

# Clone the example repository
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Build a Docker image for the sample Gilhari microservice
./build.cmd  # On Windows
# or
./build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
./curlCommandsPopulate.cmd  # On Windows
# or
./curlCommandsPopulate.sh   # On Linux/Mac

Подробная установка и настройка инструкции: README.repo com.

Установка пакета ORMCP

Рекомендуется: Виртуальное окружение

# Create and activate virtual environment
python -m venv .venv

# Activate the environment
# Linux/Mac:
source .venv/bin/activate
# Windows (Command Prompt):
.venv\Scripts\activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# Install ORMCP Server from public PyPI — no token needed
pip install ormcp-server

Глобальная установка

pip install ormcp-server

Примечание: При глобальной установке (без виртуального окружения) исполняемый файл ormcp-server будет установлен в каталог Python Scripts вашего пользователя. Смотрите руководство по вашей платформе, если вы встречаете ошибки "command not found".

Доступ к полному пакету с SDK и примерами

Чтобы получить доступ к полному пакету, включая Gilhari SDK, примеры и документацию:

# Download source distribution
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number)
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Now you have access to:
# - Gilhari_SDK/          (Complete SDK with documentation)
# - gilhari_example1/     (Ready-to-use example microservice)
# - package/client/       (Example client code)
# - package/docs/         (Additional documentation)

Пользователям Windows: Если у вас не установлен tar, вы можете:

• Использовать 7-Zip or WinRAR для извлечения .tar.gz файла

• Или использовать PowerShell: tar -xzf ormcp_server-*.tar.gz

• Или скачать напрямую со страницы проекта PyPI

Содержимое пакета

Пакет ORMCP Server включает дополнительные ресурсы в дополнение к коду Python:

Стандартная установка (Wheel)

При установке через pip вы получаете основной пакет Python, необходимый для запуска ORMCP Server:

pip install ormcp-server

Устанавливаются только основные файлы, которые необходимы для работы времени выполнения в ваше окружение Python.

Полный пакет с SDK и документацией (Source Distribution)

Полный пакет включает:

• Gilhari_SDK/ — Полный SDK с документацией, примерами и инструментами для создания собственных микросервисов Gilhari

• gilhari_example1/ — Готовый к использованию пример микросервиса Gilhari

• package/client/ — Пример кода клиента и документация по использованию

• package/docs/ — Дополнительная техническая документация

• pyproject.toml — Конфигурация сборки

• README.md — Этот файл

• LICENSE — Условия лицензии

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

Вариант 1: Загрузка с PyPI

# Download the source distribution (.tar.gz)
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number; e.g., 0.6.x)
tar -xzf ormcp_server-0.6.x.tar.gz
cd ormcp_server-0.6.x

# Now you have access to:
# - Gilhari_SDK/
# - gilhari_example1/
# - package/client/
# - package/docs/

Пользователям Windows: Если у вас нет tar, вы можете:

• Use 7-Zip or WinRAR to extract soare the .tar.gz file

• Or use PowerShell: tar -xzf ormcp_server-0.6.x.tar.gz

• Or download directly from the PyPI project page

Вариант 2: Загрузка со страницы пакета

Посетите https://pypi.org/project/ormcp-server/ и загрузите файл .tar.gz.

Найдите раздел «Download files» и загрузите дистрибутив исходного кода (.tar.gz).

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

После извлечения дистрибутива исходного кода:

# Navigate to the SDK
cd Gilhari_SDK

# Read the documentation
# - Check README files for setup instructions
# - Review examples in the examples/ directory
# - See API documentation for ORM specification details

# The SDK includes:
# - Gilhari Docker base image information
# - Documentation (READMEs, API guides)
# - Sample applications
# - Tools for reverse-engineering ORM from existing databases
# - JDX grammar specification

Запуск примера микросервиса Gilhari

# Navigate to the example
cd gilhari_example1

# Follow the README.md in that directory to:
# 1. Build the Docker image
# 2. Run the microservice
# 3. Populate sample data
# 4. Test with ORMCP Server

Почему два формата пакетов?

• Wheel (.whl) — бинарный дистрибутив, быстро устанавливается, содержит только код времени выполнения (~50 КБ)

• Дистрибутив исходного кода (.tar.gz) — полный пакет со всеми ресурсами (~несколько МБ)

Большинству пользователей для запуска ORMCP Server нужен только wheel. Загрузите дистрибутив исходного кода, если вам нужны:

• Gilhari SDK для создания пользовательских микросервисов

• Примеры приложений и клиентского кода

• Полная документация

• Дополнительные технические руководства

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

Настройка через переменные окружения:

Примечания:

• Если для READONLY_MODE задано значение True, инструменты MCP, которые могут изменять данные (например, insert, update, update2, delete, delete2), не предоставляются сервером ORMCP клиенту MCP. По умолчанию предоставляются все инструменты MCP.

• GILHARI_BASE_URL и GILHARI_NAME используются для проверки уже запущенного контейнера микросервиса Gilhari

• GILHARI_IMAGE, GILHARI_NAME и GILHARI_PORT используются для запуска нового экземпляра микросервиса Gilhari, если существующий микросервис не найден. Убедитесь, что значения переменных GILHARI_HOST и GILHARI_PORT соответствуют соответствующим значениям в настройке GILHARI_BASE_URL, поскольку именно там сервер ORMCP будет связываться с микросервисом Gilhari.

Пример конфигурации

# Linux/Mac
export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export GILHARI_TIMEOUT="30"
export MCP_SERVER_NAME="MyORMCPServer"
export LOG_LEVEL="INFO"

# Windows (Command Prompt)
set GILHARI_BASE_URL=http://localhost:80/gilhari/v1/
set GILHARI_TIMEOUT=30
set MCP_SERVER_NAME=MyORMCPServer
set LOG_LEVEL=INFO

# Windows (PowerShell)
$env:GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
$env:GILHARI_TIMEOUT="30"
$env:MCP_SERVER_NAME="MyORMCPServer"
$env:LOG_LEVEL="INFO"

Запуск сервера

Стандартный режим (рекомендуется)

Активируйте виртуальное окружение (если используете):

# Linux/Mac
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Запустите сервер с помощью команды CLI:

ormcp-server

Это запускает сервер MCP в режиме stdio через точку входа main.py.

Устранение неполадок — команда не найдена:

Если вы получаете сообщение 'ormcp-server' is not recognized или command not found, обратитесь к руководству для вашей платформы для настройки PATH и вариантов исправления: macOS · Windows · Linux

# Use Python directly on any platform (always works)
python -m ormcp_server

Использование исходного кода напрямую (для продвинутых пользователей)

Примечание: требуется дистрибутив исходного кода. Загрузите с помощью:

pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Запустите сервер напрямую с помощью Python:

python src/ormcp_server.py

Это обходит обёртку CLI и запускает сервер напрямую.

Альтернативные методы (для продвинутых пользователей)

Прямое выполнение исполняемого файла:

# Windows
.venv\Scripts\ormcp-server.exe

# Linux/Mac
.venv/bin/ormcp-server

Использование CLI fastmcp (требуется дистрибутив исходного кода):

fastmcp run src/ormcp_server.py

Использование режима разработки MCP Inspector (требуется дистрибутив исходного кода):

mcp dev src/ormcp_server.py

Использование MCP Inspector без исходного кода:

Если у вас установлен пакет ormcp-server, вы можете использовать MCP Inspector для изучения возможностей сервера:

# Using the installed package
npx @modelcontextprotocol/inspector python -m ormcp_server

# Or if you have the command in PATH
npx @modelcontextprotocol/inspector ormcp-server

Это позволяет интерактивно тестировать и изучать инструменты ORMCP Server без необходимости в дистрибутиве исходного кода.

Поддержка транспорта HTTP или SSE

Примечание: ORMCP по умолчанию использует транспорт stdio, который из коробки используют большинство настольных AI-клиентов (например, Claude Desktop). Режим HTTP (транспорт Streamable HTTP) также полностью поддерживается для автономных/сетевых развёртываний — см. руководство по взаимодействию в режиме HTTP для подробностей. Некоторые клиенты (например, Gemini CLI) в настоящее время требуют режим HTTP.

Вы можете запустить сервер ORMCP в режиме HTTP из командной строки:

# Basic HTTP mode
python src/ormcp_server.py --transport http

# Or using the CLI
ormcp-server --transport http

Настройка хоста и порта:

python src/ormcp_server.py --transport http --host 0.0.0.0 --port 9000

# Or using CLI
ormcp-server --transport http --host 0.0.0.0 --port 9000

Доступные параметры командной строки:

• --transport: выбор между "stdio" (по умолчанию) или "http"

• --host: задание адреса хоста (по умолчанию: 127.0.0.1, используется только в режиме HTTP)

• --port: задание номера порта (по умолчанию: 8080, используется только в режиме HTTP)

Быстрая настройка HTTP:

python src/ormcp_server.py --transport http
# or
ormcp-server --transport http

Убедитесь, что uvicorn установлен как зависимость, поскольку режим HTTP использует его для обслуживания приложения.

Использование в режиме HTTP

Сервер MCP, работающий в режиме HTTP, не предназначен для прямого доступа через веб-браузер. Это сервер API, который ожидает определённые сообщения протокола MCP, а не HTTP GET-запросы к корневому пути.

Резюме

• Используйте CLI ormcp-server для наиболее чистого и рекомендуемого опыта.

• Используйте прямой запуск python src/ormcp_server.py для простых запусков с дистрибутивом исходного кода.

• Используйте mcp dev или fastmcp run для продвинутых сценариев разработки/тестирования с дистрибутивом исходного кода.

Ожидаемый результат

[INFO] ORMCP server name: ORMCPServerDemo
[INFO] GILHARI BASE URL: http://localhost:80/gilhari/v1/
[INFO] ORMCP server v0.5.x starting in stdio (or http) mode ...

Контейнерное развёртывание (реестры MCP)

Для развёртывания через реестры MCP, такие как Glama, в корне этого репозитория предоставляется скрипт start.sh. Он обрабатывает установку и запуск ORMCP Server в контейнерной среде. См. скрипт для получения информации о требуемых переменных окружения и деталях конфигурации.

Конфигурация клиента MCP

Claude Desktop

Расположение файлов конфигурации и настройка путей для конкретных платформ: macOS · Windows · Linux

Вариант 1: Использование имени команды (требуется настроенный PATH)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Вариант 2: Использование полного пути (рекомендуется для Windows)

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "C:\\Users\\<YourUsername>\\AppData\\Roaming\\Python\\Python313\\Scripts\\ormcp-server.exe",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Чтобы найти точный путь установки:

# Windows (PowerShell)
(Get-Command ormcp-server).Source

# Windows (Command Prompt)
where ormcp-server

# Linux/Mac
which ormcp-server

# Any platform
pip show -f ormcp-server | grep "ormcp-server.exe"  # Windows
pip show -f ormcp-server | grep "ormcp-server$"     # Linux/Mac

Вариант 3: Прямое выполнение Python

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "python", 
      "args": [
        "-m",
        "ormcp_server"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Вариант 4: Использование FastMCP (для разработчиков с дистрибутивом исходного кода)

{
  "mcpServers": {
    "ORMCPServerDemo": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "<path_to_your_ormcp-server-project>/src/ormcp_server.py"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Вариант 5: Режим HTTP

{
  "mcpServers": {
    "my-ormcp-server-http": {
      "command": "ormcp-server",
      "args": [
        "--transport", "http",
        "--port", "8080"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

Примечания:

• ORMCPServerDemo — имя сервера ORMCP по умолчанию.

• Замените <YourUsername> на ваше фактическое имя пользователя Windows

• Если вы указываете номер порта соответствующего микросервиса Gilhari через переменную окружения "GILHARI_BASE_URL", убедитесь, что это порт, на котором прослушивается этот микросервис Gilhari.

• Примечание: по состоянию на 20 июля 2025 года Claude Desktop не поддерживал подключение к серверу MCP, работающему в режиме http.

Gemini CLI

Обновите файл settings.json Gemini:

{
  "mcpServers": {
    "my-ormcp-server-http": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

Примечание: Gemini CLI в настоящее время требует режим HTTP.

OpenAI GPTs (режим разработчика)

Чтобы подключить сервер ORMCP к пользовательскому GPT в режиме разработчика, сервер должен работать в режиме HTTP и быть доступным по публичному URL.

1. Подготовка бэкенда:

   • Сначала убедитесь, что микросервис Gilhari скомпилирован и запущен в своём Docker-контейнере в соответствии с инструкциями по настройке.

   • Используйте curl для проверки, что сервис Gilhari отвечает:

     curl -i http://localhost:80/gilhari/v1/getObjectModelSummary/now

2. Настройка и запуск сервера ORMCP:

   • Задайте необходимые переменные окружения для подключения сервера ORMCP к Gilhari.

     export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
     export MCP_SERVER_NAME="MyORMCPServer"
     export GILHARI_TIMEOUT="30"
     export LOG_LEVEL="INFO"

   • Запустите сервер ORMCP в режиме HTTP, поскольку это требуется для веб-клиентов.

     # Run from the project's root directory
     ormcp-server --transport http --port 8080

3. Предоставление публичного URL: Серверам OpenAI нужен публичный веб-адрес для доступа к вашему локальному серверу ORMCP. Используйте сервис туннелирования, такой как cloudflared или ngrok, чтобы создать защищённый публичный URL, перенаправляющий на вашу локальную машину.

   • Вариант A: Использование cloudflared (рекомендуется)

     • В новом терминале запустите туннель Cloudflare, указывающий на порт вашего сервера.

       cloudflared tunnel --url http://localhost:8080

     • cloudflared предоставит постоянный публичный URL (например, https://<your-tunnel-name>.trycloudflare.com).

   • Вариант B: Использование ngrok

     • В новом терминале запустите ngrok для перенаправления трафика на порт 8080.

       ngrok http 8080

     • ngrok предоставит временный публичный HTTPS URL (например, https://random-string.ngrok-free.app). Обратите внимание, что этот URL меняется при каждом перезапуске ngrok на бесплатном плане.

4. Подключение к вашему пользовательскому GPT:

   • Возьмите публичный URL, сгенерированный cloudflared или ngrok.

   • Добавьте /mcp в конец этого URL. Конечный результат будет вашей конечной точкой MCP, например: https://<your-public-url>/mcp.

   • В настройках вашего GPT (Settings → Apps & Connectors → Create) вставьте этот полный URL в поле MCP Server URL. GPT затем обнаружит и подключится к инструментам, предоставляемым вашим сервером ORMCP.

Другие клиенты MCP

• Подключитесь к серверу ORMCP и используйте совместимые с MCP инструменты ORM, предоставляемые сервером ORMCP.

• Настройте в соответствии с требованиями настройки сервера MCP вашего клиента, используя подходящий режим транспорта (STDIO или HTTP).

• 📚 Руководства по интеграции: См. подробную документацию по подключению к ORMCP Server:

  • Справочник по протоколу MCP — подробности низкоуровневого протокола JSON-RPC

  • Использование примера клиента ORMCP — руководство по использованию Python-клиента

  • Взаимодействие с ORMCP Server в режиме STDIO — руководство по транспорту STDIO

  • Взаимодействие с ORMCP Server в режиме HTTP — руководство по транспорту HTTP

  • Дополнительные руководства доступны в репозитории документации (также включены в дистрибутив исходного кода)

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

ORMCP Server предоставляет следующие инструменты MCP для взаимодействия с вашей базой данных.

📖 Подробная документация по API: Для полных спецификаций параметров и технических деталей см. Справочник по API инструментов MCP.

💡 Рабочие примеры: См. примеры использования в реальных сценариях в каталоге примеров.

Основные операции

getObjectModelSummary

Получение информации о базовой объектной модели.

Возвращает: Информацию о классах (типах), атрибутах, первичных ключах и связях в вашей доменной модели.

query

Запрос объектов с фильтрацией и обходом связей.

Параметры:

• className (string): Тип объектов для запроса

• filter (string, необязательный): SQL-подобное выражение WHERE для фильтрации

• maxObjects (integer, необязательный): Максимальное количество объектов для получения (-1 для всех, по умолчанию: -1)

• deep (boolean, необязательный): Включать ссылочные объекты в результаты (по умолчанию: true)

• operationDetails (string, необязательный): JSON-массив операционных директив для точной настройки запросов. Поддерживает операции, подобные GraphQL, например:

  • projections: Получение только конкретных атрибутов

  • ignore или follow: Управление ветвями ссылочных объектов

  • filter: Применение фильтров к ссылочным объектам

getObjectById

Получение конкретного объекта по его первичному ключу.

Параметры:

• className (string): Тип объекта для получения

• primaryKey (object): Значения первичного ключа (одно значение или объект составного ключа)

• deep (boolean, необязательный): Включать ссылочные объекты (по умолчанию: true)

• operationDetails (string, необязательный): Операционные директивы для точной настройки запросов

access

Получение объекта(ов), на которые ссылается конкретный атрибут ссылающегося объекта.

Параметры:

• className (string): Тип ссылающегося объекта

• jsonObject (object): Ссылающийся объект, содержащий ссылку

• attributeName (string): Имя атрибута, чьи ссылочные значения требуется получить

• deep (boolean, необязательный): Также включать ссылочные объекты полученных объектов (по умолчанию: true)

• operationDetails (string, необязательный): Операционные директивы для точной настройки запросов

getAggregate

Вычисление агрегированных значений по объектам (COUNT, SUM, AVG, MIN, MAX).

Параметры:

• className (string): Тип объектов для агрегации

• attributeName (string): Атрибут, по которому выполняется агрегация

• aggregateType (string): Тип агрегации - COUNT, SUM, AVG, MIN, MAX

• filter (string, необязательный): SQL-подобное выражение WHERE для фильтрации объектов перед агрегацией

Операции изменения данных

insert

Сохранение одного или нескольких JSON-объектов в базу данных.

Параметры:

• className (string): Тип объектов для вставки

• jsonObjects (array): Список JSON-объектов для сохранения в базу данных

• deep (boolean, необязательный): Также сохранять ссылочные объекты (по умолчанию: true)

update

Обновление одного или нескольких существующих объектов новыми значениями.

Параметры:

• className (string): Тип объектов для обновления

• jsonObjects (array): Список объектов с обновлёнными значениями (должны включать первичные ключи)

• deep (boolean, необязательный): Также обновлять ссылочные объекты (по умолчанию: true)

update2

Массовое обновление объектов, соответствующих критериям фильтра.

Параметры:

• className (string): Тип объектов для обновления

• filter (string): SQL-подобное выражение WHERE для определения объектов для обновления

• newValues (array): Список имен атрибутов и их новых значений

• deep (boolean, необязательный): Также обновлять ссылочные объекты (по умолчанию: true)

delete

Удаление конкретных объектов из базы данных.

Параметры:

• className (string): Тип объектов для удаления

• jsonObjects (array): Объекты для удаления (для идентификации требуются первичные ключи)

• deep (boolean, необязательный): Также удалять ссылочные объекты (по умолчанию: true)

delete2

Массовое удаление объектов, соответствующих критериям фильтра.

Параметры:

• className (string): Тип объектов для удаления

• filter (string, необязательный): SQL-подобное выражение WHERE для определения объектов для удаления (пустая строка удаляет все объекты указанного класса)

• deep (boolean, необязательный): Также удалять ссылочные объекты (по умолчанию: true)

Примечание: В режиме READONLY_MODE=True MCP-инструменты для операций изменения данных (insert, update, update2, delete, delete2) не предоставляются MCP-клиентам.

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

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

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

Проблемы установки:

• Команда не найдена → См. руководство по вашей платформе для настройки PATH: macOS · Windows · Linux

• Внешне управляемое окружение → Используйте виртуальное окружение (см. руководство по устранению неполадок)

• Пустой исполняемый файл → Переустановите пакет

• Отсутствующие зависимости → pip install --force-reinstall ormcp-server

• Обновление с v0.6.2 или более ранней версии и получение fastmcp ImportError → См. Ошибка импорта fastmcp после обновления

Проблемы с примерами Gilhari:

• Отказано в разрешении на выполнение скрипта → chmod +x *.sh или используйте sh build.sh (Linux/Mac)

• Ошибки подключения к базе данных → Проверьте JDBC-драйвер в Gilhari

Проблемы во время выполнения:

• Сервер не запускается → Проверьте, что Gilhari запущен

• Ошибки подключения к базе данных → Проверьте JDBC-драйвер в Gilhari

• Проблемы подключения MCP-клиента → Проверьте синтаксис файла конфигурации

Включить режим отладки:

# Linux/Mac
export LOG_LEVEL=DEBUG
ormcp-server

# Windows (Command Prompt)
set LOG_LEVEL=DEBUG
ormcp-server

# Windows (PowerShell)
$env:LOG_LEVEL="DEBUG"
ormcp-server

Получить помощь:

• Документация: github.com/softwaretree/ormcp-docs

• Проблемы: github.com/softwaretree/ormcp-docs/issues

• Электронная почта: ormcp_support@softwaretree.com

Разработка

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

Для тестирования и разработки с дистрибутивом исходного кода:

# Download source distribution
pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Разработка микросервиса Gilhari

• ORMCP Server использует программное обеспечение Gilhari — RESTful-микросервисный фреймворк для интеграции JSON-данных с базами данных.

• Сначала вы создаёте пользовательский микросервис Gilhari на основе объектно-реляционных моделей данных вашего приложения.

• Спецификация объектно-реляционного отображения (ORM) определяет и контролирует область и форму объектной модели, соответствующей вашей реляционной модели.

• Спецификация ORM определяется декларативно в текстовом файле (.jdx) на основе простой грамматики.

• Вы можете восстановить спецификацию ORM из существующей схемы базы данных с помощью инструментов/примеров, предоставляемых в составе Gilhari SDK. Проверьте каталог examples\JDX_ReverseEngineeringJSONExample.

• Пример обратного проектирования также доступен онлайн по адресу github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample

• Подробнее о создании пользовательских микросервисов Gilhari см. в документации Gilhari SDK, включённой в пакет дистрибутива исходного кода.

• Хотя сервер ORMCP может запустить микросервис Gilhari, если это настроено (с использованием переменных окружения GILHARI_IMAGE, GILHARI_NAME и GILHARI_PORT), рекомендуется запускать пользовательский микросервис Gilhari перед использованием сервера ORMCP. Также убедитесь, что номер порта в переменной окружения 'GILHARI_BASE_URL' для сервера ORMCP соответствует номеру порта, на котором пользовательский микросервис Gilhari прослушивает входящие REST-вызовы.

Участие в разработке

Благодарим вас за интерес к ORMCP Server!

🚫 В настоящее время вклад в код не принимается

ORMCP Server — это проприетарное программное обеспечение. Мы не принимаем вклад в код, pull request'ы или предложения новых функций.

🐞 Обратная связь и отчёты об ошибках

Мы приветствуем обратную связь о бета-версии! Вы можете помочь нам улучшить ORMCP Server:

• Сообщая об ошибках или проблемах

• Предлагая улучшения

• Делясь своим опытом

Как предоставить обратную связь

• GitHub Issues: Сообщить о проблемах или предложениях

• Электронная почта: ormcp_support@softwaretree.com

Любая предоставленная вами обратная связь может быть использована Software Tree для улучшения продукта без каких-либо обязательств указывать вас как автора или выплачивать вознаграждение.

Стороннее программное обеспечение

Зависимость от Gilhari и JDX: Для работы ORMCP Server требуется микросервис Gilhari, который, в свою очередь, зависит от JDX — базовой ORM-технологии, используемой Gilhari. Оба продукта являются проприетарными продуктами Software Tree. Gilhari и JDX включают различные компоненты стороннего программного обеспечения. Полные сведения об этих сторонних компонентах и их лицензиях см. в файле LICENSE в составе Gilhari SDK или на сайтах: https://www.softwaretree.com/v1/products/gilhari/ и https://www.softwaretree.com/v1/products/jdx/jdx.html

Зависимости Python: ORMCP Server использует следующие библиотеки Python с открытым исходным кодом, каждая из которых регулируется соответствующей лицензией:

• mcp (Model Context Protocol SDK)

• fastmcp (фреймворк FastMCP)

• httpx (библиотека HTTP-клиента)

• pydantic (библиотека валидации данных)

• uvicorn (ASGI-сервер)

• requests (HTTP-библиотека)

Лицензия

ORMCP Server — это проприетарное программное обеспечение, принадлежащее Software Tree, LLC. Полные условия см. в файле LICENSE.

Оценка бета-версии: ORMCP Server в настоящее время доступен как бета-продукт по ознакомительной лицензии. Это разрешает бесплатное использование в целях тестирования и оценки в течение ограниченного ознакомительного периода (30 дней с даты установки).

Зависимость от Gilhari и JDX: Для работы ORMCP Server требуется микросервис Gilhari, который, в свою очередь, зависит от JDX — базовой ORM-технологии, используемой Gilhari. Оба продукта являются проприетарными продуктами Software Tree и действуют в соответствии с собственными лицензионными соглашениями. Используя ORMCP Server, вы соглашаетесь также соблюдать условия лицензии Gilhari и лицензии JDX. Gilhari и JDX включают различные компоненты стороннего программного обеспечения — подробности см. в файле LICENSE в составе Gilhari SDK или на сайтах https://www.softwaretree.com/v1/products/gilhari/ и https://www.softwaretree.com/v1/products/jdx/jdx.html.

Коммерческое лицензирование: Использование ORMCP Server за пределами ознакомительного периода регулируется действующими на тот момент условиями лицензирования Software Tree. Для получения информации или выражения заинтересованности свяжитесь с Software Tree по адресу ormcp_support@softwaretree.com или посетите https://www.softwaretree.com.

Поддержка и ресурсы

• Документация: Полная документация и руководства

• Руководства по платформам: macOS · Windows · Linux

• Рабочие примеры: Просмотр примеров | Руководство по примерам - реальные сценарии использования и интеграции

• Пример микросервиса: Репозиторий gilhari_example1

• Отчёты об ошибках: Сообщить о проблемах

• Поддержка по электронной почте: ormcp_support@softwaretree.com

• Поддержка Gilhari: Документация Gilhari от Software Tree

• Протокол MCP: Официальный сайт MCP

• Установка ORMCP Server: pip install ormcp-server — бета-токен не требуется. Полные инструкции по установке см. на softwaretree.com/products/ormcp.

Сделано с ❤️ для сообщества ИИ и баз данных