内容
# 🚀 MCP 工作流代理 — Redfish 版本
> **82.0% 工具减少 • 74.7% Token 节省 • 133 端点 → 24 高价值 MCP 工具**
>
> 一个模型上下文协议（MCP）服务器，简化了原始的 133 端点 DMTF Redfish 规范，转化为 **21 个语义工作流工具** + **3 个高级元工具**。这使得 LLM 代理（如 Claude 或 Cursor）能够使用纯英文管理整个服务器基础设施，消除上下文窗口膨胀和工具选择混淆。
---
## ⚡ 关键亮点
* **82.0% 工具数量减少：** 将 133 个原始、令人困惑的 API 端点合并为 24 个智能、语义化的 MCP 工具。
* **74.7% Token 足迹节省：** 将工具定义大小从 **12,060+** Token 减少到 **3,058** Token（与原始 OpenAPI 规范摄入相比，节省了 **99.3%**）。
* **零运行时 LLM 成本：** 工作流执行在纯 Python 引擎中本地运行。运行时不进行 LLM 调用，确保亚秒级执行时间和确定性行为。
* **分层暴露（"层切换"）：** 提供高级别抽象，但为 LLM 提供了一个逃生门工具集，以调用原始端点。
* **状态缓存集成：** 为 GET 调用实现了一个内存 TTL 缓存，该缓存会在工作流执行中的状态更改请求（POST/PATCH/PUT/DELETE）时自动失效。
* **动态自然语言构建器：** 使用纯英文提示动态生成新的工作流 YAML 模板，该模板可以直接热加载到活动 MCP 服务器工具中，无需服务器停机。
* **丰富的可观察性仪表盘：** 基于 FastAPI 的仪表盘，具有实时 SSE 执行跟踪、映射可视化、指标图表和手动执行门户。
---
## 📐 高级架构
MCP 工作流代理在混合 **两阶段工作流** 中运行：
```
┌─────────────────────────────────────────────────────────────────────────────┐
│ 1. 设计时（离线） │
│ │
│ 原始 OpenAPI 规范 ──► parse_spec.py ──► 摘要 ──► LLM 聚类 ──────┐│
│ （133 端点） （人员 1） （Token 清洁） （设计时提示） ││
│ ││
│ workflows.yaml ◄─────────────────┘│
│ （21 个工作流蓝图） │
└─────────────────────────────────────────────────────────────────────────────┘
│
│ （加载 YAML 并注册工具）
▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ 2. 运行时（本地引擎） │
│ │
│ AI 代理 ──► MCP 客户端 ──► mcp_server.py ──► workflow_engine.py │
│ （Claude, （FastMCP） （stdio/SSE） （链接和条件） │
│ Cursor） │ │
│ ▼ │
│ 本地缓存（GET） │
│ │ │
│ ▼ │
│ Prism 模拟 / 真实 BMC │
│ （localhost:4010） │
└─────────────────────────────────────────────────────────────────────────────┘
```
---
## 📂 仓库结构
```
MCP-Workflow/
├── setup.bat # Windows 一键设置
├── setup.sh # Mac/Linux 一键设置
├── generate_config.py # 自动生成 Claude Desktop 配置片段
├── mcp_server.py # 将引擎包装为 FastMCP stdio/SSE 服务器（人员 4）
├── workflow_engine.py # 核心运行时引擎，带有变量链接、循环和条件（人员 3）
├── workflows.yaml # 声明式工作流蓝图（21 个 YAML 配置文件）（人员 2）
├── requirements.txt # Python 项目依赖项
├── download_spec.py # 下载 DMTF Redfish 模式文件（人员 1）
├── parse_spec.py # 合并和清理模式为摘要格式（人员 1）
├── fix_spec_for_prism.py # 修补合并的 OpenAPI 规范以兼容 Prism（人员 1）
├── calculate_metrics.py # 计算前后工具/Token 指标（人员 5）
├── nl_workflow_generator.py # 自然语言工作流合成器（Gemini Pro / 本地离线）
├── observability_engine.py # 带有计时和 HTTP 请求跟踪的仪器执行器
├── observability_server.py # FastAPI 服务器，提供实时 SSE 流和 HTML 仪表盘
├── ARCHITECTURE.md # 架构图、聚类策略和权衡分析
├── WORKFLOW_DEFINITIONS.md # 从原始 API 端点到工作流级工具的完整映射
├── specs/
│ ├── raw/ # 原始 OpenAPI 模式组件（85 个文件）
│ ├── merged/
│ │ ├── full_spec.yaml # 合并的 Redfish 规范（OpenAPI 3.0 格式）
│ │ └── full_spec_local.yaml # 合并的规范，修补了本地模拟服务器详细信息
│ ├── cleaned/
│ │ ├── all_endpoints.json # 处理的端点列表
│ │ └── endpoints_summary.yaml # Token 高效摘要，用于 LLM 设计时输入
│ ├── baseline_metrics.json # 原始指标（133 个工具，410,562 个完整规范 Token）
│ └── after_metrics.json # 实时指标验证输出
├── dashboard/ # 主要可观察性仪表盘 UI（HTML、CSS、JS）
└── prompts/
└── workflow_generation_prompt.md # 用于分组端点的确切 Claude 提示
```
---
## 🛠️ 快速入门
### 先决条件
* **Python 3.10+**
* **Node.js 18+** （用于 Prism 模拟服务器）
---
### 步骤 1 — 运行设置（仅一次）
**Windows：**
```
setup.bat
```
**Mac/Linux：**
```bash
chmod +x setup.sh && ./setup.sh
```
这会创建一个虚拟环境，安装所有依赖项，并打印您的 ready-to-paste Claude Desktop 配置片段。它还会将片段保存到 `claude_desktop_config_snippet.json`。
---
### 步骤 2 — 添加到 Claude Desktop
打开您的 Claude Desktop 配置文件：
| 平台 | 路径 |
|---|---|
| Windows（标准） | `%APPDATA%\Claude\claude_desktop_config.json` |
| Windows（Store/MSIX） | `%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json` |
| Mac/Linux | `~/Library/Application Support/Claude/claude_desktop_config.json` |
粘贴 `mcpServers` 块，由设置脚本打印。它看起来像这样：
```json
{
"mcpServers": {
"redfish-workflow-proxy": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/mcp_server.py"],
"env": {}
}
}
}
```
> **注意：** 设置脚本会自动填写您机器的精确路径 — 无需手动编辑。
保存文件并 **完全重启 Claude Desktop**。
---
### 步骤 3 — 启动模拟 Redfish 服务器
在终端中运行：
```bash
npx.cmd @stoplight/prism-cli mock specs/merged/full_spec_local.yaml --port 4010
```
> 使用 `full_spec_local.yaml`（不是 `full_spec.yaml`）— 它具有所有外部模式引用本地解析，因此 Prism 不需要 Internet 访问。
在测试期间保持此终端打开。
---
### 步骤 4 — 在 Claude Desktop 中测试
启动新的聊天并尝试：
* *"有哪些工具可用？"*
* *"对 Server1 进行健康检查。"*
* *"显示机箱的热状态。"*
* *"使用映像 URI http://mock-server/firmware/bios-2.1.0.bin 更新 Server1 上的固件。"*
---
### 步骤 5 — 启动可观察性仪表盘（可选）
```bash
venv/Scripts/python observability_server.py # Windows
venv/bin/python observability_server.py # Mac/Linux
```
在 `http://localhost:8765` 打开 — 显示实时执行跟踪、工作流映射和指标。
---
## 📊 实时指标和验证
```bash
python calculate_metrics.py
```
### 测量项目指标：
| 指标组件 | 之前 | 之后（MCP 代理） | 减少 % | 状态 |
| :--- | :---: | :---: | :---: | :---: |
| **暴露的 MCP 工具** | 133 端点 | **24 工具** （21 个工作流 + 3 个元工具） | **82.0%** | **通过（≥80%）** |
| **工具定义 Token** | 12,060+（估计） | **3,058** | **74.7%** | **通过（≥70%）** |
| **完整规范原始摄入** | 410,562 | **3,058** | **99.3%** | 信息 |
---
## 💡 如何使用 MCP 工具
### 1. 高级工作流（21 个工具）
这些工具在 Redfish API 上执行多步骤、条件操作。
* **`server_health_check`**: 在系统、处理器、内存、机箱和热日志上运行 8 步诊断管道。
* **`firmware_update`**: 检查现有的库存版本，与目标映像 URI 进行比较，触发一个简单的更新任务，并轮询进度状态。
* **`hardware_inventory_report`**: 收集综合库存数据，包括网络卡、PCI 设备和存储阵列，在单个执行中。
*Claude 示例提示：*
* *"对系统 Server1 运行完整的健康状态报告。"*
* *"使用映像 http://firmware.local/v2.bin 更新服务器固件。"*
* *"获取机箱的热级别和电源统计数据。"*
### 2. 层切换和逃生门（3 个元工具）
如果高级工作流失败或代理遇到需要直接 API 访问的边缘情况：
1. **`list_workflows_meta`**: 列出所有可用的工作流定义。
2. **`list_raw_endpoints`**: 返回特定工作流使用的原始 API 端点。
3. **`run_raw_endpoint`**: 直接调用模拟服务器上的 HTTP 请求，绕过工作流抽象。
*示例提示序列：*
> **用户：** *"配置一个不在 bios 工作流中的 BIOS 设置。"*
> **Claude：** 调用 `list_raw_endpoints("bios_configuration")`，然后 `run_raw_endpoint(method="PATCH", path="/redfish/v1/Systems/Server1/Bios/Settings", body_json="{\"Attributes\": {\"BootMode\": \"Uefi\"}}")`
---
## 🔍 详细功能
### 1. 内存请求缓存
在单个工作流执行中，使用 `cachetools.TTLCache` 缓存 `GET` 响应。任何状态更改请求（`POST`、`PATCH`、`PUT`、`DELETE`）都会立即清除该 URL 的缓存条目。
### 2. 实时可观察性仪表盘
运行 `observability_server.py` 以在 `http://localhost:8765` 打开 Web 控制台：
* **概览选项卡：** 实时工具/Token 指标和执行历史。
* **工作流映射：** 可视化工作流节点如何映射到原始端点。
* **执行跟踪：** 实时 SSE 驱动的逐步计时和状态更新。
* **工作流目录：** 所有 21 个蓝图的搜索库。
### 3. 自然语言工作流构建器
在 **NL 构建器** 选项卡中，用纯英文编写需求。后台编译一个 YAML 工作流蓝图，将其附加到 `workflows.yaml`，然后服务器 **热加载** — 新工作流立即成为一个活跃的 MCP 工具。
---
## ⚡ 扩展指南：5 分钟上线新规范
1. **放置规范：** 将原始 OpenAPI YAML/JSON 文件放入 `specs/raw/`。
2. **合并和清理：** 运行 `python parse_spec.py` 生成 `specs/cleaned/endpoints_summary.yaml`。
3. **与 AI 聚类：** 使用 `prompts/workflow_generation_prompt.md` 中的提示和清理后的摘要。
4. **部署 workflows.yaml：** 将 LLM 输出保存为根目录下的 `workflows.yaml`。
5. **启动服务器：** 运行 `python mcp_server.py`。新工作流自动注册为 MCP 工具。
---
## 👥 黑客马拉松团队积分
| 团队成员 | 角色 | 主要贡献 |
| :--- | :--- | :--- |
| **人员 1** | 数据和模拟工程师 | 规范下载、OpenAPI 解析、Prism 模拟修补 |
| **人员 2** | AI 聚类架构师 | LLM 聚类提示、`workflows.yaml` 蓝图结构 |
| **人员 3** | 运行时引擎构建者 | `workflow_engine.py` 逻辑、循环/分支执行器、JSONPath 提取 |
| **人员 4** | MCP 服务器开发人员 | FastMCP 包装器、动态工具生成、层切换实现 |
| **人员 5** | 集成和推销大师 | Token 指标脚本、可观察性仪表盘、推销演示文稿 |
---
