ORMCP

ORMCP proporciona una vista curada, orientada a objetos y compatible con MCP de datos relacionales en cualquier base de datos compatible con JDBC (por ejemplo, PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite), mejorando la claridad del razonamiento, reduciendo el uso de tokens y estableciendo un límite de gobernanza claro.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Copyright (c) 2025, Software Tree

Servidor ORMCP - Beta

Última actualización: 2026-09-15 7:06 PM PDT

Un Servidor de Protocolo de Contexto de Modelo (MCP) para conectar tus aplicaciones de IA a bases de datos relacionales

El Servidor ORMCP permite que los LLMs de IA y los clientes MCP intercambien fácilmente datos orientados a objetos (en formato JSON) con cualquier base de datos relacional utilizando el protocolo estándar MCP.

El Servidor ORMCP hace que tus datos relacionales estén listos para IA.

⚠️ Aviso de Beta

ORMCP Server se encuentra actualmente en Beta, y estamos ofreciendo acceso temprano a usuarios que quieran probar el software, proporcionar comentarios y ayudarnos a garantizar que el producto cumpla con los más altos estándares de calidad. Esta versión Beta no está destinada para uso comercial, y se proporciona solo con fines de prueba.

📋 Tabla de Contenidos

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es un estándar abierto que proporciona una forma unificada para que los modelos de IA interactúen con herramientas externas y fuentes de datos. Estandariza la comunicación, facilitando la integración de LLMs en flujos de trabajo complejos sin necesidad de construir integraciones de API personalizadas para cada caso de uso.

Aprende más en el Sitio Web Oficial de MCP.

✨ Características

  • ✅ Interfaz Estandarizada: Totalmente compatible con la especificación del Protocolo de Contexto de Modelo (MCP)
  • 🌐 Agnóstico de Base de Datos: Funciona con cualquier base de datos compatible con JDBC (por ejemplo, PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)
  • ↔️ Flujo de Datos Bidireccional: Comunicación fluida IA ↔ Base de Datos con soporte opcional para operaciones solo de LECTURA
  • 🔄 Mapeo Objeto-Relacional (ORM): Operaciones de objetos JSON (CRUD) mapeadas transparentemente a datos relacionales
  • 🔒 Acceso Seguro a Datos: Las operaciones específicas del modelo de dominio promueven la protección de datos
  • 🧾 Especificación ORM Declarativa: Especificación ORM intuitiva, no intrusiva y flexible basada en una gramática simple
  • 🕸️ Soporte para Modelado de Objetos Complejos: Incluyendo relaciones uno-a-uno, uno-a-muchos y muchos-a-muchos, y expresiones de ruta
  • 🖇️ Consultas Flexibles: Consultas profundas y superficiales, varios directivas operacionales similares a las capacidades de GraphQL para refinar la forma y el alcance de los objetos devueltos
  • 🚀 Motor de Mapeo Altamente Optimizado y Ligero: Agrupación de conexiones, sentencias preparadas, sentencias SQL optimizadas, viajes mínimos a la base de datos, caché de metadatos
  • 🔌 Compatible con Datos y Bases de Datos Existentes: Funciona con esquemas y datos existentes en cualquier base de datos; No requiere ningún tipo de dato JSON nativo
  • 📚 Documentación Completa: Manual de usuario detallado y archivos README, documentación de API, aplicaciones de ejemplo
  • ☁️ Agnóstico de Nube: Despliega en cualquier lugar con soporte para Docker
  • ⚡ Alto Rendimiento: Construido sobre la versátil arquitectura de microservicios Gilhari y un motor ORM optimizado
  • 🛡️ Manejo Robusto de Errores: Mensajes de error claros y mecanismos de recuperación
  • 📈 Escalable: Maneja múltiples solicitudes concurrentes de manera eficiente; Despliegue Docker escalable

Cómo Funciona

+---------------------+         +----------------------+         +-------------------------+
| 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)   |                                 |
         |<-------------------------------|                                 |

Importante: La aplicación de IA (cliente LLM) traduce el lenguaje natural en llamadas a herramientas MCP. El Servidor ORMCP luego traduce estas llamadas a herramientas MCP en llamadas a la API REST hacia Gilhari.

ORMCP Server cierra la brecha entre las aplicaciones modernas de IA y las bases de datos relacionales a través de:

  • Protocolo MCP: Comunicación estandarizada de IA a herramienta
  • Gilhari: Capa de integración con bases de datos relacionales mediante ORM y JDBC
  • Mapeo JSON: Mapeo objeto-relacional transparente

