ORMCP Server

Copyright (c) 2025, Software Tree

ORMCP Server - Beta

最后更新：2026-10-06（ORMCP 0.7.1）

一种 Model Context Protocol（MCP）服务，可将 AI 应用连接到关系数据库

ORMCP Server 让 AI 大模型和 MCP 客户端能够轻松使用 MCP 标准协议，以 JSON 格式与任何关系数据库交换面向对象的数据。

ORMCP Server 让您的关系数据为 AI 做好准备。

⚠️ Beta 版公告

ORMCP Server 目前处于 Beta 阶段。我们正在向希望检查软件、提供反馈并帮助我们确保产品达到最高质量标准的用户提供早期访问权限。此 Beta 版本不适用于商业用途，仅供测试。

📋 目录

• 什么是 MCP？
• 功能
• 工作原理
• 快速开始
• 特定平台指南 — 🍎 macOS · 🪟 Windows · 🐧 Linux
• 安装
• Gilhari 微服务设置
• 配置
• 启动服务
• 客户端配置
• 使用示例
• MCP 工具参考
• 故障排除
• 开发
• 贡献
• 许可证
• 支持与资源

什么是 MCP？

Model Context Protocol（MCP）是一种开放标准，为 AI 模型与外部工具和数据源交互提供统一方式。它规范了通信方式，让大模型更容易集成到复杂工作流中，而无需针对每种使用场景构建自定义 API 集成。

请访问 MCP 官方网站了解更多信息。

✨ 功能

• ✅ 标准化接口： 完全符合 Model Context Protocol（MCP）规范
• 🌐 数据库无关： 适用于任何兼容 JDBC 的数据库（例如 PostgreSQL、MySQL、Oracle、SQL Server、DB2、SQLite）
• ↔️ 双向数据流： 实现 AI ↔ 数据库的无缝通信，并可选择仅支持只读操作
• 🔄 对象关系映射（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)   |                                 |
         |<-------------------------------|                                 |

重要提示： AI 应用（大模型客户端）会将自然语言转换为 MCP 工具调用。ORMCP Server 随后会将这些 MCP 工具调用转换为 Gilhari 的 REST API 调用。

ORMCP Server 通过以下方式弥合现代 AI 应用与关系数据库之间的差距：

• MCP Protocol：标准化 AI 与工具之间的通信
• Gilhari：通过 ORM 和 JDBC 与关系数据库集成的层
• JSON Mapping：透明的对象关系映射

🚀 快速开始

初次使用 ORMCP？请直接跳转到适合你平台的指南，快速完成设置： 🍎 macOS · 🪟 Windows · 🐧 Linux

以下章节涵盖所有平台，可作为完整参考。

使用 ORMCP，只需三个简单步骤

1. 确定数据范围

• 为相关数据定义轻量级对象模型
• 使用简单的 (JDX) 语法，在文本文件中为这些模型编写声明式 ORM 规范

2. 构建 Gilhari 微服务

• 将模型、ORM 规范和 JDBC 驱动程序添加到 Dockerfile
• 构建 Gilhari Docker 镜像

3. 使用 ORMCP 运行

• 将 ORMCP 连接到 Gilhari 微服务
• 先启动 Gilhari，再启动 ORMCP
• 使用 AI Agent 或 MCP 客户端，以直观的面向对象方式与限定范围的关系数据交互

---

快速开始详解

前置条件

• Python 3.12+
• Docker（用于 Gilhari 微服务）
• 目标数据库的 JDBC 驱动程序

1. 安装 ORMCP Server

平台专属指南提供适用于你操作系统的分步安装说明： macOS · Windows · Linux

ORMCP Server 可从公共 PyPI 获取。安装时无需账号、令牌或申请 Beta 访问权限：

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

如果你在之前安装 Beta 版时使用过 Gemfury 令牌，该令牌将不再有效，因为 Gemfury 访问已停止。请使用 pip install ormcp-server，该命令会直接从公共 PyPI 获取软件包。

如果安装后找不到 ormcp-server 命令：

将 Python 可执行文件目录添加到 PATH。详情请参阅你的平台指南： macOS · Windows · Linux

2. 设置 Gilhari 微服务

请参阅下方的 Gilhari 微服务设置章节，了解详细设置方法。

注意： 完整的可运行示例位于单独的代码仓库中：gilhari_example1

