# Shop Analytics MCP

MCP-сервер на TypeScript для безопасной аналитики SQLite-базы интернет-магазина. Работает только по stdio и предоставляет шесть специализированных tools; произвольный SQL не принимается.

## Требования

- Node.js 24.10+;
- npm;
- `sqlite3` CLI только для повторного применения миграции.

## Установка и запуск

```bash
npm ci
npm run build
SHOP_DB_PATH=./shop.db npm start
```

`SHOP_DB_PATH` имеет приоритет. Если переменная не задана, сервер ищет `shop.db` в текущей рабочей директории. Путь к базе не вшит в исходный код.

## Данные

В репозитории находится готовая мигрированная `shop.db`. Она содержит страны клиентов и данные за 2025 год. Денежные значения интерпретируются как EUR и не конвертируются.

Чтобы применить миграцию к исходной базе один раз:

```bash
npm run migrate
```

Исходная схема находится в `database/schema.sql`, а детерминированная миграция в `database/001-add-analytics-data.sql`.

## Подключение к клиенту

Готовые шаблоны конфигурации находятся в `config/`:

- `claude-code.mcp.json`;
- `codex.mcp.json`;
- `cursor.mcp.json`.

Замените `/absolute/path/to/mcp-server` в выбранном шаблоне на путь к этому проекту. Все конфигурации запускают `dist/src/index.js` по stdio и передают путь к `shop.db` через `SHOP_DB_PATH`.

## Tools

| Tool | Назначение |
| --- | --- |
| `get_database_schema` | Таблицы, колонки, ключи и связи. |
| `get_customer_metrics` | Количество клиентов в стране или страна-лидер. |
| `get_product_sales` | Рейтинг товаров по проданным единицам и выручке. |
| `get_category_revenue` | Рейтинг категорий по выручке. |
| `get_revenue_by_period` | Выручка за UTC-период `[from, to)`. |
| `get_order_leaders` | Клиент с наибольшими тратами или количеством заказов. |

Финансовые и товарные показатели, а также количество заказов, исключают `cancelled`. Суммы возвращаются в полях с суффиксом `Eur`. Рейтинги принимают `limit` от 1 до 100; периоды используют даты `YYYY-MM-DD`.

## Пример работы

Ниже показано, как MCP-клиент вызывает `get_database_schema` для описания таблиц, а затем `get_customer_metrics` для подсчета клиентов из Германии.

![Пример вызова MCP-инструментов](docs/images/mcp-tools-example.png)

## Безопасность

- SQLite открывается с `readOnly: true` и `PRAGMA query_only = ON`.
- SQLite authorizer запрещает запись, DDL, `ATTACH`, `DETACH` и транзакции.
- Все значения привязываются как SQL-параметры.
- Tools не принимают SQL, поэтому агент не может передать destructive statement.
- Ошибки валидации не раскрывают SQL, абсолютные пути или stack traces.

## Тесты

```bash
npm test
```

Тесты покрывают эталонные ответы восьми приемочных вопросов, SQL-инъекцию в параметре страны, запрет `DELETE`, неизменность SHA-256 временной копии БД и MCP-взаимодействие по stdio.

## Приемочные вопросы

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?