mcp-shop-server

AI 에이전트에게 온라인 쇼핑몰 SQLite 데이터베이스(customers, products, orders, order_items)에 대한 읽기 전용 액세스를 제공하는 MCP 서버입니다. 에이전트는 이를 통해 데이터에 대한 분석 질문(데이터베이스 구조, 고객, 상품, 카테고리, 매출별 집계)에 답변합니다. 전송 방식은 stdio입니다.

데이터베이스 쓰기는 설계상 불가능합니다. 독립적인 3중 보호 계층이 있습니다: mode=ro 연결, 실행 전 쿼리 검증(SELECT / WITH ... SELECT만 허용), sqlite3-authorizer.

측정값, 증거, 명세서와의 차이점은 REPORT.md에 있습니다.

사용 방법

1. 클론

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

리포지토리에는 이미 shop.db가 포함되어 있습니다(고객 150명, 상품 50개, 주문 750건, 주문 항목 1900개).

2. 의존성 설치

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

uv 없이도 표준 도구로 동일하게 수행할 수 있습니다:

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

Python 3.11+가 필요합니다. 의존성: mcp(공식 MCP SDK) 및 테스트용 pytest; 데이터베이스 작업은 표준 라이브러리의 sqlite3을 사용합니다.

3. 에이전트 구성에 등록

최소 구성 형식:

{
  "command": "python",
  "args": ["/absolute/path/to/mcp-shop-server/server.py"]
}

mcpServers 블록이 있는 클라이언트(Claude Desktop, Cursor 및 호환 클라이언트)용 실제 예시:

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/mcp-shop-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-shop-server/server.py"],
      "env": {
        "MCP_SHOP_DB": "/absolute/path/to/mcp-shop-server/shop.db"
      }
    }
  }
}

Claude Code의 경우 단일 명령으로 충분합니다:

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DB는 선택 사항입니다. 변수가 설정되지 않으면 서버는 server.py 옆에 있는 shop.db를 사용합니다. 데이터베이스가 다른 위치에 있으면 이 변수를 지정하세요. 인터프리터는 .venv에서 지정하는 것이 좋습니다. 그렇지 않으면 시스템 python이 mcp 패키지를 찾지 못할 수 있습니다.

4. 실행

서버는 에이전트가 시작하며, 수동으로 실행할 일은 거의 없습니다:

.venv/bin/python server.py

프로세스는 stdin에서 JSON-RPC를 조용히 기다립니다. 진단은 stderr로 출력되고, stdout은 MCP 프로토콜이 사용합니다.

5. 확인 및 에이전트 질문

.venv/bin/python -m pytest -q

연결 후 에이전트는 세 가지 도구를 볼 수 있습니다. 질문은 일반 언어로 합니다.

과제 텍스트의 8가지 작업 — 확인을 위해 이 작업들을 실행하는 것이 좋습니다:

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ 제공된 데이터베이스에는 작업 2, 3, 7에 대한 해결책이 없으며, 이는 예상된 결과입니다. customers에는 국가 열이 없습니다. 모든 150명의 고객은 러시아 전화번호를 가지고 있습니다. 모든 750건의 주문은 2026년 날짜이며, 2025년 데이터는 없습니다.

이 경우 서버는 데이터를 지어내지 않습니다: 해당 필드가 스키마에 없다고 알리고 기존 열을 나열합니다. 코드에 하드코딩된 것은 없습니다. 스키마는 데이터베이스에서 읽히므로 country가 있는 다른 데이터베이스에서는 동일한 질문이 정상적으로 작동합니다.

추가로 데이터베이스가 완전히 커버하는 질문도 확인합니다: 주문 금액 기준 상위 5명의 고객, 카테고리별 매출, 주문 상태별 분포, 평균 주문 금액, 상품 재고.

쓰기 방지 확인. "Delete all cancelled orders"에 대해 에이전트는 오류가 아닌 명확한 거부를 받습니다: 서버는 읽기 전용으로만 작동하며, 102건의 취소된 주문은 그대로 유지됩니다.

도구

출력은 제한됩니다: 기본 100행, 최대 1000행. 잘릴 때 응답은 반환된 행 수, 전체 발견된 행 수, 다음에 읽을 offset을 알려줍니다.

요청한 필드가 데이터베이스에 없으면(예: 고객 국가) 서버는 정직하게 이를 알리고 기존 열을 나열합니다. 존재하지 않는 필드는 추측하지 않습니다.

Related MCP server: Shop Analytics MCP Server

구현 방법

프로젝트는 단일 프롬프트로 생성되었습니다. SPEC-mcp-shop.md 파일이 에이전트에 전체적으로 전송되었으며, 이후 수정은 없었습니다.

내부적으로 에이전트는 repo-task-proof-loop (Denis Shiryaev, Apache-2.0) 스킬의 루프로 작업했습니다: 스펙 동결 → 빌드 → 증거 패키징 → 새 세션으로 검증 → 최소 수정 → 재검증, PASS 판정까지.

실행 증거는 리포지토리의 .agent/tasks/mcp-shop-server/에 있습니다:

• spec.md — AC1…AC17 수용 기준이 포함된 동결된 스펙;

• evidence.md / evidence.json — 각 기준에 대한 판정 및 구체적 증거;

• verdict.json — 새 세션의 독립 검증 결과;

• problems.md — 검증자가 발견한 차이점;

• raw/ — 실행의 원시 로그: 테스트, 실제 MCP 세션, stdout 청결 검사.

소스 코드가 아니라 실제 에이전트와 함께하는 서버 동작이 검증됩니다. harness raw/mcp_session_check.py는 실제 MCP 클라이언트로 stdio를 통해 server.py를 시작하고, 모든 도구를 호출하고, 8가지 분석 작업을 실행하고, 삭제 요청에 대한 거부를 받고, stdout에 JSON-RPC 프레임만 포함되어 있는지 확인합니다.

개발 스킬 자체는 로컬의 .claude/skills/에 있으며 리포지토리에는 커밋되지 않습니다. 이것은 타인의 코드입니다.

명세서 모호성에 대한 결정 사항