Mini-ERP MCP — 学習プロジェクト

模擬的なERPドメイン（製品、顧客、売上）上に構築された**Model Context Protocol (MCP)**サーバーです。言語モデルが外部のツールやデータを、LLMプロバイダーごとの個別統合ではなく標準化された方法で発見し利用できる仕組みを、端から端まで理解するためのものです。

コンテキスト: これは個人的な技術探求プロジェクトであり、本番製品でも、クライアント向けの開発でもありません。ERPドメインは意図的に最小限です（JSONファイルを「データベース」として使用）— 目的はビジネスロジックではなく、プロトコルを理解することです。

何をするか

（例えばWhatsAppからの）受信メッセージがERPのようなシステムに届く流れをシミュレートします。システムはモデルに関連するコンテキストを組み立て、ツール一式を提供し、モデルは応答するためにどのアクションを取るかを自律的に決定します。実際の効果を伴うアクション（売上の登録）も含まれており、実行前に人間の確認が必要です。

Related MCP server: OdooSurface MCP

このプロジェクトが実践する概念

MCPは3つのプリミティブを定義しています。このプロジェクトでは、それぞれに明確な設計方針を定めて、その3つすべてを利用しています。

このプロジェクトで実際に確認できる中心的な違いは次のとおりです。ツールの場合、ホストはそれを呼び出す決定をモデルに委ねます。リソースの場合、ホストはその決定を自分自身に留めます。

アーキテクチャ

┌───────────────────────┐   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クライアントは通常、ホスト内のモジュールであり、独立した部品ではありません）。

スタック

• mcp[cli]（FastMCP）— MCPサーバー用の公式Python SDK。

• Hugging Face Inference Providers — OpenAI API互換ルーター経由のオープンソースモデル（https://router.huggingface.co/v1 を指す openai SDK）。

• Anthropic SDK — 代替サポートであり、同じMCPサーバーが異なる2つのプロバイダーで動作する様子を比較するため、並行して維持されています。

• 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を開くと、ツールを呼び出したり、リソースを手動で読み取ったりできます。

完全なフローを実行する（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() のすべてをホストが仲介する。

• LLMプロバイダーごとのネイティブなfunction callingの違い（AnthropicとOpenAI互換APIでは形式が異なる）と、MCPがそうした特定の形式に依存せずにツールの公開を標準化する方法。

• 推論プロバイダーが提供するモデルの中には、tool-callingを確実にサポートしていないものもあること、そして統合前にそれを確認する方法。

• 実際の効果を伴うアクションに対する人間の制御の責任がどこにあるか（これはプロトコルが自動的に解決するものではなく、ホストの設計上の判断である）。

• 実際の移植性。同じ server.py が無修正のまま、異なる2つのLLMプロバイダーで同じように動作する。

プロジェクトの現状

学習プロジェクトであり、定義された範囲に対して完全かつ機能的です。将来の拡張候補として保留中：同じサーバーをClaude Desktopに接続し、実際のクライアント（host_demo.pyスクリプトだけでなく）に対して移植性を確認すること。