inventory-mcp

Servidor MCP de demostración para consultas de inventario, desarrollado en Python con FastMCP. El proyecto apoya el estudio de los principales conceptos del Model Context Protocol (MCP), con separación entre transporte, interfaz MCP, reglas de negocio, validación y datos.

El alcance actual es intencionalmente de solo lectura: el servidor permite consultar productos y cantidades en stock, sin operaciones de registro, modificación o eliminación.

Tecnologías

• Python 3.11+

• FastMCP

• Pydantic

• pytest

• Ruff

Related MCP server: vanam-erp-mcp

Arquitectura

• app/server.py: crea el servidor FastMCP, registra las herramientas e inicia el transporte stdio o SSE.

• app/client.py: cliente demostrativo que lista y llama a las herramientas por stdio o SSE.

• app/tools/: interfaz MCP; valida entradas, delega en el servicio y transforma errores esperados en respuestas estables.

• app/services/: reglas de consulta y carga del inventario.

• app/schemas/: modelos Pydantic que definen y validan los contratos de producto y existencias.

• app/data/: fuente local de datos, actualmente el archivo inventory.json.

• tests/: pruebas automatizadas del servicio, de las herramientas y de la configuración del servidor.

Client → MCP Server → Tool → InventoryService → inventory.json

Las herramientas no acceden al archivo directamente. Delegan las reglas de negocio en el InventoryService.

Herramientas MCP

get_product

• Propósito: consultar los datos completos de un producto por nombre.

• Entrada: name (string no vacía).

• Salida en caso de éxito: objeto con name, quantity y price.

• Salida para producto inexistente: objeto con error: "product_not_found" y un message descriptivo.

• Descripción MCP: Use this tool to retrieve the complete data of a product by name, including its price and stock quantity.

• Clasificación: solo lectura.

{
  "name": "Mouse",
  "quantity": 25,
  "price": 89.9
}

get_stock

• Propósito: consultar solo la cantidad actual de un producto por nombre.

• Entrada: name (string no vacía).

• Salida en caso de éxito: objeto con quantity.

• Salida para producto inexistente: objeto con error: "product_not_found" y un message descriptivo.

• Descripción MCP: Use this tool to retrieve only the current stock quantity of a product by name.

• Clasificación: solo lectura.

{
  "quantity": 25
}

Validación de entrada

Las herramientas exigen que name sea una string con contenido. Los nombres vacíos o formados solo por espacios se rechazan antes de la consulta. El servicio aplica strip() para eliminar espacios en los extremos y casefold() para comparar nombres sin diferenciación entre mayúsculas y minúsculas.

Pydantic valida los registros cargados del JSON y los modelos de salida. Un producto debe tener nombre no vacío, cantidad entera no negativa y precio numérico no negativo. El rechazo de nombres de consulta vacíos se realiza mediante _validate_product_name(). Los registros inválidos interrumpen la carga con un error explícito.

Tratamiento de errores

El InventoryService lanza ProductNotFoundError cuando no encuentra el producto solicitado. Las herramientas capturan ese error esperado y devuelven un payload predecible:

{
  "error": "product_not_found",
  "message": "Product not found: Monitor"
}

Los errores de entrada, como nombre vacío o valor que no sea string, no se ocultan: se reportan como errores de la llamada a la herramienta.

Transportes MCP

• stdio: se comunica mediante la entrada y salida estándar. En este proyecto, el cliente inicia el servidor FastMCP como subproceso, realiza las llamadas y cierra el proceso al finalizar.

• SSE: se comunica mediante un endpoint HTTP con Server-Sent Events. El servidor y el cliente se ejecutan en procesos separados; por defecto, el servidor atiende en http://127.0.0.1:8000/sse.

Cómo ejecutar

Los comandos siguientes usan PowerShell y deben ejecutarse en la raíz del proyecto.

Crear y activar el entorno virtual

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Instalar las dependencias

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Ejecutar mediante stdio

El cliente usa stdio por defecto e inicia el servidor como subproceso:

.\.venv\Scripts\python.exe -m app.client

Para iniciar solo el servidor directamente:

.\.venv\Scripts\python.exe -m app.server --transport stdio

Ejecutar mediante SSE

Inicie el servidor en una terminal (sse es el transporte por defecto del servidor):

.\.venv\Scripts\python.exe -m app.server

El comando explícito equivalente es python -m app.server --transport sse. En otra terminal, conecte el cliente:

