Shop Analytics MCP Server

MCP-сервер только для чтения, работающий через stdio. Он позволяет ИИ-агенту отвечать на аналитические вопросы об SQLite-базе данных интернет-магазина (customers, products, orders, order_items) — без какой-либо возможности изменить её.

Полное обоснование устройства (журнал решений, схема, модель безопасности, стратегия тестирования) — в SPEC.md.

Требования

• Node.js >= 24.10.0 (нужен для setAuthorizer из node:sqlite, на котором основана описанная ниже гарантия режима только для чтения). Проверить версию можно с помощью node --version.

• Других рантайм-зависимостей, кроме тех, что устанавливает npm ci, нет.

Related MCP server: db-mcp

Установка → настройка → запуск → подключение

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

• shop.db уже лежит в репозитории и готов к использованию. Если потребуется пересоздать его детерминированно из схемы, выполните npm run seed (см. База данных ниже).

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

• Сервер работает по MCP только через stdio — никакого HTTP-сервера нет, и запускать больше ничего не нужно.

Подключение ИИ-агента

Примеры конфигурации для двух клиентов находятся в config/:

• config/claude-code.mcp.json — скопируйте его в .mcp.json проекта или выполните claude mcp add-json с его записью shop-analytics. Предварительно укажите абсолютные пути в полях args/env.

• config/codex.mcp.toml — скопируйте секцию [mcp_servers.shop-analytics] в ~/.codex/config.toml (или в проектный .codex/config.toml) либо используйте команду codex mcp add, описанную в комментарии в начале файла.

Если нужно вручную проверить сервер без привязки к конкретному агенту, используйте универсальный MCP Inspector:

SHOP_DB_PATH=$(pwd)/shop.db npx @modelcontextprotocol/inspector node dist/src/index.js

Инструменты

Сервер предоставляет ровно 8 специализированных инструментов только для чтения — ни один из них не принимает и не выполняет произвольный SQL. Каждый успешный ответ имеет вид { "data": [...], "meta": {...} }; каждая ошибка — простое, безопасное и понятное человеку сообщение (без SQL, путей к файлам и стек-трейсов), помеченное флагом isError: true.

Параметры from/to задаются в формате YYYY-MM-DD и описывают полуоткрытый интервал UTC [from, to); from должен быть строго раньше to. Все финансовые и счётные метрики исключают заказы со статусом cancelled. Полные контракты инструментов (точные формы ответов и правила разрешения равенств) — в SPEC.md §4.

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

Три независимых уровня защиты (defense-in-depth) гарантируют, что база данных никогда не будет изменена, даже злонамеренным запросом вида «Удалить все отменённые заказы»:

1. Подключение к SQLite открывается с параметром readOnly: true.

2. Сразу после открытия устанавливается PRAGMA query_only = ON.

3. Авторизатор SQLite (authorizer) явно запрещает любые операции записи и DDL (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, ATTACH, DETACH, транзакции и т.д.).

Кроме того, ни один инструмент не принимает ни сырой SQL, ни имена таблиц, ни имена столбцов — каждый запрос является фиксированным подготовленным оператором, а каждое входное значение проверяется через zod и передаётся как связанный параметр, но никогда не подставляется в строку.

База данных

shop.db создаётся из database/schema.sql с помощью детерминированного seed-скрипта — повторный запуск каждый раз даёт байт-в-байт идентичные данные (фиксированный seed генератора случайных чисел, отсутствие зависимости от времени стенных часов):

npm run seed   # builds, then (re)writes ./shop.db from schema.sql + the seed script

На этапе генерации seed-скрипт также проверяет, что в данных нет неоднозначных лидербордов (например, уникальная страна-лидер или уникальный лидер по тратам) и что выручка за 2025 год не равна нулю — см. SPEC.md §3.

Разработка

npm run build           # tsc + copy database/schema.sql into dist/
npm run test:unit        # business logic, in isolation, against fixture databases
npm run test:integration # spawns the built server over stdio via the MCP SDK client
npm test                 # both

Этот проект создавался по методологии TDD: для каждого модуля сначала писался падающий тест, затем — реализация, инструмент за инструментом. Интеграционный набор покрывает все 8 приёмочных сценариев насквозь (end-to-end), тестовые входные данные, имитирующие SQL-инъекции, некорректные комбинации параметров, а также проверяет, что SHA-256-хэш файла базы данных не изменяется после каждого прогона.

Структура проекта

database/       schema.sql + the deterministic seed generator
src/
  db.ts          read-only SQLite connection (see Safety above)
  errors.ts      error taxonomy, safe error formatting
  validation.ts  zod schemas shared across tools (dates, limits, periods)
  period.ts      half-open period SQL clause builder
  tools/         one module per tool: pure query function + types
  server.ts      registers all 8 tools on the MCP server
  index.ts       stdio entrypoint
test/
  unit/          one file per module/tool, fixture-based
  integration/   spawns dist/src/index.js over stdio via the MCP SDK client
config/         example client configuration (Claude Code, Codex CLI)