Shop MCP Server

온라인 상점 SQLite 데이터베이스 분석을 위한 로컬 MCP 서버입니다. AI 에이전트가 MCP 도구를 호출하면 서버가 요청을 안전한 SQL SELECT로 변환하고, shop.db를 직접 읽어 구조화된 결과를 반환합니다.

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

기능

• HTTP 및 별도 DB 서버 없이 SQLite에 직접 연결;

• MCP 전송 stdio;

• tools/list를 통한 query_shop 및 inspect_database 검색;

• 설명 및 도구 JSON Schema에 8가지 작업 예시;

• 일반 텍스트, JSON intent 또는 준비된 안전한 SELECT;

• 모든 분석에서 cancelled 주문 제외;

• 페이지네이션 및 결과 제한;

• 다층 read-only 보호.

Related MCP server: Shop Analytics MCP Server

설치

Python 3.11 이상이 필요합니다.

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

준비된 데이터베이스는 이미 data/shop.db에 있습니다. 150명의 고객이 있으며, customers.country 필드는 모든 고객에게 채워져 있고, 45명의 고객이 Germany에 속합니다.

데이터베이스 재준비

원본 데이터베이스는 변경되지 않습니다. 명령은 새 작업 복사본을 만들고 재현 가능한 합성 값으로 country TEXT NOT NULL을 추가합니다:

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

분포는 customers.id에만 의존하므로 재준비 시 동일한 값이 생성됩니다. 국가는 테스트 데이터이며 고객의 실제 위치를 나타내지 않습니다.

경로 설정

경로는 다음 순서로 결정됩니다:

1. SHOP_DB_PATH;

2. SHOP_MCP_CONFIG 또는 config/shop_mcp.json의 JSON 파일;

3. 작업 디렉터리 기준 data/shop.db.

환경 변수 예시는 .env.example에 있고, MCP 클라이언트 구성은 config/mcp.example.json에 있습니다. /absolute/path/to/MCPDeveloper를 프로젝트의 절대 경로로 바꾸세요.

실행

일반적으로 MCP 클라이언트가 자체 구성에서 서버를 실행합니다. 프로세스를 수동으로 실행하려면:

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout은 MCP JSON-RPC용으로 예약되어 있습니다. 진단 정보는 프로토콜 스트림으로 출력되지 않습니다.

도구

inspect_database

인수:

{"action": "list_tables"}

또는:

{"action": "describe_table", "table": "customers"}

query_shop

인수:

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

tools/list를 통해 선언되는 예시:

1. 데이터베이스에 어떤 테이블이 있고 각 테이블에 어떤 필드가 있나요?

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

3. 어느 국가에 고객이 가장 많나요?

4. 어느 고객이 가장 많이 지출했나요? 이름, 이메일, 총 금액을 반환하세요.

5. 판매 수량과 매출 기준 상위 5개 상품을 보여주세요.

6. 매출 기준 상위 3개 카테고리를 보여주세요.

7. 2025년 매출은 얼마였나요?

8. 어느 고객이 가장 많은 주문을 했나요?

구조화된 intent를 전달할 수 있습니다:

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

또는 준비된 쿼리:

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

비즈니스 규칙

• orders.status = 'cancelled'는 지표에 포함되지 않습니다.

• 고객 지출과 연간 매출은 orders.total_amount로 계산됩니다.

• 상품 및 카테고리 매출은 quantity * unit_price로 계산됩니다.

• 연도 간격은 반개방형입니다: 1월 1일 포함부터 다음 해 1월 1일 제외까지.

• 제공된 데이터베이스의 모든 주문은 2026년에 속하므로 2025년 매출은 0입니다.

보안

서버는 mode=ro로 SQLite를 열고, query_only를 활성화하며, SQLite authorizer를 설정하고, 여러 문장, DML, DDL, ATTACH, 변경하는 PRAGMA, 확장 로드를 금지하며 실행 시간을 제한합니다.

SELECT가 아닌 작업을 실행하려는 모든 시도는 정확한 응답을 반환합니다:

Не доступный вариант запроса

SQLite 내부 오류, 스택 추적 및 로컬 경로는 클라이언트에 반환되지 않습니다.

검증

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

테스트에는 MCP 서버를 subprocess로 실제 실행, stdio를 통한 ClientSession 연결, tools/list, 두 도구 모두 호출, 분석 시나리오 및 데이터베이스 변경 시도가 포함됩니다.

전체 승인된 사양은 docs/specification.md에 있습니다.