MCP 服务器

shop-db

This MCP server lets an AI agent securely connect to a read-only SQLite store database, inspect its tables and schema, and run analytical SQL queries without modifying any data.

README

MCP-сервер для базы интернет-магазина (read-only)

MCP-сервер на Python (mcp SDK), который даёт AI-агенту безопасный доступ к SQLite-базе shop.db. Работает по stdio, сам подключается к базе, не изменяет данные.

Возможности

list_tables — список таблиц и количество строк.
describe_table — схема таблицы: столбцы, типы, ключи, внешние ключи.
query_database — read-only SQL (SELECT/WITH/VALUES/EXPLAIN) с агрегациями, JOIN'ами, пагинацией и лимитом строк.

Безопасность (read-only)

Тройная защита от изменения базы:

Соединение открывается в режиме mode=ro — сам SQLite физически не даёт записать данные.
Дополнительно включён PRAGMA query_only = ON.
Валидация запроса: запрещены INSERT/UPDATE/DELETE/DROP/ALTER/CREATE и другие destructive-операции, запрещены несколько операторов за один вызов.

Запрос «Delete all cancelled orders» будет отклонён с понятной ошибкой, база не изменится.

Установка

cd /path/to/project
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Настройка

По умолчанию сервер ищет shop.db рядом с mcp_server.py. Если база лежит в другом месте — задайте путь через переменную окружения:

export SHOP_DB_PATH=/absolute/path/to/shop.db

Запуск

python mcp_server.py

Сервер общается через stdio, поэтому запускается не вручную, а как дочерний процесс агента (см. ниже). Проверить, что всё поднялось, можно так:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}\n' | python mcp_server.py

Подключение к AI-агенту (Claude Code)

Добавьте сервер в конфигурацию MCP. Пример для ~/.claude.json или .mcp.json проекта (см. mcp_config.json.example):

{
  "mcpServers": {
    "shop-db": {
      "command": "/path/to/project/.venv/bin/python",
      "args": ["/path/to/project/mcp_server.py"],
      "env": {
        "SHOP_DB_PATH": "/path/to/project/shop.db"
      }
    }
  }
}

В Claude Code: /mcp → подтвердите, что сервер shop-db подключён. После этого агент сможет отвечать на аналитические вопросы по данным магазина.

Тесты

source .venv/bin/activate
python -m pytest tests/ -q

Структура

mcp_server.py            # сам MCP-сервер
shop.db                  # база данных (read-only)
requirements.txt         # зависимости
mcp_config.json.example  # пример подключения к агенту
tests/test_server.py     # автотесты