内容
# 🧠 思科 ACI 智能探索器 — MCP 服务器
> 一个由人工智能驱动的 **模型上下文协议（MCP）** 服务器，允许任何人工智能助手（Claude、Cursor、VS Code Copilot 等）以自然语言查询和探索您的思科 ACI 结构。
[](https://python.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
---
## 🌟 这是什么？
该项目通过 **模型上下文协议（MCP）** 连接 **思科 ACI（Application Centric Infrastructure）** 和 **人工智能助手**。您不再需要手动浏览 APIC GUI 或编写 REST API 调用，而是可以直接询问您的人工智能：
> *"哪些桥接域的单播路由已禁用，但仍连接到 L3Out？*"
> *"显示给我节点 101 上所有处于 DOWN 状态的接口及其原因。*"
> *"leaf-1 上配置了哪些 BGP 邻居，多少个邻居已建立？*"
MCP 服务器会将这些问题翻译成精确的 APIC REST API 调用，并返回结构化的答案。
---
## 🏗️ 架构
```
┌─────────────────────┐ MCP / SSE ┌────────────────────────┐
│ AI 客户端 │ ◄──────────────────────► │ ACI MCP 服务器 │
│ (Claude, Cursor, │ (127.0.0.1:9000) │ aci_mcp_server.py │
│ VS Code 等) │ │ │
└─────────────────────┘ │ ┌──────────────────┐ │
│ │ RAG 引擎 │ │
│ │ (ACI MIM 的语义搜索│ │
│ │ ) │ │
│ └──────────────────┘ │
│ │
│ ┌──────────────────┐ │
│ │ APIC REST API │ │
│ │ 即时查询 │ │
│ └──────────────────┘ │
└────────┬───────────────┘
│ HTTPS
┌────────▼───────────────┐
│ 思科 APIC │
│ (您的结构) │
└────────────────────────┘
```
---
## 📁 项目结构
```
cisco-aci-mcp-server/
│
├── aci_mcp_server.py ← 🚀 主要 MCP 服务器（每天运行）
├── apic_config.py ← 🔑 APIC 凭证（首次使用前配置）
├── requirements.txt ← 📦 Python 依赖项（pip install -r requirements.txt）
│
├── mcp_config/
│ ├── aci_rag_dataset.json ← ACI 类知识库（~2.4 MB，1000+ 类）
│ ├── aci_rag_embeddings.npy ← 预计算的语义嵌入（~9 MB）
│ └── aci_filters.json ← APIC 查询过滤器参考指南
│
├── download_classes.py ← 🔄 一次性：从思科 DevNet 下载 ACI 类元数据
├── build_rag_dataset.py ← 🔄 一次性：构建 RAG 知识库
│
└── aci_advanced_test_results.md ← 示例：32 个真实场景测试输出（Markdown）
```
---
## 🛠️ 可用的 MCP 工具
服务器向 AI 客户端公开 **12 种工具**：
| 工具 | 类型 | 描述 |
|------|------|-------------|
| `search_aci_schema` | 📚 架构 | 使用自然语言在 1000+ ACI 类中进行语义搜索 |
| `get_class_properties` | 📚 架构 | 获取 ACI 类的所有属性及其类型和描述（支持模糊大小写匹配） |
| `get_class_children` | 📚 架构 | 获取给定父类下可以存在的子类（支持模糊大小写匹配） |
| `get_class_parents` | 📚 架构 | 获取包含给定类的父类（支持模糊大小写匹配） |
| `get_class_relations` | 📚 架构 | 统一工具，用于探索类的逻辑关系（传入、传出或两者） |
| `get_class_relations_to` | 📚 架构 | 从给定类出发的传出关系，指向其他类 |
| `get_class_relations_from` | 📚 架构 | 指向给定类的传入关系，来自其他类 |
| `build_aci_filter` | 🔧 实用程序 | 构造语法有效的 ACI 查询过滤器字符串（防止括号错误） |
| `get_live_object_sample` | 🔴 即时 | 从 APIC 获取一个真实的对象，以显示实际字段值（支持模糊大小写匹配） |
| `get_live_class_objects` | 🔴 即时 | 查询 APIC 获取给定类下的所有对象，支持过滤、分页和客户端属性过滤 |
| `get_live_object_by_dn` | 🔴 即时 | 通过其区分名称获取特定的受管对象，支持客户端属性过滤 |
| `get_api_query_guide` | 📖 指南 | 用于构建 APIC 过滤器查询的参考指南 |
---
## ⚡ 快速入门
### 1. 先决条件
- Python **3.10+**
- 访问思科 APIC（或使用免费的 [思科 DevNet 沙盒](https://devnetsandbox.cisco.com/)）
- 支持 MCP over SSE 的 AI 客户端（Claude Desktop、Cursor、带有 MCP 扩展的 VS Code 等）
### 2. 安装依赖项
```bash
pip install -r requirements.txt
```
或单独安装：
```bash
pip install fastmcp httpx sentence-transformers numpy urllib3
```
### 3. 配置您的 APIC
编辑 `apic_config.py`:
```python
APIC_SERVERS = [
{
"apicname": "myFabric", # 您选择的名称（用于查询）
"url": "https://192.168.10.10", # 您的 APIC IP 或 FQDN
"username": "admin",
"password": "您的密码"
}
]
```
> ⚠️ **安全：** 永远不要将真实的凭证提交到公共存储库中。
> 在生产部署中，请使用环境变量或机密管理器。
### 4. 启动 MCP 服务器
```bash
python aci_mcp_server.py
```
预期输出：
```
INFO: 启动 MCP 服务器 '思科 ACI 智能探索器代理'，使用 'sse' 传输协议，监听 http://127.0.0.1:9000/sse
INFO: Uvicorn 运行于 http://127.0.0.1:9000
```
### 5. 连接您的 AI 客户端
**Claude Desktop** — 添加到 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"cisco-aci": {
"url": "http://127.0.0.1:9000/sse"
}
}
}
```
**Cursor** — 添加到 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"cisco-aci": {
"url": "http://127.0.0.1:9000/sse"
}
}
}
```
---
## 🔄 脚本参考 — 何时运行什么
主要服务器 (`aci_mcp_server.py`) 是您 **每天运行的唯一文件**。其他脚本是一次性设置或定期更新工具：
### `aci_mcp_server.py` — 每次使用系统时运行
```bash
python aci_mcp_server.py
```
- 在 `http://127.0.0.1:9000/sse` 上启动 MCP 服务器
- 加载 RAG 数据集和语义模型（~10-15 秒）
- 如果您编辑 `apic_config.py`、添加新的 APIC 服务器或更新 `mcp_config/` 文件，请重启此服务器
---
### `download_classes.py` — 设置时运行一次（或升级 ACI 版本时）
```bash
python download_classes.py
```
- 从思科 DevNet 文档下载 ACI 类元数据
- 将 JSON 文件保存到 `aci_classes_json/` 目录
- **何时重新运行：** 仅当思科发布新的 ACI 软件版本并且您想要更新的类定义时
---
### `build_rag_dataset.py` — 在 `download_classes.py` 之后运行
```bash
python build_rag_dataset.py
```
- 读取 `aci_classes_json/` 下的所有 JSON 文件
- 使用精选的 **首字母缩写词/同义词词典**（29 个条目：VRF、EPG、BD、AEP、vPC、LACP、OSPF、CDP、STP、VMM 域、L3Out EPG、过滤器/ACL、合约主题、VLAN 池等）丰富数据
- 动态提取所有类的 **可配置属性** (`isConfigurable=True`) 以防止系统噪音
- 构建 `mcp_config/aci_rag_dataset.json`（知识库）
- 计算向量嵌入 → `mcp_config/aci_rag_embeddings.npy`
- **何时重新运行：** 在运行 `download_classes.py` 之后，或如果您修改类数据/同义词映射
---
### 完整设置流程（首次或 ACI 版本更新）
```
步骤 1： python download_classes.py
└─ 从思科 DevNet 下载类元数据 → aci_classes_json/
步骤 2： python build_rag_dataset.py
└─ 构建知识库 → mcp_config/aci_rag_dataset.json
└─ 计算嵌入 → mcp_config/aci_rag_embeddings.npy
步骤 3： python aci_mcp_server.py
└─ 服务器准备就绪，位于 http://127.0.0.1:9000/sse
```
> 💡 **提示：** `mcp_config/` 文件已包含在此存储库中。
> 对于大多数用户，**您只需要步骤 3** （直接启动服务器）。
> 步骤 1 和 2 仅在更新新的思科 ACI 版本时需要。
---
## 🔒 安全设计
| 保护措施 | 描述 |
|-----------|-------------|
| **无凭证泄露** | 错误消息不会将 APIC URL、用户名、密码或令牌等敏感详细信息发送给 AI 客户端 — 敏感详细信息仅保留在服务器日志中 |
| **仅 GET 请求** | 服务器仅使用 HTTP GET 请求 — 它无法创建、更新或删除任何结构对象 |
| **速率限制** | 滑动窗口限制器（30 请求 / 60 秒）防止 AI 环路淹没您的 APIC |
| **输入验证** | 所有 DN 输入都经过严格的正则表达式验证 — 在进行任何网络调用之前阻止路径遍历攻击和注入尝试 |
| **页面大小控制** | 单个查询最多返回 1,000 个对象；分页使用 `page` 参数安全支持获取大型数据集 |
| **客户端属性过滤** | 通过在 Python 中过滤属性（`rsp_props`）防止 400 Bad Request，在返回 JSON 之前从 APIC 内部获取所有字段 |
| **不区分大小写的规范化** | 通过动态规范化查询类名（例如 `fvbd` -> `fvBD`）防止 AI 匹配错误 |
| **AI 错误恢复提示** | 每个验证错误（无效过滤器、错误的 DN、错误的 rsp_props、速率限制）都包含一个 `_retry_hint` 字段，告诉 AI 如何准确修复和重试调用 |
---
## 💬 示例查询
连接后，请向您的 AI 提出自然语言问题：
```
"显示我结构中的所有租户"
"哪些 EPG 提供 'web-contract'？"
"在租户 CHA_PCIDSS_TN 中查找所有没有子网的桥接域"
"节点 101 上所有端口的运行状态是什么？"
"有任何严重性为 'critical' 或 'major' 的故障吗？"
"显示节点 101 的 BGP 对等体配置，并与运行时状态进行比较"
"哪些 LLDP 策略禁用了 TX 并且在哪里应用了它们？"
"查找具有静态端口绑定但没有活动端点的 EPG"
"哪些是活动的 VTEP 隧道，它们属于哪些节点？"
```
---
## 📋 需求
```
fastmcp>=0.1.0
httpx
sentence-transformers
numpy
urllib3
```
一次性安装所有依赖项：
```bash
pip install fastmcp httpx sentence-transformers numpy urllib3
```
---
## 🧪 测试结果
请参阅 [aci_advanced_test_results.md](aci_advanced_test_results.md) 以获取完整的诊断测试运行输出。
总共 **32 个现实世界运行和审计场景** （包括高级故障排除、逻辑关系跟踪、DN 钻取探索和示例查询运行）已成功针对思科 DevNet 沙盒 APIC 执行。结果文件包含工具调用流程、参数和实时 APIC 响应的完整详细信息，展示了 MCP 服务器的端到端成功执行。
---
## 🤝 贡献和反馈
欢迎贡献、问题和功能请求！请随意：
- 打开一个 **问题** 来报告错误或建议新功能。
- 发起一个 **讨论** （如果启用）如果你有问题或想法要分享。
- 提交一个 **拉取请求** （PR）来改进代码库。
有关直接反馈，您可以通过电子邮件联系：ciftcigkhn@gmail.com
---
## 📄 许可证
该项目在 MIT 许可证下提供用于教育和操作使用。 不隶属于或得到思科系统公司（Cisco Systems, Inc.） 的认可。
---
## 🇹🇷 土耳其文档
有关土耳其使用指南，请参见：[README_TR.md](README_TR.md)
