Ormcp Docs

🚀 ORMCP Server - 測試版

一款基於模型上下文協議（MCP）的服務器，用於將您的人工智能應用程序連接到關係型數據庫

ORMCP 服務器使人工智能大語言模型（LLMs）和 MCP 客戶端能夠使用 MCP 標準協議，輕鬆地與任何關係型數據庫交換面向對象的數據（JSON 格式）。

ORMCP 服務器讓您的關係型數據做好迎接人工智能的準備。

⚠️ 測試版聲明

ORMCP 服務器目前處於測試版，我們向希望試用該軟件、提供反饋並幫助我們確保產品達到最高質量標準的用戶提供早期訪問權限。此測試版不用於商業用途，僅用於測試目的。

📋 目錄

• 什麼是 MCP？
• ✨ 主要特性
• 💡 工作原理
• 🚀 快速開始
• 📦 安裝指南
• 📁 Gilhari 微服務設置
• ⚙️ 配置說明
• 🏁 啟動服務器
• 👨‍💻 客戶端配置
• 💻 使用示例
• 📚 MCP 工具參考
• ❓ 故障排除
• 🛠️ 開發說明
• 🤝 貢獻指南
• 📄 許可證
• 📘 支持與資源

什麼是 MCP？

模型上下文協議（MCP）是一種開放標準，它為人工智能模型與外部工具和數據源進行交互提供了統一的方式。它對通信進行了標準化，使得在不針對每個用例構建自定義 API 集成的情況下，更輕鬆地將大語言模型集成到複雜的工作流程中。

瞭解更多信息，請訪問 MCP 官方網站。

✨ 主要特性

• ✅ 標準化接口：完全符合模型上下文協議（MCP）規範。
• 🌐 數據庫無關性：可與任何支持 JDBC 的數據庫配合使用（例如，PostgreSQL、MySQL、Oracle、SQL Server、DB2、SQLite）。
• ↔️ 雙向數據流：實現人工智能與數據庫之間的無縫通信，還可選支持只讀操作。
• 🔄 對象關係映射（ORM）：將 JSON 對象操作（CRUD）透明地映射到關係型數據。
• 🔒 安全的數據訪問：特定於領域模型的操作有助於保護數據。
• 🧾 聲明式 ORM 規範：基於簡單語法的直觀、非侵入式且靈活的 ORM 規範。
• 🕸️ 支持複雜對象建模：包括一對一、一對多和多對多關係，以及路徑表達式。
• 🖇️ 靈活的查詢：支持深度和淺層查詢，以及各種類似於 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)   |                                 |
         |<-------------------------------|                                 |

重要提示：人工智能應用程序（大語言模型客戶端）將自然語言轉換為 MCP 工具調用。然後，ORMCP 服務器將這些 MCP 工具調用轉換為對 Gilhari 的 REST API 調用。

ORMCP 服務器通過以下方式彌合了現代人工智能應用程序與關係型數據庫之間的差距：

• MCP 協議：標準化的人工智能與工具之間的通信。
• Gilhari：通過 ORM 和 JDBC 與關係型數據庫進行集成的中間層。
• JSON 映射：透明的對象關係映射。

🚀 快速開始

使用 ORMCP 的三個簡單步驟

1. 確定數據範圍

• 為您的相關數據定義輕量級的對象模型。
• 使用簡單的（JDX）語法在文本文件中為這些模型編寫聲明式 ORM 規範。

2. 構建您的 Gilhari 微服務

• 將模型、ORM 規範和 JDBC 驅動程序添加到 Dockerfile 中。
• 構建 Gilhari Docker 鏡像。

3. 與 ORMCP 一起運行

• 將 ORMCP 連接到 Gilhari 微服務。
• 啟動 Gilhari，然後啟動 ORMCP。
• 使用人工智能代理或 MCP 客戶端以直觀的面向對象方式與指定範圍的關係型數據進行交互。

---

詳細快速開始指南

前提條件

