ORMCP

ORMCP fornece uma visão orientada a objetos, curada e compatível com MCP, de dados relacionais em qualquer banco de dados compatível com JDBC (ex.: PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite) — melhorando a clareza do raciocínio, reduzindo o uso de tokens e estabelecendo um limite claro de governança.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Copyright (c) 2025, Software Tree

Servidor ORMCP - Beta

Última atualização: 15/09/2026 19:06 PDT

Um Servidor de Protocolo de Contexto de Modelo (MCP) para conectar suas aplicações de IA a bancos de dados relacionais

O Servidor ORMCP permite que LLMs de IA e clientes MCP troquem facilmente dados orientados a objetos (em formato JSON) com qualquer banco de dados relacional usando o protocolo padrão MCP.

O Servidor ORMCP torna seus dados relacionais prontos para IA.

⚠️ Aviso de Beta

O Servidor ORMCP está atualmente em Beta, e estamos oferecendo acesso antecipado a usuários que desejam testar o software, fornecer feedback e nos ajudar a garantir que o produto atenda aos mais altos padrões de qualidade. Esta versão Beta não se destina ao uso comercial e é fornecida apenas para fins de teste.

📋 Sumário

O que é MCP?

O Protocolo de Contexto de Modelo (MCP) é um padrão aberto que fornece uma maneira unificada para modelos de IA interagirem com ferramentas externas e fontes de dados. Ele padroniza a comunicação, facilitando a integração de LLMs em fluxos de trabalho complexos sem a necessidade de criar integrações de API personalizadas para cada caso de uso.

Saiba mais no Site Oficial do MCP.

✨ Recursos

  • ✅ Interface Padronizada: Totalmente compatível com a especificação do Protocolo de Contexto de Modelo (MCP)
  • 🌐 Agnóstico de Banco de Dados: Funciona com qualquer banco de dados compatível com JDBC (por exemplo, PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)
  • ↔️ Fluxo de Dados Bidirecional: Comunicação perfeita entre IA ↔ Banco de Dados com suporte opcional para operações somente de LEITURA
  • 🔄 Mapeamento Objeto-Relacional (ORM): Operações de objetos JSON (CRUD) mapeadas de forma transparente para dados relacionais
  • 🔒 Acesso Seguro a Dados: Operações específicas do modelo de domínio promovem a proteção de dados
  • 🧾 Especificação ORM Declarativa: Especificação ORM intuitiva, não intrusiva e flexível baseada em uma gramática simples
  • 🕸️ Suporte para Modelagem de Objetos Complexos: Incluindo relacionamentos um-para-um, um-para-muitos e muitos-para-muitos, e expressões de caminho
  • 🖇️ Consultas Flexíveis: Consultas profundas e rasas, várias diretivas operacionais semelhantes aos recursos do GraphQL para refinar a forma e o escopo dos objetos retornados
  • 🚀 Mecanismo de Mapeamento Altamente Otimizado e Leve: Pool de conexões, declarações preparadas, declarações SQL otimizadas, viagens mínimas ao banco de dados, cache de metadados
  • 🔌 Compatível com Dados e Bancos de Dados Existentes: Funciona com esquemas e dados existentes em qualquer banco de dados; Não requer nenhum tipo de dado JSON nativo
  • 📚 Documentação Abrangente: Manual do usuário detalhado e arquivos README, documentação de API, aplicativos de exemplo
  • ☁️ Agnóstico de Nuvem: Implante em qualquer lugar com suporte a Docker
  • ⚡ Alto Desempenho: Construído sobre a arquitetura versátil de microsserviços Gilhari e mecanismo ORM otimizado
  • 🛡️ Tratamento Robusto de Erros: Mensagens de erro claras e mecanismos de recuperação
  • 📈 Escalável: Lida com múltiplas solicitações concorrentes de forma eficiente; Implantação Docker escalável

Como 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: A aplicação de IA (cliente LLM) traduz a linguagem natural em chamadas de ferramentas MCP. O Servidor ORMCP então traduz essas chamadas de ferramentas MCP em chamadas de API REST para o Gilhari.

