Labsco
SoftwareTree logo

ORMCP

★ 6

from SoftwareTree

ORMCP provides a curated, object-oriented, MCP-compliant view of relational data in any JDBC-compliant database (e.g., PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite) — improving reasoning clarity, reducing token usage, and establishing a clear governance boundary.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#email#automation#database#cloud#devops#git#maps#translation

Copyright (c) 2025, Software Tree

ORMCP Server - Beta

A Model Context Protocol (MCP) Server to connect your AI applications to relational databases

ORMCP Server enables AI LLMs and MCP clients to easily exchange object-oriented data (in JSON format) with any relational database using the MCP standard protocol.

ORMCP Server makes your relational data AI ready.

⚠️ Beta Notice

ORMCP Server is currently in Beta, and we are offering early access to users who want to check the software, provide feedback, and help us ensure the product meets the highest quality standards. This Beta version is not intended for commercial use, and it is provided for testing purposes only.

📋 Table of Contents

What is MCP?

The Model Context Protocol (MCP) is an open standard that provides a unified way for AI models to interact with external tools and data sources. It standardizes communication, making it easier to integrate LLMs into complex workflows without building custom API integrations for every use case.

Learn more at the Official MCP Website.

✨ Features

  • ✅ Standardized Interface: Fully compliant with the Model Context Protocol (MCP) specification
  • 🌐 Database Agnostic: Works with any JDBC-compliant database (e.g., PostgreSQL, MySQL, Oracle, SQL Server, DB2, SQLite)
  • ↔️ Bi-directional Data Flow: Seamless AI ↔ Database communication with optional support for only READONLY operations
  • 🔄 Object-Relational Mapping (ORM): JSON object operations (CRUD) transparently mapped to relational data
  • 🔒 Secure Data Access: Domain model-specific operations promote data protection
  • 🧾 Declarative ORM Specification: Intuitive, non-intrusive, and flexible ORM specification based on a simple grammar
  • 🕸️ Support for Complex Object Modeling: Including one-to-one, one-to-many, and many-to-many relationships, and path-expressions
  • 🖇️ Flexible Queries: Deep and Shallow queries, Various operational directives similar to GraphQL capabilities to refine the shape and scope of returned objects
  • 🚀 Highly Optimized and Lightweight Mapping Engine: Connection pooling, Prepared statements, Optimized SQL statements, Minimal database trips, Caching of metadata
  • 🔌 Compatible with Existing Data and Databases: Works with existing schemas and data in any database; Does not require any native JSON data type
  • 📚 Comprehensive Documentation: Detailed User manual and README files, API documentation, sample apps
  • ☁️ Cloud Agnostic: Deploy anywhere with Docker support
  • ⚡ High Performance: Built on versatile Gilhari microservice architecture and optimised ORM engine
  • 🛡️ Robust Error Handling: Clear error messages and recovery mechanisms
  • 📈 Scalable: Handles multiple concurrent requests efficiently; Scalable Docker deployment

How It Works

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

Important: The AI application (LLM client) translates natural language into MCP tool calls. ORMCP Server then translates these MCP tool calls into REST API calls to Gilhari.

ORMCP Server bridges the gap between modern AI applications and relational databases through:

  • MCP Protocol: Standardized AI-to-tool communication
  • Gilhari: Integration layer with relational databases via ORM and JDBC
  • JSON Mapping: Transparent object-relational mapping

Package Contents

The ORMCP Server package includes additional resources beyond the Python code:

Runtime Installation (Wheel)

When you install via pip, you get the core Python package needed to run ORMCP Server:

pip install ormcp-server

This installs only the essential runtime files to your Python environment.

Full Package with SDK and Documentation (Source Distribution)

The complete package includes:

  • Gilhari_SDK/ - Complete SDK with documentation, examples, and tools for creating custom Gilhari microservices
  • gilhari_example1/ - Ready-to-use example Gilhari microservice
  • package/client/ - Example client code and usage documentation
  • package/docs/ - Additional technical documentation
  • pyproject.toml - Build configuration
  • README.md - This file
  • LICENSE - License terms

Accessing the Full Package

Option 1: Download from PyPI/Gemfury

Beta (Gemfury):

# Download the source distribution (.tar.gz)
# Note: --extra-index-url is required because build dependencies (like hatchling) 
# are available on PyPI but not on Gemfury
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server

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

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

Replace YOUR_TOKEN with your beta access token.

Production (PyPI) - available after beta:

# Download the source distribution
pip download --no-binary :all: ormcp-server

# Extract it
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Windows users: If you don't have tar installed, you can:

  • Use 7-Zip or WinRAR to extract the .tar.gz file
  • Or use PowerShell: tar -xzf ormcp_server-0.5.x.tar.gz
  • Or download directly from the Gemfury/PyPI website

