Mini-ERP MCP — Lernprojekt

Ein Model Context Protocol (MCP)-Server, aufgebaut auf einer simulierten ERP-Domäne (Produkte, Kunden, Verkäufe), um von Anfang bis Ende zu verstehen, wie ein Sprachmodell externe Tools und Daten auf standardisierte Weise entdecken und nutzen kann, statt über maßgeschneiderte Integrationen für jeden LLM-Anbieter.

Kontext: Dies ist ein persönliches technisches Erkundungsprojekt, kein Produkt in Produktion und keine Entwicklung für einen Kunden. Die ERP-Domäne ist bewusst minimal gehalten (eine JSON-Datei als „Datenbank") — das Ziel ist nicht die Geschäftslogik, sondern das Verständnis des Protokolls.

Was es macht

Es simuliert den Ablauf einer eingehenden Nachricht (z. B. von WhatsApp), die in einem ERP-ähnlichen System eintrifft. Das System erstellt den relevanten Kontext für das Modell, stellt ihm einen Satz von Tools zur Verfügung, und das Modell entscheidet autonom, welche Aktion es zur Antwort ergreift — einschließlich einer Aktion mit realer Wirkung (einen Verkauf erfassen), die vor der Ausführung eine menschliche Bestätigung erfordert.

Related MCP server: OdooSurface MCP

Konzepte, die dieses Projekt umsetzt

MCP definiert drei Primitive, und dieses Projekt nutzt alle drei mit einem expliziten Designkriterium für jedes:

Die zentrale Unterscheidung, die dieses Projekt in der Praxis überprüfen lässt: Bei einem Tool überlässt der Host dem Modell die Entsheidung, es aufzurufen; bei einem Resource behält der Host diese Entsheidung selbst.

Architektur

┌───────────────────────┐   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 übernimmt in diesem Projekt sowohl die Rolle des Hosts als auch des MCP-Clients (in einer echten Integration ist der MCP-CLient in der Regel ein Modul innerhalb des Hosts, kein separates Bauteil).

Stack

• mcp[cli] (FastMCP) — offizielles Python-SDK für MCP-Server.

• Hugging Face Inference Providers — Open-Source-Modelle, über den mit der OpenA-API kompatiblen Router (openai SDK, das auf https://router.huggingface.co/v1 zeigt).

• Anthropic SDK — alternative Unterstützung, paralle gepflegt, um denselben MCP-Server mit zwei verschiedenen Anbietern zu vergleichen.

• MCP Inspector — Entwicklerwerkzeug, um den Server ohne einen echten ClLient zu testen.

So lässt es sich lokal ausführen

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

Den Server isoliert testen (ohne LLM)

Im Browser öffnet man den MCP Inspector, wo sich die Tools aufrufen und die Resources manuell lesen lassen.

uv run mcp dev server.py

Den vollständigen Ablauf ausführen (Host + echtes LLM)

Standarmäßig wird Hugging Face verwendet (procesar_mensaje_huggingface). Der Code für die Verwendung von Anthropic (procesar_mensaje) bleibt in derselben Datei verfügbar, auskommentiert im Block if __name__ == "__main__":.

uv run host_demo.py

Umgebungsvariablen

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

Was ich beim Aufbau gelert habe

• Der eigentliche Mechanismus von Tool-Erkennung und Tool-Aufruf in MCP: Das Modell kommuniziert nie direkt mit dem MCP-Server; der Host vermittelt jeden list_tools() / call_tool() / read_resource()-Aufruf.

• Der Unterschied zwischen dem nativen function calling jedes LLM-Anbieters (unterschiedliche Formate zwischen Anthropic und OpenAI-kompatiblen APIs) und wie MCP die Bereitstellung von Tools standardisiert, ohne von diesen spezifischen Formaten abzuhängen.

• Dass nicht alle Modelle, die von einem Inferenzanbieter bereitgestellt werden, tool-calling zuverlässig unterstützen, und wie man das vor der Integration überprüft.

• Wo die Verantwortung für die menschliche Kontrolle über Aktioenen mit realer Wirkung liegt (das löst das Protokoll nicht automatisch; es ist eine Designentscheidung des Hosts).

• Echte Portabilität: Derselbe server.py funktioniert ohne Änderungen genauso mit zwei verschiedenen LLM-Anbietern.

Projektstatus

Lernprojekt, vollständig und funktionsfähig für den definierten Umfang. Als mögliche zukünftige Erweiterung offen: denselben Server mit Claude Desktop zu verbinden, um die Portabilität gegen einen echten Client zu testen (nicht nur das Skript host_demo.py).