O Servidor ORMCP preenche a lacuna entre aplicações modernas de IA e bancos de dados relacionais através de:

  • Protocolo MCP: Comunicação padronizada de IA para ferramenta
  • Gilhari: Camada de integração com bancos de dados relacionais via ORM e JDBC
  • Mapeamento JSON: Mapeamento objeto-relacional transparente

🚀 Início Rápido

Novo no ORMCP? Vá direto ao guia específico da sua plataforma para uma configuração simplificada: 🍎 macOS · 🪟 Windows · 🐧 Linux

As seções abaixo cobrem todas as plataformas juntas como uma referência completa.

Três Passos Simples para Usar o ORMCP

1. Defina o Escopo dos Seus Dados

  • Defina modelos de objetos leves para seus dados relevantes
  • Escreva uma especificação ORM declarativa para esses modelos em um arquivo de texto usando uma gramática simples (JDX)

2. Construa Seu Microsserviço Gilhari

  • Adicione modelos, especificação ORM e driver JDBC a um Dockerfile
  • Construa a imagem Docker do Gilhari

3. Execute com o ORMCP

  • Conecte o ORMCP ao microsserviço Gilhari
  • Inicie o Gilhari e depois o ORMCP
  • Interaja com dados relacionais definidos de forma intuitiva e orientada a objetos usando um Agente de IA ou cliente MCP

Início Rápido Detalhado

Pré-requisitos

  • Python 3.12+
  • Docker (para o microsserviço Gilhari)
  • Driver JDBC para seu banco de dados de destino

1. Instale o Servidor ORMCP

Guias específicos por plataforma com instruções de instalação passo a passo para seu sistema operacional: macOS · Windows · Linux

O Servidor ORMCP está disponível no PyPI público. Nenhuma conta, token ou solicitação de acesso beta é necessária para instalá-lo:

pip install ormcp-server

# Verify installation
pip show ormcp-server

📌 Usuários de Linux/Mac: Distribuições Linux modernas e macOS podem exigir ambientes virtuais. Consulte seu guia de plataforma ou o guia de solução de problemas se você receber erros de "ambiente gerenciado externamente".

# 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

Se você tiver um token Gemfury existente de uma instalação beta anterior, ele não funcionará mais — o acesso ao Gemfury foi descontinuado. Use pip install ormcp-server, que puxa diretamente do PyPI público.

Se o comando ormcp-server não for encontrado após a instalação:

Adicione o diretório de executáveis do Python ao seu PATH. Consulte o guia da sua plataforma para obter detalhes: macOS · Windows · Linux

2. Configure o Microsserviço Gilhari

Consulte a configuração detalhada na seção Configuração do Microsserviço Gilhari abaixo.

Nota: Um exemplo completo e funcional está disponível em um repositório separado: gilhari_example1

Para executar o exemplo:

IMPORTANTE: Docker é necessário para construir e executar um microsserviço Gilhari — Obtenha o Docker se ainda não estiver instalado em sua 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. Configure o Ambiente

# 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. Inicie o Servidor ORMCP

ormcp-server

Se você receber erros de comando não encontrado, consulte o guia da sua plataforma: macOS · Windows · Linux

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

5. Conecte Seu Cliente de IA

Para Claude Desktop, adicione a claude_desktop_config.json:

Opção 1: Usando o nome do comando (requer PATH configurado):

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

