MCP SQLite Server (только чтение)

Готовый к продакшену сервер Model Context Protocol, который предоставляет ИИ-агентам безопасный доступ только для чтения к базе данных SQLite (shop.db). Создан с использованием официального Python SDK mcp с транспортом stdio.

Возможности

• 3 инструмента MCP: list_tables, describe_table, query_database

• Многоуровневая защита только для чтения: режим только для чтения в URI SQLite + PRAGMA query_only + валидатор SQL + проверка кодов операций EXPLAIN

• Проверка запросов: отклоняет INSERT/UPDATE/DELETE/DROP/ALTER/CREATE/REPLACE/TRUNCATE/ATTACH/DETACH, многооператорные запросы (;), комментарии SQL (--, /* */) и изменяющие PRAGMA — без ложных срабатываний на строковых литералах

• Пагинация: лимит строк по умолчанию (100), параметры limit/offset, флаг усечённого вывода

• Логирование только в stderr: все логи и трассировки идут в sys.stderr; stdout зарезервирован исключительно для JSON-RPC

• Полные аннотации типов: mypy --strict без ошибок

• TDD: 105 тестов, покрывающих безопасность, слой БД, инструменты MCP, 8 эталонных запросов и защиту stderr

Related MCP server: sqlite-mcp-server

Быстрый старт

Предварительные требования

• Python 3.10+

• Файл базы данных SQLite (по умолчанию: ./shop.db)

Локальная настройка

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Конфигурация

Скопируйте .env.example и укажите путь к базе данных:

cp .env.example .env
# Edit DATABASE_PATH to point to your SQLite file

Или задайте переменную окружения напрямую:

export DATABASE_PATH=/abs/path/to/shop.db

Запуск сервера

python -m mcp_server.server

Сервер обменивается данными через stdin/stdout с использованием транспорта stdio MCP. Вы не взаимодействуете с ним напрямую — клиент MCP (например, Claude Desktop, ваш ИИ-агент) подключается к нему.

Конфигурации клиента MCP

Стандартный Python

Добавьте это в конфигурацию вашего клиента MCP (например, claude_desktop_config.json у Claude Desktop):

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "env": {
        "DATABASE_PATH": "/abs/path/to/shop.db"
      }
    }
  }
}

Docker

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

docker build -t mcp-shop:latest .

Затем настройте ваш клиент MCP:

{
  "mcpServers": {
    "sqlite-shop": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/abs/path/to/shop.db:/app/shop.db",
        "-e", "DATABASE_PATH=/app/shop.db",
        "mcp-shop:latest"
      ]
    }
  }
}

Docker Compose

docker compose up -d

Инструменты

list_tables

Выводит список всех пользовательских таблиц и представлений в базе данных (исключая внутренние таблицы sqlite_*).

Параметры: нет

Возвращает:

{
  "tables": ["customers", "orders", "order_items", "products"],
  "count": 4
}

describe_table

Описывает схему таблицы: столбцы, внешние ключи, количество строк и оператор CREATE.

Параметры:

• table (строка, обязательный): имя таблицы для описания.

Возвращает:

{
  "table": "customers",
  "columns": [
    {"cid": 0, "name": "id", "type": "INTEGER", "notnull": 0, "default": null, "pk": 1},
    {"cid": 1, "name": "first_name", "type": "TEXT", "notnull": 1, "default": null, "pk": 0}
  ],
  "foreign_keys": [],
  "row_count": 150,
  "sql": "CREATE TABLE customers (...)"
}

query_database

Выполняет SQL-запрос только для чтения с поддержкой пагинации.

Параметры:

• sql (строка, обязательный): один оператор SQL только для чтения (SELECT, WITH, EXPLAIN или PRAGMA только для чтения).

• limit (целое, необязательный): максимальное количество возвращаемых строк. По умолчанию: 100. Максимум: 1000.

• offset (целое, необязательный): количество пропускаемых строк. По умолчанию: 0.

Возвращает:

{
  "columns": ["id", "first_name"],
  "rows": [{"id": 1, "first_name": "Alice"}, {"id": 2, "first_name": "Bob"}],
  "row_count": 2,
  "truncated": false,
  "limit": 100,
  "offset": 0
}

Когда truncated равен true, доступно больше строк — увеличьте offset, чтобы получить следующую страницу.

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

Сервер реализует многоуровневую защиту для гарантии доступа только для чтения:

Уровень 1: Подключение SQLite (режим только для чтения в URI)

