OHMS - Order Hub Management System

Flauraly Flowers and Plants - Python FastMCP server hosted on Replit Reserved VM.

Purpose

OHMS exposes a small, hardened set of order- and inventory-related tools to Violet (and any other authorized MCP client) over the Model Context Protocol. It centralizes Shopify Admin REST access behind a Bearer-auth gate so agents never touch raw Shopify credentials.

Architecture

+-----------------+      Bearer       +------------------------------+
|  MCP Client     |  ---------------> |  OHMS (Replit Reserved VM)   |
|  (Violet, etc.) |   /mcp or /sse    |                              |
+-----------------+                   |  Starlette parent app        |
                                      |  +-- /health (open)          |
                                      |  +-- /mcp   (Streamable HTTP)|
                                      |  +-- /sse   (SSE fallback)   |
                                      |  +-- BearerAuthMiddleware    |
                                      +--------------+---------------+
                                                     |
                                                     v
                                      +------------------------------+
                                      |  Shopify Admin REST API      |
                                      +------------------------------+

Both /mcp (Streamable HTTP) and /sse (Server-Sent Events fallback) are mounted simultaneously so any MCP client transport profile works.

Environment Variables

OHMS authenticates to Shopify via the OAuth 2.0 client_credentials grant. The server never holds a long-lived SHOPIFY_ACCESS_TOKEN; instead it holds a SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET pair and mints a short-lived access token on demand against https://{shop}.myshopify.com/admin/oauth/access_token. The minted token is cached in-memory with a 5-minute clock-skew buffer and re-minted automatically (or on a 401/403 from any subsequent call). All values are read via os.environ.get(...). Nothing is hardcoded.

See .env.example for the placeholder template.

Local Dev (Windows)

OHMS reads .env only when running locally (via python-dotenv). Bootstrap your .env from the Windows DPAPI-protected secrets store rather than typing secrets in plaintext:

# 1. Pull each secret from DPAPI into the local .env (PowerShell pseudocode)
$secrets = @("OHMS_API_TOKEN","SHOPIFY_STORE_URL","SHOPIFY_CLIENT_ID","SHOPIFY_CLIENT_SECRET","SHOPIFY_API_VERSION","PRINTER_IP")
foreach ($k in $secrets) {
    $v = Unprotect-DpapiSecret -Name $k    # your local helper
    Add-Content .env "$k=$v"
}

# 2. Run the server
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt
python main.py

The server listens on http://0.0.0.0:8080 by default. Probe with:

curl http://localhost:8080/health
# => OHMS OK

Replit Deploy

1. Create a Replit project and import this folder.

2. In the Secrets pane, set every variable from .env.example (using the real values - never paste them into any committed file).

3. Confirm .replit shows deploymentTarget = "reserved_vm" and port 8080 -> 80.

4. Deploy. The public URL is https://ohms-server.crashzero9.replit.app.

5. Verify both transports:

   curl https://ohms-server.crashzero9.replit.app/health
   curl -H "Authorization: Bearer $OHMS_API_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' \
        https://ohms-server.crashzero9.replit.app/mcp

Tool Registry

Phase Status

• Phase 1 (current): MVP scaffold, Bearer auth, six tools (4 live + 2 stubs), Replit Reserved VM deploy, basic pytest suite.

• Phase 2 (planned): OAuth 2.1 replacing static bearer, full DoorDash driver, real network printer driver, structured logging with secret redaction, rate limiting.

Security Notes

• No secret values appear in any committed file.

• Authorization headers and full Shopify response bodies are never logged.

• /health returns only the literal string OHMS OK - no version, env, or path info.

• All httpx calls have an explicit 30-second timeout.