Opção 2: Usando o caminho completo (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 seu caminho exato:

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

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

# Linux/Mac
which ormcp-server

Você está pronto! Seu cliente de IA agora pode interagir com seu banco de dados usando linguagem natural.

Nota: Os passos 3 (Configurar o Ambiente) e 4 (Iniciar o Servidor ORMCP) não são necessários se você estiver usando o Claude Desktop como cliente, pois o Claude Desktop inicia automaticamente um servidor ORMCP configurado no modo STDIO.

Exemplos de Uso

Consultar Dados

Prompt de IA: "Mostre-me todos os usuários com idade maior ou igual a 55"

Chamada MCP Gerada:

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

Inserir Dados

Nota: insert (como as outras ferramentas de modificação de dados) só é exposta quando READONLY_MODE=False está definido — consulte Configuração para o Servidor ORMCP. Com o READONLY_MODE=True padrão, a chamada MCP deste exemplo não estará disponível para o cliente.

Prompt de IA: "Adicione um novo Usuário (id = 65) chamado John Smith de Boston, MA, com idade de 65 anos"

Chamada MCP Gerada:

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

Dados Agregados

Prompt de IA: "Qual é a idade média dos usuários na Califórnia?"

Chamada MCP Gerada:

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

Resultado:

49

Configuração do Microsserviço Gilhari

O Servidor ORMCP depende do software Gilhari, um framework de microsserviços para integração de dados JSON com bancos de dados. Esta configuração deve ser concluída antes de iniciar o servidor ORMCP.

IMPORTANTE: Docker é necessário para construir e executar um microsserviço Gilhari — Obtenha o Docker se ainda não estiver instalado em sua máquina

Instale o Software Gilhari

  1. Baixe a imagem Docker do Gilhari:

    docker pull softwaretree/gilhari:latest

  2. Instale o SDK do Gilhari:

Configure Seu Microsserviço Gilhari Específico do Aplicativo

Siga estes passos (detalhados na documentação do SDK do Gilhari):

  1. Defina classes de modelo de domínio - Classes contêiner Java para seus objetos JSON

  2. Crie a especificação ORM declarativa - Mapeie atributos JSON para o esquema do banco de dados

  3. Construa a imagem Docker do microsserviço Gilhari específico do aplicativo - Inclua classes de domínio, especificação ORM e driver JDBC

  4. Execute o microsserviço:

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

Nota: Um exemplo completo e funcional está disponível em um repositório separado: gilhari_example1. Este exemplo demonstra um microsserviço Gilhari que gerencia objetos User.

Início Rápido com Exemplo:

# 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 instruções detalhadas de configuração, consulte o README do gilhari_example1.

Instalação do Pacote ORMCP

Recomendado: Ambiente 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

Instalação Global

pip install ormcp-server

Nota: Ao instalar globalmente (sem um ambiente virtual), o executável ormcp-server será instalado no diretório de Scripts do Python do seu usuário. Consulte seu guia de plataforma se encontrar erros de "comando não encontrado".

Acessando o Pacote Completo com SDK e Exemplos

Para acessar o pacote completo, incluindo o SDK do Gilhari, exemplos e documentação:

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

Usuários do Windows: Se você não tiver o tar instalado, você pode:

  • Usar 7-Zip ou WinRAR para extrair o arquivo .tar.gz
  • Ou usar o PowerShell: tar -xzf ormcp_server-*.tar.gz
  • Ou baixar diretamente da página do projeto no PyPI

Conteúdo do Pacote

O pacote do Servidor ORMCP inclui recursos adicionais além do código Python:

Instalação em Tempo de Execução (Wheel)

Quando você instala via pip, obtém o pacote Python principal necessário para executar o Servidor ORMCP:

pip install ormcp-server

Isso instala apenas os arquivos de tempo de execução essenciais em seu ambiente Python.

Pacote Completo com SDK e Documentação (Distribuição de Código Fonte)

O pacote completo inclui:

  • Gilhari_SDK/ - SDK completo com documentação, exemplos e ferramentas para criar microsserviços Gilhari personalizados
  • gilhari_example1/ - Microsserviço Gilhari de exemplo pronto para uso
  • package/client/ - Código de cliente de exemplo e documentação de uso
  • package/docs/ - Documentação técnica adicional
  • pyproject.toml - Configuração de build
  • README.md - Este arquivo
  • LICENSE - Termos de licença

Acessando o Pacote Completo

Opção 1: Baixar do 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/

Usuários do Windows: Se você não tiver o tar instalado, você pode:

  • Usar 7-Zip ou WinRAR para extrair o arquivo .tar.gz
  • Ou usar o PowerShell: tar -xzf ormcp_server-0.6.x.tar.gz
  • Ou baixar diretamente da página do projeto no PyPI

Opção 2: Baixar da Página do Pacote

Visite https://pypi.org/project/ormcp-server/ e baixe o arquivo .tar.gz.

Procure pela seção "Download files" e baixe a distribuição de código fonte (.tar.gz).

Usando o SDK do Gilhari

Após extrair a distribuição de código fonte:

# 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

Executando o Exemplo do Microserviço Gilhari

# Navigate to the example
cd gilhari_example1

# Follow the README.md in that directory to:
# 1. Build the Docker image
# 2. Run the microservice
# 3. Populate sample data
# 4. Test with ORMCP Server

Por que dois formatos de pacote?

  • Wheel (.whl) - Distribuição binária, instalação rápida, inclui apenas o código de execução (~50KB)
  • Source Distribution (.tar.gz) - Pacote completo com todos os recursos (~vários MB)

A maioria dos usuários só precisa do wheel para executar o ORMCP Server. Baixe a distribuição de código-fonte se precisar de:

  • O SDK do Gilhari para criar microserviços personalizados
  • Aplicativos de exemplo e código de cliente
  • Documentação completa
  • Guias técnicos adicionais

Configuração para o ORMCP Server

Configure por meio de variáveis de ambiente:

VariávelDescriçãoPadrãoExemplo
GILHARI_BASE_URLURL do microserviço Gilharihttp://localhost:80/gilhari/v1/http://myhost:8888/gilhari/v1/
MCP_SERVER_NAMEIdentificador do servidorORMCPServerDemoMyCompanyORMCP
GILHARI_TIMEOUTTempo limite da API (segundos)3060
LOG_LEVELNível de detalhe do logINFODEBUG, WARNING, ERROR
READONLY_MODEExpor apenas operações de leituraTrueFalse
GILHARI_NAMENome do microserviço Gilhari específico do aplicativo""my-gilhari-microservice
GILHARI_IMAGENome da imagem Docker do microserviço Gilhari específico do aplicativo""gilhari_example1:1.0
GILHARI_HOSTEndereço IP da máquina host para o microserviço Gilharilocalhost10.20.30.40
GILHARI_PORTNúmero da porta para contatar o microserviço Gilhari808888

Observações:

  • READONLY_MODE tem como padrão True: as ferramentas MCP que podem potencialmente modificar dados (insert, update, update2, delete, delete2) não são expostas pelo servidor ORMCP ao cliente MCP, a menos que você defina explicitamente READONLY_MODE=False.
  • GILHARI_BASE_URL e GILHARI_NAME são usados para verificar um contêiner de microserviço Gilhari já em execução
  • GILHARI_IMAGE, GILHARI_NAME e GILHARI_PORT são usados para executar uma nova instância do microserviço Gilhari se um microserviço existente não for encontrado. Certifique-se de que os valores das variáveis GILHARI_HOST e GILHARI_PORT correspondam aos valores correspondentes na configuração GILHARI_BASE_URL, pois é onde o servidor ORMCP contatará o microserviço Gilhari.

Exemplo de Configuração

# 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 o Servidor

Modo Padrão (Recomendado)

Ative seu ambiente virtual (se estiver usando um):

# Linux/Mac
source .venv/bin/activate

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

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

Inicie o servidor usando o comando CLI:

ormcp-server

Isso executa o servidor MCP no modo stdio por meio do ponto de entrada main.py.

Solução de problemas — Comando não encontrado:

Se você receber 'ormcp-server' is not recognized ou command not found, consulte o guia da sua plataforma para configuração do PATH e opções de correção: macOS · Windows · Linux

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

Usando o Código-Fonte Diretamente (Avançado)

Observação: Requer a distribuição de código-fonte. Baixe com:

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

Execute o servidor diretamente com Python:

python src/ormcp_server.py

Isso ignora o wrapper CLI e executa o servidor diretamente.

Métodos Alternativos (Usuários Avançados)

Execução direta do executável:

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

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

Usando a CLI fastmcp (requer distribuição de código-fonte):

fastmcp run src/ormcp_server.py

Usando o modo de desenvolvimento do MCP Inspector (requer distribuição de código-fonte):

mcp dev src/ormcp_server.py

Usando o MCP Inspector sem código-fonte:

Se você tiver o pacote ormcp-server instalado, pode usar o MCP Inspector para explorar os recursos do 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

Isso permite que você teste e explore interativamente as ferramentas do ORMCP Server sem precisar da distribuição de código-fonte.

Suporte a Transporte HTTP ou SSE

Observação: O ORMCP usa como padrão o transporte stdio, que é o que a maioria dos clientes de IA para desktop (por exemplo, Claude Desktop) usa por padrão. O modo HTTP (transporte HTTP Streamable) também é totalmente suportado para implantações autônomas/em rede — consulte o guia de interação em modo HTTP para obter detalhes. Alguns clientes (por exemplo, Gemini CLI) atualmente exigem o modo HTTP.

Você pode iniciar o servidor ORMCP no modo HTTP pela linha de comando:

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

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

Personalize host e porta:

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

Opções de linha de comando disponíveis:

  • --transport: Escolha entre "stdio" (padrão) ou "http"
  • --host: Defina o endereço do host (padrão: 127.0.0.1, usado apenas no modo HTTP)
  • --port: Defina o número da porta (padrão: 8080, usado apenas no modo HTTP)

Configuração HTTP rápida:

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

Certifique-se de ter o uvicorn instalado como dependência, pois o modo HTTP o usa para servir o aplicativo.

Uso no Modo HTTP

O servidor MCP em execução no modo HTTP não foi projetado para ser acessado diretamente por um navegador da web. É um servidor de API que espera mensagens específicas do protocolo MCP, não solicitações HTTP GET para o caminho raiz.

Resumo

  • Use a CLI ormcp-server para a experiência mais limpa e recomendada.
  • Use python src/ormcp_server.py diretamente para execuções simples com a distribuição de código-fonte.
  • Use mcp dev ou fastmcp run para cenários avançados de desenvolvimento/teste com a distribuição de código-fonte.

Saída 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 ...

Implantação em Contêiner (Registros MCP)

Para implantação por meio de registros MCP, como Glama, um script start.sh é fornecido na raiz deste repositório. Ele lida com a instalação e inicialização do ORMCP Server em um ambiente conteinerizado. Consulte o script para obter as variáveis de ambiente e detalhes de configuração necessários.

Configuração do Cliente MCP

Claude Desktop

Locais de arquivos de configuração específicos da plataforma e configuração de PATH: macOS · Windows · Linux

Opção 1: Usando o Nome do Comando (Requer PATH Configurado)

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

Opção 2: Usando o Caminho Completo (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 seu caminho de instalação exato:

# 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

Opção 3: Execução Direta com Python

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

Opção 4: Usando FastMCP (Para Desenvolvedores com Distribuição de Código-Fonte)

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

Opção 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"
      }
    }
  }
}

