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.

python3 install.py

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

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. Если файла нет, скрипт остановится с понятной ошибкой и не создаст пустую базу.

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

.venv/bin/python -m shop_mcp.print_schema

Connect to agent

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

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

• Cursor: откройте эту папку как workspace (копия лежит в .cursor/mcp.json) или импортируйте корневой mcp.json в MCP settings;

• Claude Desktop / другой клиент: скопируйте содержимое mcp.json в конфиг MCP.

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

Шаблон с placeholders — только 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

.venv/bin/pytest

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

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

Delete all cancelled orders.

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

Project files

• install.py — единственная команда установки: зависимости/образ, путь к БД, генерация конфига;

• mcp.json — готовый конфиг подключения (команда + путь к БД);

• 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 — решения по неоднозначностям задания.