MCP 服务器

retail-order-sync-hub

MCP server enabling AI agents to trace and resolve order synchronization incidents between an ERP (Odoo) and multiple marketplaces.

README

Retail Order Sync Hub — ERP ↔ Marketplaces

Sistema de sincronización de órdenes entre Odoo ERP y múltiples marketplaces (MercadoLibre sandbox + paris-mock), construido con outbox pattern, DLQ, observabilidad end-to-end y un MCP server que permite a un agente IA trazar y operar incidentes de sincronización.

"¿Por qué la orden ML-98345 no apareció en MELI?" → El agente responde con el trace completo y puede reintentar el envío con los permisos correctos.

El escenario

Un lunes con el equipo de Comercio Exterior:

Las órdenes en Odoo no aparecen en los marketplaces.
Los webhooks llegan pero nadie sabe si se procesaron.
El equipo de soporte no tiene visibilidad — necesita abrir un ticket a IT.

Este repo resuelve ese escenario end-to-end:

Odoo como fuente de verdad de órdenes.
Sync confiable a MercadoLibre y Paris con retry exponencial y DLQ.
Webhooks idempotentes con deduplicación y firma HMAC.
Bronze/Silver/Gold en BigQuery para analytics (dbt).
Observabilidad con OpenTelemetry, Grafana y alertas.
MCP server con IAM por scope y audit log — el agente puede responder y actuar.

Arquitectura

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Retail Order Sync Hub                             │
│                                                                             │
│  ┌─────────┐   outbox   ┌──────────────┐    ┌────────────┐                │
│  │  Odoo   │──pattern──▶│ Outbox Worker│───▶│ Adapters   │──▶ MercadoLibre│
│  │  (ERP)  │            │  retry/DLQ   │    │ ML · Paris │──▶ paris-mock  │
│  └─────────┘            └──────────────┘    └────────────┘                │
│       ▲                        │                   │                       │
│       │                   sync.dlq            webhooks                     │
│  reconcile              (Pub/Sub)           (signed · idempotent)         │
│       │                                           │                        │
│  ┌────┴────────────┐                    ┌─────────▼──────┐                │
│  │ Subscriber +    │◀── marketplace ────│ Webhook         │               │
│  │ Reconciler      │      .events       │ Receiver        │               │
│  │ (silver orders) │    (Pub/Sub)       │ (bronze · dedup)│               │
│  └────────┬────────┘                    └────────┬────────┘               │
│           │                                      │                         │
│     ┌─────▼──────────────────────────────────────▼──────┐                 │
│     │                   BigQuery                         │                 │
│     │   bronze (raw) → silver (clean) → gold (SLA/KPIs) │                 │
│     │   dbt models · contracts · singular tests          │                 │
│     └─────────────────────────┬──────────────────────────┘                │
│                               │                                            │
│  ┌────────────────────────────▼──────────────────────────┐                │
│  │                    MCP Server                          │                │
│  │  get_order_status · trace_order · get_dlq_depth        │                │
│  │  get_sla_metrics · find_failed_orders                  │                │
│  │  replay_dlq_message · retry_failed_sync · drain_dlq    │                │
│  │  IAM (scopes: orders.read / dlq.replay / dlq.admin)    │                │
│  │  Audit log (mcp_audit_log, transacción separada)       │                │
│  └────────────────────────────▲──────────────────────────┘                │
│                               │ MCP protocol (stdio)                       │
│                          Claude Code / Desktop                             │
│                                                                            │
│  ┌──────────────────────────────────────────────────────┐                 │
│  │  Observabilidad: OTel Collector → Prometheus + Tempo  │                │
│  │  Grafana: Comex Ops dashboard · Pipeline Health       │                │
│  └──────────────────────────────────────────────────────┘                 │
└─────────────────────────────────────────────────────────────────────────────┘

Diagrama Mermaid completo: docs/diagrams/architecture.mmd

Stack

Capa	Tecnología
Runtime	Python 3.11, uv, ruff, mypy strict
API	FastAPI + Pydantic v2
DB	PostgreSQL (psycopg3) + SQLAlchemy 2.x + Alembic
Broker	Google Cloud Pub/Sub (emulator local, real en GCP)
Outbox	Patrón outbox con `ON CONFLICT DO NOTHING + RETURNING`
DLQ	Pub/Sub topic `marketplace.sync.dlq`
Analytics	BigQuery + dbt (bronze/silver/gold, contratos, tests singulares)
AI	FastMCP 2.x, stdio transport, MCP_STATIC_TOKENS IAM
Observabilidad	OpenTelemetry SDK + Collector → Prometheus + Tempo → Grafana
Infra local	Docker Compose (stack + obs stack separados)
CI	GitHub Actions (ruff + mypy + pytest, coverage ≥ 85%)

Quickstart (10 minutos)

Prerequisitos

Docker Desktop
Python 3.11 (uv lo gestiona automáticamente)
uv instalado: curl -LsSf https://astral.sh/uv/install.sh | sh

1. Clonar e instalar

git clone https://github.com/JulioPradenas/retail-order-sync-hub.git
cd retail-order-sync-hub
uv sync --dev

2. Levantar el stack

make up         # Odoo, Postgres, Pub/Sub emulator, paris-mock
make migrate    # aplica migraciones Alembic
make seed       # carga órdenes demo en Odoo

El primer make up descarga ~2 GB de imágenes. Odoo tarda ~60 s en iniciar.