运行示例：

重要提示： 构建和运行 Gilhari 微服务需要 Docker。如果你的计算机尚未安装 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
gilhari\build.cmd    # On Windows
# or
./gilhari/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
gilhari\curlCommandsPopulate.cmd    # On Windows
# or
./gilhari/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 服务），因为 Claude Desktop 会自动以 STDIO 模式启动已配置的 ORMCP 服务。

使用示例

查询数据

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"}
]

插入数据

注意： 只有在设置 READONLY_MODE=False 时才会开放 insert（与其他数据修改工具一样）——请参阅 ORMCP 服务配置。在默认的 READONLY_MODE=True 设置下，客户端无法使用此示例中的 MCP 调用。

AI 提示词： “添加一位新用户（id = 65），姓名为 John Smith，来自 Boston, MA，年龄为 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 服务依赖 Gilhari 软件，这是一种用于将 JSON 数据与数据库集成的微服务框架。必须先完成此设置，才能启动 ORMCP 服务。

重要： 构建和运行 Gilhari 微服务需要 Docker——如果你的计算机上尚未安装，请**获取 Docker**

安装 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。此示例演示了一个管理 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
gilhari\build.cmd    # On Windows
# or
./gilhari/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
gilhari\curlCommandsPopulate.cmd    # On Windows
# or
./gilhari/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 目录。如果遇到“找不到命令”错误，请参阅你的平台指南。

获取包含 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 服务软件包除 Python 代码外，还包含其他资源：

运行时安装（Wheel）

通过 pip 安装时，你会获得运行 ORMCP Server 所需的核心 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 下载

# Download the source distribution (.tar.gz)
pip download --no-binary :all: ormcp-server

# Extract it (use the appropriate version number; e.g., 0.7.x)
tar -xzf ormcp_server-0.7.x.tar.gz
cd ormcp_server-0.7.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.7.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) - 二进制分发包，安装快速，仅包含运行时代码（约 50 KB）
• 源码分发包 (.tar.gz) - 包含所有资源的完整软件包（约数 MB）

大多数用户只需使用 wheel 即可运行 ORMCP Server。如果你需要以下内容，请下载源码分发包：

• 用于创建自定义微服务的 Gilhari SDK
• 示例应用和客户端代码
• 完整文档
• 更多技术指南

ORMCP Server 配置

通过环境变量进行配置：

变量	描述	默认值	示例
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
ORMCP_LOG_FILE	日志文件（除控制台外）；设置为 none（或 off）则仅输出到控制台	系统临时目录中的 ormcp_server_debug.log	C:\Logs\ormcp.log、none
READONLY_MODE	仅公开读取操作	True	False
GILHARI_NAME	应用专属 Gilhari 微服务的名称	my-gilhari-microservice	sakila-service
GILHARI_IMAGE	应用专属 Gilhari 微服务的 Docker 镜像名称	""	gilhari_example1:1.0
GILHARI_HOST	启动时可用性检查使用的主机；与 GILHARI_BASE_URL 中的主机不同时使用（极少需要）	GILHARI_BASE_URL 中的主机	10.20.30.40
GILHARI_PORT	启动时可用性检查（以及 ORMCP 启动的容器）使用的端口；与 GILHARI_BASE_URL 中的端口不同时使用（极少需要）	GILHARI_BASE_URL 中的端口	8888
HOST_ORIGIN_PROTECTION	HTTP 模式：拒绝 Host/Origin 标头不受信任的请求（DNS 重绑定防护）	true	false
ALLOWED_HOSTS	HTTP 模式：除默认主机外，其他要信任的主机名，以逗号分隔	无	host.docker.internal,ormcp.internal
ALLOWED_ORIGINS	HTTP 模式：要信任的来源，以逗号分隔	无	https://app.example.com

注意：