Observações:

  • ORMCPServerDemo é o nome padrão do servidor ORMCP.
  • Substitua <YourUsername> pelo seu nome de usuário real do Windows
  • Se você estiver fornecendo um número de porta do microserviço Gilhari associado por meio da variável de ambiente "GILHARI_BASE_URL", certifique-se de que essa seja a porta onde o microserviço Gilhari está escutando.
  • Observação: Em 20 de julho de 2025, o Claude desktop não suportava conexão a um servidor MCP em execução no modo http.

Gemini CLI

Atualize o arquivo settings.json do Gemini:

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

Observação: O Gemini CLI atualmente requer o modo HTTP.

OpenAI GPTs (Modo Desenvolvedor)

Para conectar o servidor ORMCP a um GPT personalizado no modo desenvolvedor, o servidor deve estar em execução no modo HTTP e ser acessível por uma URL pública.

  1. Prepare o Backend:

    • Primeiro, certifique-se de que o microserviço Gilhari esteja compilado e em execução em seu contêiner Docker, conforme as instruções de configuração.

    • Use curl para verificar se o serviço Gilhari está respondendo:

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

  2. Configure e Execute o Servidor ORMCP:

    • Defina as variáveis de ambiente necessárias para o servidor ORMCP se conectar ao Gilhari.

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

    • Inicie o servidor ORMCP no modo HTTP, pois isso é necessário para clientes baseados na web.

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

  3. Exponha o Servidor com uma URL Pública: Os servidores da OpenAI precisam de um endereço web público para alcançar seu servidor ORMCP local. Use um serviço de tunelamento como cloudflared ou ngrok para criar uma URL pública segura que encaminhe para sua máquina local.

    • Opção A: Usando cloudflared (Recomendado)

      • Em um novo terminal, inicie um túnel Cloudflare apontando para a porta do seu servidor.

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

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

    • Opção B: Usando ngrok

      • Em um novo terminal, inicie o ngrok para encaminhar o tráfego para a porta 8080.

        ngrok http 8080

      • ngrok fornecerá uma URL HTTPS pública temporária (por exemplo, https://random-string.ngrok-free.app). Observe que essa URL muda toda vez que você reinicia o ngrok no plano gratuito.

  4. Conecte-se ao Seu GPT Personalizado:

    • Pegue a URL pública gerada por cloudflared ou ngrok.
    • Acrescente /mcp ao final dessa URL. O resultado final será seu endpoint MCP, por exemplo: https://<your-public-url>/mcp.
    • Nas configurações do seu GPT (Configurações → Aplicativos e Conectores → Criar), cole essa URL completa no campo URL do Servidor MCP. O GPT descobrirá e se conectará às ferramentas fornecidas pelo seu servidor ORMCP.

Outros Clientes MCP

Referência de Ferramentas MCP

O ORMCP Server fornece as seguintes ferramentas MCP para interagir com seu banco de dados.

📖 Documentação Detalhada da API: Para especificações completas de parâmetros e detalhes técnicos, consulte a Referência da API de Ferramentas MCP.

💡 Exemplos Práticos: Consulte exemplos de uso no mundo real no diretório de exemplos.

Operações Principais

getObjectModelSummary

Recupera informações sobre o modelo de objetos subjacente.

Retorna: Informações sobre classes (tipos), atributos, chaves primárias e relacionamentos no seu modelo de domínio.

query

Consulta objetos com filtragem e travessia de relacionamentos.

Parâmetros:

  • className (string): Tipo de objetos a consultar
  • filter (string, opcional): Cláusula WHERE semelhante a SQL para filtragem
  • maxObjects (inteiro, opcional): Número máximo de objetos a recuperar (-1 para todos, padrão: -1)
  • deep (booleano, opcional): Incluir objetos referenciados nos resultados (padrão: true)
  • operationDetails (string, opcional): Matriz JSON de diretivas operacionais para ajuste fino de consultas. Suporta operações semelhantes a GraphQL, como:
    • projections: Recuperar apenas atributos específicos
    • ignore ou follow: Controlar ramificações de objetos referenciados
    • filter: Aplicar filtros a objetos referenciados

getObjectById

Recupera um objeto específico por sua chave primária.

Parâmetros:

  • className (string): Tipo de objeto a recuperar
  • primaryKey (objeto): Valores da chave primária (valor único ou objeto de chave composta)
  • deep (booleano, opcional): Incluir objetos referenciados (padrão: true)
  • operationDetails (string, opcional): Diretivas operacionais para ajuste fino de consultas

access

Recupera objeto(s) referenciado(s) por um atributo específico de um objeto de referência.

Parâmetros:

  • className (string): Tipo do objeto de referência
  • jsonObject (objeto): O objeto de referência que contém a referência
  • attributeName (string): Nome do atributo cujo(s) valor(es) referenciado(s) devem ser recuperados
  • deep (booleano, opcional): Incluir também objetos referenciados dos objetos recuperados (padrão: true)
  • operationDetails (string, opcional): Diretivas operacionais para ajuste fino de consultas

getAggregate

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

Parâmetros:

  • className (string): Tipo de objetos a agregar
  • attributeName (string): Atributo sobre o qual realizar a agregação
  • aggregateType (string): Tipo de agregação - COUNT, SUM, AVG, MIN, MAX
  • filter (string, opcional): Cláusula WHERE estilo SQL para filtrar objetos antes da agregação

Operações de Modificação de Dados

Nota: Essas ferramentas só são expostas se READONLY_MODE=False estiver definido — READONLY_MODE tem como padrão True, portanto insert, update, update2, delete e delete2 não estão disponíveis por padrão. Consulte Configuração para o Servidor ORMCP acima.

insert

Salva um ou mais objetos JSON no banco de dados.

Parâmetros:

  • className (string): Tipo de objetos a inserir
  • jsonObjects (array): Lista de objetos JSON a salvar no banco de dados
  • deep (booleano, opcional): Salvar também objetos referenciados (padrão: true)

update

Atualiza um ou mais objetos existentes com novos valores.

Parâmetros:

  • className (string): Tipo de objetos a atualizar
  • jsonObjects (array): Lista de objetos com valores atualizados (deve incluir chaves primárias)
  • deep (booleano, opcional): Atualizar também objetos referenciados (padrão: true)

update2

Atualização em massa de objetos que correspondem aos critérios do filtro.

Parâmetros:

  • className (string): Tipo de objetos a atualizar
  • filter (string): Cláusula WHERE estilo SQL para identificar objetos a atualizar
  • newValues (array): Lista de nomes de atributos e seus novos valores
  • deep (booleano, opcional): Atualizar também objetos referenciados (padrão: true)

delete

Exclui objetos específicos do banco de dados.

Parâmetros:

  • className (string): Tipo de objetos a excluir
  • jsonObjects (array): Objetos a excluir (chaves primárias necessárias para identificação)
  • deep (booleano, opcional): Excluir também objetos referenciados (padrão: true)

delete2

Exclusão em massa de objetos que correspondem aos critérios do filtro.

Parâmetros:

  • className (string): Tipo de objetos a excluir
  • filter (string, opcional): Cláusula WHERE estilo SQL para identificar objetos a excluir (string vazia exclui todos os objetos da classe especificada)
  • deep (booleano, opcional): Excluir também objetos referenciados (padrão: true)

Nota: READONLY_MODE tem como padrão True, portanto as ferramentas MCP para operações de modificação de dados (insert, update, update2, delete, delete2) não são expostas aos clientes MCP, a menos que você defina explicitamente READONLY_MODE=False.

Solução de Problemas

Para problemas comuns e soluções, consulte o Guia Completo de Solução de Problemas.

Solução Rápida de Problemas

Problemas de Instalação:

Problemas de Exemplo com Gilhari:

  • Permissão negada no script de shell → chmod +x *.sh ou use sh build.sh (Linux/Mac)
  • Erros de conexão com o banco de dados → Verifique o driver JDBC no Gilhari

Problemas de Tempo de Execução:

  • O servidor não inicia → Verifique se o Gilhari está em execução
  • Erros de conexão com o banco de dados → Verifique o driver JDBC no Gilhari
  • Problemas de conexão do cliente MCP → Verifique a sintaxe do arquivo de configuração

Ativar Modo de Depuração:

# 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

Obter Ajuda:

Desenvolvimento

Testes

Para testes e desenvolvimento com a distribuição de código-fonte:

# 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

Desenvolvimento de Microsserviço Gilhari

  • Servidor ORMCP utiliza o software Gilhari, um framework de microsserviços RESTful para integração de dados JSON com bancos de dados.
  • Você primeiro cria um microsserviço Gilhari personalizado com base nos modelos de dados relacionais de objetos da sua aplicação.
  • Uma especificação de mapeamento objeto-relacional (ORM) define e controla o escopo e a forma do seu modelo de objetos correspondente ao seu modelo relacional.
  • A especificação ORM é definida declarativamente em um arquivo de texto (.jdx) com base em uma gramática simples.
  • Você pode ser capaz de fazer engenharia reversa da especificação ORM a partir de um esquema de banco de dados existente usando ferramentas/exemplos fornecidos com o SDK do Gilhari. Verifique o diretório examples\JDX_ReverseEngineeringJSONExample.
  • O exemplo de engenharia reversa também está disponível online em github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample
  • Para detalhes sobre a criação de microsserviços Gilhari personalizados, consulte a documentação do SDK do Gilhari incluída no pacote de distribuição de código-fonte.
  • Embora um servidor ORMCP possa iniciar um microsserviço Gilhari se configurado para isso (usando as variáveis de ambiente GILHARI_IMAGE, GILHARI_NAME e GILHARI_PORT), é recomendado que você inicie seu microsserviço Gilhari personalizado antes de usar o servidor ORMCP. Além disso, certifique-se de que o número da porta na variável de ambiente 'GILHARI_BASE_URL' para o servidor ORMCP corresponda ao número da porta na qual o microsserviço Gilhari personalizado está ouvindo chamadas REST recebidas.

Contribuindo

Obrigado pelo seu interesse no Servidor ORMCP!

🚫 Sem Contribuições de Código Neste Momento

O Servidor ORMCP é um software proprietário. Não estamos aceitando contribuições de código, pull requests ou envios de recursos.

🐞 Feedback e Relatórios de Bugs

Aceitamos feedback sobre a versão beta! Você pode nos ajudar a melhorar o Servidor ORMCP:

  • Relatando bugs ou problemas
  • Sugerindo melhorias
  • Compartilhando sua experiência

Como Fornecer Feedback

Qualquer feedback que você fornecer pode ser usado pela Software Tree para melhorar o produto, sem qualquer obrigação de creditar ou compensar você.

Software de Terceiros

Dependência Gilhari e JDX: O Servidor ORMCP requer o microsserviço Gilhari para funcionar, que por sua vez depende do JDX, a tecnologia ORM subjacente usada pelo Gilhari. Ambos são produtos proprietários da Software Tree. Gilhari e JDX incorporam vários componentes de software de terceiros. Para detalhes completos desses componentes de terceiros e suas licenças, consulte o arquivo LICENSE no SDK do Gilhari, ou visite: https://www.softwaretree.com/v1/products/gilhari/ e https://www.softwaretree.com/v1/products/jdx/jdx.html

Dependências Python: O Servidor ORMCP usa as seguintes bibliotecas Python de código aberto, cada uma regida por suas respectivas licenças:

  • mcp (SDK do Model Context Protocol)
  • fastmcp (framework FastMCP)
  • httpx (biblioteca de cliente HTTP)
  • pydantic (biblioteca de validação de dados)
  • uvicorn (servidor ASGI)
  • requests (biblioteca HTTP)

Licença

O Servidor ORMCP é um software proprietário de propriedade da Software Tree, LLC. Consulte o arquivo LICENSE para os termos completos.

Avaliação Beta: O Servidor ORMCP está atualmente disponível como um produto beta sob uma licença de avaliação. Isso permite uso gratuito para fins de teste e avaliação por um período de avaliação limitado (30 dias a partir da data de instalação).

Dependência Gilhari e JDX: O Servidor ORMCP requer o microsserviço Gilhari para funcionar, que por sua vez depende do JDX, a tecnologia ORM subjacente usada pelo Gilhari. Ambos são produtos proprietários da Software Tree sob seus próprios acordos de licença. Ao usar o Servidor ORMCP, você concorda em cumprir também a Licença Gilhari e a Licença JDX. Gilhari e JDX incorporam vários componentes de software de terceiros — para detalhes, consulte o arquivo LICENSE no SDK do Gilhari, ou visite https://www.softwaretree.com/v1/products/gilhari/ e https://www.softwaretree.com/v1/products/jdx/jdx.html.

Licenciamento Comercial: O uso do Servidor ORMCP além do período de avaliação está sujeito aos termos de licenciamento da Software Tree aplicáveis na época. Para obter informações ou expressar interesse, entre em contato com a Software Tree em ormcp_support@softwaretree.com ou visite https://www.softwaretree.com.

Suporte e Recursos

Feito com ❤️ para a comunidade de IA e banco de dados