🚀 Inicio Rápido

¿Nuevo en ORMCP? Ve directamente a tu guía específica de plataforma para una configuración simplificada: 🍎 macOS · 🪟 Windows · 🐧 Linux

Las secciones a continuación cubren todas las plataformas juntas como referencia completa.

Tres Pasos Simples para Usar ORMCP

1. Define el Alcance de Tus Datos

  • Define modelos de objetos ligeros para tus datos relevantes
  • Escribe una especificación ORM declarativa para esos modelos en un archivo de texto usando una gramática simple (JDX)

2. Construye Tu Microservicio Gilhari

  • Agrega modelos, especificación ORM y controlador JDBC a un Dockerfile
  • Construye la imagen Docker de Gilhari

3. Ejecuta con ORMCP

  • Conecta ORMCP al microservicio Gilhari
  • Inicia Gilhari, luego ORMCP
  • Interactúa con los datos relacionales definidos de manera intuitiva y orientada a objetos usando un Agente de IA o cliente MCP

Inicio Rápido Detallado

Requisitos Previos

  • Python 3.12+
  • Docker (para el microservicio Gilhari)
  • Controlador JDBC para tu base de datos objetivo

1. Instala el Servidor ORMCP

Guías específicas por plataforma con instrucciones de instalación paso a paso para tu sistema operativo: macOS · Windows · Linux

El Servidor ORMCP está disponible en PyPI público. No se necesita cuenta, token ni solicitud de acceso beta para instalarlo:

pip install ormcp-server

# Verify installation
pip show ormcp-server

📌 Usuarios de Linux/Mac: Las distribuciones modernas de Linux y macOS pueden requerir entornos virtuales. Consulta tu guía de plataforma o la guía de solución de problemas si obtienes errores de "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

Si tienes un token de Gemfury existente de una instalación beta anterior, ya no funcionará — el acceso a Gemfury ha sido descontinuado. Usa pip install ormcp-server, que se obtiene directamente de PyPI público.

Si el comando ormcp-server no se encuentra después de la instalación:

Agrega el directorio de ejecutables de Python a tu PATH. Consulta tu guía de plataforma para más detalles: macOS · Windows · Linux

2. Configura el Microservicio Gilhari

Consulta la configuración detallada en la sección Configuración del Microservicio Gilhari a continuación.

Nota: Un ejemplo completo y funcional está disponible en un repositorio separado: gilhari_example1

Para ejecutar el ejemplo:

IMPORTANTE: Docker es necesario para construir y ejecutar un microservicio Gilhari — Obtén Docker si aún no está instalado en tu máquina

# Clone the example repository of a sample Gilhari microservice that deals with User type of objects
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Pull Gilhari Docker image
docker pull softwaretree/gilhari:latest

# Build a Docker image for the sample Gilhari microservice
./build.cmd  # On Windows
# or
./build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
./curlCommandsPopulate.cmd  # On Windows
# or
./curlCommandsPopulate.sh   # On Linux/Mac

3. Configura el Entorno

# 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. Inicia el Servidor ORMCP

ormcp-server

Si obtienes errores de comando no encontrado, consulta tu guía de plataforma: macOS · Windows · Linux

# Or use Python directly (works on all platforms)
python -m ormcp_server

5. Conecta Tu Cliente de IA

Para Claude Desktop, agrega a claude_desktop_config.json:

Opción 1: Usando el nombre del comando (requiere PATH configurado):

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

Opción 2: Usando la ruta completa (recomendado para 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"
      }
    }
  }
}

Para encontrar tu ruta exacta:

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

# Or use pip
pip show -f ormcp-server | findstr "Location"

# Linux/Mac
which ormcp-server

¡Estás listo! Tu cliente de IA ahora puede interactuar con tu base de datos usando lenguaje natural.

Nota: Los pasos 3 (Configura el Entorno) y 4 (Inicia el Servidor ORMCP) no son necesarios si usas Claude Desktop como cliente porque Claude Desktop inicia automáticamente un servidor ORMCP configurado en modo STDIO.

Ejemplos de Uso

Consultar Datos

Prompt de IA: "Muéstrame todos los usuarios con edad mayor o igual a 55"

Llamada MCP Generada:

{
  "name": "query",
  "arguments": {
    "className": "User",
    "filter": "age >= 55",
    "maxObjects": -1,
    "deep": true
  }
}

Resultado:

[
  {"id": 55, "name": "Mary55", "city": "Campbell", "state": "CA"},
  {"id": 56, "name": "Mike56", "city": "Boston", "state": "MA"}
]

