Mini-ERP MCP — 학습 프로젝트

Model Context Protocol (MCP) 서버로, 시뮬레이션된 ERP 도메인(제품, 고객, 판매) 위에 구축되었으며, 언어 모델이 각 LLM 공급업체별 맞춤 통합이 아닌 표준화된 방식으로 외부 도구와 데이터를 발견하고 사용할 수 있는 방법을 처음부터 끝까지 이해하기 위한 프로젝트입니다.

맥락: 이 프로젝트는 개인 기술 탐구용 프로젝트로, 프로덕션 제품도 아니고 고객을 위한 개발도 아닙니다. 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는 이 프로젝트에서 호스트 및 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를 열면 tools를 수동으로 호출하고 resources를 읽을 수 있습니다.

전체 흐름 실행하기(호스트 + 실제 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가 두 개의 서로 다른 LLM 공급업체에서 동일하게 작동합니다.

프로젝트 상태

정의된 범위 내에서 완전하고 기능적인 학습 프로젝트입니다. 향후 확장 가능성으로 보류 중인 항목: 동일한 서버를 Claude Desktop에 연결해 실제 클라이언트(host_demo.py 스크립트뿐만 아니라)에 대한 이식성을 확인하는 것입니다.