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.

Related MCP server: shop

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

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

npm install
npm run build
npm test
npm run start

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

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

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

npm run build

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

{
  "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.

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

Tools

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

{"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-протокола.