Insertar Datos

Nota: insert (como las otras herramientas de modificación de datos) solo se expone cuando READONLY_MODE=False está configurado — consulta Configuración para el Servidor ORMCP. Con el valor predeterminado READONLY_MODE=True, la llamada MCP de este ejemplo no estará disponible para el cliente.

Prompt de IA: "Agrega un nuevo Usuario (id = 65) llamado John Smith de Boston, MA con edad de 65"

Llamada MCP Generada:

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

Datos Agregados

Prompt de IA: "¿Cuál es la edad promedio de los usuarios en California?"

Llamada MCP Generada:

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

Resultado:

49

Configuración del Microservicio Gilhari

ORMCP Server depende del software Gilhari, un framework de microservicios para la integración de datos JSON con bases de datos. Esta configuración debe completarse antes de iniciar el servidor ORMCP.

IMPORTANTE: Docker es necesario para construir y ejecutar un microservicio Gilhari — Obtén Docker si aún no está instalado en tu máquina

Instalar el Software Gilhari

  1. Obtén la imagen Docker de Gilhari:

    docker pull softwaretree/gilhari:latest

  2. Instala el SDK de Gilhari:

    • El SDK para el software Gilhari está incluido en el paquete del Servidor ORMCP bajo la carpeta Gilhari_SDK
    • Alternativamente, descárgalo desde: https://www.softwaretree.com/v1/products/gilhari/download-gilhari.php
    • El SDK incluye documentación (READMEs, guías de API, aplicaciones de ejemplo) para ayudarte a usar el software Gilhari fácilmente

Configura Tu Microservicio Gilhari Específico de la Aplicación

Sigue estos pasos (detallados en la documentación del SDK de Gilhari):

  1. Define clases de modelo de dominio - Clases contenedoras de Java para tus objetos JSON

  2. Crea la especificación ORM declarativa - Mapea atributos JSON al esquema de la base de datos

  3. Construye la imagen Docker del microservicio Gilhari específico de la aplicación - Incluye clases de dominio, especificación ORM y controlador JDBC

  4. Ejecuta el microservicio:

    docker run -p 80:8081 your-gilhari-service:1.0

Nota: Un ejemplo completo y funcional está disponible en un repositorio separado: gilhari_example1. Este ejemplo demuestra un microservicio Gilhari que gestiona objetos User.

Inicio Rápido con Ejemplo:

# Clone the example repository
git clone https://github.com/SoftwareTree/gilhari_example1.git
cd gilhari_example1

# Build a Docker image for the sample Gilhari microservice
./build.cmd  # On Windows
# or
./build.sh   # On Linux/Mac

# Run the sample microservice
docker run -p 80:8081 gilhari_example1:1.0

# Optionally, populate the database with sample data
./curlCommandsPopulate.cmd  # On Windows
# or
./curlCommandsPopulate.sh   # On Linux/Mac

Para instrucciones detalladas de configuración, consulta el README de gilhari_example1.

Instalación del Paquete ORMCP

Recomendado: Entorno Virtual

# 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

Instalación Global

pip install ormcp-server

Nota: Al instalar globalmente (sin entorno virtual), el ejecutable ormcp-server se instalará en el directorio de Scripts de Python de tu usuario. Consulta tu guía de plataforma si encuentras errores de "comando no encontrado".

Acceso al Paquete Completo con SDK y Ejemplos

Para acceder al paquete completo que incluye el SDK de Gilhari, ejemplos y documentación:

# 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)

Usuarios de Windows: Si no tienes tar instalado, puedes:

  • Usar 7-Zip o WinRAR para extraer el archivo .tar.gz
  • O usar PowerShell: tar -xzf ormcp_server-*.tar.gz
  • O descargar directamente desde la página del proyecto en PyPI

Contenido del Paquete

El paquete del Servidor ORMCP incluye recursos adicionales más allá del código Python:

Instalación en Tiempo de Ejecución (Wheel)

Cuando instalas vía pip, obtienes el paquete Python central necesario para ejecutar el Servidor ORMCP:

pip install ormcp-server

Esto instala solo los archivos de tiempo de ejecución esenciales en tu entorno Python.

Paquete Completo con SDK y Documentación (Distribución de Fuente)

El paquete completo incluye:

  • Gilhari_SDK/ - SDK completo con documentación, ejemplos y herramientas para crear microservicios Gilhari personalizados
  • gilhari_example1/ - Microservicio Gilhari de ejemplo listo para usar
  • package/client/ - Código de cliente de ejemplo y documentación de uso
  • package/docs/ - Documentación técnica adicional
  • pyproject.toml - Configuración de compilación
  • README.md - Este archivo
  • LICENSE - Términos de licencia

