Ormcp Docs

## 🚀 ORMCP Server - Beta

*AIアプリケーションをリレーショナルデータベースに接続するためのモデルコンテキストプロトコル（MCP）サーバー*

ORMCP Serverを使用すると、AIの大規模言語モデル（LLM）やMCPクライアントは、MCP標準プロトコルを使用して、任意のリレーショナルデータベースとオブジェクト指向データ（JSON形式）を簡単に交換できます。

**ORMCP Serverにより、リレーショナルデータをAIに対応させることができます。**

## ⚠️ ベータ版の注意事項

**ORMCP Server**は現在**ベータ版**であり、ソフトウェアをチェックし、フィードバックを提供し、製品が最高の品質基準を満たすように支援したいユーザーに早期アクセスを提供しています。このベータ版は**商用利用を目的としておらず**、**テスト目的のみ**で提供されています。

## 📋 目次

- [MCPとは？](#mcpとは)
- [特徴](#-特徴)
- [動作原理](#動作原理)
- [クイックスタート](#-クイックスタート)
- [インストール](#ormcpパッケージのインストール)
- [Gilhariマイクロサービスのセットアップ](#gilhariマイクロサービスのセットアップ)
- [設定](#ormcpサーバーの設定)
- [サーバーの起動](#サーバーの起動)
- [クライアントの設定](#mcpクライアントの設定)
- [使用例](#使用例)
- [MCPツールのリファレンス](#mcpツールのリファレンス)
- [トラブルシューティング](#トラブルシューティング)
- [開発](#開発)
- [コントリビュート](#コントリビュート)
- [ライセンス](#ライセンス)
- [サポートとリソース](#サポートとリソース)

## MCPとは？

モデルコンテキストプロトコル（MCP）は、AIモデルが外部ツールやデータソースと相互作用するための統一された方法を提供するオープン標準です。これにより、通信が標準化され、各ユースケースに対してカスタムAPI統合を構築することなく、LLMを複雑なワークフローに簡単に統合できます。

詳細については、[公式MCPウェブサイト](https://modelcontextprotocol.io/)を参照してください。

## ✨ 特徴

- **✅ 標準化されたインターフェイス:** モデルコンテキストプロトコル（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アプリ / LLMクライアント | <---> | ORMCPサーバー | <---> | リレーショナルデータベース | | (MCP対応ツール) | | (MCP + Gilhari) | | (Postgres, MySQL, etc.) | +---------------------+ +----------------------+ +-------------------------+ | | | | JSON (MCPツール経由) | | |------------------------------->| | | | ORM + JDBC | | |-------------------------------->| | | | | JSON結果 (MCP形式) | | |<-------------------------------| |

**重要:** AIアプリケーション（LLMクライアント）は自然言語をMCPツール呼び出しに変換します。その後、ORMCP ServerはこれらのMCPツール呼び出しをGilhariへのREST API呼び出しに変換します。

**ORMCP Server**は、以下を通じて、最新のAIアプリケーションとリレーショナルデータベースの間のギャップを埋めます。
- **MCPプロトコル**: 標準化されたAIとツール間の通信
- **Gilhari**: ORMとJDBCを介したリレーショナルデータベースとの統合層
- **JSONマッピング**: 透過的なオブジェクトリレーショナルマッピング

## 🚀 クイックスタート

### ORMCPを使用するための3つの簡単な手順

**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サーバーをインストールする

**ベータ版ユーザー（GemfuryプライベートPyPI）の場合:**

ベータアクセスをリクエストし、トークンを受け取るには、[softwaretree.com/products/ormcp](https://www.softwaretree.com)を参照してください。

```bash
# トークンを使用してインストール
# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# インストールを確認
pip show ormcp-server

YOUR_TOKENをベータアクセストークンに置き換えてください。

📌 Linux/Macユーザー: 最新のLinuxディストリビューションでは、仮想環境が必要です。「externally-managed-environment」エラーが発生した場合は、トラブルシューティングを参照してください。

# 仮想環境を作成してアクティブ化する（最新のLinuxで必要）
python3 -m venv .venv
source .venv/bin/activate

# トークンを使用してインストール
pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

本番ユーザー（PyPI）の場合:

# PyPIからインストール（ベータ版終了後利用可能）
pip install ormcp-server

# インストールを確認
pip show ormcp-server

Windowsユーザー - PythonスクリプトをPATHに追加する:

'ormcp-server' is not recognizedエラーが発生した場合は、PythonのScriptsディレクトリをPATHに追加してください。

# オプション1: クイックコマンド（PowerShellで実行し、ターミナルを再起動）
setx PATH "%PATH%;%APPDATA%\Python\Python313\Scripts"

# オプション2: 直接完全パスを使用
%APPDATA%\Python\Python313\Scripts\ormcp-server.exe

Scriptsディレクトリを見つけるには:

# Windows
pip show -f ormcp-server | findstr "Location"
# Scriptsフォルダは: Location\..\..\Scripts\ にあります。

# Linux/Mac
pip show -f ormcp-server | grep Location
# binフォルダは: ~/.local/bin/ にあります。

Linux/Macユーザー:

ormcp-serverコマンドが見つからない場合は:

# ~/.bashrcまたは~/.zshrcにPATHを追加
export PATH="$HOME/.local/bin:$PATH"

# シェルを再読み込み
source ~/.bashrc  # または source ~/.zshrc

2. Gilhariマイクロサービスをセットアップする

詳細なセットアップについては、以下のGilhariマイクロサービスのセットアップセクションを参照してください。

注意: 完全な動作例は別のリポジトリにあります: gilhari_example1

例を実行するには:

# サンプルGilhariマイクロサービスの例のリポジトリをクローンする
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# GilhariのDockerイメージを取得
docker pull softwaretree/gilhari:latest

# サンプルGilhariマイクロサービスのDockerイメージをビルド
./build.cmd  # Windowsの場合
# または
./build.sh   # Linux/Macの場合

# サンプルマイクロサービスを実行
docker run -p 80:8081 gilhari_example1:1.0

# オプション: サンプルデータでデータベースを埋める
./curlCommandsPopulate.cmd  # Windowsの場合
# または
./curlCommandsPopulate.sh   # Linux/Macの場合

3. 環境を設定する

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

# Windows（コマンドプロンプト）
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サーバーを起動する

ormcp-server

コマンドが見つからないエラーが発生した場合は、上記の手順1のPATH構成を参照するか、以下を使用してください:

# Windows - 完全パス
%APPDATA%\Python\Python313\Scripts\ormcp-server.exe

# Linux/Mac - 完全パス
~/.local/bin/ormcp-server

# またはPythonを直接使用
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

# またはpipを使用
pip show -f ormcp-server | findstr "Location"

# Linux/Mac
which ormcp-server

準備完了です！これでAIクライアントが自然言語を使用してデータベースと対話できるようになりました。

注意: クライアントとしてClaude Desktopを使用する場合は、手順3（環境を設定する）と手順4（ORMCPサーバーを起動する）は必要ありません。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歳のJohn Smithという新しいユーザーを追加してください"

生成された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ソフトウェアをインストールする

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マイクロサービスを示しています。

例を使ったクイックスタート:

# 例のリポジトリをクローンする
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# サンプルGilhariマイクロサービスのDockerイメージをビルド
./build.cmd  # Windowsの場合
# または
./build.sh   # Linux/Macの場合

# サンプルマイクロサービスを実行
docker run -p 80:8081 gilhari_example1:1.0

# オプション: サンプルデータでデータベースを埋める
./curlCommandsPopulate.cmd  # Windowsの場合
# または
./curlCommandsPopulate.sh   # Linux/Macの場合

詳細なセットアップと構成手順については、gilhari_example1のREADMEを参照してください。

ORMCPパッケージのインストール

推奨: 仮想環境

# 仮想環境を作成してアクティブ化
python -m venv .venv

# 環境をアクティブ化
# Linux/Mac:
source .venv/bin/activate
# Windows（コマンドプロンプト）:
.venv\Scripts\activate
# Windows（PowerShell）:
.venv\Scripts\Activate.ps1

# ORMCPサーバーをインストール
# ベータ版（Gemfury）:
# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# 本番版（PyPI） - ベータ版終了後利用可能:
# pip install ormcp-server

YOUR_TOKENをsoftwaretree.com/products/ormcpから取得したベータアクセストークンに置き換えてください。

グローバルインストール

ベータ版（Gemfury）:

# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip install --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

YOUR_TOKENをベータアクセストークンに置き換えてください。

本番版（PyPI） - ベータ版終了後利用可能:

pip install ormcp-server

注意: 仮想環境を使用せずにグローバルにインストールする場合、ormcp-server実行ファイルはユーザーのPython Scriptsディレクトリにインストールされます。「コマンドが見つからない」エラーが発生した場合は、クイックスタートのPATH構成手順を参照してください。

SDKとサンプルを含む完全パッケージにアクセスする

Gilhari SDK、サンプル、およびドキュメントを含む完全パッケージにアクセスするには:

ベータ版（Gemfury）:

# ソース配布物をダウンロード
# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# 展開（適切なバージョン番号を使用）
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# これで以下にアクセスできます:
# - Gilhari_SDK/          (ドキュメント付きの完全なSDK)
# - gilhari_example1/     (すぐに使えるサンプルマイクロサービス)
# - package/client/       (サンプルクライアントコード)
# - package/docs/         (追加の技術ドキュメント)

YOUR_TOKENをベータアクセストークンに置き換えてください。

本番版（PyPI） - ベータ版終了後利用可能:

# ソース配布物をダウンロード
pip download --no-binary :all: ormcp-server

# 展開
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Windowsユーザー: tarがインストールされていない場合は、以下の方法があります:

• 7-ZipまたはWinRARを使用して.tar.gzファイルを展開する
• またはPowerShellを使用: tar -xzf ormcp_server-*.tar.gz
• またはGemfury/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/Gemfuryからダウンロード

ベータ版（Gemfury）:

# ソース配布物（.tar.gz）をダウンロード
# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

# 展開（適切なバージョン番号を使用; 例: 0.4.x）
tar -xzf ormcp_server-0.4.x.tar.gz
cd ormcp_server-0.4.x

# これで以下にアクセスできます:
# - Gilhari_SDK/
# - gilhari_example1/
# - package/client/
# - package/docs/

YOUR_TOKENをベータアクセストークンに置き換えてください。

本番版（PyPI） - ベータ版終了後利用可能:

# ソース配布物をダウンロード
pip download --no-binary :all: ormcp-server

# 展開
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Windowsユーザー: tarがインストールされていない場合は、以下の方法があります:

• 7-ZipまたはWinRARを使用して.tar.gzファイルを展開する
• またはPowerShellを使用: tar -xzf ormcp_server-0.4.x.tar.gz
• またはGemfury/PyPIウェブサイトから直接ダウンロードする

オプション2: パッケージページからダウンロード

ベータ版: ormcp_support@softwaretree.comに直接ダウンロードリンクをリクエストしてください。

本番版（ベータ版終了後）: https://pypi.org/project/ormcp-server/にアクセスし、.tar.gzファイルをダウンロードしてください。

「Download files」セクションを探し、ソース配布物（.tar.gz）をダウンロードします。

Gilhari SDKを使用する

ソース配布物を展開した後:

# SDKに移動
cd Gilhari_SDK

# ドキュメントを読む
# - READMEファイルをチェックしてセットアップ手順を確認する
# - examples/ディレクトリのサンプルを確認する
# - ORM仕様の詳細についてAPIドキュメントを参照する

# SDKには以下が含まれています:
# - Gilhari Dockerベースイメージの情報
# - ドキュメント（README、APIガイド）
# - サンプルアプリケーション
# - 既存のデータベースからORMをリバースエンジニアリングするためのツール
# - JDX文法仕様

サンプルGilhariマイクロサービスを実行する

# サンプルに移動
cd gilhari_example1

# そのディレクトリのREADME.mdに従って:
# 1. Dockerイメージをビルドする
# 2. マイクロサービスを実行する
# 3. サンプルデータを埋める
# 4. ORMCPサーバーでテストする

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

• Wheel (.whl) - バイナリ配布物で、インストールが高速で、ランタイムコードのみが含まれています（約50KB）
• ソース配布物 (.tar.gz) - すべてのリソースを含む完全パッケージです（数MB）

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

• カスタムマイクロサービスを作成するためのGilhari SDKが必要な場合
• サンプルアプリケーションとクライアントコードが必要な場合
• 完全なドキュメントが必要な場合
• 追加の技術ガイドが必要な場合

ORMCPサーバーの設定

環境変数を使用して設定します。

変数	説明	デフォルト	例
GILHARI_BASE_URL	GilhariマイクロサービスのURL	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	アプリケーション固有のGilhariマイクロサービスのDockerイメージ名	""	gilhari_example1:1.0
GILHARI_HOST	GilhariマイクロサービスのホストマシンのIPアドレス	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（コマンドプロンプト）
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（コマンドプロンプト）
.venv\Scripts\activate

# Windows（PowerShell）
.venv\Scripts\Activate.ps1

CLIコマンドを使用してサーバーを起動します。

ormcp-server

これにより、main.pyエントリポイントを介してMCPサーバーがstdioモードで実行されます。

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

'ormcp-server' is not recognizedまたはコマンドが見つかりませんエラーが発生した場合:

Windows:

# オプション1: 完全パスを使用
%APPDATA%\Python\Python313\Scripts\ormcp-server.exe

# オプション2: ScriptsをPATHに追加（クイックスタートセクションを参照）
setx PATH "%PATH%;%APPDATA%\Python\Python313\Scripts"
# その後、ターミナルを再起動

# オプション3: Pythonモジュールを直接使用
python -m ormcp_server

Linux/Mac:

# オプション1: 完全パスを使用
~/.local/bin/ormcp-server

# オプション2: ~/.bashrcまたは~/.zshrcにPATHを追加
export PATH="$HOME/.local/bin:$PATH"
source ~/.bashrc  # または source ~/.zshrc

# オプション3: Pythonモジュールを直接使用
python -m ormcp_server

ソースコードを直接使用する（上級者向け）

注意: ソース配布物が必要です。以下を使用してダウンロードします。

# 注意: --extra-index-urlが必要です。ビルド依存関係（hatchlingなど）はPyPIで利用可能ですが、Gemfuryでは利用できません。
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  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を使用してサーバーの機能を調べることができます。

# インストールされたパッケージを使用
npx @modelcontextprotocol/inspector python -m ormcp_server

# またはコマンドがPATHにある場合
npx @modelcontextprotocol/inspector ormcp-server

これにより、ソース配布物を必要とせずに、ORMCP Serverツールを対話的にテストして調べることができます。

HTTPまたはSSEトランスポートのサポート

注意: 現在、stdioトランスポートのみがデフォルトで完全にサポートされています。HTTPまたはSSEトランスポートのサポートは実験的です。

コマンドラインからHTTPモードでORMCPサーバーを起動することができます。

# 基本的なHTTPモード
python src/ormcp_server.py --transport http

# またはCLIを使用
ormcp-server --mode http

ホストとポートをカスタマイズする:

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

# またはCLIを使用
ormcp-server --mode http --host 0.0.0.0 --port 9000

利用可能なコマンドラインオプション:

• --mode / --transport: "stdio"（デフォルト）または"http"から選択
• --host: ホストアドレスを設定（デフォルト: 127.0.0.1、HTTPモードでのみ使用）
• --port: ポート番号を設定（デフォルト: 8080、HTTPモードでのみ使用）

クイックHTTPセットアップ:

python src/ormcp_server.py --transport http
# または
ormcp-server --mode http

HTTPモードではuvicornが依存関係として必要です。アプリケーションを提供するために使用されます。

HTTPモードでの使用

HTTPモードで実行されるMCPサーバーは、ウェブブラウザから直接アクセスするように設計されていません。これは特定のMCPプロトコルメッセージを期待するAPIサーバーであり、ルートパスへのHTTP GETリクエストではなく、特定のMCPプロトコルメッセージを期待しています。

まとめ

• ormcp-server CLIを使用すると、最もクリーンで推奨されるエクスペリエンスが得られます。
• 直接python src/ormcp_server.pyを使用すると、ソース配布物を使用したシンプルな実行が可能です。
• mcp devまたはfastmcp runを使用すると、ソース配布物を使用した高度な開発/テストシナリオが可能です。

期待される出力

[INFO] ORMCPサーバー名: ORMCPServerDemo
[INFO] GILHARI BASE URL: http://localhost:80/gilhari/v1/
[INFO] ORMCPサーバーv0.4.xがstdio（またはhttp）モードで起動しています...

MCPクライアントの設定

Claude Desktop

オプション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（コマンドプロンプト）
where ormcp-server

# Linux/Mac
which ormcp-server

# 任意のプラットフォーム
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": [
        "--mode", "http",
        "--port", "8080"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServerHTTP"
      }
    }
  }
}

注意事項:

• ORMCPServerDemoはORMCPサーバーのデフォルト名です。
• <YourUsername>を実際のWindowsユーザー名に置き換えてください。
• 「GILHARI_BASE_URL」環境変数を介して関連するGilhariマイクロサービスのポート番号を指定する場合、そのポートがGilhariマイクロサービスがリッスンしているポートであることを確認してください。
• 注意: 2025年7月20日現在、Claudeデスクトップは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サーバーを起動します。これはウェブベースのクライアントに必要です。

     # プロジェクトのルートディレクトリから実行
     ormcp-server --mode 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を使用する

     • 新しいターミナルで、ポート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サーバーURLフィールドに貼り付けます。GPTはそれにより、ORMCPサーバーが提供するツールを検出して接続します。

その他のMCPクライアント

• ORMCPサーバーに接続し、ORMCPサーバーが提供するMCP互換ORMツールを使用します。
• 適切なトランスポートモード（STDIOまたはHTTP）を使用して、クライアントのMCPサーバーセットアップ要件に従って構成します。
• 📚 統合ガイド: ORMCPサーバーへの接続に関する詳細なドキュメントは以下を参照してください:
  • MCPプロトコルリファレンス - 低レベルのJSON-RPCプロトコルの詳細
  • ORMCPクライアントサンプルの使用方法 - Pythonクライアントの使用ガイド
  • STDIOモードでのORMCPサーバーとの対話 - STDIOトランスポートガイド
  • HTTPモードでのORMCPサーバーとの対話 - HTTPトランスポートガイド
  • 追加のガイドはドキュメントリポジトリ（ソース配布物にも含まれています）にあります。

MCPツールのリファレンス

ORMCPサーバーは、データベースとの対話のために以下のMCPツールを提供します。

📖 詳細なAPIドキュメント: 完全なパラメータ仕様と技術的詳細については、MCPツールAPIリファレンスを参照してください。

💡 実際の使用例: examplesディレクトリで実際の使用例を確認できます。

コア操作

getObjectModelSummary

基になるオブジェクトモデルに関する情報を取得します。

戻り値: ドメインモデル内のクラス（タイプ）、属性、主キー、および関係に関する情報。

query

フィルタリングと関係のトラバーサルを使用してオブジェクトをクエリします。

パラメータ:

• className (文字列): クエリするオブジェクトのタイプ
• filter (文字列, オプシ