Copyright (c) 2025, Software Tree

ORMCP Server - 베타

AI 애플리케이션을 관계형 데이터베이스에 연결하기 위한 Model Context Protocol (MCP) 서버

ORMCP Server는 AI LLM 및 MCP 클라이언트가 MCP 표준 프로토콜을 사용하여 모든 관계형 데이터베이스와 객체 지향 데이터(JSON 형식)를 쉽게 교환할 수 있게 해줍니다.

ORMCP Server는 관계형 데이터를 AI에 적합하게 만듭니다.

⚠️ 베타 공지

ORMCP Server는 현재 베타 단계에 있으며, 소프트웨어를 확인하고 피드백을 제공하며 제품이 최고 품질 기준을 충족하도록 도와주고자 하는 사용자에게 조기 액세스를 제공하고 있습니다. 이 베타 버전은 상업적 사용을 위한 것이 아니며, 테스트 목적으로만 제공됩니다.

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

📋 목차

• MCP란 무엇인가?

• 기능

• 작동 방식

• 빠른 시작

• 플랫폼별 가이드 — 🍎 macOS · 🪟 Windows · 🐧 Linux

• 설치

• Gilhari 마이크로서비스 설정

• 구성

• 서버 시작

• 클라이언트 구성

• 사용 예시

• MCP 도구 참조

• 문제 해결

• 개발

• 기여

• 라이선스

• 지원 및 리소스

MCP란 무엇인가?

Model Context Protocol (MCP)은 AI 모델이 외부 도구 및 데이터 소스와 상호 작용할 수 있는 통합된 방법을 제공하는 개방형 표준입니다. 이는 통신을 표준화하여 모든 사용 사례에 맞춤형 API 통합을 구축하지 않고도 LLM을 복잡한 워크플로우에 더 쉽게 통합할 수 있게 해줍니다.

자세한 내용은 공식 MCP 웹사이트에서 확인하세요.

✨ 기능

• ✅ 표준화된 인터페이스: Model Context Protocol (MCP) 사양을 완전히 준수

• 🌐 데이터베이스 독립적: 모든 JDBC 호환 데이터베이스(예: PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)에서 작동

• ↔️ 양방향 데이터 흐름: 원활한 AI ↔ 데이터베이스 통신, READONLY 작업만 지원하는 옵션 제공

• 🔄 객체-관계 매핑 (ORM): JSON 객체 작업(CRUD)이 관계형 데이터에 투명하게 매핑됨

• 🔒 안전한 데이터 액세스: 도메인 모델별 작업이 데이터 보호를 촉진

• 🧾 선언적 ORM 사양: 간단한 문법에 기반한 직관적이고 비침습적이며 유연한 ORM 사양

• 🕸️ 복잡한 객체 모델링 지원: 일대일, 일대다, 다대다 관계 및 경로 표현식 포함

• 🖇️ 유연한 쿼리: 심층 및 얕은 쿼리, 반환되는 객체의 형태와 범위를 정제하기 위한 GraphQL과 유사한 다양한 운영 지시어

• 🚀 고도로 최적화되고 가벼운 매핑 엔진: 연결 풀링, 준비된 문(Prepared statements), 최적화된 SQL 문, 최소한의 데이터베이스 왕복, 메타데이터 캐싱

• 🔌 기존 데이터 및 데이터베이스와 호환: 모든 데이터베이스의 기존 스키마 및 데이터와 함께 작동; 네이티브 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 도구 호출을 Gilhari에 대한 REST API 호출로 변환합니다.

ORMCP Server는 다음을 통해 최신 AI 애플리케이션과 관계형 데이터베이스 간의 격차를 해소합니다:

• MCP 프로토콜: 표준화된 AI-도구 통신

• Gilhari: ORM 및 JDBC를 통한 관계형 데이터베이스와의 통합 계층

• JSON 매핑: 투명한 객체-관계 매핑

🚀 빠른 시작

ORMCP가 처음이신가요? 간소화된 설정을 위해 플랫폼별 가이드로 바로 이동하세요: 🍎 macOS · 🪟 Windows · 🐧 Linux