Acceso al Paquete Completo

Opción 1: Descargar desde PyPI

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

# Extract it (use the appropriate version number; e.g., 0.6.x)
tar -xzf ormcp_server-0.6.x.tar.gz
cd ormcp_server-0.6.x

# Now you have access to:
# - Gilhari_SDK/
# - gilhari_example1/
# - package/client/
# - package/docs/

Usuarios de Windows: Si no tienes tar instalado, puedes:

  • Usar 7-Zip o WinRAR para extraer el archivo .tar.gz
  • O usar PowerShell: tar -xzf ormcp_server-0.6.x.tar.gz
  • O descargar directamente desde la página del proyecto en PyPI

Opción 2: Descargar desde la Página del Paquete

Visita https://pypi.org/project/ormcp-server/ y descarga el archivo .tar.gz.

Busca la sección "Download files" y descarga la distribución de fuente (.tar.gz).

Usando el SDK de Gilhari

Después de extraer la distribución de fuente:

# 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

Ejecución del Microservicio Gilhari de Ejemplo

# 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

¿Por qué dos formatos de paquete?

  • Wheel (.whl) - Distribución binaria, rápida de instalar, incluye solo el código de ejecución (~50KB)
  • Distribución de código fuente (.tar.gz) - Paquete completo con todos los recursos (~varios MB)

La mayoría de los usuarios solo necesitan el wheel para ejecutar ORMCP Server. Descargue la distribución de código fuente si necesita:

  • El SDK de Gilhari para crear microservicios personalizados
  • Aplicaciones de ejemplo y código de cliente
  • Documentación completa
  • Guías técnicas adicionales

Configuración para ORMCP Server

Configure mediante variables de entorno:

VariableDescripciónValor por defectoEjemplo
GILHARI_BASE_URLURL del microservicio Gilharihttp://localhost:80/gilhari/v1/http://myhost:8888/gilhari/v1/
MCP_SERVER_NAMEIdentificador del servidorORMCPServerDemoMyCompanyORMCP
GILHARI_TIMEOUTTiempo de espera de la API (segundos)3060
LOG_LEVELNivel de detalle del registroINFODEBUG, WARNING, ERROR
READONLY_MODEExponer solo operaciones de lecturaTrueFalse
GILHARI_NAMENombre del microservicio Gilhari específico de la aplicación""my-gilhari-microservice
GILHARI_IMAGENombre de la imagen Docker del microservicio Gilhari específico de la aplicación""gilhari_example1:1.0
GILHARI_HOSTDirección IP de la máquina host para el microservicio Gilharilocalhost10.20.30.40
GILHARI_PORTNúmero de puerto para contactar el microservicio Gilhari808888

Notas:

  • READONLY_MODE tiene como valor por defecto True: las herramientas MCP que pueden modificar datos potencialmente (insert, update, update2, delete, delete2) no se exponen por el servidor ORMCP al cliente MCP a menos que establezca explícitamente READONLY_MODE=False.
  • GILHARI_BASE_URL y GILHARI_NAME se utilizan para sondear un contenedor de microservicio Gilhari ya en ejecución.
  • GILHARI_IMAGE, GILHARI_NAME y GILHARI_PORT se utilizan para ejecutar una nueva instancia del microservicio Gilhari si no se encuentra un microservicio existente. Asegúrese de que los valores de las variables GILHARI_HOST y GILHARI_PORT coincidan con los valores correspondientes en la configuración de GILHARI_BASE_URL, porque es allí donde el servidor ORMCP contactará al microservicio Gilhari.

Ejemplo de Configuración

# 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"

Iniciando el Servidor

Modo Estándar (Recomendado)

Active su entorno virtual (si usa uno):

# Linux/Mac
source .venv/bin/activate

# Windows (Command Prompt)
.venv\Scripts\activate

# Windows (PowerShell)
.venv\Scripts\Activate.ps1

Inicie el servidor usando el comando CLI:

ormcp-server

Esto ejecuta el servidor MCP en modo stdio a través del punto de entrada main.py.

Solución de problemas — Comando no encontrado:

Si obtiene 'ormcp-server' is not recognized o command not found, consulte la guía de su plataforma para la configuración de PATH y las opciones de corrección: macOS · Windows · Linux

# Use Python directly on any platform (always works)
python -m ormcp_server

