OHMS - Order Hub Management System

Flauraly Flowers and Plants - Python FastMCP-Server, gehostet auf einer Replit Reserved VM.

Zweck

OHMS stellt eine kleine, gehärtete Auswahl an Tools für Bestellungen und Bestandsverwaltung für Violet (und jeden anderen autorisierten MCP-Client) über das Model Context Protocol bereit. Es zentralisiert den Zugriff auf die Shopify Admin REST-API hinter einer Bearer-Authentifizierung, sodass Agenten niemals mit rohen Shopify-Anmeldedaten in Berührung kommen.

Architektur

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

Sowohl /mcp (Streamable HTTP) als auch /sse (Server-Sent Events Fallback) sind gleichzeitig eingebunden, sodass jedes MCP-Client-Transportprofil funktioniert.

Umgebungsvariablen

OHMS authentifiziert sich bei Shopify über den OAuth 2.0 client_credentials-Grant. Der Server speichert niemals ein langlebiges SHOPIFY_ACCESS_TOKEN; stattdessen hält er ein SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET-Paar und erstellt bei Bedarf ein kurzlebiges Zugriffstoken über https://{shop}.myshopify.com/admin/oauth/access_token. Das erstellte Token wird im Arbeitsspeicher mit einem 5-Minuten-Puffer für die Uhrzeit-Abweichung zwischengespeichert und automatisch (oder bei einem 401/403-Fehler eines nachfolgenden Aufrufs) neu erstellt. Alle Werte werden über os.environ.get(...) gelesen. Nichts ist fest codiert.

Siehe .env.example für die Platzhalter-Vorlage.

Lokale Entwicklung (Windows)

OHMS liest .env nur bei lokaler Ausführung (über python-dotenv). Bootstrappen Sie Ihre .env aus dem Windows DPAPI-geschützten Secrets-Speicher, anstatt Geheimnisse im Klartext einzugeben:

# 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

Der Server lauscht standardmäßig auf http://0.0.0.0:8080. Testen mit:

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

Replit-Bereitstellung

1. Erstellen Sie ein Replit-Projekt und importieren Sie diesen Ordner.

2. Setzen Sie im Bereich „Secrets“ jede Variable aus .env.example (unter Verwendung der echten Werte – fügen Sie diese niemals in eine committete Datei ein).

3. Bestätigen Sie, dass .replit deploymentTarget = "reserved_vm" und Port 8080 -> 80 anzeigt.

4. Bereitstellen. Die öffentliche URL lautet https://ohms-server.crashzero9.replit.app.

5. Überprüfen Sie beide Transporte:

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-Registrierung

Phasenstatus

• Phase 1 (aktuell): MVP-Gerüst, Bearer-Authentifizierung, sechs Tools (4 live + 2 Stubs), Replit Reserved VM-Bereitstellung, grundlegende pytest-Suite.

• Phase 2 (geplant): OAuth 2.1 als Ersatz für statische Bearer-Token, vollständiger DoorDash-Treiber, echter Netzwerkdruckertreiber, strukturierte Protokollierung mit Schwärzung von Geheimnissen, Ratenbegrenzung.

Sicherheitshinweise

• In keiner committeten Datei erscheinen geheime Werte.

• Authorization-Header und vollständige Shopify-Antwortkörper werden niemals protokolliert.

• /health gibt nur die Zeichenfolge OHMS OK zurück – keine Versions-, Umgebungs- oder Pfadinformationen.

• Alle httpx-Aufrufe haben ein explizites Timeout von 30 Sekunden.