Skip to main content
Glama
enesjakoru
SoftwareTree

ORMCP Server

by SoftwareTree
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

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?

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

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

Переменная

Описание

По умолчанию

Пример

GILHARI_BASE_URL

URL микросервиса Gilhari

http://localhost:80/gilhari/v1/

http://myhost:8888/gilhari/v1/

MCP_SERVER_NAME

Идентификатор сервера

ORMCPServerDemo

MyCompanyORMCP

GILHARI_TIMEOUT

Тайм-аут API (секунды)

30

60

LOG_LEVEL

Подробность журналирования

INFO

DEBUG, WARNING, ERROR

READONLY_MODE

Предоставлять только операции чтения

False

True

GILHARI_NAME

Имя микросервиса Gilhari для конкретного приложения

""

my-gilhari-microservice

GILHARI_IMAGE

Имя Docker-образа микросервиса Gilhari для приложения

""

gilhari_example1:1.0

GILHARI_HOST

IP-адрес хост-машины для микросервиса Gilhari

localhost

10.20.30.40

GILHARI_PORT

Номер порта для связи с микросервисом Gilhari

80

8888

Примечания:

  • Если для 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

Справочник по инструментам 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-клиентам.

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

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

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

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

Проблемы с примерами 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

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

Разработка

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

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

# 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:

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

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

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

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

Любая предоставленная вами обратная связь может быть использована 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.

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

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

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • CentralMind/Gateway

    centralmind
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDB
    550
    Apache 2.0

  • io.github.ralfbecher/orionbelt

    ralforion
    A
    license
    Not graded
    quality
    A
    maintenance
    OrionBelt Analytics is an MCP server that analyzes relational database schemas and generates RDF/OWL ontologies with embedded SQL mappings. It provides relationship-aware Text-to-SQL with automatic fan-trap prevention, GraphRAG for intelligent schema discovery, and interactive charting -- all accessible through any MCP-compatible AI client.
    105 PyPI
    48
    Business Source 1.1

  • mcp-db-server

    Souhar-dya
    F
    license
    Not graded
    quality
    A
    maintenance
    An MCP server that exposes relational databases (PostgreSQL/MySQL) to AI agents with natural language to SQL query support.
    19
    -

  • scopedb-mcp

    xieweicong
    A
    license
    Not graded
    quality
    D
    maintenance
    Config-driven MCP server that gives AI scoped, auditable database access without exposing the entire database.
    10 npm
    6
    MIT