Copyright (c) 2025, Software Tree

ORMCP Server - Beta

Un servidor de Model Context Protocol (MCP) para conectar tus aplicaciones de IA a bases de datos relacionales

ORMCP Server permite a los LLM de IA y a los clientes MCP intercambiar fácilmente datos orientados a objetos (en formato JSON) con cualquier base de datos relacional utilizando el protocolo estándar MCP.

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

⚠️ Aviso de Beta

ORMCP Server se encuentra actualmente en Beta, y ofrecemos acceso temprano a los 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.

Related MCP server: io.github.ralfbecher/orionbelt-analytics

📋 Tabla de Contenidos

• ¿Qué es MCP?

• Características

• Cómo Funciona

• Inicio Rápido

• Guías específicas por plataforma — 🍎 macOS · 🪟 Windows · 🐧 Linux

• Instalación

• Configuración del Microservicio Gilhari

• Configuración

• Iniciar el Servidor

• Configuración del Cliente

• Ejemplos de Uso

• Referencia de Herramientas MCP

• Solución de Problemas

• Desarrollo

• Contribuciones

• Licencia

• Soporte y Recursos

¿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 LLM 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 entre IA y Base de Datos con soporte opcional para operaciones de solo LECTURA

• 🔄 Mapeo Objeto-Relacional (ORM): Operaciones de objetos JSON (CRUD) mapeadas de forma transparente 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, diversos directivos 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: Pool 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: Despliegue 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 escalable con Docker

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. Luego, ORMCP Server 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 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 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. Instalar ORMCP Server

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

ORMCP Server 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 recibes 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. Configurar 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. Configurar 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. Iniciar el Servidor ORMCP

ormcp-server