• Python 3.12 或更高版本
• Docker（用於 Gilhari 微服務）
• 目標數據庫的 JDBC 驅動程序

1. 安裝 ORMCP 服務器

測試版用戶（Gemfury 私有 PyPI）：

在 softwaretree.com/products/ormcp 請求測試版訪問權限並獲取令牌。

# 使用令牌進行安裝
# 注意：--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"

# 然後重新加載 shell
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. 連接您的人工智能客戶端

對於 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

您已準備就緒！您的人工智能客戶端現在可以使用自然語言與您的數據庫進行交互。

注意：如果您使用 Claude Desktop 作為客戶端，則不需要步驟 3（配置環境）和步驟 4（啟動 ORMCP 服務器），因為 Claude Desktop 會自動以 STDIO 模式啟動已配置的 ORMCP 服務器。

💻 使用示例

查詢數據

人工智能提示：“顯示所有年齡大於或等於 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"}
]

插入數據

人工智能提示：“添加一個新用戶（id = 65），名為 John Smith，來自馬薩諸塞州波士頓，年齡為 65 歲”

生成的 MCP 調用：

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

聚合數據

人工智能提示：“加利福尼亞州用戶的平均年齡是多少？”

生成的 MCP 調用：

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

結果：

49

Gilhari 微服務設置

ORMCP 服務器依賴於 Gilhari 軟件，這是一個用於將 JSON 數據集成到數據庫的微服務框架。在啟動 ORMCP 服務器之前，必須完成此設置。

安裝 Gilhari 軟件

1. 拉取 Gilhari Docker 鏡像：

   docker pull softwaretree/gilhari:latest
   

2. 安裝 Gilhari SDK：

   • Gilhari 軟件的 SDK 包含在 ORMCP 服務器包的 Gilhari_SDK 文件夾中。
   • 您也可以從以下地址下載：https://www.softwaretree.com/v1/products/gilhari/download-gilhari.php
   • SDK 包含文檔（README 文件、API 指南、示例應用程序），可幫助您輕鬆使用 Gilhari 軟件。

配置特定於應用程序的 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。此示例展示了一個管理 用戶 對象的 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 服務器包除了 Python 代碼外，還包含其他資源：

運行時安裝（Wheel）

當您通過 pip 安裝時，您將獲得運行 ORMCP 服務器所需的核心 Python 包：

pip install ormcp-server

這隻會將必要的運行時文件安裝到您的 Python 環境中。

包含 SDK 和文檔的完整包（源代碼分發版）

完整包包含：

• Gilhari_SDK/ - 包含文檔、示例和工具的完整 SDK，用於創建自定義 Gilhari 微服務。
• 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/ 目錄中的示例
# - 查看 API 文檔以瞭解 ORM 規範詳細信息

# SDK 包含：
# - Gilhari Docker 基礎鏡像信息
# - 文檔（README 文件、API 指南）
# - 示例應用程序
# - 用於從現有數據庫逆向工程 ORM 的工具
# - JDX 語法規範

運行示例 Gilhari 微服務

# 導航到示例目錄
cd gilhari_example1

# 按照該目錄中的 README.md 文件進行操作：
# 1. 構建 Docker 鏡像
# 2. 運行微服務
# 3. 填充示例數據
# 4. 使用 ORMCP 服務器進行測試

為什麼有兩種包格式？

• Wheel (.whl) - 二進制分發版，安裝速度快，僅包含運行時代碼（約 50KB）。
• 源代碼分發版 (.tar.gz) - 包含所有資源的完整包（約幾 MB）。

大多數用戶只需要 wheel 包來運行 ORMCP 服務器。如果您需要以下內容，請下載源代碼分發版：

• 用於創建自定義微服務的 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，則 ORMCP 服務器 不會向 MCP 客戶端暴露可能修改數據的 MCP 工具（例如，insert、update、update2、delete、delete2）。默認情況下，所有 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 入口點以 stdio 模式運行 MCP 服務器。

故障排除 - 命令未找到：

