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仕様

• 🕸️ 複雑なオブジェクトモデリングのサポート: 1対1、1対多、多対多のリレーションシップ、パス式を含む

• 🖇️ 柔軟なクエリ: ディープおよびシャロークエリ、GraphQLに類似したさまざまな操作ディレクティブにより、返されるオブジェクトの形状と範囲を調整可能

• 🚀 高度に最適化された軽量マッピングエンジン: コネクションプーリング、プリペアドステートメント、最適化された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を使用するための3つの簡単なステップ

1. データの範囲を定義する

• 関連データの軽量オブジェクトモデルを定義する

• シンプルな（JDX）文法を使用して、テキストファイル内のそれらのモデルに対する宣言型ORM仕様を記述する

2. Gilhariマイクロサービスを構築する

• モデル、ORM仕様、JDBCドライバーをDockerfileに追加する

• Gilhari Dockerイメージをビルドする

3. ORMCPで実行する

• ORMCPをGilhariマイクロサービスに接続する

• Gilhariを起動し、次にORMCPを起動する

• AIエージェントまたはMCPクライアントを使用して、範囲定義されたリレーショナルデータと直感的でオブジェクト指向の方法で対話する

詳細なクイックスタート

前提条件

• Python 3.12以上

• Docker（Gilhariマイクロサービス用）

• 対象データベース用のJDBCドライバー

1. ORMCP Serverをインストールする

OS別のステップバイステップのインストール手順が記載されたプラットフォーム別ガイド： 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）在住、年齢65歳のJohn Smithという名前の新しいユーザー（id = 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

なぜ2種類のパッケージ形式があるのか？

• Wheel (.whl) - バイナリ配布物。インストールが高速で、ランタイムコードのみを含む（約50KB）

• ソース配布物 (.tar.gz) - すべてのリソースを含む完全なパッケージ（数MB）

ほとんどのユーザーは、ORMCP Server を実行するために wheel のみが必要です。以下の場合にソース配布物をダウンロードしてください:

• カスタムマイクロサービスを作成するための Gilhari SDK

• サンプルアプリケーションとクライアントコード

• 完全なドキュメント

• 追加の技術ガイド

ORMCP Server の設定

環境変数で設定します:

注記:

• READONLY_MODE が True に設定されている場合、データを変更する可能性のある MCP ツール（例: insert、update、update2、delete、delete2）は ORMCP server から MCP クライアントに公開されません。デフォルトでは、すべての MCP ツールが公開されます。

• GILHARI_BASE_URL と GILHARI_NAME は、実行中の Gilhari マイクロサービスコンテナをプローブするために使用されます。

• GILHARI_IMAGE、GILHARI_NAME、GILHARI_PORT は、既存のマイクロサービスが見つからない場合に Gilhari マイクロサービスの新しいインスタンスを実行するために使用されます。GILHARI_HOST と GILHARI_PORT 変数の値が GILHARI_BASE_URL 設定の対応する値と一致していることを確認してください。ORMCP server はその場所で 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 エントリポイントを介して MCP サーバーが stdio モードで実行されます。

トラブルシューティング — コマンドが見つからない場合:

'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 サーバーは、Web ブラウザから直接アクセスするようには設計されていません。これは、ルートパスへの 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"

   • Web ベースのクライアントに必要なため、ORMCP サーバーを HTTP モード で起動します。

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

3. 公開 URL でサーバーを公開: OpenAI のサーバーは、ローカルの ORMCP サーバーに到達するために公開 Web アドレスが必要です。cloudflared や ngrok などのトンネリングサービスを使用して、ローカルマシンに転送する安全な公開 URL を作成します。

   • オプション A: cloudflared を使用（推奨）

     • 新しいターミナルで、サーバーのポートを指す Cloudflare トンネルを開始します。

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

     • cloudflared は永続的な公開 URL（例: https://<your-tunnel-name>.trycloudflare.com）を提供します。

   • オプション B: ngrok を使用

     • 新しいターミナルで、ポート 8080 にトラフィックを転送する ngrok を開始します。

       ngrok http 8080

     • ngrok は一時的な公開 HTTPS URL（例: https://random-string.ngrok-free.app）を提供します。無料プランでは、ngrok を再起動するたびにこの URL が変更されることに注意してください。

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 Tools API リファレンス を参照してください。

💡 実用的な例: examples ディレクトリ で実際の使用例を参照してください。

コア操作

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

1つ以上のJSONオブジェクトをデータベースに保存します。

パラメータ:

• className (string): 挿入するオブジェクトの型

• jsonObjects (array): データベースに保存するJSONオブジェクトのリスト