Usando el Código Fuente Directamente (Avanzado)

Nota: Requiere la distribución de código fuente. Descargue con:

pip download --no-binary :all: ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Ejecute el servidor directamente con Python:

python src/ormcp_server.py

Esto omite el envoltorio CLI y ejecuta el servidor directamente.

Métodos Alternativos (Usuarios Avanzados)

Ejecución directa del ejecutable:

# Windows
.venv\Scripts\ormcp-server.exe

# Linux/Mac
.venv/bin/ormcp-server

Usando la CLI de fastmcp (requiere distribución de código fuente):

fastmcp run src/ormcp_server.py

Usando el modo de desarrollo de MCP Inspector (requiere distribución de código fuente):

mcp dev src/ormcp_server.py

Usando MCP Inspector sin código fuente:

Si tiene el paquete ormcp-server instalado, puede usar MCP Inspector para explorar las capacidades del servidor:

# Using the installed package
npx @modelcontextprotocol/inspector python -m ormcp_server

# Or if you have the command in PATH
npx @modelcontextprotocol/inspector ormcp-server

Esto le permite probar y explorar interactivamente las herramientas de ORMCP Server sin necesidad de la distribución de código fuente.

Soporte de Transporte HTTP o SSE

Nota: ORMCP tiene como valor por defecto el transporte stdio, que es el que la mayoría de los clientes de IA de escritorio (por ejemplo, Claude Desktop) usan de forma predeterminada. El modo HTTP (transporte HTTP Streamable) también es totalmente compatible para implementaciones independientes/en red — consulte la guía de interacción en modo HTTP para más detalles. Algunos clientes (por ejemplo, Gemini CLI) actualmente requieren el modo HTTP.

Puede iniciar el servidor ORMCP en modo HTTP desde la línea de comandos:

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

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

Personalizar host y puerto:

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

Opciones de línea de comandos disponibles:

  • --transport: Elija entre "stdio" (valor por defecto) o "http"
  • --host: Establezca la dirección del host (valor por defecto: 127.0.0.1, solo se usa en modo HTTP)
  • --port: Establezca el número de puerto (valor por defecto: 8080, solo se usa en modo HTTP)

Configuración HTTP rápida:

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

Asegúrese de tener uvicorn instalado como dependencia, ya que el modo HTTP lo usa para servir la aplicación.

Uso en Modo HTTP

El servidor MCP que se ejecuta en modo HTTP no está diseñado para ser accedido directamente a través de un navegador web. Es un servidor API que espera mensajes específicos del protocolo MCP, no solicitudes HTTP GET a la ruta raíz.

Resumen

  • Use la CLI ormcp-server para la experiencia más limpia y recomendada.
  • Use python src/ormcp_server.py directamente para ejecuciones simples con la distribución de código fuente.
  • Use mcp dev o fastmcp run para escenarios avanzados de desarrollo/pruebas con la distribución de código fuente.

Salida Esperada

[INFO] ORMCP server name: ORMCPServerDemo
[INFO] GILHARI BASE URL: http://localhost:80/gilhari/v1/
[INFO] ORMCP server v0.5.x starting in stdio (or http) mode ...

Implementación Contenerizada (Registros MCP)

Para la implementación a través de registros MCP como Glama, se proporciona un script start.sh en la raíz de este repositorio. Se encarga de instalar y lanzar ORMCP Server en un entorno contenerizado. Consulte el script para conocer las variables de entorno requeridas y los detalles de configuración.

Configuración del Cliente MCP

Claude Desktop

Ubicaciones de archivos de configuración específicos de la plataforma y configuración de PATH: macOS · Windows · Linux

Opción 1: Usando el Nombre del Comando (Requiere PATH Configurado)

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

Opción 2: Usando la Ruta Completa (Recomendado para 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"
      }
    }
  }
}

Para encontrar su ruta de instalación exacta:

# 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

Opción 3: Ejecución Directa de Python

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

Opción 4: Usando FastMCP (Para Desarrolladores con Distribución de Código Fuente)

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

Opción 5: Modo HTTP

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

Notas:

  • ORMCPServerDemo es el nombre por defecto del servidor ORMCP.
  • Reemplace <YourUsername> con su nombre de usuario real de Windows.
  • Si está proporcionando un número de puerto del microservicio Gilhari asociado a través de la variable de entorno "GILHARI_BASE_URL", asegúrese de que sea el puerto donde ese microservicio Gilhari está escuchando.
  • Nota: A partir del 20 de julio de 2025, Claude desktop no admitía conectarse a un servidor MCP que se ejecuta en modo http.

