Shop Database MCP Server

포함된 교육용 SQLite 상점 픽스처를 탐색하고 분석하기 위한 로컬, 읽기 전용 Model Context Protocol 서버입니다. 정확히 세 가지 도구를 제공합니다: list_tables, describe_table, query_database.

커밋된 shop.db에는 합성적 교육용 국가 값이 들어 있습니다. 이 값들은 개인 속성을 추론한 것이 아니라 결정적(deterministic) 픽스처 데이터입니다.

1. 설치

사전 요구 사항: Node.js 20 이상, npm, 그리고 better-sqlite3를 지원하는 플랫폼(또는 npm이 prebuilt native binary를 얻을 수 없을 때 필요한 로컬 C/C++ 빌드 체인).

npm install

2. 구성

포함된 shop.db를 사용하는 경우 구성이 필요 없습니다. 다른 호환 데이터베이스를 선택하려면 절대 경로 또는 상대 경로를 설저하세요:

export SHOP_DB_PATH=/path/to/shop.db

서버는 default database 경로를 호출자의 작업 디렉터리가 아닌, 자버 자신 모듈을 기저으로 해석합니다. 존자하지 않는 데이터베이스를 생서하지 않습니다. .env.example을 참조하세요. 환경 파일은 자동으로 로드되지 않습니다.

3. 픽스처 준비 또는 검증

npm run prepare-db

이 명시적 설저 명령어는 customers.country 결정적 합성 스처와 그 인덱스를 원자적으로 추거나 검증합니다. 기존 고객 필드와 ID를 보존하며, 멱등(アイデ)적으로 동작합니다. start, dev, 서버 런타임에서는 호출되지 않습니다. 저장소에는 이미 준비된 데이터베이스가 포함되어 있으므로, 이 명령은 일반적으로 검증 역할을 합니다.

4. 빌드

npm run typecheck
npm run build

5. 실행

npm run start

프로세스는 stdin/stdout으로 MCP를 통신하며 클라이언트를 기다립니다. 시작 배너를 출력하지 않으며, stdout은 MCP 메시지 전용입니다. 개발 모드는 npm run dev로 이용할 수 있습니다.

6. 연결

일반적인 stdio MCP 구성은 configuration.example.json에 제공돼 있습니다:

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

Codex CLI에서 서버를 명령줄에 직접 추가하거나:

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

config/codex-config.example.toml 템플릿을 Codex 구성으로 복사한 뒤 필요한 자리표시자를 교체해도 됩니다:

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

codex mcp list를 실행하고, Codex를 시작한 다음 /mcp를 사용해 shop_database와 세 가지 도구를 쓸 수 있는지 확인하세요.

7. 테스트

npm test

테스트 스위트는 입력 경계값, SQL 토큰화와 거부, 직렬화, 스키마 검색, 모든 허용 분석, 페이지네이션, 명명된 바인딩, stdio 프로토콜 동작, 그리고 파괴적 쿼리 매트릭스 전반에서의 데이터베이스 불변성을 다룹니다.

예시 프롬프트

1. 사용 가능한 모든 테이블과 각 테이블이 무슨 정보를 담고 있는지 설명해 주세요.

2. 독일 출신 고객은 몇 명인가요?

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

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

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

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

7. 2025년 매출은 얼마인가요?

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

의 규직 및 읽기 전용 보장

데이터베이스는 readonly: true 그리고 fileMos: true으로 열린 뒤, SQLite 으만 모드로 설정합니다. SQL 정책은 오직 하나의 SELECT 또는 재귀 없는 WITH ... SELECT만 허용하며, 데이터 변형(mutation), DDL, PRAGMA, attachment, 유지보수, 확장 (extension) 로딩, 재귀 CTE, 그리고 추가적인 querise 모두 거부됩니다. 준비된 문장(Prepared Statement)도 전용어야 하며, 사용자 값은 명명된 바인딩으로만 전달됩니다.

각 결과 페이지에는 최대 500행이 담입니다. 결정적인 ORDER BY를 사용하고, has_more가 true인 동안 next_offset으로 계속 진행하세요. 동기 SQLite 드라이버는 프로세스 내에서 CPU 사용량이 큰 르리를 중단할 수 없습니다. 따라서 v1은 서버 측의 하드 데드라인 대신 쿼리 제한, 크기가 제한된 출력, 그리고 권장되는 15초 MCP 클라이언트 시간제한에 의존합니다.

매출, 지출, 판매 수량, 제품/카테고리 판매는 취소된 주문을 빼고 집계합니다. 주문 건수는 모든 상태를 포함합니다. 주문 전체 매출과 고객 지출은 orders.total_amount를 사용하고, 특정 시점의 제품/카테고리 매출은 order_items.quantity * orders.unit_price를 사용합니다. 날짜는 시간대(Timezone) 정보가 없는 순수 값이며, 달력 연도 필터는 반개구간을 사용합니다. 이 데이터베이스는 어떤 통화 표시도 하지 않으므로 금액은 화폐 단위로 취급됩니다.

문제 해결

• DATABASE_UNAVAILABLE: SHOP_DB_PATH 변수 확인, 파일 존재 여부 및 읽기 권한을 점검하세요. 서버가 데이터베이스를 직접 만들지는 않습니다.

• DATABASE_SCHEMA_MISMATCH: 커밋된 픽스처를 사용하거나 npm run prepare-db를 실행하세요. 커스텀 데이터베이스에는 필요한 모든 테이블, 열, 외래 키, 픽스처 조건이 모두 갖춰져 있어야 합니다.

• 네이티브 종속성 설치 실패: 지원하는 Node.js 버전을 사용하고 해당 플랫폼의 컴파일러와 빌드 도구를 설치한 다음 npm install을 다시 실행하세요.

• MCP 프레이밍 또는 JSON 오류: 런타임 코드에 console.log나 stdout 로깅을 넣지 마세요. 진단은 반드시 stderr로만 보내세요.

• 쿼리가 SQL_ERROR를 반환하는 경우: 먼저 테이블을 살펴보고, 결과에 중복되는 열 이름이 있으면 고유한 별칭(alias)을 사용하고, 플레이스홀더 이름 및 SQL 구문을 확인하세요.