inventory-mcp

FastMCP로 Python에서 개발된 재고 조회용 데모 MCP 서버입니다. 이 프로젝트는 전송, MCP 인터페이스, 비즈니스 규칙, 검증, 데이터를 분리하여 Model Context Protocol(MCP)의 핵심 개념을 학습하는 데 도움을 줍니다.

현재 범위는 의도적으로 읽기 전용입니다. 서버는 제품과 재고 수량을 조회할 수 있으며 등록, 변경, 삭제 작업은 없습니다.

기술 스택

• Python 3.11+

• FastMCP

• Pydantic

• pytest

• Ruff

Related MCP server: vanam-erp-mcp

아키텍처

• app/server.py: FastMCP 서버를 생성하고 도구를 등록하며 stdio 또는 SSE 전송을 시작합니다.

• app/client.py: stdio 또는 SSE로 도구를 나열하고 호출하는 데모 클라이언트입니다.

• app/tools/: MCP 인터페이스. 입력을 검증하고 서비스에 위임하며 예상 가능한 오류를 안정적인 응답으로 변환합니다.

• app/services/: 재고 조회 및 로딩 규칙.

• app/schemas/: 제품 및 재고 계약을 정의하고 검증하는 Pydantic 모델.

• app/data/: 로컬 데이터 소스, 현재는 inventory.json.

• tests/: 서비스, 도구, 서버 설정에 대한 자동화된 테스트.

Client → MCP Server → Tool → InventoryService → inventory.json

도구는 파일에 직접 접근하지 않습니다. 비즈니스 규칙을 InventoryService에 위임합니다.

MCP 도구

get_product

• 목적: 이름으로 제품의 전체 데이터를 조회합니다.

• 입력: name (비어 있지 않은 string).

• 성공 시 출력: name, quantity, price가 있는 객체.

• 존재하지 않는 제품 출력: error: "product_not_found"와 설명적인 message가 있는 객체.

• MCP 설명: Use this tool to retrieve the complete data of a product by name, including its price and stock quantity.

• 분류: 읽기 전용.

{
  "name": "Mouse",
  "quantity": 25,
  "price": 89.9
}

get_stock

• 목적: 이름으로 제품의 현재 수량만 조회합니다.

• 입력: name (비어 있지 않은 string).

• 성공 시 출력: quantity가 있는 객체.

• 존재하지 않는 제품 출력: error: "product_not_found"와 설명적인 message가 있는 객체.

• MCP 설명: Use this tool to retrieve only the current stock quantity of a product by name.

• 분류: 읽기 전용.

{
  "quantity": 25
}

입력 검증

도구는 name이 내용이 있는 문자열이어야 합니다. 비어 있거나 공백만 있는 이름은 조회 전에 거부됩니다. 서비스는 strip()을 적용하여 양쪽 끝의 공백을 제거하고 casefold()를 사용하여 대소문자 구분 없이 이름을 비교합니다.

Pydantic은 JSON에서 로드된 레코드와 출력 모델을 검증합니다. 제품은 비어 있지 않은 이름, 음수가 아닌 정수 수량, 음수가 아닌 숫자 가격을 가져야 합니다. 빈 조회 이름의 거부는 _validate_product_name()에서 수행됩니다. 잘못된 레코드는 명시적 오류와 함께 로딩을 중단합니다.

오류 처리

InventoryService는 요청한 제품을 찾지 못하면 ProductNotFoundError를 발생시킵니다. 도구는 이 예상된 오류를 캡처하여 예측 가능한 페이로드를 반환합니다:

{
  "error": "product_not_found",
  "message": "Product not found: Monitor"
}

빈 이름이나 문자열이 아닌 값과 같은 입력 오류는 숨겨지지 않습니다. 도구 호출 오류로 보고됩니다.

MCP 전송

• stdio: 표준 입력과 출력으로 통신합니다. 이 프로젝트에서 클라이언트는 FastMCP 서버를 하위 프로세스로 시작하고 호출을 수행한 뒤 종료 시 프로세스를 종료합니다.

• SSE: Server-Sent Events를 사용하는 HTTP 엔드포인트로 통신합니다. 서버와 클라이언트는 별도 프로세스에서 실행되며, 기본적으로 서버는 http://127.0.0.1:8000/sse에서 수신합니다.

실행 방법

아래 명령은 PowerShell을 사용하며 프로젝트 루트에서 실행해야 합니다.

가상 환경 생성 및 활성화

python -m venv .venv
.\.venv\Scripts\Activate.ps1

종속성 설치

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

stdio로 실행

클라이언트는 기본적으로 stdio를 사용하며 서버를 하위 프로세스로 시작합니다:

.\.venv\Scripts\python.exe -m app.client

서버만 직접 시작하려면:

.\.venv\Scripts\python.exe -m app.server --transport stdio

SSE로 실행

한 터미널에서 서버를 시작합니다(sse는 서버의 기본 전송입니다):

.\.venv\Scripts\python.exe -m app.server

동등한 명시적 명령은 python -m app.server --transport sse입니다. 다른 터미널에서 클라이언트를 연결합니다:

.\.venv\Scripts\python.exe -m app.client --transport sse