Option 2: Download from Package Page

Beta: Contact ormcp_support@softwaretree.com for direct download links.

Production (after beta): Visit https://pypi.org/project/ormcp-server/ and download the .tar.gz file.

Look for the "Download files" section and download the source distribution (.tar.gz).

Using the Gilhari SDK

After extracting the source distribution:

# 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

Running the Example Gilhari Microservice

# 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

Why Two Package Formats?

  • Wheel (.whl) - Binary distribution, fast to install, includes only runtime code (~50KB)
  • Source Distribution (.tar.gz) - Complete package with all resources (~several MB)

Most users only need the wheel for running ORMCP Server. Download the source distribution if you need:

  • The Gilhari SDK for creating custom microservices
  • Example applications and client code
  • Complete documentation
  • Additional technical guides

Starting the Server

Activate your virtual environment (if using one):

# Linux/Mac
source .venv/bin/activate

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

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

Start the server using the CLI command:

ormcp-server

This runs the MCP server in stdio mode via the main.py entry point.

Troubleshooting — Command Not Found:

If you get 'ormcp-server' is not recognized or command not found, see your platform guide for PATH configuration and fix options: macOS · Windows · Linux

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

Using Source Code Directly (Advanced)

Note: Requires source distribution. Download with:

# Note: --extra-index-url is required because build dependencies (like hatchling) 
# are available on PyPI but not on Gemfury
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

Run the server directly with Python:

python src/ormcp_server.py

This bypasses the CLI wrapper and runs the server directly.

Alternative Methods (Advanced Users)

Direct executable execution:

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

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

Using fastmcp CLI (requires source distribution):

fastmcp run src/ormcp_server.py

Using MCP Inspector dev mode (requires source distribution):

mcp dev src/ormcp_server.py

Using MCP Inspector without source code:

If you have the ormcp-server package installed, you can use MCP Inspector to explore the server's capabilities:

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

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

This allows you to interactively test and explore ORMCP Server tools without needing the source distribution.

HTTP or SSE Transport Support

Note: Currently only the stdio transport is fully supported out of the box. Support for HTTP or SSE transports is experimental.

You can start the ORMCP server in HTTP mode from the command line:

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

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

Customize host and port:

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

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

Available command-line options:

  • --mode / --transport: Choose between "stdio" (default) or "http"
  • --host: Set the host address (default: 127.0.0.1, only used in HTTP mode)
  • --port: Set the port number (default: 8080, only used in HTTP mode)

Quick HTTP setup:

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

Make sure you have uvicorn installed as a dependency since HTTP mode uses it to serve the application.

Usage in HTTP Mode

The MCP server running in HTTP mode isn't designed to be accessed directly through a web browser. It's an API server that expects specific MCP protocol messages, not HTTP GET requests to the root path.

Summary

  • Use ormcp-server CLI for the cleanest, recommended experience.
  • Use direct python src/ormcp_server.py for simple runs with source distribution.
  • Use mcp dev or fastmcp run for advanced dev/testing scenarios with source distribution.

Expected Output