아래 섹션은 완전한 참조 자료로 모든 플랫폼을 함께 다룹니다.

ORMCP 사용을 위한 세 가지 간단한 단계

1. 데이터 범위 지정

• 관련 데이터에 대한 경량 객체 모델 정의

• 간단한 (JDX) 문법을 사용하여 텍스트 파일에 해당 모델에 대한 선언적 ORM 사양 작성

2. Gilhari 마이크로서비스 구축

• Dockerfile에 모델, ORM 사양, JDBC 드라이버 추가

• Gilhari Docker 이미지 빌드

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 액세스가 중단되었습니다. 공개 PyPI에서 직접 가져오는 pip install ormcp-server를 사용하세요.

설치 후 ormcp-server 명령을 찾을 수 없는 경우:

Python 실행 파일 디렉터리를 PATH에 추가하세요. 자세한 내용은 플랫폼 가이드를 참조하세요: macOS · Windows · Linux

2. Gilhari 마이크로서비스 설정

자세한 설정은 아래 Gilhari 마이크로서비스 설정 섹션을 참조하세요.

참고: 완전한 작동 예제는 별도 저장소에서 확인할 수 있습니다: gilhari_example1

예제를 실행하려면:

중요: Gilhari 마이크로서비스를 빌드하고 실행하려면 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

명령을 찾을 수 없는 오류가 발생하면 플랫폼 가이드를 참조하세요: macOS · Windows · Linux

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

5. AI 클라이언트 연결

Claude Desktop의 경우 claude_desktop_config.json에 추가하세요:

옵션 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

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

# Linux/Mac
which ormcp-server

준비 완료! 이제 AI 클라이언트가 자연어를 사용하여 데이터베이스와 상호 작용할 수 있습니다.

참고: Claude Desktop을 클라이언트로 사용하는 경우 3단계(환경 구성)와 4단계(ORMCP Server 시작)는 필요하지 않습니다. 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 프롬프트: "보스턴(MA) 출신의 John Smith라는 새 사용자(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는 데이터베이스와의 JSON 데이터 통합을 위한 마이크로서비스 프레임워크인 Gilhari 소프트웨어에 의존합니다. 이 설정은 ORMCP 서버를 시작하기 전에 완료되어야 합니다.

중요: Gilhari 마이크로서비스를 빌드하고 실행하려면 Docker가 필요합니다 — 아직 설치되지 않은 경우 Docker 받기 를 참조하세요

Gilhari 소프트웨어 설치

1. Gilhari Docker 이미지 가져오기:

   docker pull softwaretree/gilhari:latest

2. Gilhari SDK 설치:

   • Gilhari 소프트웨어용 SDK는 ORMCP Server 패키지의 Gilhari_SDK 폴더에 포함되어 있습니다

   • 또는 다음에서 다운로드: https://www.softwaretree.com/v1/products/gilhari/download-gilhari.php

   • SDK에는 Gilhari 소프트웨어를 쉽게 사용하는 데 도움이 되는 문서(README, API 가이드, 샘플 애플리케이션)가 포함되어 있습니다

앱별 Gilhari 마이크로서비스 구성

다음 단계를 따르세요 (Gilhari SDK 문서에 자세히 설명됨):

1. 도메인 모델 클래스 정의 - JSON 객체용 Java 컨테이너 클래스

2. 선언적 ORM 사양 생성 - JSON 속성을 데이터베이스 스키마에 매핑

3. 앱별 Gilhari 마이크로서비스의 Docker 이미지 빌드 - 도메인 클래스, ORM 사양, JDBC 드라이버 포함

4. 마이크로서비스 실행:

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

참고: 완전한 작동 예제는 별도 저장소에서 확인할 수 있습니다: gilhari_example1. 이 예제는 User 객체를 관리하는 Gilhari 마이크로서비스를 보여줍니다.

예제로 빠른 시작:

# 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

자세한 설정 및 구성 지침은 gilhari_example1 README를 참조하세요.

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 또는 WinRAR을 사용하여 .tar.gz 파일을 추출하세요

• 또는 PowerShell 사용: tar -xzf ormcp_server-*.tar.gz

