Content
# Dell Enterprise MCP Proxy - Infrastructure Command Center CLI (`drake`)
The **Infrastructure Command Center CLI (`drake`)** is the primary operational control plane and administration utility for the Dell Enterprise MCP Proxy platform.
It is designed for:
* **Infrastructure Engineers** managing bare-metal systems and server topologies.
* **Platform Reliability Engineers (PRE)** monitoring runtime states and API availability.
* **Dell PowerEdge Administrators** validating hardware compliance and firmware inventories.
* **Governance & Compliance Teams** auditing AI-generated workflows and reviewing action ledgers.
The CLI acts as a thin presentation and orchestration layer over the underlying Dell MCP services, presenting a high-performance, unified, and resilient command center experience.
---
## 🏛 System Architecture & Data Flow
Drake is built on a highly modular architecture spanning AI ingestion, human-in-the-loop governance, and dynamic proxying. We utilize a **4-Stage Hybrid Pipeline** that employs semantic clustering for operational boundary discovery and strict DAGs for internal execution mapping.
### 1. Ingestion Phase (Hybrid Intelligent Workflow Discovery)
Raw specification files (OpenAPI, GraphQL, gRPC, AsyncAPI) are ingested and semantically parsed.
* **Stage 1: Semantic Discovery (Intent Boundary)**: We use `sentence-transformers` and the **Leiden Algorithm** to mathematically group endpoints into "Goldilocks Zone" clusters (e.g., 5-6 endpoints per workflow). This eliminates the "God Tool" context-window overload and gives the LLM perfect, human-readable boundaries.
* **Stage 2: Schema-Aware Dependency Discovery**: Inside each cluster, we extract exact producer-consumer relationships using field types and references to build a strict **Directed Acyclic Graph (DAG)**.
* **Stage 3: Variable Mapping Engine**: We automatically generate runtime bindings (`{{step.id}}`) to wire data flow between endpoints (e.g. POST ID automatically passes to PATCH body).
* **Stage 4: Execution DAG & Cycle Management**: We resolve circular dependencies with a self-correcting cycle management engine to guarantee safe execution.
* **Automated Naming**: The `ollama_service` assigns human-readable titles (e.g., *Dell Power Supply Management*) to these clustered workflows.
### 2. Governance Phase (Sub-10ms Zero-Trust Interceptor)
Once individual endpoints (tools) are synthesized into high-level workflows, they enter the `governance` layer.
* **The Strict Rule:** When tools are clustered and converted into an operational workflow, **this is the exact and only moment where human approval is strictly mandatory.**
* **Dynamic Risk Assessment:** We abandon naive HTTP-method-only scoring. Operations are dynamically assessed on blast radius and criticality.
* **DAG Cycle Detection:** Utilizing Depth-First Search to ensure workflows form valid, acyclic dependencies.
* **Stateful Campaign Tracking:** Tracks multi-step chained actions across sessions to prevent slow-loris or complex exfiltration attempts.
* **Human-in-the-loop (HITL)**: Administrators use the CLI (`drake governance review`) or Web Console to certify workflows as production-ready FastMCP tools.
### 3. Runtime Phase (Dynamic Proxy Interceptor)
* **Dynamic Tool Initialization**: The `FastMCP` FastAPI backend reads approved workflows from the database and uses `inspect.Signature` to synthesize strictly-typed Python functions dynamically on-the-fly.
* **Asynchronous Execution Routing**: Decouples execution logic with pluggable engines like the raw HTTP executor or the Dell OMSDK stub.
* **Extreme Token Compression**: The `compress_redfish_response()` engine natively shrinks JSON payloads by recursively stripping verbose HATEOAS/Redfish links, nulls, and empty arrays, saving >80% of LLM token limits (compressing 1,500 tokens down to 200).
* **Standardized Transport**: The interactive AI Agent connects via standard `stdio` pipe streaming, ensuring native integration with modern MCP clients (like Claude Desktop).
```mermaid
flowchart TD
subgraph Presentation Layer
A[Operator Console / shell] -->|drake CLI| B[Typer Main Router src/cli/main.py]
B -->|Command Group Router src/cli/commands/*| C[CLIContainer src/cli/container.py]
C -->|Lazy Resolution| D[CLI Service Adapter src/cli/services/*]
end
subgraph Core Platform Services
D -->|Database Sync / Async Session| E[(SQLite governance.db)]
D -->|Pre-flight Verification| F[Compatibility Engine]
D -->|Playbook Enrichment| G[Ansible Exporter]
D -->|FastMCP Runtime State| H[Execution Manager]
end
```
---
## 🛡️ Security & Execution Guardrails
To prevent the LLM from making accidental or malicious infrastructure changes, Drake implements robust runtime guardrails located in `src/drake/governance/middleware.py`.
* **Sub-10ms FastPreFilter**: We stripped out heavy PyTorch dependencies. A blazing-fast regex engine intercepts prompt injections, role-play jailbreaks, and evasions instantaneously in under 5 milliseconds with zero ML latency penalty.
* **Universal State-Aware Rollback**:
* **DUAL_BANK**: The proxy issues automated `SwitchActiveFirmwarePartition` POST commands to flip iDRAC boot banks upon firmware update failure.
* **SCP_SNAPSHOT**: Automated XML `ExportSystemConfiguration` snapshots are taken *before* mutating calls, reverting to `ImportSystemConfiguration` on failure.
* **Advanced Escalation & Session Engines**: Dynamically elevates risk tiers based on anomalous runtime contexts.
* **SOC Integration (`soc_logger.py`)**: A specialized SOC logging hook routes intercepted payload attempts directly into enterprise SIEM platforms like Splunk.
* **Policy Engine Engine (`policy.yaml`)**:
* `AutoApproveLowRisk`: Approves highly-confident safe workflows.
* `BlockDestructiveBulk`: Flags or denies bulk endpoints containing destructive methods.
* `RequireApprovalForHighRisk`: Forces manual review for system-critical modifications.
---
## ✨ Advanced Proxy Capabilities (Wow Factors)
We implemented major beyond-baseline capabilities directly in the proxy layer to solve complex enterprise problems:
* **Hierarchical Tool Exposure:** When an agent gets stuck, it can use `expand_workflow(workflow_id)`. The server dynamically generates fine-grained micro-tools for just that workflow, injects them into the prompt window via `mcp.add_tool()`, and broadcasts a `send_tool_list_changed()` event—all without overflowing context.
* **Dynamic OpenAPI Simulator Generation (`generate_simulator.py`):** The engine reads the live SQLite `governance.db` to extract approved policies and auto-generates a dynamic `auto_simulator.json` spec. Our Docker Compose mock environment instantly serves this via `prism-simulator` for zero-risk, high-speed LLM integration testing.
* **Dell OMSDK Integration Stub (`DellOMSDKExecutor`):** Native factory pattern backing that hot-swaps raw HTTP requests with official Dell OMSDK wrappers (`DELL_EXECUTOR_TYPE`) for bulletproof production deployment.
---
## 📂 Codebase Directory Structure
```text
drake/
├── data/ # Local SQLite databases (governance.db, mcp_proxy.db)
├── frontend/ # Next.js Web Governance Dashboard
├── tests/fixtures/ # OpenAPI specifications and simulated payloads
├── windows_scripts/ # Windows Launcher Scripts (start.ps1, start.bat)
├── linux_scripts/ # Linux/macOS Launcher Scripts (start.sh, test_all.sh)
└── src/drake/ # Core Python Backend
├── ai_clustering/ # Hybrid Pipeline: Leiden graphs, Dependency DAGs, NLP mappings
├── cli/ # Typer presentation layer and CLI commands
├── core/ # SQLAlchemy models and shared types
├── governance/ # Sub-10ms PreFilter, Policy engine, Risk V2, SOC logging
├── parser/ # Multi-protocol OpenAPI ingestion logic
└── proxy/ # FastMCP Runtime, Token Compression, Simulator Generation
```
### 📚 Deep-Dive Component Documentation
For deep technical insights, architecture rules, and specific "Wow Factors" of each core subsystem, refer to the following authoritative documents:
| Component | Path / Link | Description |
| :--- | :--- | :--- |
| **AI Clustering & Graph Engine** | [src/drake/ai_clustering/README.md](src/drake/ai_clustering/README.md) | Details on the 4-Stage DAG Pipeline, Leiden algorithm, and Variable Mapping. |
| **CLI Command Center** | [src/drake/cli/README.md](src/drake/cli/README.md) | Full command reference, plugin architecture, and dashboard overviews. |
| **Core Compatibility & Compression** | [src/drake/core/README.md](src/drake/core/README.md) | Specs for the Redfish Response Compression Engine and Ansible playbook enricher. |
| **Governance & Security** | [src/drake/governance/README.md](src/drake/governance/README.md) | Deep dive into the Sub-10ms PreFilter, Escalation Engine, and SOC logging. |
| **Multi-Protocol Parser** | [src/drake/parser/README.md](src/drake/parser/README.md) | Architecture of the unified AST and support for GraphQL, gRPC, and AsyncAPI. |
| **FastMCP Proxy Server** | [src/drake/proxy/README.md](src/drake/proxy/README.md) | Details on Hierarchical Tools, Universal Rollback, and the Auto-Simulator. |
---
## 💻 Next.js Web Governance Console
While the `drake` CLI provides immense terminal power, the platform also includes a robust React/Next.js dashboard (running on `http://localhost:3000`).
* **Visual Workflows**: It hooks directly into the FastAPI backend (`/api/workflows`) to provide a visual interface for the Governance Phase.
* **One-Click Approval**: Operators can visually inspect the exact HTTP methods, API paths, and payloads assigned to a clustered workflow and click "Approve" or "Reject".
---
## 🚀 End-to-End Workflow Tutorial
Follow these steps if this is your first time setting up the platform and you need to ingest a large number of endpoints into the MCP Proxy.
### Step 1: Ingest OpenAPI Specification & Auto-Approve
First, parse your Redfish OpenAPI specification file. The AI Clustering Engine will group hundreds of individual endpoints into logical workflows, resolving cycle dependencies.
Run the following command to ingest the endpoints. The `--auto-approve` flag triggers the Governance Engine to automatically approve all safe, low-risk workflows based on your `policy.yaml` rules, saving you from manual auditing:
```powershell
# 1. Activate venv (once per terminal session)
.venv\Scripts\Activate.ps1
# 2. Run the ingestion pipeline
drake pipeline tests\fixtures\openapi-7.xx.yaml --auto-approve
```
### Step 2: Verify Governance Status
Once the pipeline finishes, verify how many workflows were successfully approved and if any require manual review (or were denied due to destructive bulk rules):
```powershell
# Check workflows that still require human review
drake governance pending
# Manually approve a specific workflow that was blocked by policy (e.g., HIGH/CRITICAL risk)
drake governance approve <workflow_id>
# Example: drake governance approve wf_c_616cc9a0
# Check workflows that are fully certified and ready for the AI Agent
drake governance approved
```
### Step 3: Launch Platform Services
With the database seeded with approved workflows, launch all local services:
```powershell
# Windows
.\windows_scripts\start.ps1
# Linux / macOS
bash linux_scripts/start.sh
```
When you run this script, it orchestrates the entire stack automatically:
1. **Environment Config**: Verifies your `.env` secrets.
2. **Virtual Environment**: Installs and syncs `uv` Python dependencies.
3. **LLM Engine**: Ensures Ollama is running locally with the target model.
4. **Mock API (Auto-Simulator)**: Executes `generate_simulator.py` to create a `prism-mock` dynamic simulator reflecting the exact approved DAGs, running on port `4010` via Docker Compose so the agent can execute requests against dummy hardware with zero risk.
5. **Security Suite**: Runs the AI Guardrails tests to ensure campaign tracking, the Sub-10ms PreFilter, and SOC logic are active.
6. **FastMCP / FastAPI Proxy**: Launches the backend proxy server on port `8001`, dynamically injecting approved workflows.
7. **Next.js Console**: Launches the web governance dashboard on port `3000`.
At the end of the script, press **Y** to launch the interactive AI Agent Terminal.
### Step 4: Test the AI Agent
Inside the Drake AI Agent Terminal, the agent will automatically connect to the Proxy and load all approved MCP workflows.
These test prompts are designed to be intentionally vague and omit required IDs. This tests the AI's ability to semantically map your request to the correct tool, and then halt to ask you for the missing information before executing:
**Test 1: Core System Diagnostics**
* **Prompt:** *"Are you connected to the backend proxy? Give me a status report on the connection."*
* **Expected Tool:** `get_proxy_status`
* **What to expect:** The agent should instantly fire the tool (no params needed).
**Test 2: Power Diagnostics**
* **Prompt:** *"Can you grab the current power metrics and consumption data for my server?"*
* **Expected Tool:** `power_management` or `power_supply_metrics_management`
* **What to expect:** The agent should halt and ask for missing IDs.
* **What to type:** When it asks, type `1` for the `ChassisId`, and `1` for the `PowerSupplyId`.
**Test 3: Compatibility Engine**
* **Prompt:** *"I need to run a compatibility check against a target server before we deploy anything to it."*
* **Expected Tool:** `check_workflow_compatibility` or `drake_compatibility_validate`
* **What to expect:** The agent should stop and ask you for the specific `workflow_id`.
* **What to type:** When it asks, type `wf_c_616cc9a0` (a firmware update workflow ID). If it asks for an IP, type `192.168.1.100`.
**Test 4: Hierarchical Tool Exposure (Wow Factor Test)**
* **Prompt:** *"Expand the Dell RAID Service Operations workflow to show fine-grained steps."*
* **Expected Tool:** `expand_workflow`
* **What to expect:** The agent calls the tool, and the proxy dynamically injects new micro-tools into the context window for granular debugging. You can then say *"Collapse the Dell RAID workflow back to clean up the context"* to fire `collapse_workflow`.
**Test 5: Complex Nested Management**
* **Prompt:** *"Fetch the current metrics and capabilities for the Fibre Channel network."*
* **Expected Tool:** `dell_f_c_management`
* **What to expect:** The agent will map "Fibre Channel" to the tool, realize it is missing many nested IDs, and prompt you to provide them.
**Test 6: Rollback and Reversion Execution**
* **Prompt:** *"I need to rollback the last configuration change we made on server 192.168.1.150."*
* **Expected Tool:** `revert_previous_action`
* **What to expect:** The agent should call the revert tool, specifying `server_ip`. Depending on the last action logged, the proxy executes the appropriate simulated rollback strategy:
* **NONE**: If the last workflow has no rollback capability, it is rejected.
* **SCP_SNAPSHOT**: Reverts system configuration using the automatically exported SCP XML snapshot.
* **DUAL_BANK**: Switches active firmware partitions via simulated warm reboot.
* **What to type:** Provide `192.168.1.150` if prompted for the server IP.
> **Testing Tip:** When the agent replies asking for missing IDs, simply invent dummy IDs (e.g., `System.Embedded.1` or `CPU.1`) and give them back to it to watch it successfully execute the simulated tool!
---
## 🎬 Video Demonstration Command Guide
This section outlines the step-by-step command sequence and visual actions for recorded presentations and demonstration shoots:
### **Scene 1: The Problem**
* **Visual Action**: Open the terminal.
* **Commands**:
```powershell
# 1. View the first 30 lines of the raw OpenAPI spec
head -30 data/raw_specs/openapi-7.xx.yaml
# 2. Show the massive count of operations (500+)
grep -c "operationId:" data/raw_specs/openapi-7.xx.yaml
```
### **Scene 2: Architecture Overview**
* **Visual Action**: Display the architecture diagram on screen and hover/point to each stage (Ingestion DAG, Governance Interceptor, FastMCP Server, Execution/Rollback).
* **Commands**: *None (Visual slide/diagram presentation).*
### **Scene 3: CLI Magic & Health**
* **Visual Action**: Run CLI commands in the terminal to show groups, overview metrics, and system status.
* **Commands**:
```powershell
# 1. Show the main CLI help menu and the 7 command groups
drake --help
# 2. Query the SQLite database for the executive overview
drake overview
# 3. Perform a health check of all subsystems
drake health
```
### **Scene 4: Clustering & DAG Verification**
* **Visual Action**: Show the cluster statistics and output the network graph.
* **Commands**:
```powershell
# 1. View the semantic workflow clusters summary
drake cluster summary
# 2. View the generated Leiden community detection network graph
drake cluster graph
```
### **Scene 5: Governance & Guardrails**
* **Visual Action**: Split your screen.
* **Left side (Terminal)**: Manage reviews.
* **Right side (Browser)**: Navigate to `http://localhost:3000` to show risk badges, audit tab, and UI-based reviews.
* **Commands (Terminal)**:
```powershell
# 1. List pending workflows waiting for human review
drake governance pending
# 2. Review the detailed API steps of a specific workflow (replace <id> with a pending workflow ID, e.g. wf_c_21621502)
drake governance review <id>
# 3. Approve the workflow to register it as a live MCP tool
drake governance approve <id>
```
### **Scene 6: AI Agent Execution**
* **Visual Action**: Full-screen terminal. Launch the interactive agent using a local Ollama model and send prompts.
* **Commands**:
```powershell
# 1. Set the proxy URL environment variable (port 8001) and launch the interactive agent
# Note: For Windows PowerShell:
$env:MCP_PROXY_URL="http://localhost:8001/mcp/sse"; python scripts/interactive_agent.py
# Note: For Git Bash / Linux / macOS:
# MCP_PROXY_URL=http://localhost:8001/mcp/sse python scripts/interactive_agent.py
```
* **Agent Prompts to Type**:
1. `Check the proxy status and list available workflow tools`
2. `Expand the Dell RAID Service Operations workflow to show fine-grained steps`
3. `Collapse the Dell RAID workflow back to clean up the context`
### **Scene 7: Compatibility & Rollback**
* **Visual Action**: Check compatibility for a workflow target, then launch the agent again to execute a configuration and trigger a rollback.
* **Commands**:
```powershell
# 1. Run the Compatibility Cockpit check (replace <workflow_id> with your active workflow ID, e.g., wf_c_3383c7f8)
drake compatibility dashboard <workflow_id> --target-ip 192.168.0.120
# 2. Launch the agent again
$env:MCP_PROXY_URL="http://localhost:8001/mcp/sse"; python scripts/interactive_agent.py
```
* **Agent Prompts to Type**:
1. `Deploy the BIOS configuration setup on server 192.168.1.150 with override policy WARN_ONLY.`
2. `Rollback the previous configuration change on server 192.168.1.150.`
### **Scene 8: The Dashboard Tour**
* **Visual Action**: Full-screen your browser at `http://localhost:3000`. Click through the following sections:
* **Dashboard** (KPIs)
* **Workflows** (Approvals and risk analysis)
* **Graph** (Visual representation of Leiden clustering)
* **Metrics** (Token savings & endpoint reduction charts)
* **Audit** (SHA-256 ledger)
* **Commands**: *None (Browser walkthrough).*
### **Scene 9: Closing**
* **Visual Action**: Bring the terminal back to full focus and show the final version output.
* **Commands**:
```powershell
# Show the package version to close out the demo
drake --version
```
---
## 🤖 AI Agent Terminal (Dual-Mode)
Drake includes an Ollama-powered AI agent that understands natural language and can execute **both** infrastructure workflows and platform admin commands:
```powershell
# Launch via start.ps1 or start.sh (recommended) — choose Y when prompted
.\windows_scripts\start.ps1
# Or launch manually after activating venv
python scripts/interactive_agent.py
```
The agent has **two tool namespaces**:
| Mode | When the LLM uses it | Example prompt |
|---|---|---|
| **CLI** (`cli`) | Platform admin: cluster, govern, audit, diagnose | *"show me pending workflows"* |
| **MCP** (`mcp`) | Infrastructure execution: firmware, config, rollback | *"execute the firmware update workflow"* |
---
## ⚙️ Advanced Usage (Manual Commands)
If you prefer to run commands manually instead of using the AI agent, activate the virtual environment first:
```powershell
# 1. Activate venv (once per terminal session)
.venv\Scripts\Activate.ps1
# 2. Print global help instructions and subcommand catalog
drake --help
# 3. Render the executive control plane dashboard overview
drake overview
# 4. Verify subsystem readiness and health assessment matrix
drake health
```
---
## 📜 Command Reference
The Command Center organizes operational tasks into specialized command groups:
### 1. `cluster`
Manages AI clustering, OpenAPI integrations, and spec parsing.
* **`summary`** - Render clustering metrics and distribution data.
* **`graph`** - Display active relationship graphs of endpoints.
* **`run --spec <path>`** - Parse an OpenAPI specification file and regenerate workflow clusters.
### 2. `governance`
Enforces human-in-the-loop review cycles for LLM-generated workflows.
* **`pending`** - List all workflows awaiting human approval.
* **`approved`** - List all certified/approved operational workflows.
* **`rejected`** - List workflows blocked or rejected by operators.
* **`review <workflow_id>`** - Inspect a workflow's details and constituent API steps.
* **`approve <workflow_id>`** - Approve a pending workflow, promoting it to an executable FastMCP tool.
* **`reject <workflow_id> --reason <text>`** - Reject a workflow and document the audit reason.
### 3. `compatibility`
Pre-flight verification intelligence.
* **`validate <workflow_id> --target-ip <ip>`** - Validate workflow steps against target hardware.
* **`explain <workflow_id>`** - Render the DAG rules tree that evaluates the workflow.
* **`dashboard <workflow_id> --target-ip <ip>`** - Renders the decision cockpit.
* **`rules`** - Print the active policies and compatibility rules catalog.
* **`device <ip>`** - Query stateful cached specifications for a datacenter node.
### 4. `runtime`
Controls the FastMCP integration hooks.
* **`tools`** - List currently exposed FastMCP tools ready for client consumption.
* **`reload`** - Trigger hot-reloads to refresh tool mappings from database states.
* **`execute <tool_name> --params <json>`** - Manually invoke a registered workflow.
### 5. `ansible`
Exports workflow logic to infrastructure-as-code files, automatically translating clustered AI workflows into production-ready `ansible.builtin.uri` playbook YAML for DevOps integration.
* **`preview <workflow_id>`** - Render syntax-highlighted playbook configurations directly on the console.
* **`export <workflow_id> --output <path>`** - Export enriched playbooks directly to files.
### 6. `audit`
Exposes the compliance history ledger.
* **`events`** - List administrative events, modifications, and approvals.
* **`executions`** - Print workflow runs, durations, status codes, and targets.
* **`summary`** - Present compliance summaries and error trends.
### 7. `system`
Prints operational topology data.
* **`topology`** - Display the system dependencies tree.
### 8. `diagnostics`
Evaluates internal health checks.
* **`db`** / **`api`** / **`compatibility`** / **`runtime`** - Troubleshoot connections to database files, REST endpoints, and facts caches.
### 9. `config` & `server`
Administrative daemon controls.
* **`drake config`** - Manage secure `.env` configurations and execution policies natively.
* **`drake server`** - Manage local FastMCP server daemons and proxy states.
---
## ✈️ Flagship Feature: Compatibility Cockpit
The **Compatibility Cockpit** provides a single Go/No-Go verdict before executing any workflow on target hardware:
```bash
drake compatibility dashboard <workflow_id> --target-ip <ip>
```
### Cockpit Panels
1. **Target Device**: Displays model, BIOS version, Lifecycle Controller version, and scan time.
2. **Validation Scores**: Compatibility Score, Risk Score, Blast Radius, Confidence.
3. **Violations**: Lists check failures, expected vs actual properties, and corrective remediation actions.
4. **Prerequisites Dependencies**: Structured tree showing parent-child dependency checks.
5. **Final Execution Verdict**: Bold colored indicator marking either `✓ SAFE TO EXECUTE` or `✗ BLOCK EXECUTION`.
---
## 🛠️ Universal JSON Mode
To support scripting, automation pipeline runs, and DevOps integration, every CLI command supports the `--json` flag:
```bash
drake --json compatibility dashboard test_wf_1 --target-ip 192.168.0.120
```
---
## 🔌 Plugin System
The Command Center includes a self-discovering plugin mechanism located in **`src/cli/plugins/`**. The CLI automatically loads modules that do not start with an underscore (`_`) and registers them as subcommands.
---
## ❓ Troubleshooting
* **Legacy Windows Output Crash (`UnicodeEncodeError`)**: Force the environment to use UTF-8 encoding (`$env:PYTHONIOENCODING="utf-8"`).
* **Packaging Script Location Error (`ModuleNotFoundError`)**: Activate the `uv` virtual environment before running any commands (`.venv\Scripts\Activate.ps1`).
* **SQLite Database Locks**: Run `drake diagnostics db` to check connection status. Ensure the microservice FastAPI server is running with WAL journal modes.
