Агент управления данными Sentinel MCP

Sentinel — это небольшой автономный агент управления данными, который проводит аудит базы данных PostgreSQL через протокол Model Context Protocol (MCP). Вместо предоставления LLM прямого доступа к базе данных, проект использует контролируемый мост FastMCP со специализированными инструментами для проверки схемы, профилирования пустых значений и обнаружения аномалий.

Демонстрация заполняет намеренно «грязную» таблицу raw_inventory, запрашивает у агента на базе OpenAI проверку через инструменты MCP и записывает отчет об аудите в формате Markdown в файл LATEST_AUDIT.md.

Что это демонстрирует

• Python-клиент MCP, который следует рабочему процессу в стиле ReAct: Рассуждение (Reason) -> Действие (Act) -> Наблюдение (Observe).

• Сервер FastMCP, выступающий в роли моста управления между агентом и PostgreSQL.

• Инструменты на базе SQLAlchemy для безопасной и структурированной проверки базы данных.

• Проверки качества данных на наличие пропущенных адресов электронной почты, отрицательных значений запасов и дубликатов SKU.

• Сгенерированный отчет о состоянии данных (Data Health Audit) с SQL-запросами для исправления.

Архитектура

flowchart LR
    U[User question] --> A[Python Agent<br/>MCP Client]
    A -->|tools/list and tools/call| M[FastMCP Server<br/>Sentinel-Bridge]
    M -->|SQLAlchemy queries| DB[(PostgreSQL 16<br/>raw_inventory)]
    DB -->|schema and quality metrics| M
    M -->|structured MCP tool results| A
    A -->|OpenAI analysis or local fallback| R[LATEST_AUDIT.md]

Инструменты MCP

inspect_schema() возвращает имена таблиц и определения столбцов для структурного аудита.

get_data_health_sample() возвращает 100 последних строк из raw_inventory для проверки на уровне строк.

check_null_ratios(table_name="raw_inventory") возвращает количество и процент пустых значений для каждого столбца.

find_logical_anomalies() возвращает строки с отрицательными значениями stock_count и дублирующимися группами sku.

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

agent.py              # MCP client and ReAct audit workflow
server.py             # FastMCP server exposing database audit tools
seed_data.py          # Faker-based dirty data generator
docker-compose.yml    # PostgreSQL 16 local database
architecture.md       # Mermaid architecture diagram
.env.example          # Safe environment variable template

Настройка

Требования:

• Windows 11, macOS или Linux

• Docker Desktop

• Python, управляемый с помощью uv

• API-ключ OpenAI с доступной квотой API

Создайте файл локальной среды:

Copy-Item .env.example .env

Отредактируйте .env и замените значения-заполнители. Не добавляйте .env в систему контроля версий.

Установите зависимости:

uv sync

Запустите PostgreSQL:

docker compose up -d

Заполните таблицу «грязными» данными инвентаризации:

uv run python seed_data.py

Запустите сервер MCP напрямую:

uv run python server.py

В другом терминале запустите автономного агента аудита:

uv run python agent.py

Агент записывает свой отчет в:

LATEST_AUDIT.md

Проверка заполненных данных

docker exec -it sentinel_postgres psql -U sentinel_user -d sentinel_db -c "SELECT COUNT(*) AS negative_stock_rows FROM raw_inventory WHERE stock_count < 0;"

Ожидаемый результат после заполнения:

30

Примечания по безопасности

• .env игнорируется Git и никогда не должен попадать в репозиторий.

• .env.example содержит только заполнители.

• LLM не получает прямые учетные данные базы данных; она взаимодействует с утвержденными инструментами MCP.

• Сервер MCP является границей политики, где возможности базы данных раскрываются явно.

• Ротируйте любой API-ключ, который появился в логах, скриншотах, выводе терминала или чате.

Почему MCP, а не прямой SQLAlchemy в агенте?

MCP предоставляет LLM ограниченный интерфейс инструментов вместо неограниченного доступа к базе данных. Сервер FastMCP определяет разрешенные действия, делая границу управления явной и проверяемой. Тот же агент позже сможет взаимодействовать с каталогами, движками политик, хранилищами и системами наблюдаемости через MCP без необходимости переписывать агента под прямые подключения к базе данных.