MCP Data Analysis Agent

Локально-ориентированная, управляемая аналитика для MCP-клиентов поверх SQLite и PostgreSQL.

mcp-data-analysis-agent предоставляет MCP-клиенту небольшой, проверяемый слой доступа к данным вместо прямого доступа к базе данных. Он проверяет SQL перед выполнением, использует соединения только для чтения, ограничивает результаты и время выполнения, записывает записи наблюдаемости с подтверждениями и хранит учётные данные на машине оператора.

Зачем это существует

MCP-клиенты могут рассуждать о данных, но им не следует выдавать неограниченные учётные данные базы данных или позволять незаметно выполнять произвольные операторы. Этот проект предоставляет локальную контрольную точку для этой границы:

• Храните пути к базам данных, URL-адреса, пароли и токены в игнорируемом файле .env.

• Разрешайте только один параметризованный оператор SELECT или WITH.

• Блокируйте мутации, DDL, команды, вложения, многооператорные запросы, небезопасные функции, ограниченные поля и небезопасные пути к артефактам.

• Требуйте доступ только для чтения на уровне базы данных в дополнение к политике приложения.

• Сохраняйте нормализованный SQL, время выполнения, привязку к задачам, подтверждения, хэши и временные шкалы событий для последующего аудита.

Сервер использует только stdio. Он не размещает публичный API, не загружает исходные данные, не хранит удалённые учётные данные и не создаёт пользователей производственной базы данных.

Related MCP server: sql-explorer-mcp

Возможности

• Доступ к SQLite и PostgreSQL через SQLAlchemy Core с проверкой политики SQLGlot.

• Обнаружение источников, схем, связей, профилей, качества/свежести и дрейфа схем.

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

• Классификации для публичных, внутренних, конфиденциальных и ограниченных полей/источников.

• Одобренные семантические метрики, Git-нативные рецепты, сравнение периодов, обнаружение изменений и рекомендации по диаграммам.

• Офлайн HTML-дашборды, CSV, Parquet, Typst PDF, метаданные подтверждений и безопасные атомарные выходные каталоги.

• Загрузка контекста ClineFlow, журналы задач, неизменяемые записи запросов/выполнений, временные шкалы событий и проверка целостности.

• Детерминированные фикстуры для розничной торговли, SaaS и поддержки, включая локальные фикстуры паритета SQLite-к-PostgreSQL.

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

• Python 3.11 или новее и uv.

• Typst для поддерживаемой установки рендеринга отчётов.

• Инструменты командной строки PostgreSQL, включая createdb для локальных фикстур паритета.

• Работоспособный пакет ClineFlow/OKF в целевом проекте.

Запустите mcp-data-cli preflight, чтобы установить или сообщить о требуемых локальных инструментах через доступный менеджер пакетов на уровне пользователя. Он никогда не связывается с настроенным источником. mcp-data-cli doctor проверяет локальную установку; отсутствие настроенного источника сообщается как configuration_pending, а не как сбой установки.

Установка

Установка этого репозитория в текущий проект

Когда агента или оператора просят установить этот GitHub-репозиторий в проект, используйте установщик репозитория, а не простую команду uv tool install:

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

Установщик устанавливает инструмент командной строки и инициализирует каталог, из которого он был запущен. Он создаёт игнорируемую детерминированную розничную песочницу, записывает единственное приватное значение MCP_DATA_SOURCE_URL в .env, записывает политику источника и объединяет MCP-сервер в каждый обнаруженный поддерживаемый клиент. Он не копирует пакет в проект и никогда не помещает URL-адрес базы данных или учётные данные в конфигурацию клиента. Подсказки о доверии/включении клиента и перезапуске остаются под контролем каждого клиентского приложения.

uv tool install намеренно устанавливает исполняемые файлы на уровне пользователя и не выполняет изменяющие проект пост-установочные хуки. Используйте его только тогда, когда вы хотите установить исполняемый файл отдельно, а затем запустите mcp-data-cli init самостоятельно.

Рабочий процесс, совместимый с PyPI

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

Чтобы установить текущую версию репозитория до выпуска пакета, замените команду установки на:

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

При первом использовании сервера в любом поддерживаемом MCP-клиенте агент создаёт и открывает детерминированную розничную SQLite-песочницу только для разработки в .mcp-data/playground.sqlite. Общий MCP-инструмент welcome объясняет, как её исследовать и как переключиться на реальный источник. init материализует ту же песочницу в явную политику проекта и приватный .env, затем объединяет безопасные записи MCP-клиента после одного подтверждения. Явный установщик репозитория использует init --yes, потому что запуск этого установщика является единственной авторизацией для этих ограниченных записей.

Используйте setup --all для предварительного просмотра конфигурации клиента или setup --all --apply для объединения только записи stdio mcp-data-analysis после одного явного подтверждения. Он сохраняет несвязанные серверы и настройки. Используйте setup --status для проверки обнаружения и текущего состояния конфигурации.

Настройка определяет только MCP-конфигурации. Она не может обойти запрос доверия/включения клиента или запустить/перезапустить IDE. Детали конфигурации VS Code задокументированы VS Code и GitHub Copilot в VS Code; Continue документирует проектные MCP-фрагменты в своём руководстве по MCP.

