Nautobot MCP 聊天接口

一个独立的、容器化的演示，它暴露了一个用于Nautobot开源平台的FastMCP服务器，并提供了一个轻量级的聊天UI，可以列出可用的MCP工具，调用它们并导出聊天记录。

🚀 版本 2.0：多工具执行与递归工具链

版本2.0引入了先进的并发工具执行和递归工具链功能，能够自动从多个来源收集全面的数据，进行复杂的网络分析查询。

✅ 多工具执行

• 同时执行多个工具以全面收集数据
• 不同数据源之间的自动协调
• 智能查询规划和执行顺序

✅ 递归工具链

• 一个工具的结果自动告知后续工具调用
• 基于先前结果的动态数据驱动工具选择
• 相关查询的无缝链接以进行深入分析

✅ 增强的数据展示

• 使用表格和结构化数据的丰富Markdown格式
• 自动突出显示关键信息（WAN接口、电路等）
• 结合网络拓扑理解的全面分析

✅ 实时状态更新

• 工具执行期间的详细进度跟踪
• 性能指标和时间信息
• 清晰地指示处理阶段和完成情况

✅ 智能上下文管理

• 缓存数据重用以回答后续问题
• 根据上下文响应而无需冗余工具调用
• 对之前收集的信息进行智能分析

📋 目录

• 🚀 快速开始
• 🎯 包含内容
• 🔧 安装步骤
  • 步骤1：启动服务
  • 步骤2：配置环境
  • 步骤3：获取OpenAI API密钥
  • 步骤4：创建管理员用户
  • 步骤5：获取Nautobot API令牌
  • 步骤6：访问聊天UI
• 🛠️ 可用的MCP工具
• 📊 演示数据结构
• 💬 示例查询
• 📤 导出聊天记录
• 🏗️ 架构
• 🤝 贡献新工具
• 🔍 故障排除

🚀 快速开始

# 1. 启动所有服务
docker-compose up -d

# 2. 复制环境文件并配置
cp .env.example .env

# 3. 获取OpenAI API密钥（聊天功能所需）：
#    - 访问 https://platform.openai.com/api-keys
#    - 创建一个新的API密钥
#    - 将其添加到你的.env文件中：OPENAI_API_KEY=your_openai_api_key_here

# 4. 创建管理员用户
docker exec -it nautobot_mcp-1-nautobot-1 nautobot-server createsuperuser --username admin --email admin@example.com

# 5. 获取你的Nautobot API令牌：
#    - 访问 http://localhost:8080 并使用用户名和密码登录
#    - 导航到您的用户资料 → API令牌 → 添加令牌
#    - 复制令牌键并更新你的.env文件：NAUTOBOT_TOKEN=your_api_token_here
#    - 重启服务：docker-compose restart

# 6. 打开聊天UI
#    http://localhost:8501

🎯 包含内容

• Nautobot，带有预填充的演示数据和启用的GraphQL
• FastMCP服务器，将Nautobot实用程序作为MCP工具公开
• 聊天UI，用于测试MCP工具和导出对话
• 演示数据，包括位置、设备、接口和IPAM

🔧 安装步骤

步骤1：启动服务

docker-compose up -d

步骤2：配置环境

cp .env.example .env

步骤3：获取OpenAI API密钥

1. 访问 https://platform.openai.com/api-keys
2. 创建一个新的API密钥
3. 将其添加到你的.env文件中：

   OPENAI_API_KEY=your_openai_api_key_here
   

   注意：这需要正确设置以使聊天功能正常工作。

步骤4：创建管理员用户

docker exec -it nautobot_mcp-nautobot-1 nautobot-server createsuperuser --username admin --email admin@example.com

步骤5：获取Nautobot API令牌

1. 访问 http://localhost:8080 并登录
2. 导航到用户资料 → API令牌 → 添加令牌
3. 复制令牌并更新你的.env文件：

   NAUTOBOT_TOKEN=your_api_token_here
   

4. 重启服务：

   docker-compose restart
   

步骤6：访问聊天UI

在浏览器中打开 http://localhost:8501

🛠️ 可用的MCP工具

1. get_prefixes_by_location_enhanced - 根据位置查询前缀，带格式选项
2. get_devices_by_location - 获取特定位置的设备
3. get_devices_by_location_and_role - 根据位置和角色获取设备
4. get_interfaces_by_device - 获取设备的接口、IP地址和电路信息
5. get_circuits_by_location - 获取特定位置的电路
6. get_circuits_by_provider - 获取特定提供商的电路
7. get_locations - 获取所有可用位置及其层级信息
8. get_providers - 获取所有可用电路提供商
9. 动态工具发现 - 聊天UI自动发现并呈现可用工具

📊 演示数据结构

系统包括一个全面的网络拓扑：

• 位置：区域 → 国家 → 校园/分支机构/数据中心
• 设备：WAN路由器、核心路由器、接入交换机、脊叶交换机
• 接口：正确配置了VLAN和IP地址
• IPAM：与位置和接口关联的前缀

💬 示例查询

在聊天UI中尝试这些查询：

基本位置查询（仅使用精确的位置代码）：

• "NYDC存在哪些前缀？"
• "显示BRCN的所有设备"
• "列出USBN1的设备"
• "LODC有什么？"

发现查询：

• "系统中有哪些可用位置？"
• "显示所有电路提供商"
• "列出所有可用位置及其国家和地区"

电路查询：

