Servidor FastMCP de Pedidos

Un servidor del Protocolo de Contexto de Modelos (MCP) construido con FastMCP que expone una herramienta para consultar pedidos de clientes desde una base de datos PostgreSQL.

Estructura del Proyecto

├── mcp_server.py        # FastMCP server — stdio transport (default), HTTP optional
├── mcp_client.py        # Demo client — connects via stdio, calls the tool
├── .env.example         # Template for DB credentials
├── requirements.txt     # Python dependencies
├── schema.sql           # DDL to create customers + orders tables
├── seed.sql             # Sample data for local testing
└── README.md            # This file

Related MCP server: Mock Store MCP Server

Requisitos Previos

• Python ≥ 3.10

• Instancia de PostgreSQL con una base de datos que contenga el esquema descrito a continuación

Esquema de la Base de Datos

El servidor espera dos tablas:

Ejecute los archivos SQL proporcionados para crearlas:

psql -d orders_db -f schema.sql
psql -d orders_db -f seed.sql

Configuración

1. Instalar dependencias

pip install -r requirements.txt

2. Configurar credenciales de la base de datos

Copie la plantilla de entorno y complete sus datos de conexión:

cp .env.example .env
nano .env   # edit values to match your PostgreSQL instance

Ejecutar el Servidor

Transporte Stdio (por defecto)

python mcp_server.py

Este es el modo estándar para servidores MCP locales y funciona con Claude Desktop, el Inspector MCP y cualquier cliente compatible con stdio.

Transporte HTTP (opcional — clientes remotos)

python mcp_server.py --transport http --port 9000

Útil cuando los clientes necesitan un endpoint HTTP remoto en lugar de un proceso local.

Ejecutar el Cliente de Demostración

El cliente incluido se conecta al servidor a través de stdio y ejecuta tres escenarios de prueba:

python mcp_client.py

Salida esperada (con datos de semilla cargados):

[TEST 1] Orders for customer_id=1 with min_amount=100.0
  Order ID   Date          Amount (€)     Status
  --------------------------------------------------------
  5          2025-06-15    180.75 €       completed
  3          2025-03-01    520.00 €       shipped
  1          2025-01-10    250.00 €       completed

  → 3 order(s) found

[TEST 2] Orders for 'carlos@example.com' with min_amount=300.0
  Order ID   Date          Amount (€)     Status
  --------------------------------------------------------
  8          2025-05-10    890.00 €       shipped
  6          2025-02-01    340.00 €       completed

  → 2 order(s) found

[TEST 3] Lookup nonexistent email (expecting error)
  ⚠ Customer not found (nobody@nowhere.com)

Pruebas con el Inspector MCP

El Inspector MCP es una herramienta interactiva para explorar servidores MCP.

npx @modelcontextprotocol/inspector node mcp_server.js

Para servidores Python:

npx @modelcontextprotocol/inspector python mcp_server.py

1. El inspector abre una ventana del navegador en http://localhost:6287.

2. En la interfaz, localice get_customer_orders_above_amount bajo Herramientas.

3. Complete los parámetros (ej., {"customer_id": 1, "min_amount": 100}) y haga clic en Llamar.

4. Inspeccione la respuesta JSON estructurada.

Especificación de la Herramienta

get_customer_orders_above_amount

Recupera los pedidos de un cliente cuyo total supera un importe mínimo en euros.

Debe proporcionarse al menos uno de customer_id o customer_email.

Devuelve: list[dict] — cada diccionario tiene las claves order_id, order_date, total_amount, status. Los resultados se ordenan por order_date descendente.

Las respuestas de error se devuelven como una lista que contiene un único diccionario con una clave "error" (no se filtran trazas de pila sin procesar al cliente).

Notas de Seguridad

• Sin credenciales codificadas — todos los parámetros de la base de datos provienen de variables de entorno cargadas mediante python-dotenv.

• Solo consultas parametrizadas — la inyección SQL se previene utilizando marcadores de posición $1, $2 en todo el código.

• Pool de conexiones — se crea un pool de asyncpg (2–10 conexiones) una vez al iniciar el servidor y se cierra al apagarlo.