如果您遇到 'ormcp-server' is not recognized 或 command not found 錯誤：

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 服務器工具。

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

請確保您已經安裝了 uvicorn 作為依賴項，因為 HTTP 模式使用它來提供應用程序服務。

HTTP 模式下的使用

以 HTTP 模式運行的 MCP 服務器並非設計用於通過 Web 瀏覽器直接訪問。它是一個 API 服務器，期望接收特定的 MCP 協議消息，而不是對根路徑的 HTTP GET 請求。

總結

• 使用 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.4.x starting in stdio (or http) mode ...

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 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 服務器，因為基於 Web 的客戶端需要此模式。

     # 從項目根目錄運行
     ormcp-server --mode http --port 8080
     

3. 使用公共 URL 暴露服務器： OpenAI 的服務器需要一個公共 Web 地址來訪問您的本地 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）。請注意，在免費計劃下，每次重啟 ngrok 時此 URL 都會更改。

4. 連接到您的自定義 GPT：

   • 獲取 cloudflared 或 ngrok 生成的公共 URL。
   • 在該 URL 末尾添加 /mcp。最終結果將是您的 MCP 端點，例如：https://<your-public-url>/mcp。
   • 在您的 GPT 配置設置（設置 → 應用程序與連接器 → 創建）中，將此完整 URL 粘貼到 MCP 服務器 URL 字段中。GPT 將發現並連接到 ORMCP 服務器提供的工具。

其他 MCP 客戶端

• 連接到 ORMCP 服務器，並使用 ORMCP 服務器提供的 MCP 兼容 ORM 工具。
• 根據您的客戶端的 MCP 服務器設置要求，使用適當的傳輸模式（STDIO 或 HTTP）進行配置。
• 📚 集成指南：有關連接到 ORMCP 服務器的詳細文檔，請參閱：
  • MCP 協議參考 - 底層 JSON-RPC 協議詳細信息。
  • 使用 ORMCP 客戶端示例 - Python 客戶端使用指南。
  • 在 STDIO 模式下與 ORMCP 服務器交互 - STDIO 傳輸指南。
  • 在 HTTP 模式下與 ORMCP 服務器交互 - HTTP 傳輸指南。
  • 其他指南可在 文檔倉庫 中找到（也包含在源代碼分發版中）。

MCP 工具參考

ORMCP 服務器提供以下 MCP 工具，用於與您的數據庫進行交互。

📖 詳細 API 文檔：有關完整的參數規範和技術細節，請參閱 MCP 工具 API 參考。

💡 實際示例：請參閱 示例目錄 中的實際使用示例。

核心操作

getObjectModelSummary

檢索底層對象模型的信息。

返回值：有關您的領域模型中的類（類型）、屬性、主鍵和關係的信息。

query

使用過濾和關係遍歷查詢對象。

參數：

• className（字符串）：要查詢的對象類型。
• filter（字符串，可選）：用於過濾的類似 SQL 的 WHERE 子句。
• maxObjects（整數，可選）：要檢索的最大對象數（-1 表示所有對象，默認值：-1）。
• deep（布爾值，可選）：在結果中包含引用的對象（默認值：true）。
• operationDetails（字符串，可選）：用於微調查詢的操作指令的 JSON 數組。支持類似 GraphQL 的操作，例如：
  • projections：僅檢索特定屬性。
  • ignore 或 follow：控制引用的對象分支。
  • filter：對引用的對象應用過濾器。

getObjectById

通過主鍵檢索特定對象。

參數：

• className（字符串）：要檢索的對象類型。
• primaryKey（對象）：主鍵值（單個值或複合鍵對象）。
• deep（布爾值，可選）：包含引用的對象（默認值：true）。
• operationDetails（字符串，可選）：用於微調查詢的操作指令。

access

檢索引用對象的特定屬性所引用的對象。

參數：

