OHMS - Sistema de Gestión de Hub de Pedidos

Flauraly Flowers and Plants - Servidor Python FastMCP alojado en una VM reservada de Replit.

Propósito

OHMS expone un conjunto pequeño y reforzado de herramientas relacionadas con pedidos e inventario a Violet (y a cualquier otro cliente MCP autorizado) a través del Protocolo de Contexto de Modelo (MCP). Centraliza el acceso a la API REST de Shopify Admin detrás de una puerta de autenticación Bearer para que los agentes nunca toquen las credenciales sin procesar de Shopify.

Arquitectura

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

Tanto /mcp (HTTP transmitible) como /sse (alternativa de eventos enviados por el servidor) están montados simultáneamente para que cualquier perfil de transporte de cliente MCP funcione.

Variables de entorno

OHMS se autentica en Shopify mediante la concesión client_credentials de OAuth 2.0. El servidor nunca mantiene un SHOPIFY_ACCESS_TOKEN de larga duración; en su lugar, mantiene un par SHOPIFY_CLIENT_ID + SHOPIFY_CLIENT_SECRET y genera un token de acceso de corta duración bajo demanda contra https://{shop}.myshopify.com/admin/oauth/access_token. El token generado se almacena en caché en la memoria con un búfer de desviación de reloj de 5 minutos y se vuelve a generar automáticamente (o ante un 401/403 de cualquier llamada posterior). Todos los valores se leen mediante os.environ.get(...). Nada está codificado de forma rígida.

Consulte .env.example para ver la plantilla de marcador de posición.

Desarrollo local (Windows)

OHMS lee .env solo cuando se ejecuta localmente (a través de python-dotenv). Arranque su .env desde el almacén de secretos protegido por DPAPI de Windows en lugar de escribir secretos en texto plano:

# 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

El servidor escucha en http://0.0.0.0:8080 de forma predeterminada. Pruebe con:

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

Despliegue en Replit

1. Cree un proyecto en Replit e importe esta carpeta.

2. En el panel de Secrets, establezca cada variable desde .env.example (usando los valores reales; nunca los pegue en ningún archivo confirmado).

3. Confirme que .replit muestre deploymentTarget = "reserved_vm" y el puerto 8080 -> 80.

4. Despliegue. La URL pública es https://ohms-server.crashzero9.replit.app.

5. Verifique ambos transportes:

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

Registro de herramientas

Estado de la fase

• Fase 1 (actual): Estructura MVP, autenticación Bearer, seis herramientas (4 activas + 2 stubs), despliegue en VM reservada de Replit, suite básica de pytest.

• Fase 2 (planificada): OAuth 2.1 reemplazando al portador estático, controlador completo de DoorDash, controlador de impresora de red real, registro estructurado con redacción de secretos, limitación de tasa.

Notas de seguridad

• No aparecen valores secretos en ningún archivo confirmado.

• Los encabezados Authorization y los cuerpos completos de respuesta de Shopify nunca se registran.

• /health devuelve solo la cadena literal OHMS OK: sin información de versión, entorno o ruta.

• Todas las llamadas httpx tienen un tiempo de espera explícito de 30 segundos.