• deep (boolean, 任意): 参照先のオブジェクトも保存するかどうか（デフォルト: true）

update

1つ以上の既存オブジェクトを新しい値で更新します。

パラメータ:

• 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 ImportErrorを参照してください

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/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 は、データベースとのJSONデータ統合のためのRESTfulマイクロサービスフレームワークである Gilhariソフトウェア を活用しています。

• まず、アプリケーションのオブジェクトリレーショナルデータモデルに基づいて、カスタムGilhariマイクロサービスを作成します。

• オブジェクトリレーショナルマッピング（ORM）仕様は、リレーショナルモデルに対応するオブジェクトモデルの範囲と形状を定義し、制御します。

• ORM仕様は、シンプルな文法に基づいてテキストファイル（.jdx）に宣言的に定義されます。

• Gilhari SDKに付属のツール/例を使用して、既存のデータベーススキーマからORM仕様をリバースエンジニアリングできる場合があります。examples\JDX_ReverseEngineeringJSONExample ディレクトリを確認してください。

• リバースエンジニアリングの例は、github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample でもオンラインで入手できます。

• カスタムGilhariマイクロサービスの作成の詳細については、ソース配布パッケージに含まれているGilhari SDKのドキュメントを参照してください。

• ORMCPサーバーは、設定されていればGilhariマイクロサービスを起動できますが（GILHARI_IMAGE、GILHARI_NAME、GILHARI_PORT 環境変数を使用）、ORMCPサーバーを使用する前にカスタムGilhariマイクロサービスを起動することをお勧めします。また、ORMCPサーバーの 'GILHARI_BASE_URL' 環境変数のポート番号が、カスタムGilhariマイクロサービスが着信REST呼び出しを待ち受けているポート番号と一致していることを確認してください。

コントリビューション

ORMCP Server に関心をお寄せいただきありがとうございます！

🚫 現時点ではコードのコントリビューションは受け付けていません

ORMCP Server はプロプライエタリソフトウェアです。コードのコントリビューション、プルリクエスト、機能提案は 受け付けていません。

🐞 フィードバックとバグ報告

ベータ版に関するフィードバックは 歓迎します！ 以下の方法でORMCP Serverの改善にご協力いただけます:

• バグや問題の報告

• 改善提案

• ご経験の共有

フィードバックの提供方法

• GitHub Issues: 問題や提案を報告

• メール: ormcp_support@softwaretree.com

提供いただいたフィードバックは、Software Treeが製品を改善するために使用する場合がありますが、クレジットの表示や報酬をお支払いする義務はありません。

サードパーティソフトウェア

GilhariおよびJDXへの依存: ORMCP Server が機能するにはGilhariマイクロサービスが必要であり、Gilhariはその基盤となるORM技術であるJDXに依存しています。どちらもSoftware Treeのプロプライエタリ製品です。GilhariとJDXにはさまざまなサードパーティソフトウェアコンポーネントが組み込まれています。これらのサードパーティコンポーネントとそのライセンスの詳細については、Gilhari SDKのLICENSEファイルを参照するか、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マイクロサービスが必要であり、Gilhariはその基盤となるORM技術であるJDXに依存しています。どちらも独自のライセンス契約に基づくSoftware Treeのプロプライエタリ製品です。ORMCP Serverを使用することにより、GilhariライセンスおよびJDXライセンスにも準拠することに同意したものとみなされます。GilhariとJDXにはさまざまなサードパーティソフトウェアコンポーネントが組み込まれています。詳細については、Gilhari SDKのLICENSEファイルを参照するか、https://www.softwaretree.com/v1/products/gilhari/ および https://www.softwaretree.com/v1/products/jdx/jdx.html をご覧ください。

商用ライセンス: 評価期間を超えたORMCP Serverの使用は、その時点で適用されるSoftware Treeのライセンス条件に従うものとします。詳細については、ormcp_support@softwaretree.com までSoftware Treeにお問い合わせいただくか、https://www.softwaretree.com をご覧ください。

サポートとリソース

• ドキュメント: 完全なドキュメントとガイド

• プラットフォームガイド: macOS · Windows · Linux

• 実践例: 例を閲覧 | 例のガイド - 実際のユースケースと統合例

• マイクロサービスの例: gilhari_example1 リポジトリ

• バグ報告: 問題を報告

• メールサポート: ormcp_support@softwaretree.com

• Gilhariサポート: Software Tree Gilhariドキュメント

• MCPプロトコル: 公式MCPサイト

• ORMCP Serverのインストール: pip install ormcp-server — ベータトークンは不要です。完全なセットアップ手順については、softwaretree.com/products/ormcp を参照してください。

AIとデータベースコミュニティのために ❤️ を込めて作られました