# Shop SQLite MCP

Локальный stdio MCP-сервер для безопасного анализа существующей SQLite-базы интернет-магазина. Сервер динамически читает схему из `sqlite_master` и SQLite PRAGMA, поэтому не зависит от заранее известных имён колонок.

## Возможности

- `list_tables` — таблицы и представления;
- `describe_table` — колонки, PK, FK и индексы;
- `get_schema` — полный граф схемы;
- `run_select_query` — один ограниченный `SELECT` / `WITH ... SELECT`;
- специализированные analytics tools: `count_customers_by_country`, `top_customers_by_spend`, `top_products_by_units`, `top_categories_by_revenue`, `revenue_in_year`, `top_customers_by_order_count`;
- физический read-only режим SQLite, `query_only` и authorizer;
- блокировка DML, DDL, PRAGMA, ATTACH и нескольких statements;
- pagination: `limit` 1–500 и `offset`.

## Setup

Одна команда делает всё: выбирает вариант установки, ставит зависимости (или собирает Docker-образ), находит базу, проверяет чтение схемы и записывает готовый [`mcp.json`](mcp.json).

```bash
python3 install.py
```

Скрипт спросит вариант запуска (`.venv` или Docker) и путь к базе. Без вопросов:

```bash
python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db
```

Требуется Python 3.11+; для `--mode docker` — установленный Docker.

По умолчанию база берётся из `data/shop.db`. Если файла нет, скрипт остановится с понятной ошибкой и **не создаст** пустую базу.

Ручной запуск отдельно не нужен — сервер стартует уже из конфига. Для отладки:

```bash
.venv/bin/python -m shop_mcp.print_schema
```

## Connect to agent

После `install.py` остаётся один шаг. Файл [`mcp.json`](mcp.json) уже содержит выбранную команду запуска и абсолютный путь к базе — править ничего не нужно.

Подключите его к агенту одним из способов:

- Cursor: откройте эту папку как workspace (копия лежит в `.cursor/mcp.json`) или импортируйте корневой `mcp.json` в MCP settings;
- Claude Desktop / другой клиент: скопируйте содержимое `mcp.json` в конфиг MCP.

После подключения сразу задавайте вопросы из [`ASSIGNMENT.md`](ASSIGNMENT.md). Первое действие агента — `get_schema` или специализированный analytics tool. Если tool вернул `SCHEMA_MISMATCH`, используйте `run_select_query`.

Шаблон с placeholders — только [`mcp.json.example`](mcp.json.example). Абсолютные пути есть только в клиентском конфиге, не в Python-коде.

## Docker

Отдельные команды не нужны: `python3 install.py --mode docker` сам собирает образ `shop-sqlite-mcp:local`, монтирует базу read-only и записывает в `mcp.json` запуск `docker run -i --rm`.

База пробрасывается как `/data/shop.db:ro`, флаг `-t` не используется, потому что MCP общается через stdin/stdout.

`docker-compose.yml` собирает тот же образ и полезен для локальной проверки сборки; агенту отдавайте `mcp.json`.

## Test

```bash
.venv/bin/pytest
```

Тесты используют временную fixture-базу с неизвестными серверу именами таблиц. Они проверяют runtime introspection, ограничения результатов, отсутствие хардкода схемы и отказ от destructive SQL.

Для ручной проверки после подключения задайте вопросы из [`ASSIGNMENT.md`](ASSIGNMENT.md), включая:

> Delete all cancelled orders.

Ответ tool должен содержать `WRITE_DENIED`, а база остаться неизменной.

## Project files

- [`install.py`](install.py) — единственная команда установки: зависимости/образ, путь к БД, генерация конфига;
- [`mcp.json`](mcp.json) — готовый конфиг подключения (команда + путь к БД);
- [`PROMPT.md`](PROMPT.md) — промпт, по которому AI coding agent создал сервер;
- `src/shop_mcp/` — MCP, schema introspection, SQL guard, analytics tools;
- `tests/` — автоматические safety, discovery и analytics тесты;
- `Dockerfile` / `docker-compose.yml` — контейнерный stdio MCP;
- [`NOTES.md`](NOTES.md) — решения по неоднозначностям задания.