内容
# 关联数据工厂 MCP 服务器
**独立的 MCP 标准输入/输出服务器，向 Claude Desktop 公开 Azure 数据工厂的诊断和自我修复工具。**
给定一个失败的管道，它会引导 Claude 诊断实际的根本原因（活动错误、运行历史、原始管道/数据集/链接服务/数据流定义），提出修复建议，在获得人类批准后应用修复，如果验证显示修复无效，则自动回滚。
- 🔍 **先诊断** — 在提出任何修复之前进行证据驱动的根本原因分析
- ✅ **人工参与** — 每个变更调用都需要明确的批准和说明原因
- ⏪ **始终可逆** — 每个检查点（管道、数据集、链接服务、数据流、全局参数）在进行变更之前都会快照，因此不会发生无法恢复的破坏
- 📦 **自包含** — 拥有自己的 `.venv` 和 `.env`，不依赖于其他文件夹
---
## 目录
- [设置](#设置)
- [在 Claude Desktop 上注册](#在-claude-desktop上注册)
- [在 Claude Desktop 上配置权限](#在-claude-desktop上配置权限)
- [说明](#说明)
- [工具](#工具) — 27 个工具：8 个通用资源类型工具 + 19 个特定类型工具
- [结构](#结构)
---
## 设置
```bash
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
```
在 `.env` 中填写目标工厂的服务主体凭证：
| 变量 | 描述 |
|---|---|
| `ADF_TENANT_ID` | Azure AD 租户 ID |
| `ADF_CLIENT_ID` | 服务主体客户端 ID |
| `ADF_CLIENT_SECRET` | 服务主体客户端密钥 |
| `ADF_SUBSCRIPTION_ID` | Azure 订阅 ID |
| `ADF_RESOURCE_GROUP` | 包含工厂的资源组 |
| `ADF_FACTORY_NAME` | 目标数据工厂名称 |
## 在 Claude Desktop 上注册
在 Claude Desktop 的 `claude_desktop_config.json` 中，指向此文件夹的 venv 解释器和 `mcp_adf/server.py`（将其添加到现有配置中，不要替换）：
```json
{
"mcpServers": {
"nexus-adf": {
"command": "C:\\ABSOLUTE\\PATH\\TO\\THIS\\FOLDER\\.venv\\Scripts\\python.exe",
"args": ["C:\\ABSOLUTE\\PATH\\TO\\THIS\\FOLDER\\mcp_adf\\server.py"],
"env": {
"PYTHONPATH": "C:\\ABSOLUTE\\PATH\\TO\\THIS\\FOLDER"
}
}
},
...claude 默认设置
}
```
> **注意：** 使用绝对路径 — Claude Desktop 的启动器无法可靠地解析相对路径。`PYTHONPATH` 是必需的，以便 `server.py` 的 `from mcp_adf import ...` 导入在 Claude Desktop 直接启动脚本时解析（其自己的工作目录不是此文件夹）。
## 在 Claude Desktop 上配置权限
在将服务器添加到 `claude_desktop_config.json` 并重启 Claude Desktop 后，前往 **设置 → 连接器 → nexus-adf** 并设置：
| 设置 | 值 | 原因 |
|---|---|---|
| 只读工具（`list_*`、`get_*`） | **始终允许** | 不能修改任何内容（`readOnlyHint=True`）— 批准每次调用会增加摩擦力，但没有安全益处 |
| 写/删除工具（`create_*`、`update_*`、`rerun_*`、`rollback_*`、`back_*`、`forward_*`、`start_*`、`stop_*`、`cancel_*`） | **每次询问** | 每个工具都会显示一个本地批准对话框，显示工具的 `reason` 参数（参见 [说明](#说明)) |
| 功能 → 从聊天历史记录生成内存 | **启用** | 让 Claude 携带诊断上下文（例如，特定管道的循环故障模式）跨会话 |
| 工具访问模式 | **已加载的工具** | |
## 说明
`mcp_adf/server.py` 的 `_INSTRUCTIONS`（传递给 `Server(...)` 构造函数的 MCP `instructions` 字段）现在是一个单行指针，而不是完整的流程 — 完整文本仅存在于 Claude Desktop **项目** 的说明字段中，以避免在每次消息中向 Claude 发送相同的约 1.5k 个令牌块。如果您将此设置为 **Claude Desktop 项目**（项目 → 新项目），请将以下两个块粘贴到项目的说明字段中，并将团队的 SOP 文档上传到项目的上下文中：
<details>
<summary><strong>显示说明文本</strong></summary>
```text
此服务器公开了 Azure 数据工厂的诊断和自我修复工具。每个故障调查都遵循此工作流程 — 不要跳过直接修复，不要调用您不需要的工具。
1. 经济使用工具调用。每个调用都会花费时间，每个变更调用都是对实时工厂的实际更改，而不是沙盒 — 调用您需要的最小工具集，而不是可用的最大工具集。在调用工具之前，请检查您是否已经从对话中早期的结果或用户已经告诉您的内容中获得了答案 — 不要重复调用只读工具并具有相同参数以“双重检查”而没有理由怀疑早期结果。如果用户已经指定了特定资源，请直接进入其 get_*/get_resource_definition_raw 工具 — 不要先调用匹配的 list_*/list_resources 工具来浏览。不要投机性地调用多个诊断工具“以防其中一个有答案”；确定哪一个实际上能回答您的开放式问题并调用该工具。在 create_resource 之前，请从您已经知道的内容（先前的 list_resources 结果或用户自己的声明）检查是否存在，而不是投机性地调用它并对“already_exists”错误做出反应 — 那是浪费往返，并且在变更工具上仍然意味着触发一个批准对话框来说明您可以预先排除的内容。
2. 将此处学习的所有内容视为仅限于此工厂的范围，而不是一般偏好。此服务器的事实、配置、命名约定和诊断发现仅属于其来自的特定工厂/项目 — 永远不要将它们概括为用户或应用于无关项目或对话。如果您在此服务器上继续任何学习内容（在摘要、保存的内存或对话的后续部分中），请明确将其限定在此项目范围内，除非用户明确说明更广泛的范围。
3. 在提出或采取任何行动之前进行彻底诊断，但一旦您可以自信地陈述根本原因，就停止收集更多证据 — 更多读取内容只会增加噪音，而不是改变诊断。首先使用 get_activity_run_error（或 get_pipeline_run_history + get_activity_run_history）查找失败的活动，然后使用 list_activity_runs / get_activity_run_io 获取实际的输入/输出数据，并使用 get_resource_definition_raw（resource_type=pipeline/dataset/data_flow/linked_service）获取实际配置（超时、查询、数据集或链接服务引用、主机/端口）。如果仅凭错误消息无法确定修复，请不要从错误消息中猜测修复 — 调用原始定义或活动 IO 工具以显示实际原因。不要仅为了“完整性”而调用模块中的每个只读工具。
4. 在调用任何变更工具之前，在您的回复中提出一个编号的修复计划。陈述诊断出的根本原因、具体的修复、将应用哪些工具（s）以及您将如何验证它是否有效。如果失败是 credential_expired、权限或真正的平台中断，这些是人类专属的、永久的 — 报告并停止，而不是提出修复。
5. 一次执行一个变更步骤。每个变更工具调用都会显示其自己的原生批准对话框，显示您的 `reason` — 编写它以说明特定的诊断，而不是通用短语，因为它是在批准时人类看到的唯一上下文。永远不要实验性地调用变更工具，“看看会发生什么”，或探索资源的样子 — 这就是只读工具的作用。
6. 在应用修复后进行验证（rerun，检查状态/错误） — 不要仅因为写入成功就声明成功，也不要将此服务器自己的 get_*/list_* 读取作为独立证明：它通过相同的写入路径，因此无法捕获该路径中的错误。优先检查实际结果（管道运行的实际状态，触发器的实际运行时状态）而不是重新读取您刚刚编写的定义。
7. 如果验证显示修复无效，请撤销它，而不是将不良更改留在原处 — 使用 back_resource_definition 进行“仅撤销上次更改”（不需要 state_name）。仅当跳转到特定的命名检查点时才使用 rollback_resource_definition（调用 list_resource_snapshots 时您实际上打算回滚，而不是抢先进行，以查看有哪些可用）； forward_resource_definition 在撤销后重新应用更改。 None of 这些会删除历史记录 — 每个检查点仍然可访问。
8. 当人类说“返回”/“撤销”/“恢复”某个资源时，不要仅凭对话记忆猜测他们指的是哪个检查点。先调用 list_resource_snapshots，然后以 state_name/reason/change_summary/timestamp 字段为真理来源进行交叉检查，然后再与您和人类讨论的内容进行交叉检查（例如，“我们刚刚进行的更改”应与最新条目的原因/更改摘要匹配）。如果“返回”清楚地意味着“撤销我们刚刚进行的更改”，并且最新条目与之匹配，则 back_resource_definition（不需要 state_name）更简单、正确；只有在目标是更早的、明确命名的检查点，或者快照列表与您的对话内容不符时，才使用 rollback_resource_definition，带有明确的 state_name — 快照日志是最终真相，您对对话的记忆不是。
```
</details>
<details>
<summary><strong>显示工具特定细微差别</strong>（粘贴此内容 - 从各个工具描述中修剪以保持模式 payload 小）</summary>
```text
资源类型细微差别（create_resource / update_resource_definition / get_resource_definition_raw）：
- create_resource 的 `definition` 接受 get_resource_definition_raw 返回的扁平形状，或仅适用于资源类型 pipeline/dataset/data_flow 的 ARM/Data-Factory-Studio 导出形状（{“name”：...，“properties”：{...}}）；如果存在“properties”键，则使用其内容并丢弃包装器。
- create_resource（resource_type=“trigger”）以停止状态创建触发器，与 ADF Studio 的默认值相同 — 调用 start_trigger 单独执行此操作。
- create_resource（resource_type=“global_parameter”）的 `definition` 为 {“type”：...，“value”：...}，而不是上述扁平/ARM 形状。
- get_resource_definition_raw 不支持 resource_type=“trigger” — 触发器没有原始定义获取器（get_trigger 仅返回 name/type/runtime_state）。要编辑触发器的定义，请自行构建定义 JSON（schedule/recurrence/pipelines），然后直接调用 update_resource_definition（resource_type=“trigger”）。
- update_resource_definition（resource_type=“trigger”）不会更改触发器的 Started/Stopped 运行时状态 — 使用 start_trigger/stop_trigger 进行此操作。
管道运行/活动诊断工具：
- list_pipeline_runs 一次扫描整个工厂 — 如果问题是关于最近的活动，则优先使用它而不是对每个管道调用一次 get_pipeline_run_history。 它与 ADF Studio 的 Monitor 选项卡匹配。
- list_activity_runs 与 ADF Studio 的监控视图匹配，当您深入到运行的活动列表时。
- get_activity_run_io 的 activity_run_id/run_id 已经由 get_activity_run_error 的 leaf/execution_path 显示 — 调用它作为该操作的自然后续步骤，而不是新的查找。
- get_pipeline_definition 仅限活动图（名称/类型/ExecutePipeline 引用）- 没有超时/查询/数据集详细信息；使用 get_resource_definition_raw（resource_type=“pipeline”）作为诊断的一部分，而不是仅在已经确定修复时。
集成运行时工具：
- 调用 get_integration_runtime_status 以确认 IR 是托管（Azure/Azure-SSIS）类型并且实际上已停止 — 启动不适用于自托管 IR 或非停止的 IR。
```
</details>
## 工具
27 个工具：8 个通用资源类型工具（每个工具都带有一个 `resource_type` 参数，以涵盖管道/数据集/链接服务/数据流/触发器/全局参数，在每种类型中操作相同）+ 19 个特定类型工具，不会在类型之间重复（管道运行/活动诊断、触发器启动/停止/重新运行、`get_linked_service`、集成运行时状态/启动）。
**类型** 标记工具是否修改任何内容：只读工具是安全的，始终允许；修改工具始终需要 `reason` 参数，并显示原生批准对话框（参见 [配置权限](#在-claude-desktop上配置权限)）。
<details open>
<summary><strong>通用资源类型工具</strong>（8 个工具 - 涵盖 pipeline/dataset/linked_service/data_flow/trigger/global_parameter）</summary>
每个工具都带有一个 `resource_type` 参数（`pipeline`、`dataset`、`linked_service`、`data_flow`、`trigger`、`global_parameter` 之一 - `get_resource_definition_raw` 排除 `trigger`，详见上面的细微差别）。取代了以前的 47 个特定类型工具。
| 工具 | 类型 | 用途 |
|---|---|---|
| `list_resources` | 只读 | 扫描一个 resource_type 的整个工厂 - 每个名称和轻量级元数据。 |
| `get_resource_definition_raw` | 只读 | 完整的原始定义 - 诊断的证据，以及 `update_resource_definition` 的可编辑输入。 |
| `create_resource` | 修改 | 创建一个全新的资源；如果 resource_type+name 已经存在，则失败。 |
| `update_resource_definition` | 修改 | 覆盖资源的完整定义以应用修复。 |
| `list_resource_snapshots` | 只读 | 列出资源历史中的命名检查点。 |
| `rollback_resource_definition` | 修改 | 跳转到特定的命名检查点。 |
| `back_resource_definition` | 修改 | 回退一个检查点（类似 `git checkout HEAD~1`）。 |
| `forward_resource_definition` | 修改 | 在 `back_*` 调用后向前一步。 |
</details>
<details open>
<summary><strong>特定管道工具</strong>（10 个工具）</summary>
| 工具 | 类型 | 用途 |
|---|---|---|
| `get_pipeline_definition` | 只读 | 活动图（名称/类型/ExecutePipeline 引用）- 无超时/查询/数据集详细信息；使用 `get_resource_definition_raw` 获取详细信息。 |
| `get_pipeline_run_status` | 只读 | 特定运行的当前状态（在重新运行前进行新鲜度检查）。 |
| `get_pipeline_run_history` | 只读 | **一个**管道的最近运行记录。 |
| `list_pipeline_runs` | 只读 | **整个工厂**在时间窗口内的最近运行记录。 |
| `get_activity_run_history` | 只读 | 汇总的失败计数/最近错误代码，按活动记录。 |
| `get_activity_run_error` | 只读 | 管道最近失败运行的错误详细信息 - 通常是诊断的起点。 |
| `list_activity_runs` | 只读 | 一个特定运行中的每个活动（名称/类型/状态/时间/活动运行 ID），无输入/输出负载。 |
| `get_activity_run_io` | 只读 | 一个特定活动运行的完整解析输入/输出负载。 |
| `rerun_pipeline` | 修改 | 触发新运行。 |
| `cancel_pipeline_run` | 修改 | 取消正在运行/挂起的运行。 |
</details>
<details>
<summary><strong>特定触发器工具</strong>（6 个工具）</summary>
| 工具 | 类型 | 用途 |
|---|---|---|
| `get_trigger` | 只读 | 一个触发器的运行时状态（Started/Stopped/Disabled）。 |
| `get_trigger_run_history` | 只读 | 触发器运行历史记录 - 需要用于 tumbling-window/event 触发器，其中触发器运行（而非它调用的管道运行）是失败/重新运行/取消的单位。 |
| `start_trigger` | 修改 | 启动已停止/禁用的触发器。 |
| `stop_trigger` | 修改 | 停止正在运行的触发器。 |
| `rerun_trigger_run` | 修改 | 重新运行特定的触发器运行（tumbing-window/event 触发器 `rerun_pipeline` 无法达到）。 |
| `cancel_trigger_run` | 修改 | 取消特定的正在进行中的触发器运行。 |
</details>
<details>
<summary><strong>特定链接服务工具</strong>（1 个工具）</summary>
| 工具 | 类型 | 用途 |
|---|---|---|
| `get_linked_service` | 只读 | 名称和类型 - 无连接详细信息；使用 `get_resource_definition_raw`（resource_type=“linked_service”）获取详细信息。 |
</details>
<details>
<summary><strong>集成运行时工具</strong>（2 个工具）</summary>
| 工具 | 类型 | 用途 |
|---|---|---|
| `get_integration_runtime_status` | 只读 | IR 的状态 - 适用于 Azure、自托管和 Azure-SSIS 类型。 在 `start_integration_runtime` 之前进行检查。 |
| `start_integration_runtime` | 修改 | 启动已停止的 **Azure-SSIS（托管）** IR。 不适用于自托管 IR - 无远程启动 API 存在；那是人类专属的。 |
</details>
## 结构
```text
mcp_adf/ MCP 服务器包
├── server.py MCP 入口，标准输入输出传输，工具调度
├── auth.py 服务主体身份验证 / ADF 客户端构造
├── audit.py 审计日志写入器（project/_logs/）
├── tools/ 工具实现，每个 ADF 资源类型一个模块
│ ├── _shared.py 共享帮助函数（客户端构造，线头字典转换，杂项键检查）
│ ├── _checkpoints.py 快照/回滚/后退/前进引擎，被每种资源类型共享
│ ├── _dispatch.py 资源类型 -> 每种类型函数路由，支持 8 个通用工具
│ ├── pipelines.py 管道实现 — 列表/获取/创建/更新/重新运行/取消，快照/回滚/后退/前进
│ ├── triggers.py 触发器实现 — 列表/获取/启动/停止/重新运行/取消，运行历史
│ ├── linked_services.py 联结服务实现 — 列表/获取/更新，快照/回滚/后退/前进
│ ├── datasets.py 数据集实现 — 列表/获取/更新，快照/回滚/后退/前进
│ ├── data_flows.py 数据流实现 — 获取/更新，快照/回滚/后退/前进
│ ├── global_parameters.py 全局参数实现 — 列表/获取/更新，快照/回滚/后退/前进
│ ├── integration_runtimes.py 集成运行时实现 — 获取状态/启动
│ └── __init__.py 汇集 TOOL_REGISTRY：特定类型条目 + _dispatch 的 8 个通用条目
├── schemas/ MCP 工具模式定义
│ ├── _generic.py 8 个资源类型参数化工具模式（由 tools/_dispatch.py 调度）
│ ├── pipelines.py 管道特定工具模式
│ ├── triggers.py 触发器特定工具模式
│ ├── linked_services.py 获取联结服务的模式
│ ├── integration_runtimes.py 集成运行时工具模式
│ └── __init__.py 汇集模式列表，server.py 通过 list_tools() 公开
│ （这里没有 datasets.py/data_flows.py/global_parameters.py — 这 3 种类型的每个操作都由 schemas/_generic.py 覆盖）
│
tests/ 单元测试套件 — 不需要 pytest 依赖
├── test_dispatch.py tools/_dispatch.py 路由，kwargs 重新映射，未知资源类型拒绝
├── test_schema_registry_sync.py 模式<->TOOL_REGISTRY 名称对齐，通用工具枚举<->调度表对齐
└── test_call_tool_integration.py 通过 server.call_tool() 端到端测试（Azure SDK 客户端伪造，审计日志 + 检查点/快照系统在临时目录中真实运行）
project/
├── _snapshot/ 更改前管道/数据集/数据流定义，用于回滚（gitignored，运行时创建）
└── _logs/ 工具调用的审计日志，每天一个带日期的文件夹（gitignored，运行时创建）
docs/TEST_ADF_CONTEXT.md 本研发工作的设计/决策文档 — 修改前请阅读
.env 真实凭证（gitignored，勿提交）
.env.example 模板 — 复制到 .env
requirements.txt 固定的依赖项
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器