Model Context Protocol (MCP) 서버로, 시뮬레이션된 ERP 도메인(제품, 고객, 판매) 위에 구축되었으며, 언어 모델이 각 LLM 공급업체별 맞춤 통합이 아닌 표준화된 방식으로 외부 도구와 데이터를 발견하고 사용할 수 있는 방법을 처음부터 끝까지 이해하기 위한 프로젝트입니다.
맥락: 이 프로젝트는 개인 기술 탐구용 프로젝트로, 프로덕션 제품도 아니고 고객을 위한 개발도 아닙니다. ERP 도메인은 의도적으로 최소한으로 구성되어 있습니다(JSON 파일 하나를 "데이터베이스"로 사용) — 목표는 비즈니스 로직이 아니라 프로토콜을 이해하는 것입니다.
수신 메시지(예: WhatsApp)가 ERP 유형 시스템에 도착하는 흐름을 시뮬레이션합니다. 시스템은 모델과 관련된 컨텍스트를 구성하고, 모델에게 도구 세트를 제공하며, 모델은 응답하기 위해 어떤 작업을 수행할지 자율적으로 결정합니다 — 여기에는 실행 전에 사람의 확인이 필요한 실제 효과가 있는 작업(판매 등록)도 포함됩니다.
Related MCP server: OdooSurface MCP
MCP는 세 가지 프리미티브를 정의하며, 이 프로젝트는 각각에 명시적인 설계 기준을 적용해 세 가지를 모두 사용합니다:
요소 | 유형 | 이유 |
| Resource | 안정적인 데이터; 모델이 요청하지 않아도 진입 호스트가 주입하기로 결정합니다. |
| Resource (매개변수가 있는 URI) | 호스트가 이미 메시지 작성자의 ID를 알고 있습니다(웹훅에서 오는 값). URI를 구성하여 주입합니다. |
| Tool | 모델이 대화 중간에 필요 여부를 결정합니다. |
| 파괴적 Tool | 실제 효과가 있는 작업; 실행 전에 사람의 확인이 필요합니다. |
| Prompt | 반복 작업을 위한 재사용 가능한 템플릿. |
이 프로젝트를 통해 실제로 확인할 수 있는 핵심 구분: 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는 이 프로젝트에서 호스트 및 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 syncuv run mcp dev server.py브라우저에서 MCP Inspector를 열면 tools를 수동으로 호출하고 resources를 읽을 수 있습니다.
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가 두 개의 서로 다른 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.