• 또는 PyPI 프로젝트 페이지에서 직접 다운로드하세요

패키지 내용

ORMCP Server 패키지에는 Python 코드 외에도 추가 리소스가 포함되어 있습니다:

런타임 설치 (Wheel)

pip로 설치하면 ORMCP Server를 실행하는 데 필요한 핵심 Python 패키지를 얻을 수 있습니다:

pip install ormcp-server

이것은 필수 런타임 파일만 Python 환경에 설치합니다.

SDK 및 문서가 포함된 전체 패키지 (소스 배포)

전체 패키지에는 다음이 포함됩니다:

• Gilhari_SDK/ - 맞춤형 Gilhari 마이크로서비스 생성을 위한 문서, 예제, 도구가 포함된 완전한 SDK

• 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가 설치되어 있지 않은 경우:

• 7-Zip 또는 WinRAR을 사용하여 .tar.gz 파일을 추출하세요

• 또는 PowerShell 사용: tar -xzf ormcp_server-0.6.x.tar.gz

• 또는 PyPI 프로젝트 페이지에서 직접 다운로드하세요

옵션 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) - 바이너리 배포판으로 설치가 빠르며 런타임 코드만 포함합니다(~50KB)

• 소스 배포판 (.tar.gz) - 모든 리소스를 포함한 완전한 패키지입니다(~수 MB)

대부분의 사용자는 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

이 명령은 main.py 진입점을 통해 stdio 모드에서 MCP 서버를 실행합니다.

문제 해결 — 명령을 찾을 수 없음:

'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

fastmcp CLI 사용(소스 배포판 필요):

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

HTTP 모드는 애플리케이션을 제공하기 위해 uvicorn을 사용하므로 uvicorn이 의존성으로 설치되어 있는지 확인하세요.

HTTP 모드에서의 사용

HTTP 모드에서 실행되는 MCP 서버는 웹 브라우저를 통해 직접 접근하도록 설계되지 않았습니다. 이는 루트 경로에 대한 HTTP GET 요청이 아닌 특정 MCP 프로토콜 메시지를 기대하는 API 서버입니다.

요약

• 가장 깔끔하고 권장되는 경험을 위해 ormcp-server CLI를 사용하세요.

• 소스 배포판으로 간단히 실행하려면 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 레지스트리)

Glama와 같은 MCP 레지스트리를 통한 배포를 위해, 이 저장소의 루트에 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_BASE_URL" 환경 변수를 통해 관련 Gilhari 마이크로서비스의 포트 번호를 제공하는 경우, 해당 Gilhari 마이크로서비스가 수신 대기 중인 포트인지 확인하세요.

• 참고: 2025년 7월 20일 기준, Claude desktop은 http 모드에서 실행되는 MCP 서버 연결을 지원하지 않았습니다.

Gemini CLI

Gemini settings.json 파일을 업데이트하세요:

