adf-mcp-server

Сервер MCP (Model Context Protocol) только для чтения для мониторинга Azure Data Factory и анализа первопричин, созданный для использования из VS Code / Claude Code.

Статус: Шаг 1 (скелет + проверка работоспособности). Подключения к Azure пока нет — оно будет добавлено на шаге 2 (аутентификация) и шаге 3 (инструменты ADF).

Требования

• Python 3.11+

• Регистрация приложения Azure AD (Service Principal) с ролью Reader на ресурсах Data Factory, которые вы хотите проверять (роли Reader достаточно — этот сервер полностью доступен только для чтения, поэтому ему никогда не нужна роль Contributor)

Related MCP server: mcp-azure-landing-zone

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

cd adf-mcp-server
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
cp .env.example .env

Создание Service Principal (однократно, через az-cli)

az ad sp create-for-rbac \
  --name "adf-mcp-server-reader" \
  --role "Reader" \
  --scopes "/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RG_NAME>/providers/Microsoft.DataFactory/factories/<FACTORY_NAME>"

Эта команда выводит appId, password и tenant — сопоставьте их с переменными в .env как AZURE_CLIENT_ID, AZURE_CLIENT_SECRET и AZURE_TENANT_ID соответственно. Ограничьте назначение роли конкретным фабрикой (или, в крайнем случае, группой ресурсов), а не всей подпиской — принцип минимальных привилегий, и этому SPN никогда не нужно обращаться к чему-либо за пределами ADF.

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

python -m adf_mcp.server
# or, after `pip install -e .`:
adf-mcp-server

Сервер общается через stdio — при запуске напрямую в терминале может показаться, что он завис; это ожидаемо, он ждёт подключения MCP-клиента (расширение VS Code, Claude Code, mcp dev и т.д.) через stdin/stdout.

Настройка в VS Code

Укажите конфигурацию сервера вашего MCP-совместимого расширения:

{
  "command": "python",
  "args": ["-m", "adf_mcp.server"],
  "cwd": "/absolute/path/to/adf-mcp-server"
}

После подключения:

1. Вызовите health_check — должен вернуть {"status": "ok", ...} без обращения к Azure.

2. Вызовите check_auth — этот вызов делает один реальный запрос к Azure AD для получения ARM-токена. Успех выглядит так:

   {"authenticated": true, "auth_mode": "service_principal", "token_expires_on": 1735000000}

   При сбое возвращается структурированное (не стек-трейс) объяснение, например, отсутствующие переменные окружения или неверный секрет — см. раздел «Устранение неполадок» ниже.

3. Вызовите list_factories — этот вызов делает реальный запрос к Azure Data Factory. Возвращает resource_group каждой фабрики, который нужен всем остальным инструментам ниже как входной параметр:

   {"factories": [{"name": "shell-prod-adf", "resource_group": "rg-shell-prod", "location": "eastus"}]}

Доступные инструменты (шаг 3)

Все инструменты только для чтения — ни один из них не может создавать, изменять, запускать или удалять что-либо в Azure Data Factory.

Пример RCA-потока для агента: list_factories → list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) для непосредственного разбора ошибки.

Доступные инструменты (дополнения шага 4)

Полный RCA-поток для неудачного конвейера: list_pipeline_runs(status="Failed") → get_failed_activity_details(run_id=...) для ошибки, и отдельно get_trigger_status(trigger_name=...), чтобы исключить вариант «он вообще не сработал».

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

pip install -e ".[dev]" pytest-asyncio
pytest -v

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

См. src/adf_mcp/ — server.py (транспорт MCP), config.py (настройки), logging_config.py (структурированное логирование). Доменная логика и подключение к Azure добавляются в src/adf_mcp/domain/ начиная с шага 3.

Устранение неполадок

• Клиент сразу показывает "server disconnected": сначала проверьте, что python -m adf_mcp.server запускается без ошибок — исключение при запуске убьёт процесс до того, как клиент подключится.

• Клиент не может разобрать ответы / искажённый вывод: что-то записало в stdout, кроме самого протокола MCP (например, случайный print()). Вся логика в этом проекте идёт в stderr именно по этой причине.

• check_auth возвращает "Missing required Service Principal setting(s)": одна из переменных AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET пуста в .env. Обратите внимание: эти три переменные НЕ используют префикс ADF_MCP_.

• check_auth возвращает "Azure authentication failed": обычно это истёкший/ротированный секрет клиента, отключённая регистрация приложения или опечатка в tenant ID. Перепроверьте с помощью az ad sp show --id <AZURE_CLIENT_ID>.

• ClientAuthenticationError: AADSTS7000215: неверный секрет клиента — перегенерируйте его в регистрации приложения и обновите .env.

• Инструмент возвращает {"error": "AZURE_SUBSCRIPTION_ID is not set..."}: добавьте AZURE_SUBSCRIPTION_ID в .env — требуется для каждого инструмента ADF (кроме check_auth, которому нужны только tenant/client/secret).

• Инструмент возвращает {"error": "Azure API error (403): ..."}: у Service Principal нет доступа Reader к этой фабрике/группе ресурсов — перепроверьте назначение az ad sp create-for-rbac --role Reader --scopes ... из настройки.

• Инструмент возвращает {"error": "Azure API error (404): ..."}: проверьте написание resource_group/factory_name/pipeline_name — они чувствительны к регистру и должны точно совпадать с тем, что вернули list_factories/list_pipelines.

• get_failed_activity_details возвращает пустой список, но вы знаете, что конвейер завершился с ошибкой: сбой может быть на уровне конвейера (например, недопустимый параметр), а не в отдельном действии — проверьте собственное message родительского запуска через get_pipeline_run.

• Конвейер «просто не запустился» без каких-либо неудачных запусков: проверьте get_trigger_status для его триггера — runtime_state: "Stopped" означает, что триггер был отключён и не сработал, что не отобразится как неудачный запуск, потому что запуск вообще не был создан.