.\.venv\Scripts\python.exe -m app.client --transport sse

El cliente acepta otro endpoint mediante --url.

Ejecutar las pruebas

.\.venv\Scripts\pytest.exe

Ejecutar Ruff

.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\ruff.exe format --check .

Evaluación de riesgo de las herramientas

Las herramientas actuales son de solo lectura y no pueden crear, modificar ni eliminar datos. Esta decisión reduce la superficie de riesgo, pero no elimina posibles impactos sobre la confidencialidad y la disponibilidad.

Las llamadas en gran volumen aún pueden consumir recursos del servidor. Los cambios futuros en las herramientas o en los datos devueltos deben ir acompañados de una nueva evaluación de riesgo.

Límite de confianza

Los argumentos recibidos de un cliente MCP se tratan como entrada no confiable.

MCP Client
    ↓
MCP Server
    ↓
Tool
    ↓
InventoryService
    ↓
inventory.json

La validación ocurre antes de que los argumentos sean utilizados por la capa de servicio. El servidor no asume que los datos enviados por el cliente son válidos solo porque llegaron mediante el protocolo MCP. Los registros de inventory.json también se tratan como entrada externa y se validan con Pydantic durante la carga.

Anotaciones de herramientas MCP

Las herramientas se clasifican semánticamente según su comportamiento. Las dos operaciones actuales declaran:

readOnlyHint=true
openWorldHint=false

readOnlyHint=true informa al cliente MCP que la operación no pretende modificar el estado.

openWorldHint=false indica que la herramienta trabaja sobre un dominio cerrado y conocido — en este caso, el inventario local — en lugar de consultar sistemas externos o fuentes abiertas.

Estas anotaciones funcionan como metadatos e indicaciones para clientes MCP, no como mecanismos de seguridad. Un cliente no debe confiar en ellas como sustituto de validación, autorización u otros controles reales.

Riesgo de herramientas de escritura

Una futura operación como:

update_stock(name, quantity)

tendría un riesgo significativamente mayor porque modificaría el estado persistente del sistema.

Una llamada incorrecta o maliciosa podría alterar el producto equivocado, registrar valores inválidos o permitir cambios no autorizados. Una futura herramienta como update_stock exigiría validación rigurosa, autenticación, autorización, auditoría y tracing. Las operaciones destructivas también exigirían confirmación o aprobación cuando corresponda.

Riesgo por transporte

En stdio, el servidor se inicia localmente como subproceso del cliente, reduciendo la exposición de red. En SSE, el servidor y el cliente son procesos separados y la comunicación usa un endpoint HTTP. Una eventual publicación de este endpoint fuera del host local exigiría controles adicionales de acceso y disponibilidad.

Pruebas

La suite actual valida:

• carga, búsqueda, normalización y errores del InventoryService;

• retornos de las herramientas y conversión de producto inexistente en error previsible;

• rechazo de nombres vacíos y valores que no sean strings;

• rechazo de registros de inventario inválidos por Pydantic;

• registro de las herramientas en el servidor;

• selección y configuración de los transportes SSE y stdio;

• integración real mediante stdio, incluyendo list_tools(), llamada a get_stock y lectura de las anotaciones MCP.

Los escenarios incluyen productos existentes e inexistentes, espacios en los extremos, diferencias entre mayúsculas y minúsculas y entradas inválidas. En la prueba de extremo a extremo, un cliente FastMCP real inicia el servidor como subproceso, valida readOnlyHint y openWorldHint, consulta el stock cargado del JSON local y cierra la conexión mediante el administrador de contexto.

Calidad del código

El proyecto utiliza type hints, separa responsabilidades entre MCP, servicios, schemas y datos, y mantiene dependencias mínimas. pytest cubre los comportamientos implementados, mientras que Ruff verifica lint, imports, compatibilidad con Python 3.11 y formato.

Limitaciones actuales

• Los datos se cargan de un archivo JSON local.

• No existe base de datos.

• No existe integración con IA o LLM.

• No existen herramientas de escritura.

• No hay autenticación ni autorización.

Posibles evoluciones

• tracing y logging estructurado, mantenidos fuera del alcance actual para preservar el enfoque didáctico del proyecto;

• soporte para Streamable HTTP;

• persistencia en base de datos;

• autenticación y autorización;

• herramientas de escritura con salvaguardas;

• integración futura con LLM.