Mini-ERP MCP —— 学习项目

基于模拟的 ERP 领域（产品、客户、销售）构建的 Model Context Protocol (MCP) 服务器，用于端到端地理解语言模型如何以标准化方式发现和使用外部工具与数据，而不是通过为每个 LLM 提供商定制集成。

背景： 这是一个个人技术探索项目，不是生产产品，也不是客户开发项目。ERP 领域刻意保持最小（一个 JSON 文件作为“数据库”）——目标不是业务逻辑，而是理解协议。

功能

模拟一条传入消息（例如 WhatsApp）到达类 ERP 系统的流程。系统为模型构建相关上下文，向其提供一组工具，模型自主决定采取什么行动来响应——包括一个具有实际效果的行动（登记一笔销售），该行动在执行前需要人工确认。

Related MCP server: OdooSurface MCP

本项目实践的概念

MCP 定义了三种原语，本项目全部使用了这三种，并且针对每一种都有明确的设计标准：

本项目可以在实践中验证的核心区别：使用工具时，宿主将调用它的决定权交给模型；使用资源时，宿主将该决定权留给自己。

架构

┌───────────────────────┐   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 同时扮演 宿主 和 MCP 客户端 的角色（在真实集成中，MCP 客户端通常是宿主内部的一个模块，而不是独立组件）。

技术栈

• mcp[cli]（FastMCP）——用于 MCP 服务器的官方 Python SDK。

• Hugging Face Inference Providers ——开源模型，通过兼容 OpenAI API 的路由器（openai SDK 指向 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，即可手动调用工具并读取资源。

运行完整流程（宿主 + 真实 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()。

• 不同 LLM 提供商的原生 function calling 之间的差异（Anthropic 与兼容 OpenAI 的 API 之间格式不同），以及 MCP 如何在不依赖这些特定格式的情况下标准化工具的对外暴露。

• 并非所有推理提供商提供的模型都能可靠地支持工具调用，以及如何在集成之前进行验证。

• 对具有实际效果的操作进行人工控制的责任所在（这不是协议自动解决的问题，而是宿主的设计决定）。

• 真正的可移植性：同一个 server.py 无需修改，即可在两个不同的 LLM 提供商下同样运行。

项目状态

学习项目，在既定范围内完整且可用。作为可能的未来扩展，仍待完成：将同一个服务器连接到 Claude Desktop，以验证针对真实客户端的可移植性（而不仅仅是 host_demo.py 脚本）。