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 del proceso.

Contrato HTTP

Método	Ruta	Propósito
GET	`/`	Descubrimiento de servicio (nombre, versión, recuento de herramientas, puntos finales).
GET	`/health`	Sonda de actividad utilizada por Render.
POST	`/tools/list`	Devuelve esquemas para todas las herramientas registradas.
POST	`/tools/call`	Ejecuta una herramienta por nombre con los argumentos proporcionados.

Compatible a nivel de red 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.

Autenticación

Si MCP_API_KEY está configurada en el servidor, cada solicitud POST /tools/* debe enviar el valor coincidente en X-MCP-Api-Key. Si MCP_API_KEY está vacía, la autenticación está deshabilitada (solo para desarrollo local).

Herramientas

Nombre	Descripción
`validate_address`	Valida + normaliza una dirección de envío a través del transportista configurado.
`get_quote_preview`	Vista previa de tarifa no vinculante para un paquete. Las tarifas finales provienen de la API de Java.

Las herramientas delegan en implementaciones conectables de ShippingProvider (mock, ups, fedex, dhl, usps) seleccionadas mediante SHIPPING_PROVIDER. Agregar una herramienta es cuestión de colocar una nueva clase en app/tools/ y registrarla en app/main.py.

Ejecución local

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

Consumidores

ShipSmart-API (Python/FastAPI): apunta SHIPSMART_MCP_URL al servidor desplegado y llama a /tools/list + /tools/call desde sus servicios de orquestación y asesoramiento.
ShipSmart-Orchestrator (Java/Spring Boot): llamará al mismo contrato HTTP desde sus próximos flujos de asistencia por IA. No existe lógica de herramientas en la base de código de Java.

Esto mantiene la capa de herramientas centralizada: agrega una herramienta una vez y todos los servicios la obtienen.