• READONLY_MODE 默认为 True：除非明确设置 READONLY_MODE=False，否则 ORMCP 服务不会向 MCP 客户端公开可能修改数据的 MCP 工具（insert、update、update2、delete、delete2）。
• 启动时，ORMCP 会检查 GILHARI_BASE_URL 上的 Gilhari 微服务是否有响应——之后发送所有请求时也会使用同一地址。从 ORMCP 0.7.0 开始，此检查使用的主机和端口取自 GILHARI_BASE_URL，因此只需设置 GILHARI_BASE_URL 即可；GILHARI_HOST 和 GILHARI_PORT 仅用于覆盖该设置，如果它们与 GILHARI_BASE_URL 不一致，ORMCP 会发出警告。
• 如果没有微服务响应，ORMCP 可以自行启动一个：设置 GILHARI_IMAGE（也可选择设置 GILHARI_NAME）；容器的主机端口为 GILHARI_BASE_URL 中的端口（或 GILHARI_PORT）。如果检查仍然失败，ORMCP 会停止运行，并显示它检查的地址以及后续操作说明。
• ORMCP_LOG_FILE：日志文件达到 5 MB 时会轮转，并保留两个旧版本。如果无法写入该文件，ORMCP 会记录警告并继续将日志输出到控制台。在 Windows shell 中，执行 set ORMCP_LOG_FILE= 会移除该变量（使用默认文件）；设置为 none 可关闭文件日志记录。
• HOST_ORIGIN_PROTECTION 接受 true/1/yes/on/strict 和 false/0/no/off；任何其他值（包括 auto）都会保持防护开启并记录警告。ALLOWED_HOSTS/ALLOWED_ORIGINS 仅在防护开启时生效。

配置示例

# 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 模式。

你可以从命令行以 HTTP 模式启动 ORMCP 服务：

# Basic HTTP mode
python src/ormcp_server.py --transport http

# Or using the CLI
ormcp-server --transport http

自定义主机和端口：

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

# Or using CLI
ormcp-server --transport http --host 0.0.0.0 --port 9000

可用的命令行选项：

• --transport：选择 "stdio"（默认）或 "http"
• --host：设置主机地址（默认：127.0.0.1，仅在 HTTP 模式下使用）
• --port：设置端口号（默认：8080，仅在 HTTP 模式下使用）

快速设置 HTTP：

python src/ormcp_server.py --transport http
# or
ormcp-server --transport http

请确保已将 uvicorn 安装为依赖项，因为 HTTP 模式使用它来提供应用服务。

HTTP 模式下的用法

以 HTTP 模式运行的 MCP 服务并非设计为可通过网页浏览器直接访问。它是一个 API 服务，要求接收特定的 MCP 协议消息，而不是向根路径发送 HTTP GET 请求。

总结

• 使用 ormcp-server CLI 可获得最简洁、推荐的体验。
• 使用 python src/ormcp_server.py 可在有源代码分发包的情况下简单运行。
• 使用 mcp dev 或 fastmcp run 可在有源代码分发包的情况下进行高级开发或测试。

预期输出

... - microservice_ensure - INFO - Checking the Gilhari microservice at http://localhost:80/gilhari/v1/health/check
... - microservice_ensure - INFO - Health endpoint check passed for my-gilhari-microservice
... - INFO - Gilhari microservice is available
... - INFO - ORMCP server name: ORMCPServerDemo
... - INFO - GILHARI BASE URL: http://localhost:80/gilhari/v1/
🟢 This ORMCP server is configured to expose just the READONLY MCP tools
... - INFO - Log file: <temp directory>/ormcp_server_debug.log
🟢 ORMCP server v0.7.x starting in stdio (or HTTP) mode ...

如果 GILHARI_BASE_URL 没有 Gilhari 微服务响应，ORMCP 将停止运行，并显示其检查的地址，随后给出 💡“处理方法”提示。

容器化部署（MCP 注册目录）

如需通过 Glama 等 MCP 注册目录部署（例如 Glama），本仓库根目录提供了 start.sh 脚本。该脚本负责在容器化环境中安装并启动 ORMCP Server。所需的环境变量和配置详情请参阅该脚本。

MCP 客户端配置

Claude Desktop

特定平台的配置文件位置和路径设置： macOS · Windows · Linux

选项 1：使用命令名称（需要配置 PATH）

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "ormcp-server",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

选项 2：使用完整路径（推荐用于 Windows）

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "C:\\Users\\<YourUsername>\\AppData\\Roaming\\Python\\Python313\\Scripts\\ormcp-server.exe",
      "args": [],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

查找确切的安装路径：

# Windows (PowerShell)
(Get-Command ormcp-server).Source

# Windows (Command Prompt)
where ormcp-server

# Linux/Mac
which ormcp-server

