Shop Analytics MCP Server

A read-only MCP server, over stdio, that lets an AI agent answer analytical questions about an online store's SQLite database (customers, products, orders, order_items) — without ever being able to modify it.

전체 설계 근거(의사결정 로그, 스키마, 보안 모델, 테스트 전략)는 SPEC.md를 참조하세요.

요구 사항

• Node.js >= 24.10.0 (node:sqlite의 setAuthorizer를 사용하며, 아래의 읽기 전용 보장에 사용됩니다). node --version으로 확인하세요.

• npm ci가 설치하는 것 외에 다른 런타임 의존성은 없습니다.

Related MCP server: db-mcp

설치 → 구성 → 실행 → 연결

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

• shop.db는 이 저장소에 포함되어 있으며 즉시 사용할 수 있습니다. 스키마로부터 결정적으로 다시 생성해야 한다면 npm run seed를 실행하세요(아래 데이터베이스 참조).

• SHOP_DB_PATH는 선택 사항이며, 기본적으로 현재 작업 디렉터리의 shop.db를 사용합니다. 소스 어디에도 절대 경로가 하드코딩되어 있지 않습니다.

• 서버는 stdio 전용으로 MCP를 통신합니다. HTTP 서버를 실행하거나 다른 작업은 없습니다.

AI 에이전트 연결

두 클라이언트의 구성 예시는 config/에 있습니다:

• config/claude-code.mcp.json — 프로젝트의 .mcp.json에 복사하거나, 해당 shop-analytics 항목으로 claude mcp add-json을 실행하세요. 먼저 args/env에 절대 경로로 채워 넣으세요.

• config/codex.mcp.toml — [mcp_servers.shop-analytics] 테이블을 ~/.codex/config.toml(또는 프로젝트 범위의 .codex/config.toml)에 복사하거나, 파일의 헤더 주석에 있는 codex mcp add 명령을 사용하세요.

특정 에이전트 없이 서버를 직접 다뤄보려면, 도구에 구애받지 않는 MCP Inspector를 사용하세요:

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

도구

The full per-tool contracts ... but in Korean:

서버는 정확히 8개의 특화된 읽기 전용 도구를 노출합니다. 어떤 도구도 임의의 SQL을 받아들이거나 실행하지 않습니다. 모든 성공 응답은 { "data": [...], "meta": {...} } 형태이며, 모든 오류는 isError: true로 표시된, SQL이나 파일 경로, 스택 트레이스가 없는 안전한 사람이 읽을 수 있는 일반 메시지입니다.

from/to는 YYYY-MM-DD 형식이며 반개방 UTC 구간 [from, to)을 정의합니다. from은 반드시 to보다 이전이어야 합니다. 모든 금액 및 개수 관련 지표는 상태가 cancelled인 주문을 제외합니다. 각 도구의 완전한 계약(관한 정확한 응답 형태, 동점 시 처리 규칙)은 SPEC.md §4에 있습니다.

안전

"모든 취소된 주문을 삭제하세요" 같은 적대적 프롬프트에도 데이터베이스가 절대 수정되지 않도록 보장하는 세 가지 독립적인 심층 방어 계층이 있습니다:

1. SQLite 연결이 readOnly: true로 열립니다.

2. 연결을 연 직후 PRAGMA query_only = ON이 설정됩니다.

3. SQLite의 authorizer가 모든 쓰기/DDL 작업(INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, 트랜잭션 등)을 명시적으로 거부합니다.

그 위에 어떤 도구도 원시 SQL, 테이블 이름, 컬럼 이름을 받지 않습니다. 모든 쿼리는 고정된 prepared statement이며, 모든 입력은 zod로 검증되고 문자열을 직접 연결하는 일 없이 바인딩된 매개변수로 전달됩니다.

데이터베이스

shop.db는 결정적 시드 스크립트가 database/schema.sql에서 생성합니다. 다시 실행할 때마다 바이트 단위로 동일한 데이터를 생성합니다(고정된 PRNG 시드, 벽시계에 의존하지 않음):

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

시드 스크립트는 생성 당시 데이터셋에 모호한 리더보드가 없다는 점(예: 유일한 최상위 국가, 유일한 최고 지출 고객)과 2025년 매출이 0이 아닌 것을 검증합니다 — SPEC.md §3 참조.

개발

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

이 프로젝트는 TDD 방식으로 개발되었습니다. 각 모듈마다 먼저 실패하는 테스트를 작성하고, 그다음 구현을 도구별로 수행했습니다. 통합 테스트 스위트는 8가지 인수 시나리오를 종단 간(end-to-end)으로, SQL 인젝션 형태의 입력, 잘못된 매개변수 조합을 다루며, 모든 실행 후 데이터베이스 파일의 SHA-256 해시가 변경되지 않았음을 검증합니다.

프로젝트 구조

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)