# 🧠 Cisco ACI Intelligent Explorer — MCP Server

> An AI-powered **Model Context Protocol (MCP)** server that lets any AI assistant (Claude, Cursor, VS Code Copilot, etc.) query and explore your Cisco ACI fabric in natural language.

[![Python](https://img.shields.io/badge/Python-3.10%2B-blue)](https://python.org)
[![MCP](https://img.shields.io/badge/Protocol-MCP%20SSE-green)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/License-MIT-yellow)](LICENSE)

---

## 🌟 What Is This?

This project bridges **Cisco ACI** (Application Centric Infrastructure) and **AI assistants** through the **Model Context Protocol (MCP)**. Instead of manually browsing the APIC GUI or writing REST API calls, you can simply ask your AI:

> *"Which Bridge Domains have Unicast Routing disabled but are still attached to an L3Out?"*
> *"Show me all interfaces on node-101 that are DOWN and explain why."*
> *"What BGP neighbors are configured on leaf-1 and how many are established?"*

The MCP server translates these questions into precise APIC REST API calls and returns structured answers.

---

## 🏗️ Architecture

```
┌─────────────────────┐        MCP / SSE          ┌────────────────────────┐
│   AI Client         │ ◄──────────────────────►  │  ACI MCP Server        │
│  (Claude, Cursor,   │     (127.0.0.1:9000)      │  aci_mcp_server.py     │
│   VS Code, etc.)    │                           │                        │
└─────────────────────┘                           │  ┌──────────────────┐  │
                                                  │  │  RAG Engine      │  │
                                                  │  │  (Semantic Search│  │
                                                  │  │   over ACI MIM)  │  │
                                                  │  └──────────────────┘  │
                                                  │                        │
                                                  │  ┌──────────────────┐  │
                                                  │  │  APIC REST API   │  │
                                                  │  │  Live Queries    │  │
                                                  │  └──────────────────┘  │
                                                  └────────┬───────────────┘
                                                           │ HTTPS
                                                  ┌────────▼───────────────┐
                                                  │   Cisco APIC           │
                                                  │   (your fabric)        │
                                                  └────────────────────────┘
```

---

## 📁 Project Structure

```
cisco-aci-mcp-server/
│
├── aci_mcp_server.py          ← 🚀 Main MCP Server (run this daily)
├── apic_config.py             ← 🔑 APIC credentials (configure before first use)
├── requirements.txt           ← 📦 Python dependencies (pip install -r requirements.txt)
│
├── mcp_config/
│   ├── aci_rag_dataset.json   ← ACI class knowledge base (~2.4 MB, 1000+ classes)
│   ├── aci_rag_embeddings.npy ← Pre-computed semantic embeddings (~9 MB)
│   └── aci_filters.json       ← APIC query filter reference guide
│
├── download_classes.py        ← 🔄 One-time: downloads ACI class metadata from Cisco DevNet
├── build_rag_dataset.py       ← 🔄 One-time: builds the RAG knowledge base
│
└── aci_advanced_test_results.md   ← Sample: 32 real-world scenario test output (Markdown)
```

---

## 🛠️ Available MCP Tools

The server exposes **12 tools** to the AI client:

| Tool | Type | Description |
|------|------|-------------|
| `search_aci_schema` | 📚 Schema | Semantic search across 1000+ ACI classes using natural language |
| `get_class_properties` | 📚 Schema | All properties of an ACI class with types and descriptions (supports fuzzy case-matching) |
| `get_class_children` | 📚 Schema | Child classes that can exist under a given parent class (supports fuzzy case-matching) |
| `get_class_parents` | 📚 Schema | Parent classes that contain a given class (supports fuzzy case-matching) |
| `get_class_relations` | 📚 Schema | Unified tool to explore logical relations (incoming, outgoing, or both) for a class |
| `get_class_relations_to` | 📚 Schema | Outgoing relations that originate FROM a given class pointing TO others |
| `get_class_relations_from` | 📚 Schema | Incoming relations that point TO a given class FROM others |
| `build_aci_filter` | 🔧 Utility | Constructs a syntactically valid and properly escaped ACI query filter string (prevents parens errors) |
| `get_live_object_sample` | 🔴 Live | Fetches one real live object from APIC to show actual field values (supports fuzzy case-matching) |
| `get_live_class_objects` | 🔴 Live | Queries live APIC for all objects of a class with filters, pagination, and client-side attribute filtering |
| `get_live_object_by_dn` | 🔴 Live | Fetches a specific Managed Object by its Distinguished Name with client-side attribute filtering |
| `get_api_query_guide` | 📖 Guide | Reference guide for building APIC filter queries |

---

## ⚡ Quick Start

### 1. Prerequisites

- Python **3.10+**
- Access to a Cisco APIC (or use the free [Cisco DevNet Sandbox](https://devnetsandbox.cisco.com/))
- An AI client that supports MCP over SSE (Claude Desktop, Cursor, VS Code with MCP extension, etc.)

### 2. Install Dependencies

```bash
pip install -r requirements.txt
```

Or install individually:
```bash
pip install fastmcp httpx sentence-transformers numpy urllib3
```

### 3. Configure Your APIC

Edit `apic_config.py`:

```python
APIC_SERVERS = [
    {
        "apicname": "myFabric",           # Name you choose (used in queries)
        "url": "https://192.168.10.10",   # Your APIC IP or FQDN
        "username": "admin",
        "password": "YourPassword"
    }
]
```

> ⚠️ **Security:** Never commit real credentials to a public repository.
> Use environment variables or a secrets manager in production deployments.

### 4. Start the MCP Server

```bash
python aci_mcp_server.py
```

Expected output:
```
INFO: Starting MCP server 'Cisco ACI Intelligent Explorer Agent' with transport 'sse' on http://127.0.0.1:9000/sse
INFO: Uvicorn running on http://127.0.0.1:9000
```

### 5. Connect Your AI Client

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}
```

**Cursor** — add to `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "cisco-aci": {
      "url": "http://127.0.0.1:9000/sse"
    }
  }
}
```

---

## 🔄 Script Reference — When to Run What

The main server (`aci_mcp_server.py`) is the **only file you run day-to-day**. The other scripts are one-time setup or periodic update tools:

### `aci_mcp_server.py` — Run Every Time You Use the System
```bash
python aci_mcp_server.py
```
- Starts the MCP server on `http://127.0.0.1:9000/sse`
- Loads the RAG dataset and semantic model on startup (~10-15 seconds)
- Restart this if you: edit `apic_config.py`, add new APIC servers, or update `mcp_config/` files

---

### `download_classes.py` — Run Once at Setup (or on ACI Version Upgrade)
```bash
python download_classes.py
```
- Downloads ACI class metadata from Cisco DevNet documentation
- Saves JSON files into `aci_classes_json/` directory
- **When to re-run:** Only when Cisco releases a new ACI software version and you want updated class definitions

---

### `build_rag_dataset.py` — Run After `download_classes.py`
```bash
python build_rag_dataset.py
```
- Reads all JSON files from `aci_classes_json/`
- Enriches data with a curated **Acronyms/Synonyms Dictionary** (29 entries: VRF, EPG, BD, AEP, vPC, LACP, OSPF, CDP, STP, VMM domain, L3Out EPG, Filter/ACL, Contract Subject, VLAN Pool and more)
- Dynamically extracts **configurable properties** (`isConfigurable=True`) for all classes to prevent system noise
- Builds `mcp_config/aci_rag_dataset.json` (the knowledge base)
- Computes vector embeddings → `mcp_config/aci_rag_embeddings.npy`
- **When to re-run:** After `download_classes.py`, or if you modify class data / synonym mappings

---

### Full Setup Flow (First-Time or ACI Version Update)
```
Step 1:  python download_classes.py
         └─ Downloads class metadata from Cisco DevNet → aci_classes_json/

Step 2:  python build_rag_dataset.py
         └─ Builds knowledge base → mcp_config/aci_rag_dataset.json
         └─ Computes embeddings   → mcp_config/aci_rag_embeddings.npy

Step 3:  python aci_mcp_server.py
         └─ Server ready at http://127.0.0.1:9000/sse
```

> 💡 **Tip:** The `mcp_config/` files are already included in this repository.
> For most users, **you only need Step 3** (start the server directly).
> Steps 1 and 2 are only needed when updating for a new Cisco ACI version.

---

## 🔒 Security Design

| Protection | Description |
|-----------|-------------|
| **No credential leaks** | Error messages to AI clients never contain APIC URLs, usernames, passwords, or tokens — sensitive details stay in server logs only |
| **GET-only** | The server exclusively uses HTTP GET requests — it cannot create, update, or delete any fabric object |
| **Rate limiting** | Sliding-window limiter (30 requests / 60 seconds) prevents AI loops from flooding your APIC |
| **Input validation** | All DN inputs are validated with a strict regex — path traversal attacks and injection attempts are blocked before any network call |
| **Page size control** | Single queries return at most 1,000 objects; pagination with `page` parameter supports fetching large datasets safely |
| **Client-Side Attribute Filtering** | Prevents 400 Bad Request by fetching all fields internally from APIC and filtering attributes in Python (`rsp_props`) before returning JSON |
| **Case-Insensitive Normalization** | Prevents AI matching errors by dynamically normalising query class names (e.g. `fvbd` -> `fvBD`) |
| **AI Error Recovery Hints** | Every validation error (invalid filter, bad DN, wrong rsp_props, rate limit) includes a `_retry_hint` field that tells the AI exactly how to fix and retry the call |

---

## 💬 Example Queries

Once connected, ask your AI natural language questions:

```
"Show me all tenants in the fabric"
"Which EPGs are providing the 'web-contract'?"
"Find all Bridge Domains without subnets in tenant CHA_PCIDSS_TN"
"What is the operational status of all ports on node-101?"
"Are there any faults with severity 'critical' or 'major'?"
"Show BGP peer configuration for node-101 and compare to runtime state"
"Which LLDP policies have TX disabled and where are they applied?"
"Find EPGs with static port bindings but no active endpoints"
"What are the active VTEP tunnels and which nodes do they belong to?"
```

---

## 📋 Requirements

```
fastmcp>=0.1.0
httpx
sentence-transformers
numpy
urllib3
```

Install all at once:
```bash
pip install fastmcp httpx sentence-transformers numpy urllib3
```

---

## 🧪 Test Results

See [aci_advanced_test_results.md](aci_advanced_test_results.md) for a complete diagnostics test run output.

A total of **32 real-world operational and audit scenarios** (including advanced troubleshooting, logical relation tracing, DN drill-down exploration, and example query runs) were successfully executed against the Cisco DevNet Sandbox APIC. The results file contains full details of the tool call flows, arguments, and live APIC responses, demonstrating successful end-to-end execution of the MCP server.

---

## 🤝 Contributing & Feedback

Contributions, issues, and feature requests are welcome! Feel free to:
- Open an **Issue** to report bugs or suggest new features.
- Start a **Discussion** (if enabled) if you have questions or ideas to share.
- Submit a **Pull Request** (PR) to improve the codebase.

For direct feedback, you can reach out via email: ciftcigkhn@gmail.com

---

## 📄 License

This project is provided for educational and operational use under the MIT License. Not affiliated with or endorsed by Cisco Systems, Inc.

---

## 🇹🇷 Türkçe Dokümantasyon

Türkçe kullanım kılavuzu için bkz: [README_TR.md](README_TR.md)