Mini-ERP MCP — proyecto de aprendizaje

Servidor de Model Context Protocol (MCP) construido sobre un dominio de ERP simulado (productos, clientes, ventas), para entender de punta a punta cómo un modelo de lenguaje puede descubrir y usar herramientas y datos externos de forma estandarizada, en vez de mediante integraciones a medida por cada proveedor de LLM.

Contexto: este es un proyecto personal de exploración técnica, no un producto en producción ni un desarrollo para cliente. El dominio de ERP es deliberadamente mínimo (un archivo JSON como "base de datos") — el objetivo no es la lógica de negocio, sino comprender el protocolo.

Qué hace

Simula el flujo de un mensaje entrante (por ejemplo, de WhatsApp) que llega a un sistema tipo ERP. El sistema arma el contexto relevante para el modelo, le ofrece un conjunto de herramientas, y el modelo decide de forma autónoma qué acción tomar para responder — incluyendo una acción con efecto real (registrar una venta), que requiere confirmación humana antes de ejecutarse.

Related MCP server: OdooSurface MCP

Conceptos que este proyecto pone en práctica

MCP define tres primitivas, y este proyecto usa las tres con un criterio de diseño explícito para cada una:

La distinción central que este proyecto permite comprobar en la práctica: con una tool, el host le cede al modelo la decisión de invocarla; con un resource, el host retiene esa decisión para sí.

Arquitectura

┌───────────────────────┐   stdio   ┌───────────────────────┐
│  Host (host_demo.py)    │◄────────►│  Servidor MCP           │
│  - Arma el contexto       │          │  (server.py, FastMCP)    │
│  - Ofrece tools al LLM     │          │  - Resources             │
│  - Ejecuta el loop de      │          │  - Tools                 │──► data/erp.json
│    tool-calling             │          │  - Prompts               │
│  - Pide confirmación         │          └───────────────────────┘
│    humana en acciones          │
│    destructivas                  │
└──────────┬────────────────┘
           │ API compatible OpenAI (router de HF) o API de Anthropic
           ▼
    ┌─────────────┐
    │     LLM       │
    └─────────────┘

host_demo.py cumple, en este proyecto, tanto el rol de host como de client MCP (en una integración real, el cliente MCP suele ser un módulo dentro del host, no una pieza aparte).

Stack

• mcp[cli] (FastMCP) — SDK oficial de Python para servidores MCP.

• Hugging Face Inference Providers — modelos open source, vía el router compatible con la API de OpenAI (openai SDK apuntando a https://router.huggingface.co/v1).

• Anthropic SDK — soporte alternativo, mantenido en paralelo para comparar el mismo servidor MCP funcionando con dos proveedores distintos.

• MCP Inspector — herramienta de desarrollo para probar el servidor sin necesidad de un cliente real.

Cómo correrlo en local

cp .env.example .env   # completar HF_TOKEN (y opcionalmente ANTHROPIC_API_KEY)
uv sync

Probar el servidor de forma aislada (sin LLM)

uv run mcp dev server.py

Abre el MCP Inspector en el navegador, donde se pueden invocar las tools y leer los resources manualmente.

Correr el flujo completo (host + LLM real)

uv run host_demo.py

Por defecto usa Hugging Face (procesar_mensaje_huggingface). El código para usar Anthropic (procesar_mensaje) queda disponible en el mismo archivo, comentado en el bloque if __name__ == "__main__":.

Variables de entorno

HF_TOKEN=tu_token_de_huggingface
HF_MODEL=openai/gpt-oss-120b

# Opcional, si se quiere probar con Anthropic en vez de Hugging Face
ANTHROPIC_API_KEY=tu_api_key_de_anthropic

Qué aprendí construyendo esto

• El mecanismo real de descubrimiento e invocación de herramientas en MCP: el modelo nunca habla directo con el servidor MCP, es el host quien media cada list_tools() / call_tool() / read_resource().

• La diferencia entre function calling nativo de cada proveedor de LLM (formatos distintos entre Anthropic y APIs compatibles con OpenAI) y cómo MCP estandariza la exposición de herramientas sin depender de esos formatos particulares.

• Que no todos los modelos servidos por un proveedor de inferencia soportan tool-calling de forma confiable, y cómo verificarlo antes de integrar.

• Dónde vive la responsabilidad del control humano sobre acciones con efecto (no es algo que el protocolo resuelva automáticamente, es una decisión de diseño del host).

• Portabilidad real: el mismo server.py, sin modificaciones, funciona igual con dos proveedores de LLM distintos.

Estado del proyecto

Proyecto de aprendizaje, completo y funcional para el alcance definido. Pendiente como posible extensión futura: conectar el mismo servidor a Claude Desktop para comprobar la portabilidad contra un cliente real (no solo el script host_demo.py).