База данных открывается с file:<path>?mode=ro, что предотвращает запись на уровне движка SQLite. Дополнительно на каждом подключении устанавливается PRAGMA query_only = ON.

Уровень 2: Валидатор SQL-запросов (security.py)

Прежде чем любой запрос достигнет SQLite, он проходит через многоступенчатый валидатор:

1. Удаление строковых литералов: строковые литералы ('...', "...") заменяются заполнителями, чтобы ключевые слова внутри данных (например, продукт с названием "Deleted Item") не вызывали ложных срабатываний.

2. Обнаружение комментариев: комментарии SQL (--, /* */) отклоняются для предотвращения обхода через комментарии.

3. Отклонение многооператорных запросов: любой символ точки с запятой (;) отклоняется, предотвращая составные запросы.

4. Анализ ключевых слов: первое реальное ключевое слово оператора должно быть SELECT, WITH, EXPLAIN или PRAGMA. Деструктивные ключевые слова (INSERT, UPDATE, DELETE, DROP, ALTER, CREATE, REPLACE, TRUNCATE, ATTACH, DETACH, VACUUM и т.д.) блокируются.

5. Проверка PRAGMA: разрешены только PRAGMA для чтения (table_info, database_list и т.д.). Любая PRAGMA с присваиванием (=) или входящая в блок-список изменяющих PRAGMA (journal_mode, synchronous, foreign_keys и т.д.) отклоняется.

Уровень 3: Проверка кодов операций EXPLAIN

В качестве последней защиты запрос пропускается через собственный парсер SQLite с помощью EXPLAIN <query>. Полученный поток кодов операций проверяется на наличие записывающих кодов (OpenWrite, Insert, Delete, Create, Drop и т.д.) и флагов записывающих транзакций. Если таковые обнаружены, запрос отклоняется.

Уровень 4: Очищенные сообщения об ошибках

Все ошибки, возвращаемые клиенту, очищаются — пути файловой системы и внутренние детали удаляются для предотвращения утечки информации.

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

Тесты используют только временные или in-memory базы данных — никогда не производственную shop.db.

# Run all tests
python -m pytest

# Run with verbose output
python -m pytest -v

# Run a specific test file
python -m pytest tests/test_security.py

Покрытие тестами

Статический анализ

# Type checking
python -m mypy

# Linting
python -m ruff check src/ tests/

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

.
├── .env.example          # Environment variable template
├── Dockerfile            # Docker containerization
├── docker-compose.yml    # Docker Compose config
├── pyproject.toml        # Package config, deps, tool settings
├── README.md             # This file
├── shop.db               # The SQLite database (not included in tests)
├── src/mcp_server/
│   ├── __init__.py
│   ├── config.py         # Configuration (DATABASE_PATH, limits, URI builder)
│   ├── db.py             # Read-only Database class with introspection + query
│   ├── security.py       # SQL validator (multi-layer defense-in-depth)
│   ├── server.py         # MCP server entrypoint (stdio transport)
│   ├── tools.py          # MCP tool definitions and handlers
│   └── py.typed          # PEP 561 marker
└── tests/
    ├── __init__.py
    ├── test_db.py        # Database layer + benchmark tests
    ├── test_security.py  # Query validator tests
    └── test_server.py    # MCP server/tool tests

Эталонные задачи

Инструменты сервера позволяют ИИ-агенту выполнять следующие аналитические задачи (проверены тестами на контролируемой фикстурной базе данных):

1. Обнаружение таблиц: list_tables + describe_table — список всех таблиц и описание схем.

2. Подсчёт с фильтром: query_database с SELECT COUNT(*) FROM customers WHERE country = 'Germany'.

3. Агрегация по странам: SELECT country, COUNT(*) ... GROUP BY country ORDER BY ... DESC LIMIT 1.

4. Пожизненная ценность клиента: объединение customers + orders, SUM(total_amount), сортировка по сумме.

5. Эффективность продуктов: объединение order_items + products, агрегация по количеству и выручке, LIMIT 5.

6. Агрегация по категориям: переход order_items → products → category, агрегация выручки, LIMIT 3.

7. Фильтрация по дате: SUM(total_amount) WHERE substr(order_date,1,4) = '2025'.

8. Агрегация заказов: объединение customers + orders, COUNT(o.id), сортировка по количеству.

Конфигурация

Лицензия

Этот проект предоставляется как есть для демонстрационных целей.