MCP 서버 shop-db

읽기 전용 MCP-서버(stdio 전송)로서 AI 에이전트에게 인터넷 쇼핑몰 SQLite 데이터베이스 shop.db에 대한 접근을 제공합니다: 고객, 상품, 주문 및 주문 항목.

공식 MCP Python SDK (v2) 기반입니다.

개발 메타데이터

프로젝트는 SPEC.md 명세에 따라 AI 코딩 에이전트(Claude Code, 모델 Fable 5)로 완전히 생성되었습니다.

Related MCP server: db-mcp

도구 (tools)

보안

이 서버를 통해 데이터베이스를 변경할 수 없습니다. 세 가지 독립적인 보호 계층:

1. 요청 검증 — 단일 SELECT/WITH가 아닌 모든 것 (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, PRAGMA, ATTACH, 연속된 여러 구문, 주석 뒤에 숨겨진 쓰기)은 실행 전에 이해하기 쉬운 메시지와 함께 거부됩니다.

2. 읽기 전용 연결 — 파일은 mode=ro SQLite URI로 열립니다.

3. PRAGMA query_only = ON 을 각 연결에 적용합니다.

검증을 통과한 쓰기(예: WITH ... INSERT)도 연결 수준의 읽기 전용 제한에 막힙니다.

SQL 오류는 힌트가 포함된 짧고 명확한 메시지로 반환되며, 스택 트레이스가 없습니다.

설치

필수: Python 3.10+

uv 사용 시 (권장 — 첫 실행 시 자동으로 설치됩니다):

uv sync

또는 pip 사용:

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

구성

서버는 server.py 옆에 있는 shop.db 파일에서 데이터베이스를 찾습니다. 과제에서 제공된 데이터베이스는 리포지토리에 포함되어 있습니다. 다른 파일을 사용하려면 SHOP_DB_PATH 환경 변수를 설정하세요:

export SHOP_DB_PATH=/path/to/shop.db

seed_db.py는 유사한 스키마의 데모 데이터베이스를 생성하는 보조 유틸리티입니다 (일회성 데이터에만 사용하며, 명시적으로 요청하지 않으면 shop.db를 건드리지 않습니다):

python seed_db.py /tmp/demo.db

실행

서버는 stdio로 통신하며, 사용자가 수동으로 실행하는 것이 아니라 MCP 클라이언트가 시작합니다. 오류 없이 시작되는지 확인하려면:

uv run python server.py

(서버는 stdin에서 MCP 메시지를 기다리며; 종료는 Ctrl+C)

에이전트에 연결

Claude Code

리포지토리에 .mcp.json이 있으므로 프로젝트 디렉터리에서 서버가 자동으로 인식됩니다. 수동으로 등록하려면:

claude mcp add shop-db -- uv run --directory /absolute/path/to/sqlite-mcp python server.py

Claude Desktop (또는 JSON 구성을 사용하는 클라이언트)

claude_desktop_config.json에 추가하세요 ( examples/claude_desktop_config.example.json 참조) — pip로 설치한 경우, 의존성이 구성에 지정된 인터프리터에 설치되어 있어야 합니다:

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

또는 uv 사용 시 (수동 설치 불필요):

{
  "mcpServers": {
    "shop-db": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/sqlite-mcp", "python", "server.py"]
    }
  }
}

Docker

docker build -t shop-db-mcp .

{
  "mcpServers": {
    "shop-db": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shop-db-mcp"]
    }
  }
}

에이전트가 답변하는 질문 예시

• 사용 가능한 모든 테이블을 표시하고 각 테이블의 정보를 설명하세요.

• 독일에서 온 고객은 몇 명인가요?

• 어떤 국가에 고객이 가장 많은가요?

• 가장 많은 돈을 쓴 고객은 누구인가요?

• 베스트셀러 상품 상위 5개는 무엇인가요?

• 매출 기준 상위 3개 상품 카테고리는 무엇인가요?

• 2025년에 발생한 매출은 얼마인가요?

• 주문을 가장 많이 한 고객은 누구인가요?

파괴적인 요청 («Delete all cancelled orders»)은 서버가 거부합니다.

제공된 데이터에 대한 참고사항: customers 테이블에는 국가 열이 없습니다(위치는 전화 지역번호 — 모든 번호 +7 — 또는 이메일 도메인으로만 유추 가능). 또한 모든 주문은 2026년 2월–8월로 날짜가 표시되어 있습니다. 스키마 도구는 에이전트가 이를 발견하고 정직하게 답변하는 데 필요한 모든 정보를 제공합니다.

실제 에이전트를 통한 검증 결과

명세의 모든 작업은 실제 headless 에이전트(claude -p "<вопрос>" --mcp-config .mcp.json, 모델 Sonnet)로 실행했으며, 에이전트는 서버의 세 가지 MCP 도구 만 사용 가능했고 Bash와 파일 접근은 없었습니다. 응답은 SQLite에서 직접 계산한 기준값과 대조했습니다. 결과: 9/9.

트랜스크립트에서 확인된 관찰: 에이전트는 대부분 list_tables + 집계 SQL 쿼리 하나만으로 충분했습니다. 도구 응답의 테이블 설명(국가 부재 힌트와 매출 계산식 포함)이 의도한 대로 동작했습니다.

데이터베이스 스키마

customers ──< orders ──< order_items >── products

• customers (150행) — id, first_name, last_name, email, phone, created_at

• products (50행) — id, name, category, price, stock_quantity, created_at

• orders (750행) — id, customer_id → customers, order_date, status (new/processing/shipped/completed/cancelled), total_amount

• order_items (1900행) — id, order_id → orders, product_id → products, quantity, unit_price

테스트

uv run pytest

36개의 테스트가 세 도구, 페이지네이션, 오류 처리, 읽기 전용 보장(멀티 스테이트먼트와 주석으로 위장한 쓰기 포함) 및 데모 데이터 생성기를 다룹니다.

프로젝트 구조

server.py        # MCP-сервер (3 инструмента, read-only защита)
shop.db          # выданная в задании база данных
SPEC.md          # спецификация, по которой сгенерирован проект
seed_db.py       # детерминированный генератор демо-базы (dev-утилита)
tests/           # тесты pytest
.mcp.json        # конфиг проекта для Claude Code
examples/        # пример конфига для Claude Desktop
Dockerfile       # опциональный запуск в контейнере