Gemini CLI

Actualice el archivo settings.json de Gemini:

{
  "mcpServers": {
    "my-ormcp-server-http": {
      "httpUrl": "http://127.0.0.1:8080/mcp"
    }
  }
}

Nota: Gemini CLI actualmente requiere el modo HTTP.

GPTs de OpenAI (Modo Desarrollador)

Para conectar el servidor ORMCP a un GPT personalizado en modo desarrollador, el servidor debe estar ejecutándose en modo HTTP y ser accesible desde una URL pública.

  1. Prepare el Backend:

    • Primero, asegúrese de que el microservicio Gilhari esté compilado y ejecutándose en su contenedor Docker según las instrucciones de configuración.

    • Use curl para verificar que el servicio Gilhari responda:

      curl -i http://localhost:80/gilhari/v1/getObjectModelSummary/now

  2. Configure y Ejecute el Servidor ORMCP:

    • Establezca las variables de entorno requeridas para que el servidor ORMCP se conecte a Gilhari.

      export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
export MCP_SERVER_NAME="MyORMCPServer"
export GILHARI_TIMEOUT="30"
export LOG_LEVEL="INFO"

    • Inicie el servidor ORMCP en modo HTTP, ya que esto es requerido para clientes basados en web.

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

  3. Exponga el Servidor con una URL Pública: Los servidores de OpenAI necesitan una dirección web pública para alcanzar su servidor ORMCP local. Use un servicio de túnel como cloudflared o ngrok para crear una URL pública segura que reenvíe a su máquina local.

    • Opción A: Usando cloudflared (Recomendado)

      • En una nueva terminal, inicie un túnel de Cloudflare apuntando al puerto de su servidor.

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

      • cloudflared proporcionará una URL pública persistente (por ejemplo, https://<your-tunnel-name>.trycloudflare.com).

    • Opción B: Usando ngrok

      • En una nueva terminal, inicie ngrok para reenviar el tráfico al puerto 8080.

        ngrok http 8080

      • ngrok proporcionará una URL HTTPS pública temporal (por ejemplo, https://random-string.ngrok-free.app). Tenga en cuenta que esta URL cambia cada vez que reinicia ngrok en el plan gratuito.

  4. Conéctese a Su GPT Personalizado:

    • Tome la URL pública generada por cloudflared o ngrok.
    • Agregue /mcp al final de esta URL. El resultado final será su endpoint MCP, por ejemplo: https://<your-public-url>/mcp.
    • En la configuración de su GPT (Configuración → Aplicaciones y Conectores → Crear), pegue esta URL completa en el campo URL del Servidor MCP. GPT descubrirá y se conectará a las herramientas proporcionadas por su servidor ORMCP.

Otros Clientes MCP

Referencia de Herramientas MCP

ORMCP Server proporciona las siguientes herramientas MCP para interactuar con su base de datos.

📖 Documentación Detallada de la API: Para especificaciones completas de parámetros y detalles técnicos, consulte la Referencia de la API de Herramientas MCP.

💡 Ejemplos de Trabajo: Consulte ejemplos de uso en el mundo real en el directorio de ejemplos.

Operaciones Principales

getObjectModelSummary

Recupere información sobre el modelo de objetos subyacente.

Devuelve: Información sobre clases (tipos), atributos, claves primarias y relaciones en su modelo de dominio.

query

Consulte objetos con filtrado y recorrido de relaciones.

Parámetros:

  • className (cadena): Tipo de objetos a consultar
  • filter (cadena, opcional): Cláusula WHERE similar a SQL para filtrar
  • maxObjects (entero, opcional): Número máximo de objetos a recuperar (-1 para todos, valor por defecto: -1)
  • deep (booleano, opcional): Incluir objetos referenciados en los resultados (valor por defecto: true)
  • operationDetails (cadena, opcional): Matriz JSON de directivas operativas para ajustar las consultas. Admite operaciones similares a GraphQL como:
    • projections: Recuperar solo atributos específicos
    • ignore o follow: Controlar ramas de objetos referenciados
    • filter: Aplicar filtros a objetos referenciados

getObjectById

Recupere un objeto específico por su clave primaria.

Parámetros:

  • className (cadena): Tipo de objeto a recuperar
  • primaryKey (objeto): Valores de clave primaria (valor único u objeto de clave compuesta)
  • deep (booleano, opcional): Incluir objetos referenciados (valor por defecto: true)
  • operationDetails (cadena, opcional): Directivas operativas para ajustar las consultas

access

Recupere el/los objeto(s) referenciado(s) por un atributo específico de un objeto referenciador.

Parámetros:

  • className (cadena): Tipo del objeto referenciador
  • jsonObject (objeto): El objeto referenciador que contiene la referencia
  • attributeName (cadena): Nombre del atributo cuyo(s) valor(es) referenciado(s) se van a recuperar
  • deep (booleano, opcional): Incluir también objetos referenciados de los objetos recuperados (valor por defecto: true)
  • operationDetails (cadena, opcional): Directivas operativas para ajustar las consultas

getAggregate

Calcula valores agregados entre objetos (COUNT, SUM, AVG, MIN, MAX).

Parámetros:

  • className (cadena): Tipo de objetos a agregar
  • attributeName (cadena): Atributo sobre el cual realizar la agregación
  • aggregateType (cadena): Tipo de agregación - COUNT, SUM, AVG, MIN, MAX
  • filter (cadena, opcional): Cláusula WHERE estilo SQL para filtrar objetos antes de la agregación

Operaciones de Modificación de Datos

Nota: Estas herramientas solo se exponen si READONLY_MODE=False está configurado — READONLY_MODE tiene como valor predeterminado True, por lo que insert, update, update2, delete y delete2 no están disponibles de forma predeterminada. Consulte Configuración para el Servidor ORMCP arriba.

insert

Guarda uno o más objetos JSON en la base de datos.

Parámetros:

  • className (cadena): Tipo de objetos a insertar
  • jsonObjects (matriz): Lista de objetos JSON para guardar en la base de datos
  • deep (booleano, opcional): Guardar también los objetos referenciados (predeterminado: true)

update

Actualiza uno o más objetos existentes con nuevos valores.

Parámetros:

  • className (cadena): Tipo de objetos a actualizar
  • jsonObjects (matriz): Lista de objetos con valores actualizados (debe incluir claves primarias)
  • deep (booleano, opcional): Actualizar también los objetos referenciados (predeterminado: true)

update2

Actualización masiva de objetos que coinciden con los criterios de filtro.

Parámetros:

  • className (cadena): Tipo de objetos a actualizar
  • filter (cadena): Cláusula WHERE estilo SQL para identificar los objetos a actualizar
  • newValues (matriz): Lista de nombres de atributos y sus nuevos valores
  • deep (booleano, opcional): Actualizar también los objetos referenciados (predeterminado: true)

delete

Elimina objetos específicos de la base de datos.

Parámetros:

  • className (cadena): Tipo de objetos a eliminar
  • jsonObjects (matriz): Objetos a eliminar (se requieren claves primarias para la identificación)
  • deep (booleano, opcional): Eliminar también los objetos referenciados (predeterminado: true)

delete2

Eliminación masiva de objetos que coinciden con los criterios de filtro.

Parámetros:

  • className (cadena): Tipo de objetos a eliminar
  • filter (cadena, opcional): Cláusula WHERE estilo SQL para identificar los objetos a eliminar (cadena vacía elimina todos los objetos de la clase especificada)
  • deep (booleano, opcional): Eliminar también los objetos referenciados (predeterminado: true)

Nota: READONLY_MODE tiene como valor predeterminado True, por lo que las herramientas MCP para operaciones de modificación de datos (insert, update, update2, delete, delete2) no están expuestas a los clientes MCP a menos que configure explícitamente READONLY_MODE=False.

Solución de Problemas

Para problemas comunes y soluciones, consulte la Guía Completa de Solución de Problemas.

Solución Rápida de Problemas

Problemas de Instalación:

Problemas de Ejemplo con Gilhari:

  • Permiso denegado para script de shell → chmod +x *.sh o use sh build.sh (Linux/Mac)
  • Errores de conexión a la base de datos → Verifique el controlador JDBC en Gilhari

Problemas de Ejecución:

  • El servidor no se inicia → Verifique que Gilhari esté en ejecución
  • Errores de conexión a la base de datos → Verifique el controlador JDBC en Gilhari
  • Problemas de conexión del cliente MCP → Verifique la sintaxis del archivo de configuración

Habilitar Modo de Depuración:

# 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

Obtener Ayuda:

Desarrollo

Pruebas

Para pruebas y desarrollo con la distribución de código fuente:

# 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

Desarrollo de Microservicios Gilhari

  • El Servidor ORMCP aprovecha el software Gilhari, un marco de microservicios RESTful para la integración de datos JSON con bases de datos.
  • Primero crea un microservicio Gilhari personalizado basado en los modelos de datos relacionales de objetos de su aplicación.
  • Una especificación de mapeo relacional de objetos (ORM) define y controla el alcance y la forma de su modelo de objetos correspondiente a su modelo relacional.
  • La especificación ORM se define declarativamente en un archivo de texto (.jdx) basado en una gramática simple.
  • Es posible que pueda realizar ingeniería inversa de la especificación ORM a partir de un esquema de base de datos existente utilizando las herramientas/ejemplos proporcionados con el SDK de Gilhari. Consulte el directorio examples\JDX_ReverseEngineeringJSONExample.
  • El ejemplo de ingeniería inversa también está disponible en línea en github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample
  • Para obtener detalles sobre la creación de microservicios Gilhari personalizados, consulte la documentación del SDK de Gilhari incluida en el paquete de distribución de código fuente.
  • Aunque un servidor ORMCP puede iniciar un microservicio Gilhari si está configurado para hacerlo (usando las variables de entorno GILHARI_IMAGE, GILHARI_NAME y GILHARI_PORT), se recomienda que inicie su microservicio Gilhari personalizado antes de usar el servidor ORMCP. Además, asegúrese de que el número de puerto en la variable de entorno 'GILHARI_BASE_URL' para el servidor ORMCP coincida con el número de puerto en el que el microservicio Gilhari personalizado está escuchando las llamadas REST entrantes.

Contribuciones

¡Gracias por su interés en el Servidor ORMCP!

🚫 Sin Contribuciones de Código en Este Momento

El Servidor ORMCP es software propietario. No aceptamos contribuciones de código, solicitudes de extracción o envíos de funciones.

🐞 Comentarios e Informes de Errores

¡Agradecemos los comentarios sobre la versión beta! Puede ayudarnos a mejorar el Servidor ORMCP al:

  • Informar errores o problemas
  • Sugerir mejoras
  • Compartir su experiencia

Cómo Proporcionar Comentarios

Cualquier comentario que proporcione puede ser utilizado por Software Tree para mejorar el producto, sin obligación de acreditarle o compensarle.

Software de Terceros

Dependencia de Gilhari y JDX: El Servidor ORMCP requiere el microservicio Gilhari para funcionar, que a su vez depende de JDX, la tecnología ORM subyacente utilizada por Gilhari. Ambos son productos propietarios de Software Tree. Gilhari y JDX incorporan varios componentes de software de terceros. Para obtener detalles completos de estos componentes de terceros y sus licencias, consulte el archivo LICENSE en el SDK de Gilhari, o visite: https://www.softwaretree.com/v1/products/gilhari/ y https://www.softwaretree.com/v1/products/jdx/jdx.html

Dependencias de Python: El Servidor ORMCP utiliza las siguientes bibliotecas de Python de código abierto, cada una regida por sus respectivas licencias:

  • mcp (SDK del Protocolo de Contexto de Modelo)
  • fastmcp (marco FastMCP)
  • httpx (biblioteca de cliente HTTP)
  • pydantic (biblioteca de validación de datos)
  • uvicorn (servidor ASGI)
  • requests (biblioteca HTTP)

Licencia

El Servidor ORMCP es software propietario propiedad de Software Tree, LLC. Consulte el archivo LICENSE para conocer los términos completos.

Evaluación Beta: El Servidor ORMCP está actualmente disponible como producto beta bajo una licencia de evaluación. Esto permite el uso gratuito para fines de prueba y evaluación durante un período de evaluación limitado (30 días desde la fecha de instalación).

Dependencia de Gilhari y JDX: El Servidor ORMCP requiere el microservicio Gilhari para funcionar, que a su vez depende de JDX, la tecnología ORM subyacente utilizada por Gilhari. Ambos son productos propietarios de Software Tree bajo sus propios acuerdos de licencia. Al usar el Servidor ORMCP, acepta cumplir también con la Licencia de Gilhari y la Licencia de JDX. Gilhari y JDX incorporan varios componentes de software de terceros — para obtener detalles, consulte el archivo LICENSE en el SDK de Gilhari, o visite https://www.softwaretree.com/v1/products/gilhari/ y https://www.softwaretree.com/v1/products/jdx/jdx.html.

Licencia Comercial: El uso del Servidor ORMCP más allá del período de evaluación está sujeto a los términos de licencia de Software Tree aplicables en ese momento. Para obtener información o expresar interés, contacte a Software Tree en ormcp_support@softwaretree.com o visite https://www.softwaretree.com.

Soporte y Recursos

Hecho con ❤️ para la comunidad de IA y bases de datos