# Any platform
pip show -f ormcp-server | grep "ormcp-server.exe"  # Windows
pip show -f ormcp-server | grep "ormcp-server$"     # Linux/Mac

选项 3：直接使用 Python 执行

{
  "mcpServers": {
    "my-ormcp-server": {
      "command": "python", 
      "args": [
        "-m",
        "ormcp_server"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

选项 4：使用 FastMCP（适用于拥有源代码分发包的开发者）

{
  "mcpServers": {
    "ORMCPServerDemo": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "<path_to_your_ormcp-server-project>/src/ormcp_server.py"
      ],
      "env": {
        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
        "MCP_SERVER_NAME": "MyORMCPServer"
      }
    }
  }
}

选项 5：HTTP 模式（自定义连接器）

claude_desktop_config.json 仅通过 stdio 启动本地 MCP 服务（选项 1–4）；通过该文件使用 --transport http 启动的服务无法连接。Claude Desktop 只能将 MCP 服务作为自定义连接器通过 HTTP 访问：

1. 以 HTTP 模式启动 ORMCP：ormcp-server --transport http --port 8080
2. 通过 OpenAI GPTs 中所述的 cloudflared 或 ngrok 等工具，使其可通过公共 HTTPS URL 访问。自定义连接器连接自 Anthropic 的云端，而不是你的计算机，因此 localhost URL 无法使用。
3. 允许隧道的主机名，否则 ORMCP 的 Host/Origin 保护会拒绝请求（HTTP 421）：例如 ALLOWED_HOSTS=<your-tunnel-host>。
4. 在 Claude Desktop 中：Settings → Connectors → Add custom connector，输入公共 URL，并在末尾添加 /mcp，例如 https://<your-tunnel-host>/mcp。

所有 Claude 套餐均可使用自定义连接器（免费套餐限用一个）；在 Team 和 Enterprise 套餐中，管理员可能需要先允许使用自定义连接器。

注意：

• ORMCPServerDemo 是 ORMCP 服务的默认名称。
• 将 <YourUsername> 替换为你实际的 Windows 用户名
• 如果你通过 GILHARI\_BASE\_URL 环境变量指定相关 Gilhari 微服务的端口号，请确保该端口是该 Gilhari 微服务正在监听的端口。
• Claude Desktop 仅能通过公共 HTTPS URL 将 HTTP 模式的 ORMCP 服务作为自定义连接器连接（选项 5）；对于本地服务，请使用 stdio（选项 1–4）。

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 的客户端所必需的。

     # 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）。请注意，在免费方案中，每次重启 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 工具。
• 根据客户端的 MCP 服务设置要求，使用相应的传输模式（STDIO 或 HTTP）进行配置。
• **📚 集成指南：**有关如何连接到 ORMCP 服务的详细文档，请参阅：
  • MCP 协议参考 - 低级 JSON-RPC 协议详情
  • 使用 ORMCP 客户端示例 - Python 客户端使用指南
  • 在 STDIO 模式下与 ORMCP 服务交互 - STDIO 传输指南
  • 在 HTTP 模式下与 ORMCP 服务交互 - HTTP 传输指南
  • 文档仓库中还提供了其他指南（也包含在源代码发行包中）

MCP 工具参考

ORMCP Server 提供以下 MCP 工具，用于与数据库交互。

📖 详细 API 文档： 如需完整的参数规范和技术细节，请参阅 MCP 工具 API 参考。

💡 使用示例： 请参阅 示例目录中的实际用法示例。

属性名称，而非列名称： 筛选、投影和聚合使用对象模型摘要（getObjectModelSummary）中的属性名称，而非数据库列名称。

没有唯一主键的类： 对象模型摘要中标记为 DB_PRIMARY_KEY_EXISTS FALSE 的类可能存在多个键值相同的对象。对这类对象，请使用带筛选条件的 query、access、getAggregate 和 update2/delete2；不支持 getObjectById、update 和 delete。

筛选条件： query、getAggregate、update2 和 delete2 的 filter 参数是 SQL WHERE 子句语法中的条件（不含 WHERE 一词），并在数据库中求值，例如 isactive = true AND tier IN ('Gold', 'Platinum')。query 的筛选条件可以以 ORDER BY 结尾，也可以使用路径表达式测试被引用的对象，例如 COUNT(thisObject.listCustomerorder.id) > 10。有关运算符、字面值格式和示例，请参阅筛选语法。

核心操作

getObjectModelSummary

检索底层对象模型的信息。

返回： 有关领域模型中类（类型）、属性、主键和关系的信息。

query

通过筛选和关系遍历查询对象。

参数：

• className（string）：要查询的对象类型

• filter（string，可选）：用于筛选的类 SQL WHERE 子句

• maxObjects（integer，可选）：要检索的对象数上限（-1 表示全部，默认值：-1）

• deep（boolean，可选）：在结果中包含被引用的对象（默认值：true）

• operationDetails（string，可选）：用于微调查询的操作指令 JSON 数组。支持类似 GraphQL 的操作，例如：

  • projections：仅检索特定属性
  • ignore 或 follow：控制被引用对象的分支
  • filters：对被引用的对象应用筛选条件

  投影必须包含类的主键属性，但标记为 DB_PRIMARY_KEY_EXISTS FALSE 的类除外。

• allowDuplicates（boolean，可选）：即使多个行具有相同的主键值，也将每个符合条件的行作为独立对象返回（默认值：false；需要 Gilhari 0.8.7+）

返回： 符合条件的对象 JSON 数组（若无符合条件的对象，则为 []）

getObjectById

根据主键检索特定对象。

参数：

• className（string）：要检索的对象类型
• primaryKey（object）：主键值（单值或复合主键对象）
• deep（boolean，可选）：包含被引用的对象（默认值：true）
• operationDetails（string，可选）：用于微调查询的操作指令

返回： 单个 JSON 对象；如果没有具有该 ID 的对象，则返回 null

access

检索引用对象的特定属性所引用的对象。

参数：

• className（string）：引用对象的类型
• jsonObject（object）：包含该引用的引用对象
• attributeName（string）：要检索其被引用值的属性名称
• deep（boolean，可选）：同时包含检索到的对象所引用的对象（默认值：true）
• operationDetails（string，可选）：用于微调查询的操作指令

返回： 对于集合属性，返回被引用对象的 JSON 数组（若无则为 []）；否则返回被引用的对象

getAggregate

计算对象的聚合值（COUNT、SUM、AVG、MIN、MAX）。

参数：

• className（字符串）：要进行聚合的对象类型
• attributeName（字符串）：要执行聚合的属性
• aggregateType（字符串）：聚合类型——COUNT、SUM、AVG、MIN、MAX
• filter（字符串，可选）：类 SQL WHERE 子句，用于在聚合前筛选对象

**返回：**单个 JSON 值（例如，COUNT 返回 1000），而非对象列表

get_server_version

获取 ORMCP 服务的版本。

**返回：**包含 version、description 和 gilhari_base_url 的 JSON 对象（此服务使用的 Gilhari 微服务；在 0.7.1 中添加）

数据修改操作

**注意：**只有设置 READONLY_MODE=False 时才会公开这些工具——READONLY_MODE 默认为 True，因此开箱即用时无法使用 insert、update、update2、delete 和 delete2。请参阅上文中的 ORMCP 服务配置。

insert

将一个或多个 JSON 对象保存到数据库。

参数：

• className（字符串）：要插入的对象类型
• jsonObjects（数组）：要保存到数据库的 JSON 对象列表
• deep（布尔值，可选）：同时保存引用的对象（默认值：true）

**返回：**操作成功时返回简短的确认消息（纯文本，而非 JSON）；失败时会报告错误

update

使用新值更新一个或多个现有对象。update 会用给定对象替换每个已存储对象（按主键匹配），因此请包含该对象的所有属性。若只需更改部分属性，请使用通过主键筛选的 update2。

参数：

• className（字符串）：要更新的对象类型
• jsonObjects（数组）：包含更新后完整对象的列表（每个对象都包含其主键和其他所有属性）
• deep（布尔值，可选）：同时更新引用的对象（默认值：true）

**返回：**操作成功时返回简短的确认消息（纯文本，而非 JSON）；失败时会报告错误

update2

批量更新符合筛选条件的对象。

参数：

• className（字符串）：要更新的对象类型
• filter（字符串）：用于确定要更新对象的类 SQL WHERE 子句
• newValues（数组）：交替排列的属性名称及其新值列表，例如 ["status", "active", "age", 40]
• deep（布尔值，可选）：同时更新引用的对象（默认值：true）

**返回：**已更新的顶层对象数量

delete

从数据库中删除指定对象。

参数：

• className（字符串）：要删除的对象类型
• jsonObjects（数组）：要删除的对象（需要主键以便识别）
• deep（布尔值，可选）：同时删除引用的对象（默认值：true）

**返回：**操作成功时返回简短的确认消息（纯文本，而非 JSON）；失败时会报告错误

delete2

批量删除符合筛选条件的对象。

参数：

• className（字符串）：要删除的对象类型
• filter（字符串，可选）：用于确定要删除对象的类 SQL WHERE 子句（空字符串会删除指定类的所有对象）
• deep（布尔值，可选）：同时删除引用的对象（默认值：true）

**返回：**已删除的顶层对象数量

注意：READONLY_MODE 默认为 True，因此除非显式设置 READONLY_MODE=False，否则不会向 MCP 客户端公开用于数据修改操作的 MCP 工具（insert、update、update2、delete、delete2）。

故障排除

常见问题及解决方案，请参阅完整故障排除指南。

快速故障排查

安装问题：

• 找不到命令 → 请参阅平台指南进行 PATH 配置：macOS · Windows · Linux
• 环境由外部管理 → 使用虚拟环境（参见故障排查指南）
• 可执行文件为空 → 重新安装软件包
• 缺少依赖项 → pip install --force-reinstall ormcp-server
• 从 v0.6.2 或更早版本升级后遇到 fastmcp ImportError → 请参阅升级后出现 fastmcp 导入错误

Gilhari 示例问题：

• Shell 脚本权限被拒绝 → 执行 chmod +x scripts/*.sh gilhari/*.sh，或使用 sh gilhari/build.sh（Linux/Mac）
• 数据库连接错误 → 在 Gilhari 中验证 JDBC 驱动程序

运行时问题：

• 服务无法启动 → 检查 Gilhari 是否正在运行，以及 GILHARI_BASE_URL 是否包含端口（docker ps 会显示容器的主机端口，例如 0.0.0.0:8130->8081/tcp 表示端口为 8130）；错误消息中会列出 ORMCP 检查的地址
• 查看运行详情 → 查看日志文件（系统临时目录中的 ormcp_server_debug.log，或 ORMCP_LOG_FILE）
• 数据库连接错误 → 在 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
• 电子邮件：[email protected]

开发

测试

使用源代码发行包进行测试和开发：

# 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 software，这是一个用于将 JSON 数据与数据库集成的 RESTful 微服务框架。
• 首先，根据应用程序的对象关系数据模型创建自定义 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 服务之前先启动自定义 Gilhari 微服务。另外，请确保 ORMCP 服务的 'GILHARI_BASE_URL' 环境变量中的端口号与自定义 Gilhari 微服务监听传入 REST 调用的端口号一致；ORMCP 会在启动时检查该地址。

贡献

感谢你对 ORMCP Server 感兴趣！

🚫 目前不接受代码贡献

ORMCP Server 是专有软件。我们不接受代码贡献、拉取请求或功能提交。

🐞 反馈和 Bug 报告

我们欢迎您对 Beta 版本提出反馈！您可以通过以下方式帮助我们改进 ORMCP Server：

• 报告 Bug 或问题
• 提出改进建议
• 分享您的使用体验

如何提供反馈

• GitHub Issues：报告问题或提出建议
• 电子邮件：[email protected]

您提供的任何反馈都可能被 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 文件。

**Beta 评估：**ORMCP Server 目前作为 Beta 产品提供，依据评估许可证使用。该许可证允许在有限的评估期内（自安装之日起 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 许可条款。如需了解详情或表达意向，请通过 [email protected] 联系 Software Tree，或访问 https://www.softwaretree.com。

支持与资源

• 文档：完整文档和指南
• 平台指南：macOS · Windows · Linux
• 实用示例：浏览示例 | 示例指南 - 真实场景用例和集成
• 微服务示例：gilhari_example1 Repository
• 错误报告：报告问题
• 邮件支持：[email protected]
• Gilhari 支持：Software Tree Gilhari 文档
• MCP 协议：MCP 官方网站
• 安装 ORMCP Server：pip install ormcp-server — 无需 beta token。完整设置说明请参阅 softwaretree.com/products/ormcp。

---

为 AI 和数据库社区倾心打造 ❤️