adf-mcp-server

用于 Azure Data Factory 监控和根因分析的只读 MCP（模型上下文协议）服务器，专为从 VS Code / Claude Code 使用而构建。

状态：第 1 步（骨架 + 健康检查）。 尚无 Azure 连接 - 将在第 2 步（身份验证）和第 3 步（ADF 工具）中添加。

要求

• Python 3.11+

• 一个 Azure AD 应用注册（服务主体），在你要检查的 Data Factory 资源上具有 Reader 角色（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

创建服务主体（一次性，通过 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（结构化日志）。从第 3 步开始，在 src/adf_mcp/domain/ 下添加领域逻辑和 Azure 连接。

故障排除

• 客户端立即显示“服务器已断开”：首先检查 python -m adf_mcp.server 能否独立正常运行 - 启动异常会在客户端连接之前终止进程。

• 客户端无法解析响应 / 输出乱码：有东西写入了 stdout，而不是 MCP 协议本身（例如多余的 print()）。本项目中的所有日志都输出到 stderr，正是出于这个原因。

• check_auth 返回“缺少必需的服务主体设置”：AZURE_TENANT_ID / AZURE_CLIENT_ID / AZURE_CLIENT_SECRET 之一在 .env 中为空。请注意，这三个不使用 ADF_MCP_ 前缀。

• check_auth 返回“Azure 身份验证失败”：通常是客户端密钥过期/轮换、应用注册被禁用或租户 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 不需要，它只需要租户/客户端/密钥）。

• 工具返回 {"error": "Azure API error (403): ..."}：服务主体缺少对该工厂/资源组的 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 返回空列表，但你知道管道失败了：失败可能发生在管道级别（例如参数无效），而不是任何单个活动 - 请改用 get_pipeline_run 检查父运行自身的 message。

• 管道“就是没运行”，完全没有失败的运行：检查其触发器的 get_trigger_status - runtime_state: "Stopped" 表示触发器已被禁用且从未触发，这不会显示为失败的运行，因为从未创建任何运行。