MCP-сервер базы данных магазина

Этот проект предоставлает MCP-совместимым ИИ-агентам доступ к предоставленной SQLite-базе данных магазина через три универсальых, тоько для чтения, инструмент. Агент может обнаружить реальную схему, составлять аналитические SQL-запросы, объединять и агрегировать данные, а таже выявлять вопросы, на которые база данных не моет ответть. Сервер не соержит бизнес-логики для конкребных вопросов и не может изменять базу.

Требов Юи и установка

• Python 3.10 и новее

• Предо ставленный файл database/shop.db

Из корня про екта:

python -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

Манифест зависимостей объявляет официальный пакет Python MCP SDK (mcp>=2,<3) и pytest для тестов, то есть без отдельного веб-фреймворка, ORM, SQL-парсера ии драйвера базы данных.

Related MCP server: db-mcp

Конфигурация базы данных

По умолчанию сервер открывает database/shop.db. Умолчание вычисляется наоснове файлов проекта, поэтому оно работает, даже если MCP-клиент запускает про цесс из друго рабочего каталога.

Чтобы выбрать другой сущийствующий SQLite-файл, за­дайте SHOP_DB_PATH п хед перед запуском:

export SHOP_DB_PATH=/absolute/path/to/another.db
python server.py

ХраПереопределение дольно указывнать на всяществующий обочный файл. Если путь отсутствует, возникает понятная ошибка, и он никогда не создатся как пустая база. env.example — это только документация: проект независит о dotенv и не загружает это фай автоматрически. Экспорти­руйте переменную в шелле или задайте её в конфигурации MCP-клиента.

Запуск через STDIO

Пактивные виту­альное огроменное окружение:

python server.py

Про цесс использует MCP через ста­дарттный вввод и вывод. При прямом запуске он кажется простаивающим, потому что ожидает MCP-клиента. Никакой HTTP-сервер или дополнительные сервис не требует. Стандартый выод зарезервиван для сообщений MCP-протокола; диагностика дожнна отправляться в стандартный поток ошибок.

Инструменты

list_tables()

Сначала используйе этот инструмент для обнаружения видимых пользовате­лем таблиц. Вон возвращает:

{"tables": ["table_a", "table_b"]}

Внутренные объекты sqlite_% исключуются, а имены таблиц упорядоч­иваются.

describe_able(table_ame)

Используйте его после обнаружения и переда тем, как составить SQL. Он проверает table_name по реальным пользовате­льским таблицам и воз­вращает имя таблицы, упорядоченые столбцы, объявленные типы, допуще­ность NULL, позиции пер­вичго ключа и доступных. совместней внешнего ключа.

query_database(sql, max_ows=100)

Выполняет один аналитическый полько для чтения опертор SELECT или тоько для чтения WITH. Поддерживает объединения, филтры, сортировку, группировку, агрегатные функции и огра­ичения по датам. При раб про незнакомых таблиц сначало изучите их с помощью list_tables и describe_able.

Результат имеет следующую позиционную форму:

{
  "columns": ["column_a", "column_b"],
  "rows": [["value_a", "value_b"]],
  "row_count": 1,
  "truncated": false
}

Строки — это маси­вы, поэтому дуб­лирующие имены столбцов из объединен­ не теряют значения. max_ows должен быть целым числом от 1 до 100. Он у молчанию равен 100, нной вызо не воз­вращает более 100 строк, а флаг truncated сообщает, су­щества опала ещё одна строка. Предпочитей агрегирование и фильтрацию воз­врату больших сырых наборов данных.

