Shop Analytics MCP

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

Требования

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

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

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

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

Данные

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

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

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 для подсчета клиентов из Германии.

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

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

Тесты

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?