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 请求令牌

---

用心为人工智能和数据库社区打造