• className（字符串）：引用對象的類型。
• jsonObject（對象）：包含引用的引用對象。
• attributeName（字符串）：要檢索其引用值的屬性名稱。
• deep（布爾值，可選）：也包含檢索對象的引用對象（默認值：true）。
• operationDetails（字符串，可選）：用於微調查詢的操作指令。

getAggregate

計算對象的聚合值（COUNT、SUM、AVG、MIN、MAX）。

參數：

• className（字符串）：要聚合的對象類型。
• attributeName（字符串）：要執行聚合的屬性。
• aggregateType（字符串）：聚合類型 - COUNT、SUM、AVG、MIN、MAX。
• filter（字符串，可選）：用於在聚合前過濾對象的類似 SQL 的 WHERE 子句。

數據修改操作

insert

將一個或多個 JSON 對象保存到數據庫中。

參數：

• className（字符串）：要插入的對象類型。
• jsonObjects（數組）：要保存到數據庫的 JSON 對象列表。
• deep（布爾值，可選）：也保存引用的對象（默認值：true）。

update

使用新值更新一個或多個現有對象。

參數：

• className（字符串）：要更新的對象類型。
• jsonObjects（數組）：包含更新值的對象列表（必須包含主鍵）。
• deep（布爾值，可選）：也更新引用的對象（默認值：true）。

update2

批量更新符合過濾條件的對象。

參數：

• className（字符串）：要更新的對象類型。
• filter（字符串）：用於識別要更新的對象的類似 SQL 的 WHERE 子句。
• newValues（數組）：屬性名稱及其新值的列表。
• deep（布爾值，可選）：也更新引用的對象（默認值：true）。

delete

從數據庫中刪除特定對象。

參數：

• className（字符串）：要刪除的對象類型。
• jsonObjects（數組）：要刪除的對象（需要主鍵進行識別）。
• deep（布爾值，可選）：也刪除引用的對象（默認值：true）。

delete2

批量刪除符合過濾條件的對象。

參數：

• className（字符串）：要刪除的對象類型。
• filter（字符串，可選）：用於識別要刪除的對象的類似 SQL 的 WHERE 子句（空字符串表示刪除指定類的所有對象）。
• deep（布爾值，可選）：也刪除引用的對象（默認值：true）。

注意：當 READONLY_MODE=True 時，用於數據修改操作的 MCP 工具（insert、update、update2、delete、delete2）不會暴露給 MCP 客戶端。

故障排除

有關常見問題和解決方案，請參閱 完整故障排除指南。

快速故障排除

安裝問題：

• 命令未找到 → 將 Python Scripts 目錄添加到 PATH。
• 外部管理環境 → 使用虛擬環境（請參閱 故障排除指南）。
• 可執行文件為空 → 重新安裝包。
• 缺少依賴項 → pip install --force-reinstall ormcp-server。

Gilhari 示例問題：

• 腳本權限被拒絕 → chmod +x *.sh 或使用 sh build.sh。
• 數據庫連接錯誤 → 驗證 Gilhari 中的 JDBC 驅動程序。

運行時問題：

• 服務器無法啟動 → 檢查 Gilhari 是否正在運行。
• 數據庫連接錯誤 → 驗證 Gilhari 中的 JDBC 驅動程序。
• MCP 客戶端連接問題 → 檢查配置文件語法。

啟用調試模式：

# Linux/Mac
export LOG_LEVEL=DEBUG
ormcp-server

# Windows（命令提示符）
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

開發說明

測試

對於使用源代碼分發版進行測試和開發：

測試版（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-*/

# 以開發模式安裝
pip install -e ".[dev]"

# 運行測試（如果源代碼分發版中提供）
pytest

將 YOUR_TOKEN 替換為您的測試版訪問令牌。

生產版（PyPI） - 測試版結束後可用：

# 下載源代碼分發版
pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# 以開發模式安裝
pip install -e ".[dev]"

# 運行測試
pytest

Gilhari 微服務開發

