Self-Documenting Zero-Knowledge MCP Server

Сервер Model Context Protocol (MCP), который автономно сканирует недокументированную устаревшую базу данных, генерирует CRUD-инструменты для каждой таблицы, создаёт промпты, объясняющие, как соединять таблицы, и обеспечивает Zero-Knowledge безопасность, ограничивая LLM только предварительно проверенными SQL-шаблонами.

Архитектура

Related MCP server: sqlite-mcp

Зачем MCP — и в чём настоящая инженерная работа

MCP (Model Context Protocol) — это транспортный и интерфейсный слой здесь: он отвечает за то, как LLM вызывает инструменты, передаёт параметры и получает результаты. Это осознанный выбор, а не достижение.

Собственно инженерная работа в этом проекте — это конвейер самоанализа схемы и безопасности, который лежит в основе:

Database → PRAGMA Introspection → Schema Registry → Template Engine → Security Validator → MCP Tools

Каждый этап ничего не знает о следующем. Интроспектор ничего не знает об MCP. Шаблонный движок ничего не знает о безопасности. Генератор CRUD ничего не знает о SQL — он работает только с идентификаторами шаблонов. Такое строгое разделение означает, что вы можете заменить MCP-транспорт на REST API или gRPC-сервис, не трогая ни одной строки в слое безопасности.

MCP был выбран вместо прямого вызова функций OpenAI, потому что MCP не зависит от транспорта (stdio для локального использования, SSE для сети), поддерживает ресурсы и промпты помимо простых вызовов инструментов и является открытым стандартом, который принимается в экосистеме LLM-инструментов. Но слой безопасности — предварительно проверенные шаблоны, многоуровневая санитизация, неизменяемый реестр шаблонов — работает одинаково независимо от того, какой протокол находится перед ним.

Возможности

• Автономное обнаружение схемы — сканирует любую базу данных SQLite с помощью PRAGMA-интроспекции без каких-либо предварительных знаний

• Динамические CRUD-инструменты — автоматически генерирует инструменты Create, Read, Update, Delete, List и Search для каждой обнаруженной таблицы

• Промпты для соединений — анализирует связи внешних ключей и генерирует промпты, объясняющие, как соединять таблицы

• Zero-Knowledge безопасность — всё выполнение SQL ограничено предварительно проверенными параметризованными шаблонами

• Журнал аудита — каждая операция с базой данных логируется с отметкой времени, идентификатором шаблона и параметрами

• Ресурсы схемы — ресурсы MCP предоставляют обнаруженную схему для использования LLM

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

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

• Python 3.10+

• pip

Установка

# Clone the repository
git clone https://github.com/shubhtiwari65/Self-Documenting-Zero-Knowledge-MCP-Server.git
cd "MCP SERVER"

# Install dependencies
pip install -r requirements.txt

# Or install in editable mode with dev tools (recommended)
pip install -e ".[dev]"

Заполнение демонстрационной базы данных

# Create a sample e-commerce legacy database
python server.py --seed

Это создаёт legacy_store.db с 6 таблицами: categories, customers, orders, order_items, products, reviews — с внешними ключами и демонстрационными данными.

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

# Run with stdio transport (default — for Claude Desktop)
python server.py

# Run with SSE transport (for network access)
python server.py --transport sse --port 8080

# Use a custom database
python server.py --db /path/to/your/database.db

Подключение к Claude Desktop

Добавьте в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "zk-database": {
      "command": "python",
      "args": ["C:/path/to/MCP SERVER/server.py", "--db", "C:/path/to/legacy_store.db"]
    }
  }
}

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

mcp dev server.py

Что генерируется

При запуске сервер выполняет интроспекцию базы данных и автоматически генерирует:

Инструменты (для каждой таблицы)

Промпты

Ресурсы

Модель безопасности

Модель безопасности Zero-Knowledge гарантирует, что LLM никогда не создаёт и не видит необработанный SQL:

1. Выполнение только по шаблонам — может выполняться только SQL из предварительно сгенерированного реестра шаблонов. Конечной точки с необработанным SQL не существует.

2. Проверка параметров — все параметры проверяются на соответствие типам по обнаруженной схеме перед выполнением.

3. Санитизация входных данных — многоуровневый блок-лист перехватывает паттерны SQL-инъекций в значениях параметров (хотя параметризованные запросы уже предотвращают инъекции).

4. Журнал аудита — каждая операция логируется с отметкой времени, идентификатором шаблона, параметрами и статусом успеха/неудачи.

5. Нет манипуляций со схемой — только SELECT, INSERT, UPDATE, DELETE по существующим таблицам. Операции DDL невозможны.

Полную модель безопасности, включая известные границы области действия (аутентификация на транспортном уровне), см. в SECURITY.md.

Почему SQLite — и что меняется при масштабировании

SQLite был выбран осознанно для этой демонстрации по трём причинам:

1. Нулевая конфигурация — не нужен отдельный сервер, учётные данные или сетевая настройка; база данных — это один файл

2. Встроенная PRAGMA-интроспекция — PRAGMA table_info(), PRAGMA foreign_key_list() — это именно те инструменты, на которых основано zero-knowledge обнаружение

3. Только стандартная библиотека — нет зависимости от ORM; import sqlite3 входит в состав Python

Что изменится в продакшене:

Архитектура не зависит от базы данных по замыслу — только src/introspector.py содержит код, специфичный для SQLite (~80 строк). Замена базовой базы данных означает замену этого единственного файла; слой безопасности, генератор CRUD и регистрация MCP остаются нетронутыми.

Все записи об архитектурных решениях см. в docs/DECISIONS.md.

Запуск тестов

# Run all tests
python -m pytest

# Run with coverage report
python -m pytest --cov=src --cov-report=term-missing

# Run specific test files
python -m pytest tests/test_security.py -v
python -m pytest tests/test_introspector.py -v

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

MCP SERVER/
├── .github/workflows/ci.yml    # CI pipeline (pytest + ruff + coverage)
├── .gitignore                  # Git ignore rules
├── .env.example                # Environment variable template
├── CHANGELOG.md                # Version history
├── CONTRIBUTING.md             # Dev setup and contribution guide
├── Makefile                    # Developer convenience commands
├── README.md                   # Project documentation
├── SECURITY.md                 # Security model + transport scope boundary
├── server.py                   # Main MCP server entry point
├── requirements.txt            # Python dependencies
├── pyproject.toml              # Project metadata, ruff + pytest + coverage config
├── src/
│   ├── __init__.py
│   ├── introspector.py         # PRAGMA-based schema discovery
│   ├── schema_registry.py      # In-memory schema registry
│   ├── sql_templates.py        # Pre-validated SQL template engine
│   ├── security.py             # Zero-Knowledge security validator
│   ├── crud_generator.py       # Dynamic MCP tool generator
│   └── join_analyzer.py        # FK analysis & prompt generator
├── sample_data/
│   └── seed_legacy_db.py       # Demo legacy database seeder
├── tests/
│   ├── conftest.py             # Shared pytest fixtures
│   ├── demo_client.py          # Standalone verification demo
│   ├── test_introspector.py    # Schema discovery tests
│   ├── test_crud.py            # CRUD operation tests
│   ├── test_security.py        # Security validation tests
│   └── test_joins.py           # Join analysis tests
└── docs/
    ├── APPROACH.md             # Full technical approach write-up
    ├── DECISIONS.md            # Architectural Decision Records (ADRs)
    └── MCP_architecture.png    # Architecture diagram

Лицензия

MIT