内容
<h1 align="center">思科 ACI 的社区 MCP 服务器<br /><br /></h1>
<div align="center">
<img src="https://img.shields.io/badge/Cisco-ACI-049fd9?style=flat-square&logo=cisco&logoColor=white" alt="思科 ACI">
<img src="https://img.shields.io/badge/MCP-Protocol-000000?style=flat-square&logo=anthropic&logoColor=white" alt="MCP">
<img src="https://img.shields.io/badge/FastMCP-Library-7B2CBF?style=flat-square&logo=python&logoColor=white" alt="FastMCP">
<img src="https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python">
</div>
<br />
<p align="center">
<img src="docs/images/banner.jpg" alt="思科 ACI MCP 服务器" width="900">
</p>
<div align="center">
一个使用 <a href="https://github.com/jlowin/fastmcp"><strong>FastMCP</strong></a> 构建的<strong>独立 MCP 服务器</strong>，它暴露了<strong>50个 ACI 操作</strong>作为 MCP 工具。连接任何<strong>兼容 MCP 的客户端</strong>和<strong>LLM</strong>，通过自然语言查询、配置和管理您的思科 ACI Fabric。
</div>
<h2 align="center">🎥 观看演示</h2>
<p align="center">
<a href="https://www.youtube.com/watch?v=ONOgrUq3Z5w">
<img src="https://img.youtube.com/vi/ONOgrUq3Z5w/maxresdefault.jpg"
alt="思科 ACI MCP 服务器演示"
width="800">
</a>
</p>
---
## 目录
1. [概述](#overview)
2. [功能](#features)
3. [要求](#requirements)
4. [可用的 MCP 工具](#available-mcp-tools)
5. [可用的传输选项](#available-transport-options)
6. [安装](#installation)
7. [身份验证](#authentication)
8. [运行服务器](#running-the-server)
9. [使用示例：VS Code](#usage-example-vs-code)
---
## 概述
该 MCP 服务器作为思科 ACI（Application Centric Infrastructure）和任何兼容 MCP 的客户端之间的轻量级中间层。它允许 LLM 查询 ACI Fabric，检查租户、EPG、桥接域、故障和 Fabric 健康状况 - 以及创建或删除策略对象 - 所有这些都通过结构化的 MCP 工具。
该项目是一个社区项目，不受思科任何业务或技术实体的官方支持。
服务器使用基于 Cookie 的身份验证与 APIC REST API 通信，并支持 50 个涵盖整个 ACI 策略模型的 操作。
---
## 功能
- **即插即用** - 与任何兼容 MCP 的客户端（VS Code Copilot、Claude Desktop、N8N 等）配合使用
- **50 个 ACI 操作** - 跨租户、EPG、桥接域、VRF、合同、Fabric 节点等进行 GET 和 POST
- **Fabric 健康和故障** - 查询故障摘要、关键故障和节点健康状况
- **自动重新身份验证** - 在令牌过期时透明地刷新 APIC 会话
- **复合操作** - 单个工具命令部署完整的 3 层应用程序或 Web 堆栈
- **无硬编码凭证** - 所有机密均来自 `.env` 文件
- **完全类型提示工具**，用于清晰和可扩展性
---
## 要求
- Python 3.13+
- 访问思科 APIC（本地或沙盒）
- 具有读和/或写权限的 APIC 用户
**Python 依赖项**（`requirements.txt`）：
| 包 | 目的 |
|---------|---------|
| `fastmcp` | MCP 服务器框架 |
| `httpx` | APIC API 调用的异步 HTTP 客户端 |
| `python-dotenv` | 从 `.env` 加载凭证 |
| `pydantic` | 数据验证 |
| `requests` | 补充 HTTP 支持 |
---
## 可用的 MCP 工具
### 连接和测试（1 个工具）
| 工具 | 描述 |
|------|-------------|
| `aci_simple_test()` | 验证与 MCP 服务器的连接 |
### 核心基础设施 - GET（12 个工具）
| 工具 | 描述 |
|------|-------------|
| `aci_tenants_get()` | 列出所有租户 |
| `aci_application_profiles_get()` | 列出所有应用程序配置文件 |
| `aci_endpoint_groups_get()` | 列出所有 EPG |
| `aci_bridge_domains_get()` | 列出所有桥接域 |
| `aci_contexts_get()` | 列出所有 VRF |
| `aci_subnets_get()` | 列出所有子网 |
| `aci_contracts_get()` | 列出所有合同 |
| `aci_contract_subjects_get()` | 列出所有合同主题 |
| `aci_filters_get()` | 列出所有筛选器 |
| `aci_filter_entries_get()` | 列出所有筛选器条目 |
| `aci_endpoints_get()` | 列出所有已学习的端点 |
| `aci_faults_get()` | 列出所有故障（故障摘要） |
### Fabric 和基础设施 - GET（8 个工具）
| 工具 | 描述 |
|------|-------------|
| `aci_fabric_nodes_get()` | 列出所有 Fabric 节点（叶子、脊柱、APIC） |
| `aci_fabric_health_get()` | 获取整体 Fabric 健康分数 |
| `aci_fabric_links_get()` | 列出所有 Fabric 链接 |
| `aci_physical_interfaces_get()` | 列出所有物理接口 |
| `aci_ethernet_interfaces_get()` | 列出所有以太网接口状态 |
| `aci_vlan_pools_get()` | 列出所有 VLAN 池 |
| `aci_domains_get()` | 列出所有物理域 |
| `aci_critical_faults_get()` | 列出仅严重级别的故障 |
### 核心策略 - 创建（13 个工具）
| 工具 | 参数 | 描述 |
|------|-----------|-------------|
| `aci_tenant_create` | `tenant_name`, `description?` | 创建新租户 |
| `aci_vrf_create` | `tenant_name`, `vrf_name`, `description?` | 创建 VRF |
| `aci_bridge_domain_create` | `tenant_name`, `vrf_name`, `bd_name`, `subnet_ip?` | 创建桥接域 |
| `aci_application_profile_create` | `tenant_name`, `app_name`, `description?` | 创建应用程序配置文件 |
| `aci_epg_create` | `tenant_name`, `app_name`, `epg_name`, `bd_name` | 创建 EPG |
| `aci_contract_create` | `tenant_name`, `contract_name`, `description?` | 创建合同 |
| `aci_contract_subject_create` | `tenant_name`, `contract_name`, `subject_name`, `filter_name` | 创建合同主题 |
| `aci_filter_create` | `tenant_name`, `filter_name`, `description?` | 创建筛选器 |
| `aci_filter_entry_create` | `tenant_name`, `filter_name`, `entry_name`, `protocol?`, `dst_port?` | 创建筛选器条目 |
| `aci_epg_contract_provider_bind` | `tenant_name`, `app_name`, `epg_name`, `contract_name` | 绑定 EPG 作为合同提供者 |
| `aci_epg_contract_consumer_bind` | `tenant_name`, `app_name`, `epg_name`, `contract_name` | 绑定 EPG 作为合同消费者 |
| `aci_epg_domain_bind` | `tenant_name`, `app_name`, `epg_name`, `domain_name`, `domain_type?` | 将 EPG 附加到物理或 VMM 域 |
| `aci_subnet_create` | `tenant_name`, `bd_name`, `subnet_ip`, `scope?` | 在桥接域中添加子网 |
### L3 网络（6 个工具）
| 工具 | 描述 |
|------|-------------|
| `aci_l3_outside_get()` | 列出所有 L3Out |
| `aci_external_networks_get()` | 列出所有外部 EPG |
| `aci_bgp_peers_get()` | 列出所有 BGP 对等体 |
| `aci_l3out_create` | 创建新的 L3Out |
| `aci_external_epg_create` | 在 L3Out 下创建外部 EPG |
### 高级/复合操作（8 个工具）
| 工具 | 描述 |
|------|-------------|
| `aci_vlan_pool_create` | 创建具有封装块的 VLAN 池 |
| `aci_physical_domain_create` | 创建物理域并附加 VLAN 池 |
| `aci_create_3tier_app` | 部署完整的 3 层应用（Web/App/DB），具有 BD、EPG、筛选器、合同 |
| `aci_create_web_app_stack` | 部署 Web + 应用堆栈端到端 |
| `aci_tenant_delete` | 删除租户（谨慎使用） |
| `aci_epg_delete` | 删除 EPG |
| `aci_contract_delete` | 删除合同 |
| `aci_get_operations_summary` | 返回所有 50 个操作的已结构列表 |
---
## 可用的传输选项
| 模式 | 描述 |
|------|-------------|
| `stdio` | 标准 I/O - 用于由 VS Code、Claude Desktop 等管理的本地客户端 |
`scripts/server.py` 中的服务器以 **stdio** 模式运行。 VS Code 通过 `mcp.json` 自动管理进程生命周期。
---
## 安装
克隆存储库并运行交互式设置脚本：
```bash
git clone <your-repo-url>
cd aci_mcp_devnet_submission
./setup.sh
```
`setup.sh` 脚本将：
1. 提示输入 APIC URL、用户名和密码
2. 将凭证写入 `scripts/.env`
3. 通过 `pip` 安装所有 Python 依赖项
4. 打印启动服务器的说明
或者，手动设置：
```bash
cd aci_mcp_devnet_submission
pip install -r requirements.txt
# 手动创建 scripts/.env：
cat > scripts/.env <<EOF
APIC_URL=https://<your-apic-ip>/
USERNAME=<your-username>
PASSWORD=<your-password>
EOF
```
---
## 身份验证
服务器使用基于 Cookie 的会话身份验证（`aaaLogin`）与 APIC 进行身份验证。凭证在启动时从 `scripts/.env` 加载。
**`scripts/.env` 格式：
```bash
APIC_URL=https://10.x.x.x/
USERNAME=admin
PASSWORD=yourpassword
```
服务器在 APIC 会话令牌过期（HTTP 403）时自动重新身份验证，因此长期会话无需手动干预即可保持连接。
> **安全注意：** `scripts/.env` 文件在 `.gitignore` 中列出 - 永远不要将真实凭证提交到源代码管理。
---
## 运行服务器
### 方法 1：直接 Python（推荐）
```bash
cd scripts
python3 server.py
```
### 方法 2：通过 setup.sh（首次设置 + 运行）
```bash
cd aci_mcp_devnet_submission
./setup.sh
# 按照提示，然后：
cd scripts && python3 server.py
```
### 方法 3：FastMCP 开发模式（文件更改自动重新加载）
```bash
cd scripts
fastmcp dev server.py
```
---
## 使用示例：VS Code
**VS Code 2 中的 GitHub Copilot** 具有内置的 MCP 客户端。 将 ACI MCP 服务器添加到 VS Code 的 `mcp.json` 中，即可直接从 Copilot 聊天窗口使用它。
### 步骤 1 - 添加到 mcp.json
打开 VS Code 用户 `mcp.json`（`Cmd+Shift+P` → *打开 MCP 服务器配置*），并添加：
```json
{
"servers": {
"my-aci-mcp-server": {
"type": "stdio",
"command": "python3",
"args": [
"/absolute/path/to/aci_mcp_devnet_submission/scripts/server.py"
]
}
}
}
```
> 将 `/absolute/path/to/` 替换为计算机上的实际路径。
### 步骤 2 - 启动服务器
VS Code 在打开 Copilot 聊天会话时自动启动服务器。 您也可以从 VS Code 状态栏中的 MCP 面板手动启动/重启它。
### 步骤 3 - 与 ACI Fabric 聊天
打开 **GitHub Copilot Chat**（`Cmd+Shift+I`）并尝试自然语言提示：
**📋 查询 Fabric：**
```
显示 Fabric 中的所有故障
```
```
列出前 10 个租户
```
```
当前的 Fabric 健康分数是多少？
```
**🏗️ 配置策略：**
```
在租户“MyApp_Tenant”中创建一个名为“MyApp_Tenant”的新租户
```
```
在租户“Prod_Tenant”中部署一个名为“ECommerceApp”的 3 层应用程序
```
```
在租户“Prod_Tenant”的桥接域“app_bd”中添加子网 192.168.10.1/24
```
**🩺 故障排除：**
```
显示所有关键故障
```
```
获取 Fabric 中的所有 BGP 对等体
```
```
列出 Fabric 中当前学习的所有端点
```
LLM 将自动选择正确的 MCP 工具（s），调用 APIC REST API，并返回聊天窗口中的结构化结果。
---
