模擬的なERPドメイン（製品、顧客、売上）上に構築された**Model Context Protocol (MCP)**サーバーです。言語モデルが外部のツールやデータを、LLMプロバイダーごとの個別統合ではなく標準化された方法で発見し利用できる仕組みを、端から端まで理解するためのものです。
コンテキスト: これは個人的な技術探求プロジェクトであり、本番製品でも、クライアント向けの開発でもありません。ERPドメインは意図的に最小限です（JSONファイルを「データベース」として使用）— 目的はビジネスロジックではなく、プロトコルを理解することです。
（例えばWhatsAppからの）受信メッセージがERPのようなシステムに届く流れをシミュレートします。システムはモデルに関連するコンテキストを組み立て、ツール一式を提供し、モデルは応答するためにどのアクションを取るかを自律的に決定します。実際の効果を伴うアクション（売上の登録）も含まれており、実行前に人間の確認が必要です。
Related MCP server: OdooSurface MCP
MCPは3つのプリミティブを定義しています。このプロジェクトでは、それぞれに明確な設計方針を定めて、その3つすべてを利用しています。
要素 | タイプ | 理由 |
| Resource | 安定したデータ。モデルが要求しなくても、入口のホストが注入することを決定する。 |
| Resource（パラメータ付きURI） | ホストは書き込んだ人のIDをすでに知っている（webhookから取得される）。URIを組み立てて注入する。 |
| Tool | 会話の途中で、モデルがそれを必要とするかどうかを判断する。 |
| 破壊的Tool | 実際の効果を伴うアクション。実行前に人間の確認が必要。 |
| Prompt | 繰り返し発生するタスクのための再利用可能なテンプレート。 |
このプロジェクトで実際に確認できる中心的な違いは次のとおりです。ツールの場合、ホストはそれを呼び出す決定をモデルに委ねます。リソースの場合、ホストはその決定を自分自身に留めます。
┌───────────────────────┐ 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 syncuv run mcp dev server.pyブラウザでMCP Inspectorを開くと、ツールを呼び出したり、リソースを手動で読み取ったりできます。
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_anthropicMCPにおけるツールの発見と呼び出しの実際の仕組み。モデルが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スクリプトだけでなく）に対して移植性を確認すること。
Consulta el stock disponible de un producto específico por su ID.
Usar esta herramienta cuando el cliente pregunte por disponibilidad de un producto puntual.
| Name | Required | Description | Default |
|---|---|---|---|
| producto_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. It implies a safe read operation via 'Consulta', but says nothing about behavior when the product ID is unknown, the stock format, or any limits. Minimal but adequate for a simple read tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, purpose front-loaded ahead of the usage condition, with no wasted wording. Appropriately sized for the tool's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained. For a single-parameter read tool, purpose and when-to-use cover the essentials; only edge-case behavior (unknown ID) is left unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% for the single required parameter. The phrase 'por su ID' clarifies that producto_id is an identifier rather than a name, adding some meaning, but no format or validity details are given.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Consulta) and resource (stock disponible) scoped to a single product by ID, so the agent immediately knows what it does. The purpose is functionally distinct from the sibling registrar_venta, though the description never explicitly contrasts them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The second sentence gives a clear triggering condition: use when the customer asks about the availability of a specific product. It offers no explicit exclusions or named alternatives, which is the only gap.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Registra una venta: descuenta stock y crea el registro de la operación.
ACCIÓN CON EFECTO REAL sobre el estado del sistema. Usar solo cuando
el cliente confirmó explícitamente que quiere comprar.
| Name | Required | Description | Default |
|---|---|---|---|
| cantidad | Yes | ||
| cliente_id | Yes | ||
| producto_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=false and destructiveHint=true, and the description usefully adds what actually changes: stock is decremented and an operation record is created. It does not cover reversibility, permission requirements, or failure modes such as insufficient stock, which is the remaining gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Short and front-loaded: the action and its effects come first, then the usage guardrail. The capitalised warning line is deliberate emphasis rather than filler, though it partially restates the destructive annotation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and the mutation's effect on state is described. However, an irreversible write tool with 0% parameter documentation and no auth, stock-check, or error guidance is only minimally complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds no information about the three required parameters. Their names (cliente_id, producto_id, cantidad) are self-explanatory, but no format, ID source, or unit/limit semantics are given, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (registra) and resource (una venta) plus the two concrete side effects: descuenta stock and crea el registro de la operación. That side-effect profile cleanly separates it from the read-only sibling consultar_stock, though it never names that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit gating condition: use only when the customer has explicitly confirmed they want to buy. That is a clear when-to-use rule, but no alternative tool or when-not-to-use path (e.g. first check stock via consultar_stock) is named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0consultar_stockregistrar_ventaScored across 2 tools
The two tools are unambiguously distinct: consultar_stock is a read-only stock lookup and registrar_venta is a state-changing sale registration. Descriptions explicitly frame the boundary (read vs. real-effect write), so an agent cannot confuse them.
Both names follow the same Spanish verb_noun pattern (consultar_stock, registrar_venta) with consistent snake_case and imperative verbs. There is no mixed convention.
Two tools is far too thin for a server scoped as a 'Mini-ERP' handling inventory and sales; even a minimal ERP needs product listing, restock/adjustment, and sales history. The surface only covers a single narrow checkout flow.
Only a read-stock plus create-sale pair exists, with no product catalog/listing, no inventory update or restock, no sale retrieval or cancellation, and no reporting. Agents will hit dead ends for any operation beyond checking one product and recording one sale.
Odoo ERP for AI agents: hosted OAuth endpoint, gated writes, one endpoint for every instance.
Give AI agents 30,000+ safe, token-optimized actions across Workday, SAP, Oracle + hundreds more.
Connect AI to Odoo ERP 14-20: search, create, update and manage records in natural language.
Malaysian SME accounting, e-Invoice and payroll for your AI. 77 tools; writes are approved drafts.
