Mini-ERP MCP — учебный проект

Сервер Model Context Protocol (MCP), построенный на симулированном ERP-домене (товары, клиенты, продажи), чтобы от начала до конца понять, как языковая модель может обнаруживать и использовать внешние инструменты и данные стандартизированным образом, вместо индивидуальных интеграций под каждого LLM-провайдера.

Контекст: это личный проект технического исследования, а не production-продукт и не заказная разработка. ERP-домен намеренно минимален (JSON-файл в роли «базы данных») — цель не бизнес-логика, а понимание протокола.

Что делает

Симулирует поток входящего сообщения (например, из WhatsApp), которое приходит в систему типа ERP. Система собирает релевантный контекст для модели, предоставляет ей набор инструментов, и модель автономно решает, какое действие предпринять для ответа — включая действие с реальным эффектом (регистрацию продажи), требующее подтверждения человеком перед выполнением.

Related MCP server: OdooSurface MCP

Концепции, которые реализует этот проект

MCP определяет три примитива, и этот проект использует все три, с явным дизайн-решением для каждого:

Центральное различие, которое этот проект позволяет проверить на практике: в случае tool хост уступает модели решение о вызове; в случае resource хост сохраняет это решение за собой.

Архитектура

┌───────────────────────┐   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 в этом проекте выполняет как роль host, так и роль client MCP (в реальной интеграции клиент MCP обычно является модулем внутри хоста, а не отдельной частью).

Stack

• mcp[cli] (FastMCP) — официальный Python SDK для MCP-серверов.

• Hugging Face Inference Providers — модели open source через роутер, совместимый с OpenAI API (SDK openai, указывающий на https://router.huggingface.co/v1).

• Anthropic SDK — альтернативная поддержка, поддерживаемая параллельно для сравнения одного и того же MCP-сервера, работающего с двумя разными провайдерами.

• MCP Inspector — инструмент разработки для проверки сервера без реального клиента.

Как запустить локально

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

Проверить сервер изолированно (без LLM)

uv run mcp dev server.py

Откройте MCP Inspector в браузере, где можно вызывать tools и читать resources вручную.

Запустить полный поток (host + реальная LLM)

uv run host_demo.py

По умолчанию используется Hugging Face (procesar_mensaje_huggingface). Код для использования Anthropic (procesar_mensaje) остаётся доступным в том же файле, закомментирован в блоке if __name__ == "__main__":.

Переменные окружения

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

Чему я научился, создавая это

• Реальный механизм обнаружения и вызова инструментов в MCP: модель никогда не говорит напрямую с MCP-сервером, именно хост выступает посредником при каждом list_tools() / call_tool() / read_resource().

• Разница между нативным function calling каждого LLM-провайдера (форматы различаются между Anthropic и API, совместимыми с OpenAI) и тем, как MCP стандартизирует предоставление инструментов, не завися от этих частных форматов.

• Не все модели, предоставляемые инференс-провайдером, надёжно поддерживают tool-calling, и как это проверить до интеграции.

• Где находится ответственность за контроль человека над действиями с эффектом (это не то, что протокол решает автоматически, это дизайн-решение хоста).

• Реальная переносимость: один и тот же server.py без изменений одинаково работает с двумя разными LLM-провайдерами.

Статус проекта

Учебный проект, завершённый и функциональный в рамках заданного объёма. В качестве возможного будущего расширения: подключить тот же сервер к Claude Desktop, чтобы проверить переносимость на реальном клиенте (не только в скрипте host_demo.py).