ormcp-server 0.6.1__py3-none-any.whl

README.md

@@ -0,0 +1,177 @@
+# ORMCP Server
+
+**Make your relational data AI ready**
+
+ORMCP Server is a Model Context Protocol (MCP) server that enables AI assistants to interact with relational databases using intuitive, object-oriented operations in JSON format.
+
+## What is ORMCP Server?
+
+ORMCP Server bridges the gap between AI applications and relational databases. It leverages the Gilhari microservice framework and JDX ORM to provide seamless database access through the standardized MCP protocol.
+
+Instead of writing SQL, AI assistants like Claude and Gemini can work with your data using natural language and high-level object operations.
+
+## Key Features
+
+- **🌍 Database Agnostic** - Works with any JDBC-compliant database (PostgreSQL, MySQL, Oracle, SQL Server, SQLite, etc.)
+- **✅ MCP Compliant** - Fully compatible with the Model Context Protocol standard
+- **🔄 Object-Relational Mapping** - JSON object operations transparently mapped to relational data
+- **🧾 Declarative ORM** - Define mappings using simple JDX grammar
+- **🚀 High Performance** - Optimized with connection pooling, caching, and minimal database trips
+- **🔒 Secure** - Domain model-specific operations with optional read-only mode
+
+## Quick Start
+
+### Installation
+
+```bash
+pip install ormcp-server
+```
+
+**Existing Gemfury beta users:** If you previously installed via Gemfury, you can continue using that channel or switch to PyPI. Both are supported during the beta period.
+
+### Accessing Full Package with SDK and Examples
+
+The source distribution includes everything you need to get started beyond the
+installable package itself — a curated subset of the Gilhari SDK and a
+ready-to-use example microservice.
+
+```bash
+# Download source distribution from PyPI
+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/          Gilhari SDK essentials (libs, config, docs)
+#                         Note: JDX User Manual excluded due to size; available at
+#                         https://www.softwaretree.com/v1/products/jdx/docs/JDX-5.0-Manual-v1.pdf
+# - gilhari_example1/     Ready-to-use SQLite-backed example microservice
+# - package/client/       Example MCP client code
+# - package/docs/         Additional ORMCP documentation
+```
+
+**Existing Gemfury beta users:**
+```bash
+pip download --no-binary :all: \
+  --index-url https://YOUR_TOKEN@pypi.fury.io/softwaretree/ \
+  --extra-index-url https://pypi.org/simple \
+  ormcp-server
+```
+
+### Basic Usage
+
+1. **Configure and start your Gilhari microservice** (handles database connectivity)
+2. **Configure ORMCP Server:**
+
+```bash
+export GILHARI_BASE_URL="http://localhost:80/gilhari/v1/"
+export MCP_SERVER_NAME="MyORMCPServer"
+```
+
+3. **Start the server:**
+
+```bash
+ormcp-server
+```
+
+4. **Connect your AI client** (e.g., Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "my-ormcp-server": {
+      "command": "ormcp-server",
+      "env": {
+        "GILHARI_BASE_URL": "http://localhost:80/gilhari/v1/",
+        "MCP_SERVER_NAME": "MyORMCPServer"
+      }
+    }
+  }
+}
+```
+
+## How It Works
+
+```
+AI Assistant <--MCP--> ORMCP Server <--REST--> Gilhari Microservice <--JDBC--> Database
+```
+
+1. User sends natural language request to AI assistant (e.g., Claude)
+2. AI assistant translates natural language into MCP tool calls
+3. ORMCP Server receives MCP tool calls and translates to REST API calls
+4. Gilhari microservice executes database operations via JDBC/SQL
+5. Results returned as JSON objects through the chain back to user
+
+## Example Interactions
+
+**Query data:**
+```
+"Show me all users in California"
+"What's the average age of users?"
+```
+
+**Manage data:**
+```
+"Create a new user named John Smith in Boston"
+"Update all users in New York to have status=active"
+```
+
+**Explore schema:**
+```
+"What types of objects are available?"
+"Show me the attributes of the User class"
+```
+
+## Available MCP Tools
+
+- **getObjectModelSummary** - Discover classes and relationships
+- **query** - Retrieve objects with filtering and sorting
+- **getObjectById** - Fetch specific objects by primary key
+- **access** - Navigate object relationships
+- **getAggregate** - Calculate COUNT, SUM, AVG, MIN, MAX
+- **insert** - Create new objects
+- **update** - Update existing objects
+- **update2** - Bulk-update existing objects
+- **delete** - Delete objects
+- **delete2** - Bulk-delete existing objects
+
+In the READONLY mode, the insert/update/update2/delete/delete2 tools are not available.
+
+## Requirements
+
+- Python 3.12+
+- Docker (for Gilhari microservice)
+- JDBC driver for your database
+- MCP-compatible client (Claude Desktop, Gemini CLI, etc.)
+
+## Documentation
+
+- **Complete Documentation**: [github.com/softwaretree/ormcp-docs](https://github.com/softwaretree/ormcp-docs)
+- **API Reference**: [ORMCP Tools Reference](https://github.com/softwaretree/ormcp-docs/blob/main/reference/ormcp_tools_reference.md)
+- **Quick Start**: [Getting Started Guide](https://github.com/softwaretree/ormcp-docs#quick-start)
+- **GitHub repositories with working examples**: [Browse Examples](https://github.com/softwaretree/ormcp-docs/tree/main/examples)
+- **Example Microservice**: [github.com/SoftwareTree/gilhari_example1](https://github.com/SoftwareTree/gilhari_example1)
+
+## Beta Notice
+
+ORMCP Server is currently in Beta for testing and evaluation purposes only. Not intended for commercial use.
+
+## Support
+
+- **Email**: ormcp_support@softwaretree.com
+- **Issues**: [github.com/softwaretree/ormcp-docs/issues](https://github.com/softwaretree/ormcp-docs/issues)
+- **Website**: [softwaretree.com](https://www.softwaretree.com)
+
+## License
+
+Proprietary software owned by Software Tree, LLC. See LICENSE for terms.
+
+**Beta Evaluation**: Free for testing during evaluation period. 
+
+**Commercial licensing** terms will be announced at the time of commercial release. For information or to express interest, contact Software Tree at [ormcp_support@softwaretree.com](mailto:ormcp_support@softwaretree.com) or visit [https://www.softwaretree.com](https://www.softwaretree.com).
+
+---
+
+**Software Tree** | Making databases AI-accessible

__init__.py

@@ -0,0 +1,5 @@
+"""
+ORMCP Server package
+"""
+
+__version__ = "0.6.1"

main.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2025, Software Tree
+
+# Alternate entry point for running the ORMCP server in dev/test modes.
+
+# Author: Damodar Periwal
+"""
+Alternate entry point for running the ORMCP server in dev/test/http modes.
+Example: python main.py --mode http --port 8080
+"""
+# main.py
+
+# !/usr/bin/env python3
+import argparse
+import sys
+from ormcp_server import run_server, ORMCP_SERVER_VERSION
+
+
+def main():
+    parser = argparse.ArgumentParser(description="ORMCP Dev/Test Launcher")
+    parser.add_argument("--version", action="version", 
+                        version=f"ORMCP Server v{ORMCP_SERVER_VERSION}")
+
+    parser.add_argument(
+        "--mode",
+        choices=["dev", "test", "stdio", "http"],
+        default="dev",
+        help="Run mode: dev = stdio, test = mock, stdio = explicit stdio mode, http = HTTP server"
+    )
+    parser.add_argument(
+        "--host", default="127.0.0.1",
+        help="Host to bind for HTTP mode (ignored for stdio)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=8080,
+        help="Port to bind for HTTP mode (ignored for stdio)"
+    )
+
+    args = parser.parse_args()
+
+    if args.mode == "dev":
+        print("👨💻 Running in development (stdio) mode...", file=sys.stderr)
+        sys.stderr.flush()
+        run_server("stdio")
+    elif args.mode == "test":
+        print("🧪 Running in test mode... (placeholder)", file=sys.stderr)
+        # Insert mock or testing logic here
+        print("Simulated test complete.", file=sys.stderr)
+        sys.stderr.flush()
+    elif args.mode == "stdio":
+        print("📟 Explicit stdio mode...", file=sys.stderr)
+        sys.stderr.flush()
+        run_server("stdio")
+    elif args.mode == "http":
+        print(f"🌐 Running in HTTP mode on {args.host}:{args.port}...", file=sys.stderr)
+        sys.stderr.flush()
+        run_server("http", args.host, args.port)
+    else:
+        print(f"⚠️ Unknown mode: {args.mode}", file=sys.stderr)
+        sys.stderr.flush()
+
+
+if __name__ == "__main__":
+    main()

microservice_ensure.py

@@ -0,0 +1,337 @@
+# Copyright (c) 2025, Software Tree
+# A utility to check the availability of an app-specific GIlhari microservice.
+# Author: Damodar Periwal
+
+"""
+# microservice_ensure.py
+
+# A utility to check the availability of an app-specific GIlhari microservice.
+# If the Gilhari microservice is not running on not responsive then this
+# utility tries to start the service (through Docker) using the relevant
+# parameter values read from environment variables as described below:
+
+    Env variables   |                    description                    | default value
+        
+    "GILHARI_NAME"  | Name of the app-specific Gilhari microservice     | "my-gilhari-microservice"
+    "GILHARI_HOST"  | IP address of the host machine                    | "localhost"
+    "GILHARI_PORT"  | Port number to contact the Gilhari microservice   | 80
+    "GILHARI_IMAGE" | Docker image name of the app-specific Gilhari     ! ""
+                      microservice
+"""
+import os
+import requests
+import socket
+import subprocess
+import time
+import logging
+from typing import Optional, List
+from dataclasses import dataclass
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ServiceConfig:
+    """Configuration for the microservice"""
+    name: str = ""
+    host: str = "localhost"
+    port: int = 80
+    health_endpoint: Optional[str] = "/health"
+    test_endpoint: Optional[str] = "/api/status"
+    docker_image: str = ""
+    docker_run_args: Optional[List[str]] = None
+    container_name: Optional[str] = None
+    startup_timeout: int = 60
+    health_check_interval: int = 2
+    
+    def __post_init__(self):
+        if self.docker_run_args is None:
+            self.docker_run_args = []
+        if self.container_name is None:
+            self.container_name = f"{self.name}-container"
+
+
+def check_health_endpoint(config: ServiceConfig) -> bool:
+    """
+    Method 1: Try health endpoint
+    """
+    if not config.health_endpoint:
+        logger.debug(f"No health endpoint configured for {config.name}")
+        return False
+    
+    try:
+        url = f"http://{config.host}:{config.port}{config.health_endpoint}"
+        logger.debug(f"Checking health endpoint: {url}")
+        
+        response = requests.get(url, timeout=5)
+        if response.status_code == 200:
+            logger.info(f"Health endpoint check passed for {config.name}")
+            return True
+        else:
+            logger.debug(f"Health endpoint returned status {response.status_code}")
+            return False
+            
+    except requests.exceptions.RequestException as e:
+        logger.debug(f"Health endpoint check failed: {e}")
+        return False
+
+
+def check_rest_api_endpoint(config: ServiceConfig) -> bool:
+    """
+    Method 2: Try if REST API service responds to a simple endpoint
+    """
+    if not config.test_endpoint:
+        logger.debug(f"No test endpoint configured for {config.name}")
+        return False
+    
+    try:
+        url = f"http://{config.host}:{config.port}{config.test_endpoint}"
+        logger.debug(f"Checking REST API endpoint: {url}")
+        
+        response = requests.get(url, timeout=5)
+        
+        # Option 1: Accept any HTTP response (service is running)
+        # This treats 404, 500, etc. as "service is up"
+        logger.info(f"REST API endpoint check passed for {config.name} (status: {response.status_code})")
+        return True
+        
+        # Option 2: Only accept successful responses (uncomment if you want this behavior)
+        # if 200 <= response.status_code < 400:
+        #     logger.info(f"REST API endpoint check passed for {config.name} (status: {response.status_code})")
+        #     return True
+        # else:
+        #     logger.debug(f"REST API endpoint returned error status: {response.status_code}")
+        #     return False
+        
+    except requests.exceptions.RequestException as e:
+        logger.debug(f"REST API endpoint check failed: {e}")
+        return False
+
+
+def check_port_connection(config: ServiceConfig) -> bool:
+    """
+    Method 3: Try port connection
+    """
+    try:
+        logger.debug(f"Checking port connection: {config.host}:{config.port}")
+        
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(5)
+        result = sock.connect_ex((config.host, config.port))
+        sock.close()
+        
+        if result == 0:
+            logger.info(f"Port connection check passed for {config.name}")
+            return True
+        else:
+            logger.debug(f"Port connection failed with result: {result}")
+            return False
+            
+    except Exception as e:
+        logger.debug(f"Port connection check failed: {e}")
+        return False
+
+
+def is_service_available(config: ServiceConfig) -> bool:
+    """
+    Test all three methods to check if service is available
+    """
+    logger.info(f"Checking availability of {config.name} service...")
+    
+    # Method 1: Health endpoint
+    if check_health_endpoint(config):
+        return True
+    
+    # Method 2: REST API endpoint
+    if check_rest_api_endpoint(config):
+        return True
+    
+    # Method 3: Port connection
+    if check_port_connection(config):
+        return True
+    
+    logger.info(f"Service {config.name} is not available")
+    return False
+
+
+def stop_existing_container(config: ServiceConfig) -> bool:
+    """
+    Stop and remove existing container if it exists
+    """
+    try:
+        # Ensure container_name is not None
+        container_name = config.container_name or f"{config.name}-container"
+        
+        # Check if container exists
+        result = subprocess.run(
+            ["docker", "ps", "-a", "--filter", f"name={container_name}", "--format", "{{.Names}}"],
+            capture_output=True,
+            text=True,
+            check=True
+        )
+        
+        # Fix 1: Handle potential None result from stdout and container_name
+        if result.stdout and config.container_name and config.container_name in result.stdout:
+            logger.info(f"Stopping existing container: {config.container_name}")
+            
+            # Stop container
+            subprocess.run(
+                ["docker", "stop", str(config.container_name)],
+                check=True
+            )
+            
+            # Remove container
+            subprocess.run(
+                ["docker", "rm", str(config.container_name)],
+                check=True
+            )
+            
+            logger.info(f"Removed existing container: {config.container_name}")
+            return True
+            
+    except subprocess.CalledProcessError as e:
+        logger.warning(f"Error managing existing container: {e}")
+        return False
+    
+    return False
+
+
+def start_docker_service(config: ServiceConfig) -> bool:
+    """
+    Start the microservice using Docker
+    """
+    if not config.docker_image:
+        logger.error(f"No Docker image specified for {config.name}")
+        return False
+    
+    try:
+        # Stop existing container if it exists
+        stop_existing_container(config)
+        
+        # Build Docker run command
+        docker_cmd = [
+            "docker", "run",
+            "-d",  # Run in detached mode
+            "--name", config.container_name
+        ]
+        
+        # Add any additional Docker run arguments
+        docker_cmd.extend(config.docker_run_args or [])
+        
+        # Add the image name
+        docker_cmd.append(config.docker_image)
+        
+        logger.info(f"Starting Docker container for {config.name}: {' '.join(docker_cmd)}")
+        
+        # Start the container
+        result = subprocess.run(docker_cmd, capture_output=True, text=True, check=True)
+        container_id = result.stdout.strip()
+        
+        logger.info(f"Started container {config.container_name} with ID: {container_id}")
+        return True
+        
+    except subprocess.CalledProcessError as e:
+        logger.error(f"Failed to start Docker container: {e}")
+        logger.error(f"stderr: {e.stderr}")
+        return False
+
+
+def wait_for_service(config: ServiceConfig) -> bool:
+    """
+    Wait for the service to become available
+    """
+    logger.info(f"Waiting for {config.name} to become available...")
+    
+    start_time = time.time()
+    while time.time() - start_time < config.startup_timeout:
+        if is_service_available(config):
+            elapsed = time.time() - start_time
+            logger.info(f"Service {config.name} is now available (took {elapsed:.1f}s)")
+            return True
+        
+        logger.debug(f"Service not ready yet, waiting {config.health_check_interval}s...")
+        time.sleep(config.health_check_interval)
+    
+    logger.error(f"Timeout waiting for {config.name} to become available")
+    return False
+
+
+def ensure_microservice(config: ServiceConfig) -> bool:
+    """
+    Main function to ensure microservice is running and available
+    
+    Args:
+        config: ServiceConfig object with service configuration
+        
+    Returns:
+        bool: True if service is available, False otherwise
+    """
+    logger.info(f"Ensuring microservice {config.name} is available...")
+    
+    # Check if service is already available
+    if is_service_available(config):
+        logger.info(f"Service {config.name} is already available")
+        return True
+    
+    # Service is not available, try to start it
+    logger.info(f"Service {config.name} is not available, starting Docker container...")
+    
+    if not start_docker_service(config):
+        logger.error(f"Failed to start Docker service for {config.name}")
+        return False
+    
+    # Wait for service to become available
+    if not wait_for_service(config):
+        logger.error(f"Service {config.name} failed to become available after startup")
+        return False
+    
+    logger.info(f"Successfully ensured {config.name} is available")
+    return True
+
+
+# Ensure that the app-specific Gilhari microservice is running
+def ensure_gilhari_service() -> bool:
+    """
+    Gather app-specific Gilhari microservice parameters and ensure its availability
+    """
+    
+    GILHARI_INTERNAL_PORT = "8081"  # fixed port number of Gilhari inside the container
+    portStr = os.getenv("GILHARI_PORT", "80")  # Outside port number the container is listening on
+    
+    # First gather the Gilhari microservice parameters
+    gilhari_service = ServiceConfig(
+        name=os.getenv("GILHARI_NAME", "my-gilhari-microservice"),
+        host=os.getenv("GILHARI_HOST", "localhost"),
+        port=int(portStr),
+        health_endpoint="/gilhari/v1/health/check",
+        test_endpoint="/gilhari/v1/api/status",
+        docker_image=os.getenv("GILHARI_IMAGE", ""),  # don't want any default docker image name to cause confusion
+        docker_run_args=["-p", f"{portStr}:{GILHARI_INTERNAL_PORT}"],
+        startup_timeout=30,
+        health_check_interval=3
+    )
+    
+    if not ensure_microservice(gilhari_service):
+        logger.error(f"Failed to ensure {gilhari_service.name} is available")
+        return False
+
+    return True
+
+
+# Utility functions for testing individual components
+def test_service_methods(config: ServiceConfig):
+    """
+    Test individual service checking methods
+    """
+    print(f"\nTesting service checking methods for {config.name}:")
+    print(f"Health endpoint check: {check_health_endpoint(config)}")
+    print(f"REST API endpoint check: {check_rest_api_endpoint(config)}")
+    print(f"Port connection check: {check_port_connection(config)}")
+    print(f"Overall availability: {is_service_available(config)}")
+    
+
+if __name__ == "__main__":
+    # Check for the availability of the Gilhari microservice
+    ensure_gilhari_service()