Shop SQLite MCP

로컬 stdio MCP 서버로, 기존 SQLite 온라인 쇼핑몰 데이터베이스를 안전하게 분석하기 위한 도구입니다. 이 서버는 sqlite_master와 SQLite PRAGMA에서 스키마를 동적으로 읽어오므로, 미리 알려진 컬럼 이름에 의존하지 않습니다.

기능

• list_tables — 테이블 및 뷰;

• describe_table — 컬럼, PK, FK 및 인덱스;

• get_schema — 전체 스키마 그래프;

• run_select_query — 제한된 단일 SELECT / WITH ... SELECT;

• 전용 분석 도구: count_customers_by_country, top_customers_by_spend, top_products_by_units, top_categories_by_revenue, revenue_in_year, top_customers_by_order_count;

• SQLite 물리적 read-only 모드, query_only 및 authorizer;

• DML, DDL, PRAGMA, ATTACH 및 다중 statement 차단;

• 페이지네이션: limit 1–500 및 offset.

설치

단 하나의 명령으로 모든 작업이 완료됩니다: 실행 방식 선택, 의존성 설치(또는 Docker 이미지 빌드), 데이터베이스 찾기, 스키마 읽기 확인, 그리고 준비된 mcp.json 작성.

python3 install.py

스크립트가 실행 방식(.venv 또는 Docker)과 데이터베이스 경로를 묻습니다. 질문 없이 실행하려면:

python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db

Python 3.11+ 필요; --mode docker의 경우 Docker가 설치되어 있어야 합니다.

기본적으로 데이터베이스는 data/shop.db에서 가져옵니다. 파일이 없으면 스크립트는 명확한 오류 메시지와 함께 중지되며 빈 데이터베이스를 생성하지 않습니다.

별도의 수동 실행은 필요 없습니다 — 서버는 이미 구성 파일에서 시작됩니다. 디버깅용:

.venv/bin/python -m shop_mcp.print_schema

에이전트에 연결

install.py 실행 후 남은 단계는 하나뿐입니다. mcp.json 파일에는 이미 선택된 실행 명령과 데이터베이스의 절대 경로가 포함되어 있으므로 수정할 필요가 없습니다.

다음 방법 중 하나로 에이전트에 연결하세요:

• Cursor: 이 폴더를 workspace로 열거나(복사본은 .cursor/mcp.json에 있음) 루트 mcp.json을 MCP 설정으로 가져오기;

• Claude Desktop / 기타 클라이언트: mcp.json의 내용을 MCP 구성에 복사.

연결 후 ASSIGNMENT.md의 질문을 바로 물어보세요. 에이전트의 첫 번째 작업은 get_schema 또는 전용 분석 도구입니다. 도구가 SCHEMA_MISMATCH를 반환하면 run_select_query를 사용하세요.

Placeholders가 포함된 템플릿은 mcp.json.example뿐입니다. 절대 경로는 Python 코드가 아닌 클라이언트 구성에만 있습니다.

Docker

별도 명령은 필요 없습니다: python3 install.py --mode docker가 shop-sqlite-mcp:local 이미지를 빌드하고, 데이터베이스를 read-only로 마운트하며, docker run -i --rm 실행을 mcp.json에 기록합니다.

데이터베이스는 /data/shop.db:ro로 전달되며, MCP가 stdin/stdout으로 통신하므로 -t 플래그는 사용되지 않습니다.

docker-compose.yml은 동일한 이미지를 빌드하며 로컬 빌드 확인에 유용합니다. 에이전트에는 mcp.json을 제공하세요.

테스트

.venv/bin/pytest

테스트는 서버에 알려지지 않은 테이블 이름을 가진 임시 fixture 데이터베이스를 사용합니다. 런타임 introspection, 결과 제한, 스키마 하드코딩 부재, destructive SQL 거부를 검증합니다.

연결 후 수동 확인을 위해 ASSIGNMENT.md의 질문을 물어보세요. 예를 들면:

Delete all cancelled orders.

도구 응답에는 WRITE_DENIED가 포함되어야 하며 데이터베이스는 변경되지 않은 상태로 유지되어야 합니다.

프로젝트 파일

• install.py — 유일한 설치 명령: 의존성/이미지, DB 경로, 구성 생성;

• mcp.json — 준비된 연결 구성(명령 + DB 경로);

• PROMPT.md — AI 코딩 에이전트가 서버를 만드는 데 사용한 프롬프트;

• src/shop_mcp/ — MCP, 스키마 introspection, SQL guard, 분석 도구;

• tests/ — 자동 안전성, 탐색 및 분석 테스트;

• Dockerfile / docker-compose.yml — 컨테이너형 stdio MCP;

• NOTES.md — 과제의 모호성에 대한 결정 사항.