클라이언트는 --url을 통해 다른 엔드포인트를 허용합니다.

테스트 실행

.\.venv\Scripts\pytest.exe

Ruff 실행

.\.venv\Scripts\ruff.exe check .
.\.venv\Scripts\ruff.exe format --check .

도구 위험 평가

현재 도구는 읽기 전용이며 데이터를 생성, 변경, 삭제할 수 없습니다. 이 결정은 위험 범위를 줄이지만 기밀성과 가용성에 대한 잠재적 영향을 제거하지는 않습니다.

대량 호출은 여전히 서버 리소스를 소비할 수 있습니다. 도구 또는 반환되는 데이터의 향후 변경에는 새로운 위험 평가가 수반되어야 합니다.

신뢰 경계

MCP 클라이언트로부터 받은 인수는 신뢰할 수 없는 입력으로 처리됩니다.

MCP Client
    ↓
MCP Server
    ↓
Tool
    ↓
InventoryService
    ↓
inventory.json

검증은 인수가 서비스 계층에서 사용되기 전에 이루어집니다. 서버는 클라이언트가 보낸 데이터가 MCP 프로토콜을 통해 도착했다는 이유만으로 유효하다고 가정하지 않습니다. inventory.json의 레코드도 외부 입력으로 처리되며 로딩 중에 Pydantic으로 검증됩니다.

MCP 도구 어노테이션

도구는 동작에 따라 의미적으로 분류됩니다. 현재 두 작업은 다음을 선언합니다:

readOnlyHint=true
openWorldHint=false

readOnlyHint=true는 작업이 상태를 수정하지 않음을 MCP 클라이언트에 알립니다.

openWorldHint=false는 도구가 외부 시스템이나 공개 소스를 조회하는 대신 폐쇄된 알려진 도메인(이 경우 로컬 재고)에서 작동함을 나타냅니다.

이러한 어노테이션은 MCP 클라이언트를 위한 메타데이터 및 힌트로 작동하며 보안 메커니즘이 아닙니다. 클라이언트는 이를 검증, 권한 부여 또는 기타 실제 통제를 대체하는 수단으로 신뢰해서는 안 됩니다.

쓰기 도구의 위험

다음과 같은 미래의 작업은:

update_stock(name, quantity)

시스템의 영구 상태를 수정하기 때문에 위험이 훨씬 더 큽니다.

잘못되거나 악의적인 호출은 잘못된 제품을 변경하거나, 잘못된 값을 기록하거나, 권한 없는 변경을 허용할 수 있습니다. update_stock과 같은 미래 도구는 엄격한 검증, 인증, 권한 부여, 감사 및 추적이 필요합니다. 파괴적인 작업은 해당되는 경우 확인 또는 승인도 필요합니다.

전송별 위험

stdio에서 서버는 클라이언트의 하위 프로세스로 로컬에서 시작되어 네트워크 노출을 줄입니다. SSE에서는 서버와 클라이언트가 별도 프로세스이며 통신은 HTTP 엔드포인트를 사용합니다. 이 엔드포인트를 로컬 호스트 밖으로 게시하게 되면 추가 액세스 및 가용성 통제가 필요합니다.

테스트

현재 테스트 스위트는 다음을 검증합니다:

• InventoryService의 로딩, 검색, 정규화 및 오류;

• 도구 반환 및 존재하지 않는 제품의 예측 가능한 오류 변환;

• 빈 이름 및 문자열이 아닌 값의 거부;

• Pydantic에 의한 잘못된 재고 레코드 거부;

• 서버에서 도구 등록;

• SSE 및 stdio 전송 선택 및 구성;

• list_tools(), get_stock 호출 및 MCP 어노테이션 읽기를 포함한 stdio를 통한 실제 통합.

시나리오에는 존재하는 제품과 존재하지 않는 제품, 양쪽 끝의 공백, 대소문자 차이, 잘못된 입력이 포함됩니다. 엔드 투 엔드 테스트에서는 실제 FastMCP 클라이언트가 서버를 하위 프로세스로 시작하고 readOnlyHint와 openWorldHint를 검증하며 로컬 JSON에서 로드된 재고를 조회하고 컨텍스트 관리자로 연결을 종료합니다.

코드 품질

프로젝트는 타입 힌트를 사용하고 MCP, 서비스, 스키마, 데이터 간의 책임을 분리하며 최소한의 의존성을 유지합니다. pytest는 구현된 동작을 다루고 Ruff는 린트, imports, Python 3.11 호환성 및 포맷팅을 확인합니다.

현재 제한 사항

• 데이터는 로컬 JSON 파일에서 로드됩니다.

• 데이터베이스가 없습니다.

• AI 또는 LLM 통합이 없습니다.

• 쓰기 도구가 없습니다.

• 인증 또는 권한 부여가 없습니다.

향후 발전 가능성

• 프로젝트의 교육적 초점을 유지하기 위해 현재 범위에서 제외된 추적 및 구조화된 로깅;

• Streamable HTTP 지원;

• 데이터베이스 영속성;

• 인증 및 권한 부여;

• 안전장치가 있는 쓰기 도구;

• 향후 LLM 통합.