ShipSmart-MCP

Servidor MCP (Model Context Protocol) independiente que expone las herramientas de envío de ShipSmart (validate_address, get_quote_preview, …) a través de un pequeño contrato HTTP.

Es la única fuente de verdad para el comportamiento de las herramientas en toda la plataforma. Tanto ShipSmart-API (Python / FastAPI — RAG y LLMs) como ShipSmart-Orchestrator (Java / Spring Boot — próximas funciones de IA) llaman a este servidor en lugar de implementar las herramientas dentro de sus propios procesos.

Contrato HTTP

Compatible a nivel de cable con la semántica de MCP tools/list y tools/call: cada llamada devuelve { success, content: [...], error? }, donde content es una lista de bloques {type, text} adecuados para el consumo por parte de LLMs.

/docs y /redoc se montan solo cuando APP_ENV != production.

Autenticación

Si MCP_API_KEY está configurado en el servidor, cada solicitud POST /tools/* debe enviar el valor coincidente en X-MCP-Api-Key. Si MCP_API_KEY está vacío, la autenticación está deshabilitada (solo para desarrollo local). GET / y GET /health siempre están sin autenticar para que las comprobaciones de estado y el descubrimiento de servicios funcionen sin el secreto compartido.

Respuestas de error

Los errores de validación y ejecución devuelven deliberadamente HTTP 200 con success=false para que los consumidores puedan distinguir los fallos a nivel de protocolo (4xx) de los fallos a nivel de herramienta (200 + success=false).

Related MCP server: DB2ST MCP

Herramientas

Las herramientas delegan en implementaciones de ShippingProvider conectables seleccionadas por SHIPPING_PROVIDER.

Añadir una herramienta consiste en colocar una nueva clase en app/tools/ y registrarla en app/main.py.

Comportamiento de inicio del proveedor

• SHIPPING_PROVIDER=mock (predeterminado) emite una WARNING sonora al inicio para que los operadores no se sorprendan con datos falsos.

• Seleccionar un transportista real (ups/fedex/dhl/usps) sin todas las credenciales requeridas genera un ValueError al inicio. No hay una alternativa silenciosa a mock: la configuración incorrecta falla de forma rápida y visible.

Configuración

Todos los ajustes se cargan desde variables de entorno (o .env para desarrollo local). Consulte .env.example para obtener la lista completa y los valores predeterminados.

Ejecución local

Requisitos previos: Python 3.13+ y uv.

cp .env.example .env
# fill in credentials if you want real carrier integration; default is SHIPPING_PROVIDER=mock
uv sync
uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8001

Prueba de humo:

curl -s http://localhost:8001/health
curl -s -X POST http://localhost:8001/tools/list
curl -s -X POST http://localhost:8001/tools/call \
  -H 'Content-Type: application/json' \
  -d '{
        "name": "validate_address",
        "arguments": {
          "street": "123 Main St",
          "city":   "San Francisco",
          "state":  "CA",
          "zip_code": "94105"
        }
      }'

Pruebas

uv run pytest

Observabilidad

RequestLoggingMiddleware (app/core/middleware.py) maneja los IDs de correlación para cada solicitud:

• Lee X-Request-Id de la solicitud entrante, o crea un UUID hexadecimal si está ausente.

• Lee traceparent de W3C, o crea uno nuevo si está ausente o mal formado.

• Hace eco de ambos encabezados en la respuesta para que los llamadores puedan hacer grep por ID a través de los servicios.

• Emite una línea de registro por solicitud en el registrador shipsmart_mcp.requests:

GET /health → 200 (1.4ms) [a1b2c3...]

Pase X-Request-Id desde los servicios ascendentes para unir una sola solicitud a través de ShipSmart-API → MCP → APIs de transportistas.

Despliegue (Render)

render.yaml es un plano de Render que define el servicio desplegado:

• Servicio web de Python, compilado mediante pip install uv && uv sync, iniciado mediante uvicorn app.main:app --host 0.0.0.0 --port $PORT.

• Comprobación de estado en /health.

• MCP_API_KEY es sync: false: configúrelo una vez en el panel de Render y use el mismo valor para el SHIPSMART_MCP_API_KEY de cada consumidor.

• SHIPPING_PROVIDER=fedex predeterminado apuntando a https://apis-sandbox.fedex.com (FedEx sandbox, no producción). Sobrescriba la URL base al promocionar al tráfico de transportista real.

• Los orígenes CORS están fijados en el plano a las URLs de los consumidores desplegados.

Realice el aprovisionamiento apuntando Render a este repositorio; todas las variables de entorno sync: false deben completarse antes de que el primer despliegue tenga éxito.

Consumidores

• ShipSmart-API (Python / FastAPI; desplegado como shipsmart-api-python en Render): apunta SHIPSMART_MCP_URL a este servidor y llama a /tools/list + /tools/call desde sus servicios de orquestación y asesoramiento.

• ShipSmart-Orchestrator (Java / Spring Boot; desplegado como shipsmart-api-java en Render): llamará al mismo contrato HTTP desde sus próximos flujos de asistencia por IA. No hay lógica de herramientas en la base de código de Java.

Esto mantiene la capa de herramientas centralizada: añada una herramienta una vez y todos los servicios la obtendrán.