Si recibes 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. Conectar 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 (Configurar el Entorno) y 4 (Iniciar 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

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 marco 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 ORMCP Server 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

Configurar 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 una 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 el 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 ORMCP Server incluye recursos adicionales más allá del código Python:

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

Cuando instalas mediante pip, obtienes el paquete Python principal necesario para ejecutar ORMCP Server:

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/ - Ejemplo de microservicio Gilhari 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

Visite https://pypi.org/project/ormcp-server/ y descargue el archivo .tar.gz.

Busque la sección "Download files" y descargue la distribución de código fuente (.tar.gz).

Uso del SDK de Gilhari

Después de extraer la distribución de código 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 (~50 KB)

• 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 de ORMCP Server

Configúrelo mediante variables de entorno:

Notas:

• Si READONLY_MODE se establece en True, las herramientas MCP que pueden modificar potencialmente los datos (p. ej., insert, update, update2, delete, delete2) no se exponen desde el servidor ORMCP al cliente MCP. De forma predeterminada, se exponen todas las herramientas MCP.

• 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á con el 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"

Inicio del servidor

Modo estándar (recomendado)

Active su entorno virtual (si utiliza uno):

# Linux/Mac
source .venv/bin/activate

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

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

Inicie el servidor mediante 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 recibe '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

Uso directo del código fuente (avanzado)

Nota: Requiere la distribución de código fuente. Descárguela 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

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

fastmcp run src/ormcp_server.py

Uso del modo de desarrollo de MCP Inspector (requiere la distribución de código fuente):

mcp dev src/ormcp_server.py

Uso de MCP Inspector sin código fuente:

Si tiene instalado el paquete ormcp-server, 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 utiliza por defecto el transporte stdio, que es el que usan la mayoría de los clientes de IA de escritorio (p. ej., Claude Desktop) de forma nativa. El modo HTTP (transporte HTTP transmisible) también es totalmente compatible con implementaciones independientes o en red; consulte la guía de interacción en modo HTTP para más detalles. Algunos clientes (p. ej., Gemini CLI) requieren actualmente 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

Personalice el host y el 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" (predeterminado) o "http"

• --host: Establezca la dirección del host (predeterminado: 127.0.0.1, solo se usa en modo HTTP)

• --port: Establezca el número de puerto (predeterminado: 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 utiliza para servir la aplicación.

Uso en modo HTTP

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

Resumen

• Use la CLI de 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 en contenedores (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 e iniciar ORMCP Server en un entorno contenedorizado. 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íficas de la plataforma y configuración de rutas: macOS · Windows · Linux

Opción 1: Uso del 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: Uso de 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: Uso de 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 predeterminado del servidor ORMCP.

• Reemplace <YourUsername> con su nombre de usuario real de Windows.

• Si proporciona un número de puerto del microservicio Gilhari asociado a través de la variable de entorno "GILHARI_BASE_URL", asegúrese de que ese sea el puerto en el que escucha ese microservicio Gilhari.

• Nota: A partir del 20 de julio de 2025, Claude desktop no admitía la conexión a un servidor MCP que se ejecutara 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 requiere actualmente el modo HTTP.

OpenAI GPTs (modo desarrollador)

Para conectar el servidor ORMCP a un GPT personalizado en modo desarrollador, el servidor debe ejecutarse 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 responde:

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

2. Configure y ejecute el servidor ORMCP:

   • Establezca las variables de entorno necesarias 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 necesario para los 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 llegar a 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: Uso de cloudflared (recomendado)

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

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

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

   • Opción B: Uso de 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 (p. ej., 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.

   • Añada /mcp al final de esta URL. El resultado final será su punto de conexión MCP, por ejemplo: https://<your-public-url>/mcp.

   • En la configuración de su GPT (Settings → Apps & Connectors → Create), pegue esta URL completa en el campo MCP Server URL. GPT descubrirá y se conectará a las herramientas proporcionadas por su servidor ORMCP.

Otros clientes MCP

• Conéctese al servidor ORMCP y use las herramientas ORM compatibles con MCP que proporciona el servidor ORMCP.

• Configúrelo según los requisitos de configuración del servidor MCP de su cliente, utilizando el modo de transporte adecuado (STDIO o HTTP).

• 📚 Guías de integración: Consulte la documentación detallada sobre cómo conectarse a ORMCP Server:

  • Referencia del protocolo MCP — Detalles del protocolo JSON-RPC de bajo nivel

  • Uso del ejemplo de cliente ORMCP — Guía de uso del cliente Python

  • Interacción con ORMCP Server en modo STDIO — Guía del transporte STDIO

  • Interacción con ORMCP Server en modo HTTP — Guía del transporte HTTP

  • Guías adicionales disponibles en el repositorio de documentación (también incluidas en la distribución de código fuente)

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 prácticos: Consulte ejemplos de uso reales en el directorio de ejemplos.

Operaciones principales

getObjectModelSummary

Recupera información sobre el modelo de objetos subyacente.

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

query

Consulta objetos con filtrado y recorrido de relaciones.

Parámetros:

• className (string): Tipo de objetos a consultar

• filter (string, opcional): cláusula WHERE similar a SQL para filtrar

• maxObjects (integer, opcional): Número máximo de objetos a recuperar (-1 para todos, por defecto: -1)

• deep (boolean, opcional): Incluir objetos referenciados en los resultados (por defecto: true)

• operationDetails (string, opcional): Matriz JSON de directivas operativas para ajustar 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

Recupera un objeto específico por su clave primaria.

Parámetros:

• className (string): Tipo de objeto a recuperar

• primaryKey (object): Valores de clave primaria (valor único u objeto de clave compuesta)

• deep (boolean, opcional): Incluir objetos referenciados (por defecto: true)

• operationDetails (string, opcional): Directivas operativas para ajustar consultas

access

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

Parámetros:

• className (string): Tipo del objeto referenciador

• jsonObject (object): El objeto referenciador que contiene la referencia

• attributeName (string): Nombre del atributo cuyos valores referenciados se van a recuperar

• deep (boolean, opcional): Incluir también objetos referenciados de los objetos recuperados (por defecto: true)

• operationDetails (string, opcional): Directivas operativas para ajustar consultas

getAggregate

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

Parámetros:

• className (string): Tipo de objetos a agregar

• attributeName (string): Atributo sobre el que realizar la agregación

• aggregateType (string): Tipo de agregación: COUNT, SUM, AVG, MIN, MAX

• filter (string, opcional): cláusula WHERE similar a SQL para filtrar objetos antes de la agregación

Operaciones de Modificación de Datos

insert

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

Parámetros:

• className (string): Tipo de objetos a insertar

• jsonObjects (array): Lista de objetos JSON para guardar en la base de datos

• deep (boolean, opcional): Guardar también objetos referenciados (por defecto: true)

update

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

Parámetros:

• className (string): Tipo de objetos a actualizar

• jsonObjects (array): Lista de objetos con valores actualizados (debe incluir claves primarias)

• deep (boolean, opcional): Actualizar también objetos referenciados (por defecto: true)

update2

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

Parámetros:

• className (string): Tipo de objetos a actualizar

• filter (string): cláusula WHERE similar a SQL para identificar objetos a actualizar

• newValues (array): Lista de nombres de atributos y sus nuevos valores

• deep (boolean, opcional): Actualizar también objetos referenciados (por defecto: true)

delete

Elimina objetos específicos de la base de datos.

Parámetros:

• className (string): Tipo de objetos a eliminar

• jsonObjects (array): Objetos a eliminar (se requieren claves primarias para la identificación)

• deep (boolean, opcional): Eliminar también objetos referenciados (por defecto: true)

delete2

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

Parámetros:

• className (string): Tipo de objetos a eliminar

• filter (string, opcional): cláusula WHERE similar a SQL para identificar objetos a eliminar (cadena vacía elimina todos los objetos de la clase especificada)

• deep (boolean, opcional): Eliminar también objetos referenciados (por defecto: true)

Nota: En READONLY_MODE=True, las herramientas MCP para operaciones de modificación de datos (insert, update, update2, delete, delete2) no están expuestas a los clientes MCP.

Solución de problemas

Para problemas y soluciones comunes, consulte la Guía completa de solución de problemas.

Solución rápida de problemas

Problemas de instalación:

• Comando no encontrado → Consulte su guía de plataforma para la configuración de PATH: macOS · Windows · Linux

• Entorno gestionado externamente → Use un entorno virtual (consulte la guía de solución de problemas)

• Ejecutable vacío → Reinstale el paquete

• Dependencias faltantes → pip install --force-reinstall ormcp-server

• Actualización desde v0.6.2 o anterior y obteniendo un fastmcp ImportError → Consulte Error de importación de fastmcp después de la actualización

Problemas con los ejemplos de Gilhari:

• Permiso denegado para el 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 en tiempo de ejecución:

• El servidor no se inicia → Compruebe 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 → Compruebe 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:

• Documentación: github.com/softwaretree/ormcp-docs

• Problemas: github.com/softwaretree/ormcp-docs/issues

• Correo electrónico: ormcp_support@softwaretree.com

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

• ORMCP Server aprovecha Gilhari software, 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 ORMCP Server!

🚫 Sin contribuciones de código por ahora

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

🐞 Comentarios e informes de errores

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

• Informar errores o problemas

• Sugerir mejoras

• Compartir su experiencia

Cómo proporcionar comentarios

• GitHub Issues: Informe problemas o sugerencias

• Correo electrónico: ormcp_support@softwaretree.com

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

Software de terceros

Dependencia de Gilhari y JDX:

ORMCP Server 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:

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

• mcp (Model Context Protocol SDK)

• fastmcp (FastMCP framework)

• httpx (HTTP client library)

• pydantic (Data validation library)

• uvicorn (ASGI server)

• requests (HTTP library)

Licencia

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

Evaluación beta: ORMCP Server está actualmente disponible como producto beta bajo una licencia de evaluación. Esto permite el uso gratuito con 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: ORMCP Server 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 ORMCP Server, usted 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 más 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 de ORMCP Server 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

• Documentación: Documentación y guías completas

• Guías de plataforma: macOS · Windows · Linux

• Ejemplos prácticos: Explorar ejemplos | Guía de ejemplos - Casos de uso e integraciones del mundo real

• Microservicio de ejemplo: Repositorio gilhari_example1

• Informes de errores: Informar problemas

• Soporte por correo electrónico: ormcp_support@softwaretree.com

• Soporte de Gilhari: Documentación de Software Tree Gilhari

• Protocolo MCP: Sitio oficial de MCP

• Instalar ORMCP Server: pip install ormcp-server — no se necesita token beta. Consulte softwaretree.com/products/ormcp para obtener instrucciones completas de instalación.

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