Shop MCP Server

SQLite 데이터베이스의 안전한 분석을 위한 TypeScript 기반 MCP 서버입니다. stdio로만 작동하며, 6개의 전용 도구를 제공합니다. 임의 SQL은 허용되지 않습니다.

요구 사항

• Node.js 24.10 이상;

• npm;

• sqlite3 CLI는 마이그레이션 재적용에만 사용됩니다.

Related MCP server: mcp-analytics-server

설치 및 실행

npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start

SHOP_DB_PATH가 우선합니다. 변수가 설정되지 않으면 서버는 현재 작업 디렉토리에서 shop.db를 찾습니다. 데이터베이스 경로는 소스 코드에 하드코딩되어 있지 않습니다.

데이터

리포지토리에는 마이그레이션이 완료된 shop.db가 포함되어 있습니다. 여기에는 고객 국가 및 2025년 데이터가 포함됩니다. 금액 값은 EUR로 해석되며 변환되지 않습니다.

마이그레이션을 원본 데이터베이스에 한 번 적용하려면:

npm run migrate

원본 스키마는 database/schema.sql에 있고, 결정적 마이그레이션은 database/001-add-analytics-data.sql에 있습니다.

클라이언트 연결

완성된 구성 템플릿은 config/에 있습니다:

• claude-code.mcp.json;

• codex.mcp.json;

• cursor.mcp.json.

선택한 템플릿의 /absolute/path/to/mcp-server를 이 프로젝트 경로로 바꾸세요. 모든 구성은 stdio를 통해 dist/src/index.js를 실행하고 SHOP_DB_PATH를 통해 shop.db 경로를 전달합니다.

도구

재무 및 상품 지표와 주문 수는 cancelled를 제외합니다. 금액은 Eur 접미사가 있는 필드로 반환됩니다. 순위는 limit을 1에서 100까지 허용하며, 기간은 YYYY-MM-DD 날짜를 사용합니다.

사용 예시

아래는 MCP 클라이언트가 get_database_schema를 호출하여 테이블을 설명한 다음, get_customer_metrics를 호출하여 독일 고객 수를 집계하는 방법을 보여줍니다.

보안

• SQLite는 readOnly: true 및 PRAGMA query_only = ON으로 열립니다.

• authorizer는 쓰기, DDL, ATTACH, DETACH 및 트랜잭션을 금지합니다.

• 모든 값은 SQL 매개변수로 바인딩됩니다.

• 도구는 SQL을 허용하지 않으므로 에이전트가 파괴적인 명령문을 전달할 수 없습니다.

• 검증 오류는 SQL, 절대 경로 또는 스택 추적을 노출하지 않습니다.

테스트

npm test

테스트는 8가지 승인 질문에 대한 참조 응답, 국가 매개변수의 SQL 주입, DELETE 금지, 임시 데이터베이스 사본의 SHA-256 불변성 및 stdio를 통한 MCP 상호 작용을 다룹니다.

승인 질문

1. 사용 가능한 모든 테이블을 보여주고 각 테이블에 포함된 정보를 설명하세요.

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

3. 고객이 가장 많은 국가는 어디인가요?

4. 가장 많은 돈을 지출한 고객은 누구인가요?

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

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

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

8. 가장 많은 주문을 한 고객은 누구인가요?