shop-db MCP 서버

AI 에이전트에게 전자상거래 SQLite 데이터베이스(customers, orders, order_items, products)에 대한 분석적 접근 권한을 제공하는 읽기 전용 Model Context Protocol 서버입니다. 데이터를 수정할 수 있는 기능은 전혀 없습니다.

**Node.js v24.19+**용으로 제작되었으며, 네이티브 node:sqlite와 node:test를 사용하여 TypeScript 소스 파일을 직접 실행합니다(빌드 단계 없음).

설정

npm install

저장소에는 이미 채워진 ./shop.db가 프로젝트 루트에 포함되어 있어 시딩(seeding) 단계가 필요 없습니다. npm start나 npm test에서 이 파일에 쓰는 작업은 없습니다. 서버는 읽기 전용으로 열며, 테스트 스위트는 tests/fixtures/seed.sql에서 자체 임시 데이터베이스를 tests/ 아래에 생성합니다.

Related MCP server: shop-mcp

서버 실행

npm start

서버는 stdio(StdioServerTransport)를 통해 통신합니다. 즉, MCP 클라이언트(Claude Code, Claude Desktop 등)에 의해 실행되도록 설계되었으며, 대화형으로 실행되는 것이 아닙니다.

테스트

npm test

tests/에 대해 node --test를 실행하며, SQL 검증 엣지 케이스(변형 키워드, 주석 우회, 다중 문장 주입, CTE, EXPLAIN)와 세 가지 MCP 도구를 tests/fixtures/seed.sql에서 생성된 격리된 테스트 데이터베이스에 대해 엔드투엔드로 테스트합니다. 커밋된 ./shop.db는 테스트 스위트에서 읽거나 쓰지 않습니다.

데이터베이스 경로 구성

기본적으로 서버는 (실행된 작업 디렉터리를 기준으로) ./shop.db를 읽습니다. DB_PATH 환경 변수로 재정의할 수 있습니다:

DB_PATH=/absolute/path/to/shop.db npm start

도구

• list_tables — 4개의 테이블을 각각의 간단한 설명과 함께 나열합니다.

• describe_table — 하나의 테이블(tableName) 또는 모든 테이블(생략 시)에 대해 열 정의, 유형, 기본 키, 최대 3개의 샘플 행을 제공합니다.

• read_query — 읽기 전용 SELECT/WITH/EXPLAIN/PRAGMA 쿼리(query, 필수)를 실행하고 최대 limit개의 행(선택 사항, 기본값 100, 최대 1000)을 반환합니다. 모든 변형 시도(INSERT, UPDATE, DELETE, DROP, ...)는 SQL 주석으로 위장하거나 CTE로 감싸더라도 명확한 오류와 함께 거부됩니다.

AI 에이전트 구성

{
  "mcpServers": {
    "shop-db": {
      "command": "node",
      "args": ["/absolute/path/to/src/index.ts"],
      "env": {
        "DB_PATH": "/absolute/path/to/shop.db"
      }
    }
  }
}

프로젝트 문서

• AGENTS.md — 이 저장소에서 작업하는 AI 코딩 에이전트를 위한 지침(심볼릭 링크를 통해 CLAUDE.md로도 로드됨).

• CONTEXT.md — 도메인 모델 및 안전 아키텍처.