3. Verificar

# Check de código + tests (85%+ cobertura)
make check

# Odoo disponible en
open http://localhost:8069  # admin / admin

# Paris-mock en
curl http://localhost:9100/orders -H "X-API-Key: change-me"

# Webhook receiver
curl http://localhost:8000/health

4. Observabilidad (opcional)

make obs-up     # Grafana + Prometheus + Tempo + OTel Collector
open http://localhost:3000  # Grafana — admin / admin

Dashboards disponibles:

Comex Ops — webhook throughput, sync outcomes, DLQ depth, latencia p95
Pipeline Health — OTel spans, FastAPI requests, Prometheus targets

5. Tests de integración

make up && make migrate
ROSH_INTEGRATION=1 uv run pytest -m integration -v

6. BigQuery + dbt (requiere GCP)

cp dbt/profiles.yml.template ~/.dbt/profiles.yml
# Edita con tu project_id y credenciales
cd dbt && uv run dbt run && uv run dbt test

MCP Server — Claude como operador de turno

El MCP server expone 8 herramientas a Claude Code o Claude Desktop para trazar y operar incidentes de sincronización.

Configuración (Claude Desktop)

{
  "mcpServers": {
    "retail-order-sync-hub": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.mcp_server"],
      "cwd": "/ruta/al/retail-order-sync-hub",
      "env": {
        "MCP_STATIC_TOKENS": "mi-token:orders.read,metrics.read,outbox.retry,dlq.replay",
        "APP_DB_HOST": "localhost",
        "APP_DB_PORT": "5433"
      }
    }
  }
}

Guía completa: docs/mcp-setup.md

Herramientas disponibles

Herramienta	Scope requerido	Descripción
`get_order_status`	`orders.read`	Estado actual de una orden en Postgres silver
`trace_order`	`orders.read`	Timeline completa: webhooks → outbox → silver
`get_dlq_depth`	`metrics.read`	Cantidad de órdenes en DLQ
`get_sla_metrics`	`metrics.read`	p50/p95 de latencia de sync desde BigQuery gold
`find_failed_orders`	`metrics.read`	Órdenes sin sync en un período
`replay_dlq_message`	`dlq.replay`	Resetea una entrada DLQ a pending (auditado)
`retry_failed_sync`	`outbox.retry`	Re-encola todas las entradas DLQ de una orden (auditado)
`drain_dlq`	`dlq.admin`	Lista o limpia en bulk el DLQ (dry_run por default, auditado)

Demo prompts

¿Por qué la orden ML-12345 no llegó a MercadoLibre?
trace_order("ML-12345")

¿Cuántas órdenes están bloqueadas en DLQ en este momento?
get_dlq_depth()

Hay 3 órdenes atascadas — reintentar todas con retry
retry_failed_sync("12345")

IAM y scopes

Tres roles predefinidos para configurar tokens:

Rol	Scopes
viewer	`orders.read`, `metrics.read`
operator	+ `outbox.retry`, `dlq.replay`
admin	+ `dlq.admin`

Cada operación write queda registrada en mcp_audit_log con user_id, scope, params, resultado y latencia. Referencia completa: docs/iam.md

Documentación

Documento	Contenido
`docs/iam.md`	Scopes, roles, tokens, audit log
`docs/mcp-setup.md`	Configuración Claude Desktop, demo prompts
`docs/observability.md`	Stack OTel, catálogo de métricas, dashboards
`docs/adapters.md`	Contratos de adapters, retry policy
`docs/fde-narrative.md`	Narrativa FDE: decisiones, trade-offs, contexto
`adr/`	Architecture Decision Records (5 ADRs)
`dbt/`	Modelos dbt, contratos de schema, tests singulares

Estructura del repo

src/
  adapters/          # Paris + MercadoLibre adapters (Protocol-based)
  bq_sync/           # BigQuery watermark sync (bronze)
  common/            # Config, DB, models, logging, OTel, signing
  mcp_server/        # FastMCP server (read + write tools, IAM, audit)
  outbox_worker/     # Outbox processor con retry exponencial + DLQ
  paris_mock/        # Mock del marketplace Paris (FastAPI)
  reconciler/        # Reconciliación silver → Odoo
  subscriber/        # Pub/Sub subscriber → normalize → silver
  webhook_receiver/  # Inbound webhooks (HMAC, dedupe, bronze)
infra/
  docker-compose.yml        # Stack operacional
  docker-compose.obs.yml    # Stack de observabilidad
  grafana/                  # Dashboards y datasources
dbt/                        # Modelos bronze/silver/gold + contratos
migrations/                 # Alembic migrations
tests/
  unit/              # 141 tests unitarios (85%+ cobertura)
  integration/       # Tests contra el stack real (ROSH_INTEGRATION=1)
docs/
adr/

Fases completadas

Fase	Descripción	PR
0	Setup repo, ADRs, CI	#1
1	Odoo + Postgres + OTel collector	#2
2	MercadoLibre OAuth + paris-mock	#3
3	Webhook receiver + idempotencia + bronze	#4
4	Adapter + outbox + outbound sync	#5
5	Subscriber + reconciliación + silver	#6
6	Observabilidad (OTel + Grafana)	#7
7	BigQuery + dbt + gold	#8
8	MCP read tools + IAM estático	#9
9	MCP write tools + audit log	#10
10	Tests unitarios + chaos (85% coverage)	#11
11	Docs + narrativa FDE	#12

Licencia

MIT