Загрузка релиза с проверкой контрольной суммы

Для версионированного колеса и его опубликованной SHA-256 контрольной суммы:

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

Загрузчик требует curl и uv, проверяет артефакт с помощью sha256sum или shasum и устанавливает только после совпадения контрольной суммы. Затем он инициализирует текущий проект точно так же, как установщик репозитория. Он не использует sudo и не связывается с производственной базой данных; он создаёт только локальные детерминированные демонстрационные данные.

Настройка одного активного источника

Стандартная установка использует ровно один активный источник с именем data и ровно одно приватное значение в .env: MCP_DATA_SOURCE_URL. Это не константа пакета и не тестовое значение — это единственное значение, которое оператор меняет, чтобы указать на свою собственную базу данных только для чтения. Держите .env в тайне; он игнорируется Git.

При первом использовании data автоматически указывает на сгенерированную розничную песочницу. Запустите mcp-data-cli init, когда будете готовы материализовать этот выбор в проектном .env; он записывает:

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

Песочница — это синтетические данные только для разработки. Она позволяет новой установке немедленно выполнять обнаружение схем, управляемые запросы, подтверждения и отчёты; это никогда не производственные данные и никогда не перезаписывается последующим запуском init. Все поддерживаемые клиенты получают одинаковые инструкции приветствия stdio-сервера и MCP-инструмент welcome.

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Для SQLite сделайте ту же единственную переменную абсолютным путём к файлу или URL-адресом SQLite. Для PostgreSQL используйте URL-адрес postgres:// или postgresql://. Ручная настройка диалекта не требуется:

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

Используйте data в качестве аргумента источника в вызовах CLI, например mcp-data-cli schema data. Агент отклоняет неподдерживаемые схемы URL, относительные пути SQLite и устаревший объявленный диалект, конфликтующий с URL. Установленные многоисточниковые политики остаются читаемыми, но init намеренно отказывается их переписывать; мигрируйте вручную или начните новый упрощённый проект.

Для PostgreSQL используйте выделенную учётную запись с минимальными привилегиями, без прав на запись или DDL. Агент также включает сеанс только для чтения и применяет настроенный путь поиска схемы, но контроль доступа на стороне базы данных остаётся обязательным.

Типичный рабочий процесс

Проверяйте перед выполнением, затем просматривайте план и выполняйте ограниченный запрос:

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

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

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

Генерируйте отчёты в новом, выбранном вызывающим каталоге. Существующие каталоги и обход символических ссылок отклоняются.

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

Каждый отчёт содержит офлайн HTML, CSV, необязательные артефакты Parquet/PDF, метаданные подтверждений, пути и хэши содержимого. Сгенерированные артефакты, источники и учётные данные не должны коммититься.

Фикстуры для разработки и паритет PostgreSQL

init создаёт только небольшую розничную песочницу, описанную выше. Участники могут явно генерировать дополнительные детерминированные синтетические фикстуры:

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres использует локальный createdb, отказывается от существующего имени базы данных, создаёт данные SQLite только во временном каталоге, а затем копирует их в новую базу данных PostgreSQL в схеме mcp_parity. Он не требует вручную указанного одноразового URL-адреса PostgreSQL.

seed-postgres предназначен для уже подготовленной изолированной тестовой базы данных. Он читает приватный тестовый URL из окружения и заменяет только свои зарезервированные схемы mcp_seed_retail, mcp_seed_saas или mcp_seed_support. Он никогда не касается публичных/прикладных схем.

Запустите полный локальный набор проверки качества с изолированным экземпляром PostgreSQL при разработке поведения адаптера. CI охватывает линтинг, типизацию, тесты, пороги покрытия, реальный рендеринг Typst, паритет SQLite/PostgreSQL, сканирование секретов, аудит зависимостей, генерацию SBOM и автоматизацию релизов с доверенной публикацией.

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

Критически важные для безопасности модули конфигурации, контекста, журнала и SQL-политики требуют 100% покрытия строк и ветвей. Общие пороги требуют как минимум 90% покрытия строк и 85% покрытия ветвей.

Контракт безопасности и эксплуатации

• Запросы должны быть параметризованы и проверяются до подключения/выполнения к базе данных.

• Лимиты результатов и смещения регулируются политикой проекта; вызывающий SQL не может их обойти.

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

• Журналы задач, подтверждения запросов, выполнения и события хранятся в knowledge/ и observability/; URL-адреса баз данных, необработанные секреты, исходные базы данных, кэши результатов и бинарные файлы отчётов исключаются.

• Локальные синтетические наборы данных — это только инфраструктура разработки, а не онбординг в производство.

См. руководство по эксплуатации, политику безопасности и лицензию MIT для полного контракта эксплуатации и раскрытия информации.

Вклад и релизы

Используйте сфокусированные коммиты и сохраняйте аннотированные теги checkpoint-*: они являются явными точками отката для вех поставки. Обновляйте активный инженерный журнал ClineFlow и журнал знаний при существенных изменениях, запускайте проверку OKF, затем коммитьте реализацию и доказательства знаний вместе.

GitHub Actions собирает и проверяет дистрибутивы при публикации релиза. Конечные точки релиза и учётные данные публикации являются конфигурацией репозитория; они никогда не хранятся в этом кодовой базе.