AI Assistant Chat with Nmap Tool Integration

集成 Nmap 工具的 AI 助手聊天

本项目使用 Gradio 提供基于 Web 的聊天界面，用户可以通过该界面与由 OpenAI API 驱动的 AI 助手交互。该助手配备了可与本地文件系统交互并使用容器化 Nmap 服务执行网络扫描的工具。

概述

该应用使用 OpenAI Agents SDK 框架。AI Agent 会处理用户请求、推理请求内容，并决定是否使用可用工具。其功能包括：

• 使用 Gradio 构建便于交互的前端。
• 采用 OpenAI 模型的 AI Agent 后端（需要 API 密钥）。
• 用于访问文件系统的模型上下文协议（MCP）服务（使用 @modelcontextprotocol/server-filesystem）。
• 提供 Nmap 扫描功能的容器化 MCP 服务（ping、端口扫描、服务发现、SMB 共享枚举）[cite: 14, 16, 18, 20, 22]。

Nmap 服务在 Docker 容器中运行，以便管理依赖项并实现隔离。

功能

• 对话式 AI 助手。
• 文件系统访问工具（范围限定为应用目录）。
• 通过 Nmap 使用网络扫描工具：
  • ping_host [cite: 14]
  • scan_network（前 100 个端口）[cite: 16]
  • all_scan_network（-A 综合扫描）[cite: 18]
  • all_ports_scan_network（全部 65535 个端口）[cite: 20]
  • smb_share_enum_scan（SMB 共享枚举）[cite: 22]
• 使用 Gradio 构建的 Web 界面[cite: 11, 12]。
• 使用 Docker 构建的容器化 Nmap 工具服务。

架构

1. Gradio UI（app.txt）：处理用户输入并显示对话历史。
2. 主应用（app.txt）：
   • 初始化 Gradio 界面。
   • 管理对话状态。
   • 设置并管理 MCP 服务。
   • 实例化并运行 OpenAI Agent。
3. OpenAI Agent（agents 库）：处理用户消息、在需要时调用工具并生成回复[cite: 1, 3]。
4. MCP 服务：
   • 文件系统服务：通过 npx 运行，以提供本地文件访问功能[cite: 1]。
   • Nmap 工具包服务（Docker 中的 nmap-server.txt）：在 Docker 容器中运行，通过 MCP 将 Nmap 扫描功能作为工具提供[cite: 2, 14]。app.txt 会针对每个请求使用 docker run 启动此服务。

前提条件

• Python：3.9+
• Docker：已安装并运行最新版本。
• Node.js/npm：运行文件系统 MCP 服务需要使用 npx。
• OpenAI API 密钥：设置为环境变量 OPENAI_API_KEY。

安装与设置

1. 克隆代码仓库：

   git clone <your-repository-url>
   cd <your-repository-directory>
   

2. 设置 OpenAI API 密钥： 将 API 密钥导出为环境变量。将 your_api_key_here 替换为你的实际密钥。

   • Linux/macOS：

     export OPENAI_API_KEY='your_api_key_here'
     

   • Windows（命令提示符）：

     set OPENAI_API_KEY=your_api_key_here
     

   • Windows（PowerShell）：

     $env:OPENAI_API_KEY='your_api_key_here'
     

3. 构建 Nmap Docker 镜像： 进入包含 nmap-server.py 和 Dockerfile 的目录，然后运行：

   docker build -t nmap-mcp-server .
   

   （请确保 Dockerfile 内容正确，尤其要确认 MCP 软件包名称是否为 modelcontextprotocol。）

4. 安装 Python 依赖项： 建议使用虚拟环境。

   python -m venv venv
   # Activate the virtual environment
   # Linux/macOS:
   source venv/bin/activate
   # Windows:
   .\venv\Scripts\activate
   # Install requirements
   pip install -r requirements.txt
   

运行应用

确保已设置 OpenAI API 密钥、Docker 正在运行，并且你位于项目根目录且已激活虚拟环境。

python app.py
 An example MCP server with a couple nmap scans as tools.