grantr-code/orderli_mcp_server

Orderli MCP Server

Overview

Orderli MCP (Model Context Protocol) Server is a Python-based backend for managing and analyzing PostgreSQL databases, with a focus on restaurant POS integrations and error diagnostics. It exposes a set of server functions (tools) for database inspection, health checks, query analysis, and troubleshooting Orderli/POS issues.

---

Prerequisites

• Docker (recommended for setup)
• PostgreSQL database (cloud or local)
• (For local dev) Python 3.12, pip, and system dependencies in requirements.txt

---

Quick Start with Docker

1. Build the Docker image:

   docker build -t orderli-mcp .
   

2. Run the server (replace connection details):

   docker run -it --rm \
     -e DATABASE_URI=postgres://user:pass@host:port/dbname \
     -p 8000:8000 \
     orderli-mcp
   

   • The server defaults to restricted (read-only) mode and SSE transport on port 8000.
   • You can override the access mode and transport:

     docker run -it --rm orderli-mcp --access-mode=unrestricted --transport=stdio
     

   • The entrypoint script automatically remaps localhost in the database URI for Docker compatibility.

3. Environment Variables:

   • DATABASE_URI (required): PostgreSQL connection string.

4. Exposed Port:

   • 8000 (for SSE transport)

---

Local Development (optional)

1. Install Python 3.12 and dependencies:

   pip install -r requirements.txt
   

2. Run the server:

   python -m src.postgres_mcp.server postgres://user:pass@host:port/dbname --access-mode=restricted --transport=stdio
   

---

Server Functions (API Tools)

The following server functions are available (see src/postgres_mcp/server.py):

• list_schemas: List all schemas in the database.
• list_objects: List objects (tables, views, sequences, extensions) in a schema.
• get_object_details: Show detailed information about a database object (columns, constraints, indexes, etc).
• explain_query: Explains the execution plan for a SQL query, with optional real execution and hypothetical indexes.
• execute_sql: Execute any SQL query (restricted to read-only in restricted mode).
• analyze_workload_indexes: Analyze frequently executed queries and recommend optimal indexes (DTA or LLM method).
• analyze_query_indexes: Analyze a list of up to 10 SQL queries and recommend optimal indexes.
• analyze_db_health: Analyze database health (index, connection, vacuum, sequence, replication, buffer, constraint, all).
• get_top_queries: Report the slowest or most resource-intensive queries using pg_stat_statements.
• lookup_error_info: Lookup known Orderli database errors and solutions for a specific POS system (with optional keyword search).
• get_restaurant_pos: Get the restaurant name and configured POS integration for a given restaurant id.
• search_order_errors: Search recent order HTTP requests and order groups for a restaurant, with optional error text and time filters.
• find_menu_pos_mismatches: Find menu/POS inconsistencies that may be causing errors (option requirement mismatches, etc).
• search_by_error_text: Search for a specific error pattern across all restaurants and a wide date range.
• analyze_order_error: Debug and analyze an order error by examining both the order and potential menu-POS mismatches.
• search_common_pos_errors: Search recent order errors for a restaurant matching common POS error patterns (supports relative time).
• find_restaurant: Fuzzy search restaurants by name (case-insensitive substring match).

---