[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 ...

Containerized Deployment (MCP Registries)

For deployment via MCP registries such as Glama, a start.sh script is provided in the root of this repository. It handles installing and launching ORMCP Server in a containerized environment. See the script for required environment variables and configuration details.

MCP Tools Reference

ORMCP Server provides the following MCP tools for interacting with your database.

📖 Detailed API Documentation: For complete parameter specifications and technical details, see the MCP Tools API Reference.

💡 Working Examples: See real-world usage examples in the examples directory.

Core Operations

getObjectModelSummary

Retrieve information about the underlying object model.

Returns: Information about classes (types), attributes, primary keys, and relationships in your domain model.

query

Query objects with filtering and relationship traversal.

Parameters:

  • className (string): Type of objects to query
  • filter (string, optional): SQL-like WHERE clause for filtering
  • maxObjects (integer, optional): Maximum number of objects to retrieve (-1 for all, default: -1)
  • deep (boolean, optional): Include referenced objects in results (default: true)
  • operationDetails (string, optional): JSON array of operational directives for fine-tuning queries. Supports GraphQL-like operations such as:
    • projections: Retrieve only specific attributes
    • ignore or follow: Control referenced object branches
    • filter: Apply filters to referenced objects

getObjectById

Retrieve a specific object by its primary key.

Parameters:

  • className (string): Type of object to retrieve
  • primaryKey (object): Primary key values (single value or composite key object)
  • deep (boolean, optional): Include referenced objects (default: true)
  • operationDetails (string, optional): Operational directives for fine-tuning queries

access

Retrieve object(s) referenced by a specific attribute of a referencing object.

Parameters:

  • className (string): Type of the referencing object
  • jsonObject (object): The referencing object containing the reference
  • attributeName (string): Name of the attribute whose referenced value(s) to retrieve
  • deep (boolean, optional): Include referenced objects of retrieved objects as well (default: true)
  • operationDetails (string, optional): Operational directives for fine-tuning queries

getAggregate

Calculate aggregate values across objects (COUNT, SUM, AVG, MIN, MAX).

Parameters:

  • className (string): Type of objects to aggregate
  • attributeName (string): Attribute to perform aggregation on
  • aggregateType (string): Type of aggregation - COUNT, SUM, AVG, MIN, MAX
  • filter (string, optional): SQL-like WHERE clause to filter objects before aggregation

Data Modification Operations

insert

Save one or more JSON objects to the database.

Parameters:

  • className (string): Type of objects to insert
  • jsonObjects (array): List of JSON objects to save to the database
  • deep (boolean, optional): Save referenced objects as well (default: true)

update

Update one or more existing objects with new values.

Parameters:

  • className (string): Type of objects to update
  • jsonObjects (array): List of objects with updated values (must include primary keys)
  • deep (boolean, optional): Update referenced objects as well (default: true)

update2

Bulk update objects matching filter criteria.

Parameters:

  • className (string): Type of objects to update
  • filter (string): SQL-like WHERE clause to identify objects to update
  • newValues (array): List of attribute names and their new values
  • deep (boolean, optional): Update referenced objects as well (default: true)

delete

Delete specific objects from the database.

Parameters:

  • className (string): Type of objects to delete
  • jsonObjects (array): Objects to delete (primary keys required for identification)
  • deep (boolean, optional): Delete referenced objects as well (default: true)

delete2

Bulk delete objects matching filter criteria.

Parameters:

  • className (string): Type of objects to delete
  • filter (string, optional): SQL-like WHERE clause to identify objects to delete (empty string deletes all objects of the specified class)
  • deep (boolean, optional): Delete referenced objects as well (default: true)

Note: In READONLY_MODE=True, the MCP tools for data modification operations (insert, update, update2, delete, delete2) are not exposed to MCP clients.

Development

Testing

For testing and development with the source distribution:

Beta (Gemfury):

# Download source distribution
# Note: --extra-index-url is required because build dependencies (like hatchling) 
# are available on PyPI but not on Gemfury
pip download --no-binary :all: \
  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
  --extra-index-url https://pypi.org/simple \
  ormcp-server
tar -xzf ormcp_server-*.tar.gz
cd ormcp_server-*/

# Install in development mode
pip install -e ".[dev]"

# Run tests (if available in source distribution)
pytest

Replace YOUR_TOKEN with your beta access token.

Production (PyPI) - available after beta:

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

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

Gilhari Microservice Development

  • ORMCP Server leverages Gilhari software, a RESTful microservice framework for JSON data integration with databases.
  • You first create a custom Gilhari microservice based on the object relational data models of your application.
  • An object relational mapping (ORM) specification defines and controls the scope and shape of your object model corresponding to your relational model.
  • The ORM specification is defined declaratively in a text file (.jdx) based on a simple grammar.
  • You may be able to reverse-engineer ORM specification from an existing database schema using tools/examples provided with Gilhari SDK. Check the examples\JDX_ReverseEngineeringJSONExample directory.
  • The reverse-engineering example is also available online at github.com/SoftwareTree/JDX_ReverseEngineeringJSONExample
  • For details on creating custom Gilhari microservices, refer to the Gilhari SDK documentation included in the source distribution package.
  • Although an ORMCP server may start a Gilhari microservice if configured to do so (using GILHARI_IMAGE, GILHARI_NAME, and GILHARI_PORT environment variables), it is recommended that you start your custom Gilhari microservice before using the ORMCP server. Also, please make sure that the port number in the 'GILHARI_BASE_URL' environment variable for the ORMCP server matches the port number on which the custom Gilhari microservice is listening for incoming REST calls.

Third-Party Software

Gilhari Dependency: ORMCP Server requires Gilhari microservice to function. Gilhari incorporates various third-party software components. For complete details of these third-party components and their licenses, see the LICENSE file in the Gilhari SDK or visit: https://www.softwaretree.com/v1/products/gilhari/

Python Dependencies: ORMCP Server uses the following open-source Python libraries, each governed by their respective licenses:

  • mcp (Model Context Protocol SDK)
  • fastmcp (FastMCP framework)
  • httpx (HTTP client library)
  • pydantic (Data validation library)
  • uvicorn (ASGI server)
  • requests (HTTP library)

Support & Resources

Made with ❤️ for the AI and database community