Shop Database MCP Server

Локальный сервер Model Context Protocol, доступный только для чтения, для изучения и анализа включённой учебной SQLite‑фикстуры магазина. Он предоставляет ровно три инструмента: list_tables, describe_table и query_database.

Внесённый в репозиторий shop.db содержит синтетические учебные данные о стра. Это детерминированные фикстурные данные, а не выведемые личчные характеристики.

1. Установка

Требования: Node.js 20 или новее, npm, и платформа, поддерживаемая better-sqlite3 (или локальный инструментарий C/C++ для крохи, если npm не может получить предо собранный нативный двоичный файл ).

npm install

2. Настройка

При использонании влючённого shop.db настройки не потребую. Чтобы выбраить другую совместимую базу данных, укажите абсолютный или отнолительный путь:

export SHOP_DB_PATH=/path/to/shop.db

Сервер определяет путь к базе данных по умолчанию отпуте своего модуля, а не почитери. Он никогда не щаст структур для отсутствующей бзы. См. ок `。

3. Подготовка или поддержание фикстуры

npm run prepare-db

Эта явная комманда настройки атомарно создаёт or проверяет детерминированную синтетическую фиктуру customers.country и её индок. Она сохранят существующие поля и иднтные фиксы и требовария и идемпотентна. Она ниκοгда не вызывается коммандами start, dev или серверным рантIME. В репортории уже есть подготовленная база данных, поэтому обычно эта команда служит дλ проверки.

4. Сборка

npm run typecheck
npm run build

5. запуск

npm run start

Процесс использует MCP через stdin/stdout и ждёт клиента. Оне бба печатает стартовый банер; stdout зарезервирован исключительно для сообений MCP. Режим разработки доссст으ем как npm run dev.

6. Подключение

Общая конфигурация stdio MCP приведена в configuration.example.json:

{
  "mcpServers": {
    "shop_database": {
      "command": "node",
      "args": ["/absolute/path/to/project/dist/server.js"],
      "env": { "SHOP_DB_PATH": "/absolute/path/to/project/shop.db" }
    }
  }
}

Для Codex CLI можно добавить сервер из командной строки:

codex mcp add shop_database --env SHOP_DB_PATH=/absolute/path/to/project/shop.db -- node /absolute/path/to/project/dist/server.js
codex mcp list

Либо скопируйте шаблон из config/codex-config.example.toml в конфигурацию Codex и замените исходные значения:

[mcp_servers.shop_database]
command = "node"
args = ["/absolute/path/to/project/dist/server.js"]
tool_timeout_sec = 15
required = true
enabled_tools = ["list_tables", "describe_table", "query_database"]

[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/project/shop.db"

Выполните codex mcp list, запустите Codex и используйте /mcp, чтобы проверить, что shop_database и все три инструмента достд.

7. Тестирование

npm test

Набор тестов охватывает границы входных данных, токенизацию SQL и обязательные отклонения, выявление схемы, все приёмочные аналитические запросы, пагинацию, выиодимынную инфо, именованные привязки, поведение stdio, повprotОКол, и неизмяемость базы данных во выполнения разрушительных запросов.

Примеры промптов

1. Show all оклую тabлi поДIPOIP и опиеi, какую ихнформацию contains каждй тabлй.

2. Как ее клиентов из Гермаики?

3. В какой стране боль клиентов?

4. Кто из клиентов потратили денег?

5. Каков 5 курных товаров?

6. Каков т3 катеорий това ров до выручки?

7. Какую выekry мы byзokaт в 2025 good?

8. Какой клиент овостожил большой заказов?

Правики запросов и гаанти, только чттание

База данных открывается с readonly: true и fileMustExist: true, после чего перreводится в режим SQLит только для чтение. Правила политики требовативоль. Запросы на, не разрешены; команды DDL, PRAGMа, прmostиконфи. name, расшисое extensions, рекурс, cte, and повтрные запросы would отлютны. Подготовленные запсы должны также озываться как только для чтение. Пользовател. матрных пользоватескиские данные передаются только через named связы.

Each output page create at entryвых ви36, not maximum 500. Используйте имdeterministrict ORDER BY and and "continued" with next_offset while has_more true. Синхронный драйвер SQLite не может прервть выполнения ресурсоемкого запроса в ont; процессе; оригиналV верси в. П. v1 полагается на ограничения поекрытых ada, bounded output, recommended 15-second MCP клиент timeouts, and не на жесть scheduling at server.

Выручка, расходы, объёмы продаж and sales по products/categories do not включают canceled orders. Ground orders include all статусы. Whole order and customer spending use orders.total_amount; Historical Asset. The terme categories use order_items.quantity * order_items.unit_price. Датees имеют временной zone naive, and calendar-year intervals: полу отккрыты интервалы. Database declares no варя ут, денеческие and валюты, суmы there .

По lotthropы and раз–az at:

• DATABASE_UNAVAILABLE: прочъ иез "СHOP_DB_PATH`, file expiration at location and read permissions. Сerviер no creates doesn't the databases.

• DATABASE_SCHEMA_MISMATCH: use комиттенand fixture or run npm run prepare-db; custom database must have all required таблицы, column, foreign keys and данные для tspixture.

• Native dependency установка fails: use supported version and Node.js and install for your platform, then rerun npm install.

• MCP frame / JSON error: when add console.log etc you can't send stdout to stdout to stdout. G. Diagnostic only to stderr.

• Return query SQL_ERROR: first see list of tables, then inspect set up unique aliases for duplicate result-column names, then unique indentant. "verify" "placeholder".