• "给我列出BRCN位置的所有电路"
• "显示NYDC和DACN的所有电路"
• "LODC有哪些电路？"
• "列出USBN1和USBN2的所有电路"
• "显示Zayo提供的所有电路"
• "AT&T提供了哪些电路？"
• "列出Level 3的所有电路"

设备角色查询：

• "显示NYDC的所有WAN路由器"
• "列出LODC的所有Spine交换机"
• "BRCN有哪些Leaf交换机？"
• "显示USBN1的所有分支接入交换机"
• "列出DACN的核心路由器"
• "MXCN有哪些校园接入交换机？"

接口查询：

• "BRCN-WAN01有哪些接口？"
• "显示NYDC-CORE-01的所有接口"
• "列出DACN-ACC01的接口"
• "LODC-SPINE-01的WAN接口是什么？"

复杂分析查询（版本2.0 - 多工具执行与递归）：

并发工具执行：

• "你能提供BRCN位置的前缀和设备，并告诉我这些设备上的接口吗？"
• "显示NYDC的所有设备及其接口配置"
• "LODC的WAN接口及其电路信息是什么？"
• "获取USBN1的所有设备，并显示它们的接口及IP地址"

递归工具链：

• "显示BRCN的所有WAN路由器，然后获取每个路由器的接口"
• "列出NYDC的所有核心设备，并显示它们的接口详情"
• "获取DACN的所有设备，然后显示每个设备的接口"
• "查找LODC的所有WAN路由器并显示它们的接口配置"

跨位置分析：

• "比较BRCN和NYDC的WAN路由器 - 显示它们的接口和电路"
• "获取DACN和LODC的所有核心设备并显示它们的接口配置"
• "显示BRCN、NYDC和DACN的所有电路"
• "比较USBN1和USBN2之间的网络拓扑 - 设备、接口和电路"

高级网络分析：

• "分析BRCN的网络：显示前缀、设备、接口和电路"
• "给我一个完整的NYDC网络概述，包括所有设备、它们的接口以及任何电路"
• "显示DACN的完整网络拓扑，包括设备、接口、IP地址和电路"
• "提供一个关于LODC网络的全面分析，包括所有网络组件"

基于发现的分析：

• "首先显示所有可用位置，然后分析最大的校园网络"
• "列出所有提供商，然后显示最常见的提供商的电路"
• "有哪些可用位置，哪些位置拥有最多的设备？"
• "显示所有提供商，然后从每个提供商获取电路"
• "首先发现可用位置，然后获取每个数据中心的设备和电路"

故障排除查询：

• "连接到BRCN的WAN接口的电路是什么？"
• "显示NYDC的所有具有IP地址的接口"
• "列出DACN中具有电路连接的所有设备"
• "查找LODC的所有WAN路由器并显示它们的电路信息"

📤 导出聊天记录

聊天UI可以导出对话：

• JSON格式 - 包含工具调用元数据的完整对话
• Markdown格式 - 包含工具调用细节的可读日志

🏗️ 架构

+-------------------+         +-------------------+       +------------------+
|  聊天UI         | <-----> |  MCP客户端SDK   | <-->  |  FastMCP服务器  |
|  (Flask/HTML)    |         |  (工具目录)   |       |  (Nautobot工具)|
+-------------------+         +-------------------+       +--------+---------+
                                                                     |
                                                                     v
                                                             +---------------+
                                                             |   Nautobot    |
                                                             | (GraphQL API) |
                                                             +---------------+

🤝 贡献新工具

要向服务器添加新的MCP工具：

1. 添加工具函数

在services/mcp-nautobot/mcp_server/tools/目录下创建你的工具函数。

2. 在服务器中注册工具

在services/mcp-nautobot/mcp_server/server.py中添加工具：

# 创建工具实例
my_tool = Tool.from_function(
    fn=my_tool_function,
    name="my_tool_name",
    description="""详细的工具描述。

        参数：
            param1: 参数1的描述
            param2: 参数2的描述

        返回值：
            描述工具返回的内容
        """
)

# 添加到服务器
server.add_tool(my_tool)

3. 工具描述与LLM通信

description字段至关重要 - 这是LLM阅读以了解：

• 工具的功能
• 接受的参数
• 返回的内容
• 示例值和格式

LLM使用此描述来决定何时以及如何调用你的工具。具体说明并包含示例！

🔍 故障排除

一般问题

• 服务未启动：检查docker-compose logs中的错误
• 聊天UI无法加载：确保所有服务都健康运行，使用docker-compose ps
• API错误：验证你的NAUTOBOT_TOKEN是否在.env中正确设置

种子数据问题

如果你的查询中没有看到数据，可能是种子容器失败了：

1. 检查种子容器日志：

   docker-compose logs seed-data
   

2. 查找常见的种子错误：

   • 连接到Nautobot的超时
   • 认证失败
   • 数据库约束违反
   • 缺少依赖项

3. 如有必要，重新运行种子容器：

   # 停止并删除种子容器
   docker-compose rm -f seed-data
   
   # 重新启动以重新运行播种过程
   docker-compose up -d seed-data
   
   # 再次检查日志
   docker-compose logs -f seed-data
   

4. 验证数据已创建：

   • 访问 http://localhost:8080 并登录Nautobot
   • 检查位置、设备和前缀是否存在
   • 如果没有数据存在，则播种过程失败

5. 常见的种子容器问题：

   • Nautobot未准备好：种子容器在Nautobot完全初始化之前启动
   • 网络连接：容器无法到达Nautobot API
   • 权限问题：API令牌权限不足
   • 数据库锁定：并发操作导致冲突

📝 许可证

Apache-2.0