• ORMCP 服務器 利用 Gilhari 軟件，這是一個用於將 JSON 數據集成到數據庫的 RESTful 微服務框架。
• 您首先根據應用程序的對象關係數據模型創建自定義 Gilhari 微服務。
• 對象關係映射（ORM）規範定義並控制與您的關係模型對應的對象模型的範圍和形狀。
• ORM 規範基於簡單語法在文本文件（.jdx）中以聲明方式定義。
• 您可以使用 Gilhari SDK 提供的工具/示例從現有數據庫模式逆向工程 ORM 規範。請查看 examples\JDX_ReverseEngineeringJSONExample 目錄。
• 有關創建自定義 Gilhari 微服務的詳細信息，請參閱源代碼分發版包中包含的 Gilhari SDK 文檔。
• 儘管 ORMCP 服務器可以在配置後啟動 Gilhari 微服務（使用 GILHARI_IMAGE、GILHARI_NAME 和 GILHARI_PORT 環境變量），但建議在使用 ORMCP 服務器之前啟動您的自定義 Gilhari 微服務。另外，請確保 ORMCP 服務器的 'GILHARI_BASE_URL' 環境變量中的端口號與自定義 Gilhari 微服務監聽傳入 REST 調用的端口號匹配。

貢獻指南

感謝您對 ORMCP 服務器的關注！

🚫 目前不接受代碼貢獻

ORMCP 服務器是專有軟件。我們 不接受 代碼貢獻、拉取請求或功能提交。

🐞 反饋和錯誤報告

我們 歡迎 對測試版的反饋！您可以通過以下方式幫助我們改進 ORMCP 服務器：

• 報告錯誤或問題。
• 提出改進建議。
• 分享您的使用經驗。

如何提供反饋

• GitHub 問題：報告問題或提出建議
• 電子郵件：ormcp_support@softwaretree.com

您提供的任何反饋都可能被 Software Tree 用於改進產品，無需對您進行任何致謝或補償。

第三方軟件

Gilhari 依賴項： ORMCP 服務器需要 Gilhari 微服務才能正常工作。Gilhari 包含各種第三方軟件組件。有關這些第三方組件及其許可證的完整詳細信息，請參閱 Gilhari SDK 中的 LICENSE 文件或訪問：https://www.softwaretree.com/v1/products/gilhari/。

Python 依賴項： ORMCP 服務器使用以下開源 Python 庫，每個庫都遵循各自的許可證：

• mcp（模型上下文協議 SDK）
• fastmcp（FastMCP 框架）
• httpx（HTTP 客戶端庫）
• pydantic（數據驗證庫）
• uvicorn（ASGI 服務器）
• requests（HTTP 庫）

許可證

ORMCP 服務器是 Software Tree, LLC 擁有的專有軟件。完整條款請參閱 LICENSE 文件。

測試版評估：ORMCP 服務器目前作為測試版產品提供，採用評估許可證。這允許在有限的評估期內（從首次使用起約 2 個月）免費用於測試和評估目的。

Gilhari 依賴項：ORMCP 服務器需要 Gilhari 微服務才能正常工作。使用 ORMCP 服務器即表示您同意遵守 Gilhari 許可協議。Gilhari 包含各種第三方軟件組件。詳細信息請參閱 Gilhari SDK 中的 LICENSE 文件或訪問 https://www.softwaretree.com/v1/products/gilhari/。

商業許可：商業許可條款將在商業發佈時公佈。如需瞭解信息或表達興趣，請通過 ormcp_support@softwaretree.com 聯繫 Software Tree，或訪問 https://www.softwaretree.com。

支持與資源

• 文檔：完整文檔和指南
• 實際示例：瀏覽示例 | 示例指南 - 實際用例和集成。
• 示例微服務：gilhari_example1 倉庫
• 錯誤報告：報告問題
• 電子郵件支持：ormcp_support@softwaretree.com
• Gilhari 支持：Software Tree Gilhari 文檔
• MCP 協議：MCP 官方網站
• 測試版訪問：在 softwaretree.com 請求令牌

---

用心為人工智能和數據庫社區打造