{
  "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"

   • 웹 기반 클라이언트에 필요하므로 HTTP 모드로 ORMCP 서버를 시작하세요.

     # 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에 연결:

   • cloudflared 또는 ngrok이 생성한 공개 URL을 가져오세요.

   • 이 URL 끝에 /mcp를 추가하세요. 최종 결과가 MCP 엔드포인트가 됩니다(예: https://<your-public-url>/mcp).

   • GPT의 구성 설정(Settings → Apps & Connectors → Create)에서 이 전체 URL을 MCP Server URL 필드에 붙여넣으세요. 그러면 GPT가 ORMCP 서버가 제공하는 도구를 발견하고 연결합니다.

기타 MCP 클라이언트

• ORMCP 서버에 연결하고 ORMCP 서버가 제공하는 MCP 호환 ORM 도구를 사용하세요.

• 적절한 전송 모드(STDIO 또는 HTTP)를 사용하여 클라이언트의 MCP 서버 설정 요구 사항에 따라 구성하세요.

• 📚 통합 가이드: ORMCP Server 연결에 대한 자세한 문서를 참조하세요:

  • MCP 프로토콜 참조 - 저수준 JSON-RPC 프로토콜 세부 사항

  • ORMCP 클라이언트 예제 사용 - Python 클라이언트 사용 가이드

  • STDIO 모드에서 ORMCP Server와 상호작용 - STDIO 전송 가이드

  • HTTP 모드에서 ORMCP Server와 상호작용 - HTTP 전송 가이드

  • 추가 가이드는 문서 저장소에서 확인할 수 있습니다(소스 배포판에도 포함됨)

MCP 도구 참조

ORMCP Server는 데이터베이스와 상호작용하기 위한 다음 MCP 도구를 제공합니다.

📖 상세 API 문서: 전체 매개변수 사양 및 기술 세부 사항은 MCP 도구 API 참조를 참조하세요.

💡 작업 예제: 예제 디렉토리에서 실제 사용 예제를 확인하세요.

핵심 작업

getObjectModelSummary

기본 객체 모델에 대한 정보를 검색합니다.

반환 값: 도메인 모델의 클래스(유형), 속성, 기본 키 및 관계에 대한 정보입니다.

query

필터링 및 관계 탐색을 통해 객체를 쿼리합니다.

매개변수:

• className (string): 조회할 객체의 타입

• filter (string, optional): 필터링을 위한 SQL 유사 WHERE 절

• maxObjects (integer, optional): 검색할 최대 객체 수 (-1이면 전체, 기본값: -1)

• deep (boolean, optional): 결과에 참조된 객체 포함 (기본값: true)

• operationDetails (string, optional): 쿼리를 미세 조정하기 위한 운영 지시문의 JSON 배열. 다음과 같은 GraphQL 유사 연산을 지원합니다:

  • projections: 특정 속성만 조회

  • ignore 또는 follow: 참조된 객체 분기 제어

  • filter: 참조된 객체에 필터 적용

getObjectById

기본 키로 특정 객체를 조회합니다.

매개변수:

• className (string): 조회할 객체의 타입

• primaryKey (object): 기본 키 값 (단일 값 또는 복합 키 객체)

• deep (boolean, optional): 참조된 객체 포함 (기본값: true)

• operationDetails (string, optional): 쿼리를 미세 조정하기 위한 운영 지시문

access

referencing 객체의 특정 속성이 참조하는 객체(들)을 조회합니다.

매개변수:

• className (string): 참조 객체(referencing object)의 타입

• jsonObject (object): 참조를 포함한 참조 객체

• attributeName (string): 참조된 값(들)을 조회할 속성의 이름

• deep (boolean, optional): 조회된 객체의 참조된 객체도 포함 (기본값: true)

• operationDetails (string, optional): 쿼리를 미세 조정하기 위한 운영 지시문

getAggregate

객체 전반에 걸쳐 집계 값(COUNT, SUM, AVG, MIN, MAX)을 계산합니다.

매개변수:

• className (string): 집계할 객체의 타입

• attributeName (string): 집계를 수행할 속성

• aggregateType (string): 집계 유형 - COUNT, SUM, AVG, MIN, MAX

• filter (string, optional): 집계 전에 객체를 필터링하기 위한 SQL 유사 WHERE 절

데이터 수정 작업

insert

하나 이상의 JSON 객체를 데이터베이스에 저장합니다.

매개변수:

• className (string): 삽입할 객체의 타입

• jsonObjects (array): 데이터베이스에 저장할 JSON 객체 목록

• deep (boolean, optional): 참조된 객체도 함께 저장 (기본값: true)

update

기존 객체 하나 이상을 새 값으로 업데이트합니다.

매개변수:

• className (string): 업데이트할 객체의 타입

• jsonObjects (array): 업데이트된 값을 가진 객체 목록 (기본 키 포함 필수)

• deep (boolean, optional): 참조된 객체도 함께 업데이트 (기본값: true)

update2

필터 조건과 일치하는 객체를 일괄 업데이트합니다.

매개변수:

• className (string): 업데이트할 객체의 타입

• filter (string): 업데이트할 객체를 식별할 SQL 유사 WHERE 절

• newValues (array): 속성 이름과 새 값의 목록

• deep (boolean, optional): 참조된 객체도 함께 업데이트 (기본값: true)

delete

데이터베이스에서 특정 객체를 삭제합니다.

매개변수:

• className (string): 삭제할 객체의 유형

• jsonObjects (array): 삭제할 객체 (식별을 위한 기본 키 필요)

• deep (boolean, optional): 참조된 객체도 함께 삭제 (기본값: true)

delete2

필터 조건을 충족하는 객체를 일괄 삭제합니다.

매개변수:

• className (string): 삭제할 객체의 유형

• filter (string, optional): 삭제할 객체를 식별하기 위한 SQL 유사 WHERE 절 (빈 문자열은 해당 클래스의 모든 객체를 삭제)

• deep (boolean, optional): 참조된 객체도 함께 삭제 (기본값: true)

참고: READONLY_MODE=True인 경우, 데이터 수정 작업을 위한 MCP 도구(insert, update, update2, delete, delete2)는 MCP 클라이언트에 노출되지 않 것입니다.

문제 해결

일반적인 문제 및 해결 방법을 보려면 전체 문제 해결 가이드를 참조하세요.

빠른 문제 해결

설치 문제:

• 명령을 찾을 수 없음 → PATH 구성을 위해 플랫폼 가이드를 참조하세요: [macOS](./더 가이들/getting-started-mac.md#troubleshooting) · Windows · Linux

• 외부 환경 관리 → 가상 환경 사용 ( 가상 환경 문제 해결 가이드 참조) 참조)

• 빈 실행 파일 → 패키지 재설치

• 누락된 종속성 → pip install --force-reinstall ormcp-server

• v0.6.2 이하에서 업그레이드 후 fastmcp ImportError가 발생하는 경우 → [업그레이드 후 fastmcp ImportError](https://github.com/softwaretree/orm-issues를 확인하세요) 참조)

Gilhari 예제 문제:

• 셸 스크립트 권한 거부 → chmod +x *.sh 또는 sh build.sh 사용 (Linux/Mac)

• 데이터베이스 연결 오류 → Gilhari의 JDBC 드라이버 확인

런타임 문제:

• 서버 시작 안 됨 → Gilhari 실행 확인

• 데이터베이스 연결 오류 → Gilhari의 JDBC 드라이버 확인

• 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/orm-issues

• 이슈: github.com/softwaretree/orm-issues/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 서버] [Gilhari] 소프트웨어를 기반으로 사용합니다 - 데이터베이스를 통한 RESTful JSON 데이터 통합 microservice 프레임워크입니다.

• 먼저 응용 프로그램의 객체 관계형 데이터 모델을 기반으로 커스텀 Gilhari 마이크로서비스를 만듭니다.

• 객체 관계형 매핑(ORM) 명세는 관계형 모델에 대응하는 객체 모델의 범위와 형태를 정의하고 제어합니다.

• ORM 명세는 간단한 문법을 기반으로 하는 텍스트 파일(.jdx)에서 선언적으로 정의됩니다.

• Gilhari SDK에 포함된 도구/예제를 사용하여 기존 데이터베이스 스키마에서 ORM 명세를 리버스엔지니어링할 수 있습니다. examples\JDX_ReverseEngineeringJSONExample 디렉토리를 확인하십시오.

• 리버스엔지니어링 예제는 github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample 온라인에서도 사용할 수 있습니다.

• 커스텀 Gilhari 마이크로서비스 생성에 대한 자세한 내용은 소스 배포 패키지에 포함된 Gilhari SDK 문서를 참조하는 참조하세요.

• ORMCP 서버는 GILHARI_IMAGE, GILHARI_NAME, GILHARI_PORT 환경 변수를 사용해 이미지에 이르는 Gilhari 마이크로서비스를 시작할 수 있지만, ORMCP 서버를 사용하기 전에 먼저 갈마리 마이크로서비스를 시작하는 것이 좋습니다. 또한 ORMCP 서버의 'GILHARI_BASE_URL' 환경 변수에 있는 포트 번호가 커스텀 Gilhari 마이크로서비스가 수신하고 있는 포트 번호와 일치하는지 확인하시기 바랍니다.

기여

ORMCP 서버에 관심을 주셔서 감사합니다!

🚀 현재 코드 기여는 없습니다

ORMCP 서버는 독점 소프트웨어입니다. 코드 기여 및 제공은 물론 pull-request를 받지 않습니다.

🐞 피드백 및 버그 신고

베타 버전에 대한 피드백은 대환영입니다! 다음과 같이 [ORMCP 서버] 개선에 도움을 주실 수 있습니다:

• 버그나 문제점 보고

• 개선 제안

• 사용 경험 공유

피드백을 제공하는 방법

• GitHub Issues: 이슈 혹은 제안하기

• 이메일: ormcp_support@softwaretree.com

제공하신 모든 피드백은 소프트웨어 트리(Software Tree)가 제품을 개선하는 데 사용할 수 있으며, 커다란 의무 사항의 의무나 보상은 다음과 같습니다.

타사 소프트웨어

Gilhari와 JDX 의존성:

ORMCP 서버가 작동하려면 Gilhari 마이크로서비스가 필요하며, 이는 다시 주 JDX를 기반으로 하는 기반의 ORM tech 기술을 활용하는 서비스입니다. 두 제품 모두 Software Tree 독점 제품입니다.

종속성 파이썬

ORMCP 서버는 각각의 라이선스에 따라 적용되는 다음 오픈 소스 Python 라이브러리를 사용합니다.

• mcp (Model Context Protocol SDK)

• fastmcp (FastMCP 프레임워크)

• httpx (HTTP 클라이언트 라이브러리)

• pydantic (데이터 검증 라이브러리)

• uvicorn (ASGI 서버)

• requests (HTTP 라이브러리)

라이선스

ORMCP 서버는 Software Tree, LLC가 소유한 독점 소프트웨어입니다. 전체 약관은 LICENSE 파일을 참조하십시오.

베타 평가: ORMCP 서버는 현재 평가 라이선스 하에 베타로 제공되고 있습니다. 설치 날짜부터 제한된 평가 기간(30일) 동안 테스트/평가 목적으로 사용할 수 있습니다.

Gilhari 및 JDX 의존성: ORMCP 서버는 기능을 위해 Gilhari 마이크로서비스를 요구하며, 다시 Gilhari에서 사용되는 하위 ORM 기술인 JDX에 의존합니다. 둘 다 자체 라이선스 계약에 따라 제공되는 Software Tree 제품입니다. ORMCP Server를 사용하기 위해 Gilhari 라이선스를 비롯하여 JDX 라이선스에도 동의하는 것으로 간주됩니다. 또한 Gilhari 및 JDX에 다양한 자체 소프트웨어 구성 요소가 포함되어 있으며, 상세 내용은 Gilhari SDK의 LICENSE 파일을 참조하거나 또는 https://www.softwaretree.com/v1/products/gilhari/를 확인하십시오.

상업 라이선스: 평가 기간 이후의 ORMCP 서버 사용은 그 시점의 적용 가능한 Software Tree 라이선스 조건을 따르게 됩니다. 자세한 내용 또는 관심이 있으면 Software Tree ormcp_support@softwaretree.com 또는 https://www.softwaretree.com에 문의하시기 바랍니다.

고객 지원 및 리소스

• Dokumentation - 문서와 가이드

• 플랫폼 가이드: macOS · Windows · Linux - 플랫폼별 가이드

• [Examples but](`/SoftwareTreeorm-Hub/raw mysql/습니다 ...) — 실제 구성/통합 사용 사례

• [예제 마이크로서비스] gilhari_example1

• 버그 신고 여기

• 이메일 지원 ormcp_support@softwaretree.com

• Gilhari 지원: Software Tree Gilhari Dokumentacja

• MCP 프로토콜: 공식 MCP 사이트

• ORMCP Server 설치: pip install ormcp-server — 베타 토큰이 필요 없습니다. 자세한 권장 사항은 SoftwareTree/ORM-CP/href를 참조하십시오.

AI와 데이터베이스 커뮤니티를 위해 ❤️ 로 만들어졌습니다