# Shop database MCP server

## Что делает этот MCP

Это MCP-сервер для безопасного анализа локальной SQLite-базы интернет-магазина. Он работает через стандартные потоки ввода/вывода (stdio), не поднимает HTTP-сервер и предоставляет AI-агенту доступ только для чтения.

Сервер открывает SQLite в режиме read-only и дополнительно разрешает только один запрос `SELECT` или `WITH ... SELECT`. Изменение данных, `PRAGMA`, транзакции, подключение других баз и несколько SQL-выражений блокируются. В базе нет поля страны, поэтому аналитика по странам недоступна.

Основные сущности: `customers`, `products`, `orders` и `order_items`. Связи: заказ ссылается на клиента, а строка заказа — на заказ и товар. Для исторической выручки по товарам используйте `order_items.quantity * order_items.unit_price`.

## Требования и запуск

Нужен Node.js **24.2+ LTS** — стабильная версия с нужным API `node:sqlite`. Проект использует официальный MCP TypeScript SDK, Zod, TypeScript и Vitest.

```bash
npm install
npm run build
npm test
npm run start
```

Для разработки используйте `npm run dev`, для строгой проверки типов — `npm run lint`. Протокол MCP пишется только в stdout; диагностика — только в stderr.

## Как подключить MCP

Сначала соберите проект:

```bash
npm run build
```

Добавьте сервер в конфигурацию вашего MCP-клиента, заменив абсолютные пути на свои:

```json
{
  "mcpServers": {
    "shop-database": {
      "command": "node",
      "args": ["/absolute/path/to/shop-mcp/dist/index.js"],
      "env": {
        "SHOP_DB_PATH": "/absolute/path/to/shop-mcp/data/shop.db"
      }
    }
  }
}
```

Переменная `SHOP_DB_PATH` необязательна. Если её не задать, сервер использует `data/shop.db` относительно собранного файла `dist/index.js`.

```dotenv
# .env — опционально
SHOP_DB_PATH=/absolute/path/to/shop.db
```

## Tools

| Tool | Входные данные и результат | Когда использовать |
| --- | --- | --- |
| `get_database_schema` | Пустой объект. Возвращает бизнес-таблицы, их поля, типы, ключи, значения по умолчанию, внешние ключи и индексы. Внутренние таблицы SQLite скрыты. | Перед составлением незнакомого SQL-запроса. |
| `query_database` | Обязательный `sql`; необязательные массив `parameters`, `page` (по умолчанию `1`) и `pageSize` (по умолчанию `50`, максимум `100`). Возвращает `columns`, `rows`, `page`, `pageSize`, `returnedRowCount`, `hasMore`. | Для фильтрации, JOIN, агрегаций и произвольной аналитики. |

При получении нескольких страниц обязательно добавляйте стабильный `ORDER BY`. Пагинация применяется сервером; он получает не более `pageSize + 1` строк. Значения для `?` передавайте в `parameters`, а не подставляйте в SQL-строку.

```json
{"sql":"SELECT id, name, stock_quantity FROM products ORDER BY id","page":2,"pageSize":25}
```

## Пять тестовых промптов

После подключения перезапустите или обновите MCP-клиент, чтобы он обнаружил `shop-database`. Скопируйте любой из этих запросов в чат с включённым MCP:

1. «Сначала вызови `get_database_schema`, затем перечисли таблицы, их ключевые поля и связи между ними.»

2. «Найди клиента, который потратил больше всех. Верни полное имя, email и сумму всех заказов.»

3. «Покажи 5 самых продаваемых товаров: название, суммарное число проданных единиц и выручку по исторической цене из `order_items`.»

4. «Рассчитай выручку за 2025 год по полю `orders.total_amount`. Используй параметры для границ дат.»

5. «Покажи помесячные число заказов и выручку, отсортированные по месяцу. Используй `page: 1`, `pageSize: 12` и стабильный `ORDER BY`.»

## Безопасность и ошибки

Допускается ровно один `SELECT` либо `WITH`-запрос с итоговым `SELECT`. Сервер отклоняет `DELETE FROM orders`, `UPDATE products`, `PRAGMA`, `ATTACH`, `INSERT`, DDL-команды, загрузку расширений и несколько выражений в одном запросе. Read-only подключение к SQLite является второй линией защиты.

Некорректные параметры и SQL возвращают короткие понятные ошибки без путей к файлам, переменных окружения и stack trace. Если база не найдена или недоступна, проверьте `SHOP_DB_PATH` либо наличие `data/shop.db`. Если не устанавливаются зависимости — выполните `npm install`; если сервер не запускается — проверьте версию Node.js.

Для ручной проверки stdio выполните `npm run build`, затем `node dist/index.js` из MCP-клиента: в stdout должны попадать только сообщения MCP-протокола.