使用说明

Nautobot MCP聊天界面

一个自包含的、码头化的演示，它公开了一个 FastMCP Nautobot OSS平台的服务器，加上轻量级 聊天用户界面 它可以列出可用的MCP工具，调用它们，并导出聊天记录。

🚀 版本2.0：多工具和递归工具调用

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

✅ 多工具执行

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

✅ 递归工具链

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

✅ 增强的数据展示

具有表格和结构化数据的丰富标记格式
自动突出显示关键信息（广域网接口、电路等）
具有网络拓扑理解的综合分析

✅ 实时状态更新

工具执行过程中的详细进度跟踪
性能指标和时间信息
明确表示加工阶段和完成情况

✅ 智能上下文管理

缓存数据重复用于后续问题
无冗余工具调用的上下文感知响应
对以前收集的信息进行智能分析

🚀 快速开始

# 1. Start all services
docker-compose up -d

# 2. Copy environment file and configure
cp .env.example .env

# 3. Get OpenAI API key (required for chat functionality):
#    - Go to https://platform.openai.com/api-keys
#    - Create a new API key
#    - Add it to your .env file: OPENAI_API_KEY=your_openai_api_key_here

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

# 5. Get your Nautobot API token:
#    - Go to http://localhost:8080 and log in with your username and password
#    - Navigate to your User Profile → API Tokens → Add token
#    - Copy the token key and update your .env file: NAUTOBOT_TOKEN=your_api_token_here
#    - Restart the services: docker-compose restart

# 6. Open the chat UI
#    http://localhost:8501

🎯 包含什么

瑙托波特 使用种子演示数据并启用GraphQL
FastMCP服务器 将Nautobot实用程序作为MCP工具公开
聊天界面 用于测试MCP工具和导出对话
演示数据 包括位置、设备、接口和IPAM

🔧 设置步骤

步骤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-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：访问聊天界面

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

🛠️ MCP工具可用

get_prefixes_by_location_enhanced -使用格式选项按位置查询前缀
get_devices_by_location -在特定位置获取设备
get_devices_by_location_and_role -按位置和角色获取设备
get_interfaces_by_device -获取设备的接口、IP地址和电路信息
get_circuits_by_location -获取特定位置的电路
get_circuits_by_provider -获取特定供应商的电路
get_locations -获取所有具有层次结构信息的可用位置
get_providers -获取所有可用的电路提供商
动态工具发现 -聊天UI自动发现并显示可用工具

📊 演示数据结构

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

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

💬 查询示例

在聊天界面中尝试以下操作：

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

“NYDC有哪些前缀？”
“显示BRCN上的所有设备”
“列出USBN1上的设备”
“LODC是什么？”

发现查询：

“系统中有哪些可用位置？”
“显示所有电路提供程序”
“列出所有可用的地点及其所在的国家和地区”

电路查询：

“给我一份BRCN位置的电路清单”
“显示NYDC和DACN的所有电路”
“LODC提供哪些电路？”
“列出USBN1和USBN2的所有电路”
“显示供应商Zayo的所有电路”
“AT&T提供哪些电路？”
“列出3级的所有电路”

设备角色查询：

“显示NYDC的所有广域网路由器”
“列出LODC的所有Spine交换机”
“BRCN有哪些Leaf开关？”
“显示USBN1上的所有分支接入交换机”
“列出DACN的核心路由器”
“MXCN有哪些校园接入交换机？”

界面查询：

“BRCN-WAN01上有哪些接口？”
“显示NYDC-CORE-01上的所有接口”
“列出DACN-ACC01上的接口”
“LODC-SPINE-01上的广域网接口是什么？”

复杂分析查询（2.0版-多工具和递归）：

并行工具执行：

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

递归工具链：

“显示BRCN上的所有WAN路由器，然后获取每个路由器的接口”
“列出NYDC的所有核心设备，并向我展示它们的接口详细信息”
“在DACN获取所有设备，然后向我显示每个设备的接口”
“在LODC找到所有WAN路由器并显示其接口配置”

交叉位置分析：

“比较BRCN和NYDC的广域网路由器-向我展示它们的接口和电路”
“在DACN和LODC获取所有核心设备，并显示其接口配置”
“显示BRCN、NYDC和DACN的所有电路”
“比较USBN1和USBN2之间的网络拓扑-设备、接口和电路”

高级网络分析：

分析BRCN的网络：显示前缀、设备、接口和电路
“给我一个完整的NYDC网络概述，包括所有设备、接口和任何电路”
“显示DACN的完整网络拓扑，包括设备、接口、IP地址和电路”
“对LODC网络进行全面分析，包括所有网络组件”

基于发现的分析：

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

查询疑难解答：

“哪些电路连接到BRCN的WAN接口？”
“显示NYDC上所有具有IP地址的接口”
“列出DACN上具有电路连接的所有设备”
“在LODC找到所有WAN路由器并显示其电路信息”

📤 导出聊天记录

聊天UI可以将对话导出到：

JSON格式 -使用工具调用元数据完成对话
Markdown格式 -带有工具调用详细信息的可读日志

🏗️ 建筑

+-------------------+         +-------------------+       +------------------+
|  Chat UI         | <-----> |  MCP Client SDK   | <-->  |  FastMCP Server  |
|  (Flask/HTML)    |         |  (tool catalog)   |       |  (Nautobot tools)|
+-------------------+         +-------------------+       +--------+---------+
                                                                     |
                                                                     v
                                                             +---------------+
                                                             |   Nautobot    |
                                                             | (GraphQL API) |
                                                             +---------------+

🤝 贡献新工具

要向服务器添加新的MCP工具，请执行以下操作：

1.添加工具功能

在中创建工具功能 services/mcp-nautobot/mcp_server/tools/ 目录。

2.在服务器中注册工具

将工具添加到 services/mcp-nautobot/mcp_server/server.py:

# Create Tool instance
my_tool = Tool.from_function(
    fn=my_tool_function,
    name="my_tool_name",
    description="""Detailed description of what the tool does.

        Args:
            param1: Description of parameter 1
            param2: Description of parameter 2

        Returns:
            Description of what the tool returns
        """
)

# Add to server
server.add_tool(my_tool)

3.工具说明和LLM沟通

这 description 字段是至关重要的-这是LLM阅读理解的内容：

该工具的功能是什么
它接受哪些参数
它返回什么
示例值和格式

LLM使用此描述来决定何时以及如何调用您的工具。具体点，并举例说明！

🔍 故障排除

一般问题

服务未启动：检查 docker-compose logs 对于错误
聊天UI未加载：确保所有服务都健康 docker-compose ps
API错误：验证您的 NAUTOBOT_TOKEN 在中设置正确 .env

种子数据问题

如果您在查询中没有看到数据，则种子容器可能已失败：

检查种子容器日志：
```
docker-compose logs seed-data
```
查找常见的种子错误：
- 与Nautobot的连接超时
- 身份验证失败
- 违反数据库约束
- 缺少的依赖

如果需要，重新运行种子容器：

# Stop and remove the seed container
docker-compose rm -f seed-data

# Restart it to rerun the seeding process
docker-compose up -d seed-data

# Check logs again
docker-compose logs -f seed-data

验证数据是否已创建：
- 首选http://localhost:8080登录Nautobot
- 检查位置、设备和前缀是否存在
- 如果不存在数据，则种子进程失败
常见的种子容器问题：
- Nautobot尚未准备就绪：种子容器在Nautobot完全初始化之前启动
- 网络连接：容器无法访问Nautobot API
- 权限问题：API令牌没有足够的权限
- 数据库锁：并发操作导致冲突

📝 许可证

阿帕奇-2.0