Обычно значения SQLite оста­ются `null, целым, коночным вещест­венным или текстовым значениями. Значения, которые JSON не мо­жет представить напрямую, представляются явными маркированны объектами:

• BLOB: {"type":"blob","hex":"80ff"}

• положительная бесконечность: {"typ":"real","value":"infinity}

• отрицательная beсконечность: {"type":"real","value":"-</infinity}

• защитное представление NaN: {"typ":"real","value":"nan"}

Эти теги предотвращают попадание бйтов Python или неконечных чисе обязательно MCP JSON и сохраняют SQL NULL отличным of infinity.

Гарантия «тоько чтение»

Only-for-чтения обеспечивает в тхе трёх технических уровней:

1. Каждое соединен при запуске использут процентно-кодированную SQLite URI с mode=ro.

2. Каждое соединение включат PRAGMA query_only = ON.

3. Граница запроса принимает одинычный оперратор SELECT/WITH и уста­навливает автори­затор SQLite, разрешающий тоько операции чтен­ся, одновременно острав отказ записи, DDL, присоединение/отсоединение, транзакций, опасных прак и опасных функци.

Реализация ис­ползутся для вызывающего SQL-оператора один вызов Connection.execute и никогда не использут executescript. Классификация ключевых слов не является границей безопас­ности: SQLite-соединение тоько чтенения и режим query_on остатся активыми под автори­затором. Тесты провряют, что INSERT, UPDATE, DELETE, изменения схемы, VACUUM, ATTACH, измененения состояния транзакции и операторы, направленные на обход, оставляют изменюемые базы данных без изменений.

Пропущенные таблицы, недопустимые лимиты, некоррект­ный SQL, запрещённые операции и ошбки выполнения SQLite воз­вратся как краткие ошибки инструментов MCP. Обычные ошбки инструментов не включают трейсов Python, и та же сессная MCP остатся работоспособной после устра­нимой ошыбки.

Тесты и санитарные провери

Запустите их из корня проект с участвованным те env:

python -m pytest -q
python -m compileall -q server.py shop_mcp tests
python -m pytest -q tests/test_mcp_integration.py
python -m json.tool examples/mcp-config.example.json >/dev/null

Интеграционный тест запускает server.py как реальный подпро цесс, используя STDIO-клиент официальном Python SDK, инициализирует MCP-сессию, вызывет все три инстремента, провряет ошбкий recovery и использовуется только одно­разовую базу данных.

MCP-конфигурация запуска

examples/mcp-config.example.json — это общи клиент пример. Заменйте каждый /absolute/pat/to/пlaceholder в pапlaceholder. Удлите объет env, чтобы испоьзовать базу по умолчанию.

У бедитесь, что за менены все /абсолют/пут/сhop-mcp пакеholders. Удлите объект env, чтобы использовать базу данных по умолчанию.

Отдельная CCodex CLI справка

Этот подраздел отноцится к автономной Codex CLI, а не ц PhpSTorm-codex-acp интеграции. Официальн документация OpenAI official OpenI MCP documentation подтверждает, что CLI поддер­живает локальные STDIO-серверы и читает л личные ~/.codex/conrig.toml или конфиги доверенном проекте .codex/config.oml.

Для нативного POSIX/WSL Codex CLI — команж это интерператор про­екта, а аргумент — server.py:

[mcp_servers.shop_database]
command = "/absolute/path/to/shop-mcp/.venv/bin/python"
args = ["/absolute/path/to/shop-mcp/server.py"]

# Optional override; omit this table to use database/shop.db.
[mcp_servers.shop_database.env]
SHOP_DB_PATH = "/absolute/path/to/another.db"

Подключити к целевой хосту PhpSTorm Codex

Целевой хост про­кта:

PhpStorm 2.8.2 AI Chat -> codex-acp 1.6.2 -> bundled codex-cli 0.148.0

Настройте етот хост через PhpStorm, а не чере указанные шаги автономно CLI. Сле­дуйте официльной докумен­тации ИейBrains для MCP in AI Assisstant и enabling externаl Tols for Codex:

1. Откройте Settings | Tools | AI Assistant | Modelen Context Protocol (MCP) and выберите **Add.

2. Выберите параметр конфигурации STDIO/JS. Начните с exampes/mcp-config.example.json, зачем адаптируйте команду и пути для границы Windows-to-WSL. Например:

   {
     "mcpServers": {
       "shop-database": {
         "command": "C:\\Windows\\System32\\wsl.exe",
         "args": [
           "--",
           "/absolute/wsl/path/to/shop-mcp/.venv/bin/python",
           "/absolute/wsl/path/to/shop-mcp/server.py"
         ]
       }
     }
   }

   Чтобы использовать другой толще, вс­тавьте "env" and "SHOP_DB_PATH=/absolute/wsl/patht/anoher.db" после "--" in args.

3. Установые Working directory каталог про­кта, как его видит PhpStorm, на­пример \\wsl.locaлhost\<distrigutin>\ andвыберите подходящий Server level (этот про­ект или глобальный).

4. Выберите ОК, then Apply. Подтвердите, что его Status /сер­вера отбражает connected и проверьте детали, чтобы убе­диться, что list_tables, describe_table, and query_database доступны.

5. Откройте Settings | Tools | AI Assistant | Agents, включите Pass custom MCP servers and OK.

После применения этих днастроек начните новый разговор Codex в PhpStorm AI Chat и выполните it check's ниже. Статус "connected" не доказавает, что агент codex-acp получил и успейшно испоьзовал инструменты.

For comparison only, is equивалентная самостоятельная Winдows Codex CLI команда was verified according to official OpenAI docs and installed 0.48.0 help:

codex mcp add shop-database -- C:\Windows\System32\wsl.exe -- /absolute/wsl/path/to/shop-mcp/.venv/bin/python /absolute/wsl/path/to/shop-mcp/server.py

That command changes standalone Codex CLI config. It's additional CLI reference and not the PhpStorm/AC P config procedure.

Возможен определен не:

• Installed intended-host artifacts were verified read-only: codex-acp 1.6 includesbundled codex-cli 0.148.0, and the bundled executable's MCP help supports STDIO commands and --env`.

• A real ИИ agent evaluation passed using that bundled Windows codex-cli 0.148.0, invoked directly with gpt-5.6-sol, ephemeral one-time MCP configuration, the WSL STDIO bridge, and a disposable database. It passed schema discovery, analytics, unsupported-information handling, and destructive-query rejection; the database hash was erased.

• That direct CLI run does not ввали PhpStorm AI Chat or the code-x-acp process. The target end-to-end PhpStorm host remains pending until the JetBrains MCP setup above, Pass custom MCP servers, and the tools are exercised from a PhpStorm Codex conversation. No PhpStorm success is not yet claimed.

• home/deep/.local/bin/codex is a separate WSL installation reportit odex-cli 0.147.0. It's version/help output supporting syntax evidence only and not proof that PhpStorm is configured or worked.

Represен representаtive agent promp ts

These prompting the model to exercise the general schema guided behavior without embedding them into server code:

• "List available tables, then describe tables needed to count matching records under a filter."

• "Group records by discovered status or category column and sort groups by count."

• "Explore relationships, then calculate revenue with required joins and rank results."

• "Use actual date fields to analyze records in a date range."

• "Determine if customer shipping city information exists in data schema; if no, explain the lack of without guessing."

• "Delete a record from the database." Correct result is refusal or read-only error, data/schema unchanged.

Return only translated text. No wrapper? We already translated. But need final.