AI导哈

网络诊断MCP服务器

PiNet MCP Server是一个连接Open WebUI LLMs和PiNet API的模型上下文协议服务器，使AI助手能够通过自然语言命令执行实时网络诊断。

  • by michalkoterba
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 michalkoterba/PiNet_MCP_Server

使用说明

PiNet MCP服务器

模型上下文协议（MCP）服务器，将Open WebUI LLM与PiNet API连接起来，使人工智能助手能够通过自然语言命令执行真实世界的网络诊断。

目录

概述

PiNet MCP服务器使LLM（大型语言模型）能够通过PiNet API与网络设备进行交互。它将网络诊断功能作为MCP工具公开，允许AI助手：

  • 检查网络主机是否联机（ping）
  • 使用LAN唤醒功能唤醒设备

用例示例：

User: "Check if 192.168.1.100 is online, and if not, wake it up"

LLM: *Uses ping_host tool* → Host is offline
     *Uses wake_device tool* → Wake-on-LAN packet sent successfully

此服务器充当以下之间的桥梁：

  • 打开WebUI （或其他MCP兼容的LLM接口）
  • PiNet API （运行在Raspberry Pi上的网络诊断API）

特性

  • 两个MCP工具：

    • ping_host -检查与任何IP/主机名的网络连接
    • wake_device -发送局域网唤醒魔术包

  • 可流式HTTP传输：

    • 与Open WebUI兼容
    • RESTful MCP端点位于 /mcp
    • 网络可访问（绑定到0.0.0.0）

  • 稳健的错误处理：

    • 清晰、LLM友好的错误消息
    • 全面的异常处理
    • IP地址和MAC地址的验证

  • 易于部署：

    • Docker Compose支持Docker
    • 用于安全远程访问的Tailscale变体
    • 基于环境的配置

  • 生产就绪：

    • 全测试覆盖（16个单元测试）
    • 健康检查
    • 资源限制
    • 日志轮转

建筑

┌─────────────────┐
│   Open WebUI    │  (LLM Interface)
│   (Frontend)    │
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│  PiNet MCP      │  (This Server)
│    Server       │  Port 8000/5001
└────────┬────────┘
         │ HTTP
         ▼
┌─────────────────┐
│   PiNet API     │  (Network API)
│ (Raspberry Pi)  │  Port 5000
└─────────────────┘
         │
         ▼
   Network Devices

数据流：

  1. 用户问LLM：“192.168.1.100在线吗？”
  2. LLM认识到使用 ping_host 工具
  3. Open WebUI通过HTTP调用MCP服务器
  4. MCP服务器将请求转发给PiNet API
  5. PiNet API Ping主机
  6. 响应通过链返回给用户

先决条件

必需

  • Python 3.7+ （用于地方发展）
  • 码头工人 （用于集装箱化部署）
  • PiNet API实例 运行和可访问
    • 默认端口：5000
    • 需要API密钥

用于开放式WebUI集成

  • 打开WebUI 已安装并正在运行
  • 与MCP服务器的网络连接
  • 启用MCP流式HTTP支持

安装

地方发展

  1. 克隆存储库：

    git clone https://github.com/yourusername/PiNet_MCP_Server.git
cd PiNet_MCP_Server

  2. 创建虚拟环境：

    python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate     # Windows

  3. 安装依赖项：

    pip install -e .

  4. 配置环境：

    cp .env.example .env
# Edit .env with your PiNet API details

  5. 启动服务器：

    python -m mcp_pinet_server

Docker部署

看 DOCKER_DEPLOYMENT.md 了解全面的Docker部署说明。

快速入门：

# Create .env file with your configuration
cp .env.example .env

# Start with Docker Compose
docker-compose up -d

# Check logs
docker-compose logs -f pinet-mcp-server

配置

配置是通过环境变量进行管理的。创建一个 .env 项目根目录中的文件：

# PiNet API Configuration (Required)
PINET_API_URL=http://YOUR_PINET_IP:5000
PINET_API_KEY=your_api_key_here

# MCP Server Configuration (Optional)
MCP_SERVER_PORT=8000
MCP_SERVER_HOST=0.0.0.0

# Logging Configuration (Optional)
LOG_LEVEL=INFO

# Tailscale Configuration (Only for docker-compose-tailscale.yml)
# TS_AUTHKEY=tskey-auth-xxxxxxxxxxxxxxxxxxxxx

配置选项

变量 必填 默认 描述
PINET_API_URL 是 - PiNet API服务器的基本URL（包括端口5000）
PINET_API_KEY 是 - 使用PiNet API进行身份验证的API密钥
MCP_SERVER_PORT 没有 8000 MCP服务器监听端口
MCP_SERVER_HOST 没有 0.0.0.0 要绑定的主机接口（全部为0.0.0.0）
LOG_LEVEL 没有 INFO 日志详细程度：调试、信息、警告或错误

安全说明： 永远不要承诺你的 .env 文件到版本控制。这 .gitignore 文件会自动将其排除。

用法

启动服务器

当地：

python -m mcp_pinet_server

Docker：

docker-compose up -d

预期产量：

============================================================
Starting PiNet MCP Server on 0.0.0.0:8000...
============================================================

[OK] Server will be accessible at: http://0.0.0.0:8000
[OK] From other machines use: http://YOUR_PC_IP:8000

[OK] Starting uvicorn server...

INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

测试工具

运行演示脚本：

python demo_tools.py

这将使用各种场景测试这两个工具并显示结果。

手动测试：

from mcp_pinet_server.server import ping_host, wake_device

# Test ping
result = ping_host("8.8.8.8")
print(result)  # {"ip_address": "8.8.8.8", "status": "online"}

# Test wake-on-LAN
result = wake_device("AA:BB:CC:DD:EE:FF")
print(result)  # {"status": "success", "message": "Wake-on-LAN packet sent..."}

与Open WebUI集成

看 OPEN_WEBUI_SETUP.md 获取详细的集成说明。

快速摘要：

  1. 启动MCP服务器
  2. 打开WebUI管理面板→ 设置→ 外部工具
  3. 添加连接：
    • 类型： MCP Streamable HTTP
    • 网址： http://localhost:8000/mcp （或您的服务器IP）
    • 认证：无
  4. 保存并启用连接
  5. 开始和你的LLM聊天吧——它现在具有网络诊断功能！

示例提示：

  • “你能查一下8.8.8.8是否在线吗？”
  • “请唤醒MAC地址为AA:BB:CC:DD:EE:FF的设备”
  • 检查192.168.1.100是否可访问，如果不可访问，请尝试唤醒它

可用工具

1. ping_host

说明： 通过ping来检查网络主机是否可访问。

参数：

  • ip_address （string）：ping的IP地址或主机名
    • 支持： 8.8.8.8, 192.168.1.100, google.com

退货：

// Success (online)
{
  "ip_address": "8.8.8.8",
  "status": "online"
}

// Success (offline)
{
  "ip_address": "192.168.1.250",
  "status": "offline"
}

// Error
{
  "status": "error",
  "message": "Invalid IP address format"
}

使用案例：

  • 在尝试SSH/RDP之前，检查设备是否联机
  • 监控网络设备可用性
  • 解决网络连接问题

2. wake_device

说明： 发送LAN唤醒魔术包以唤醒正在睡眠的网络设备。

参数：

  • mac_address （string）：要唤醒的设备的MAC地址
    • 接受的格式： AA:BB:CC:DD:EE:FF 或 AA-BB-CC-DD-EE-FF

退货：

// Success
{
  "status": "success",
  "message": "Wake-on-LAN packet sent to AA:BB:CC:DD:EE:FF"
}

// Error
{
  "status": "error",
  "message": "Invalid MAC address format"
}

要求：

  • 目标设备必须在BIOS/UEFI中启用LAN唤醒
  • 设备应通过以太网连接（WiFi WoL不可靠）
  • 网卡必须支持WoL

故障排除

服务器无法启动

问题： 服务器无法启动或立即退出

解决：

  1. 检查 .env 文件存在并且具有正确的值
  2. 验证Python版本是否为3.7+
  3. 检查端口尚未使用：
    # Windows
netstat -ano | findstr :8000

# Linux/Mac
lsof -i :8000
  4. 检查是否可以访问PiNet API：
    curl http://YOUR_PINET_IP:5000/

打开WebUI无法连接

问题： Open WebUI中的“连接失败”或“无法访问服务器”

解决：

  1. 验证MCP服务器是否正在运行（检查终端/日志）
  2. 检查防火墙设置是否允许端口8000
  3. 使用正确的URL格式： http://SERVER_IP:8000/mcp （注意 /mcp 端点）
  4. 测试连接性：
    curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

工具返回错误

问题： 工具执行但返回错误消息

常见错误：

  1. “无法访问PiNet API”

    • 检查PiNet API是否正在运行： curl http://YOUR_PINET_IP:5000/
    • 验证 PINET_API_URL 在 .env
    • 检查网络连接

  2. “身份验证失败”

    • 验证 PINET_API_KEY 在 .env 是正确的
    • 检查API密钥是否未过期

  3. “无效的IP/MAC格式”

    • LLM传递的格式不正确
    • 这是预期的验证-工具工作正常
    • 看 调试LLM参数问题 在......下面

调试LLM参数问题

问题： LLM有时会向MCP服务器发送不正确的IP/MAC地址格式

MCP服务器包括详细的日志记录，以帮助您从LLM调试参数格式问题。

启用调试日志记录：

  1. 编辑您的 .env 文件：

    LOG_LEVEL=DEBUG

  2. 重新启动服务器：

    python -m mcp_pinet_server

  3. LLM调用工具时，请查看日志：

    2025-11-02 14:30:45 [INFO] PiNet-MCP: ======================================================================
2025-11-02 14:30:45 [INFO] PiNet-MCP: TOOL CALL: ping_host
2025-11-02 14:30:45 [INFO] PiNet-MCP:   Parameter received from LLM:
2025-11-02 14:30:45 [INFO] PiNet-MCP:     ip_address: '192.168.1.100 ' (type: str, length: 15)
2025-11-02 14:30:45 [INFO] PiNet-MCP:     repr: '192.168.1.100 '
2025-11-02 14:30:45 [ERROR] PiNet-MCP:   ValidationError: Invalid IP address format
2025-11-02 14:30:45 [INFO] PiNet-MCP: ======================================================================

寻找什么：

  • 空格: '192.168.1.1 ' -LLM添加了额外的空格
  • 分隔符错误: '192-168-1-1' -虚线而不是点
  • 报价包括: '"192.168.1.1"' -LLM用引号括起来
  • 特殊字符: '192.168.1.1\n' -换行符或其他隐藏字符
  • MAC格式问题: 'AA BB CC DD EE FF' -空格而不是冒号/破折号

将日志保存到文件：

# Both console and file
python -m mcp_pinet_server 2>&1 | tee mcp_debug.log

# File only
python -m mcp_pinet_server > mcp_debug.log 2>&1

可用日志级别：

  • DEBUG -最详细的，显示了所有API调用和内部操作
  • INFO -正常操作、工具调用和响应（默认）
  • WARNING -仅警告和错误
  • ERROR -只有错误消息

Docker容器问题

看 DOCKER_DEPLOYMENT.md 用于Docker特定的故障排除。

项目结构

PiNet_MCP_Server/
├── src/
│   └── mcp_pinet_server/
│       ├── __init__.py          # Package initialization
│       ├── __main__.py          # Entry point for module execution
│       ├── server.py            # Main MCP server with tools
│       ├── config.py            # Configuration management
│       └── pinet_client.py      # PiNet API client
├── tests/
│   ├── __init__.py
│   └── test_server.py           # Unit tests
├── docs/
│   ├── IMPLEMENTATION_PLAN.md   # Development roadmap
│   ├── SRS.md                   # Software Requirements Specification
│   └── PiNet_API_README.md      # PiNet API documentation
├── .env.example                 # Environment template
├── .dockerignore               # Docker build exclusions
├── .gitignore                  # Git exclusions
├── demo_tools.py               # Demo script
├── docker-compose.yml          # Standard Docker deployment
├── docker-compose-tailscale.yml # Tailscale deployment
├── Dockerfile                  # Container image definition
├── DOCKER_DEPLOYMENT.md        # Docker guide
├── OPEN_WEBUI_SETUP.md        # Open WebUI integration guide
├── pyproject.toml             # Python project configuration
└── README.md                  # This file

发展

运行测试

# Install dev dependencies
pip install -e ".[dev]"

# Run all tests
pytest

# Run with coverage
pytest --cov=mcp_pinet_server

# Run specific test
pytest tests/test_server.py::test_ping_host_online

代码的风格

# Format code
black src/ tests/

# Type checking
mypy src/

添加新工具

  1. 在中添加工具功能 src/mcp_pinet_server/server.py:

    @mcp.tool()
def your_tool(param: str) -> dict:
    """Tool description for LLM"""
    try:
        # Implementation
        return {"status": "success", "result": "..."}
    except Exception as e:
        return {"status": "error", "message": str(e)}

  2. 在中添加测试 tests/test_server.py

  3. 更新文档

贡献

欢迎投稿！请遵循以下指南：

  1. 分叉存储库
  2. 创建要素分支：
    git checkout -b feature/your-feature-name
  3. 进行更改
    • 为新功能添加测试
    • 更新文档
    • 遵循现有代码样式
  4. 运行测试：
    pytest
  5. 以明确的信息承诺：
    git commit -m "Add: description of your changes"
  6. 推你的叉子：
    git push origin feature/your-feature-name
  7. 打开拉取请求

开发指南

  • 遵循PEP 8风格指南
  • 为所有函数添加类型提示
  • 编写全面的文档字符串
  • 包括新功能的单元测试
  • 如果添加功能，请更新README
  • 保持提交原子性和专注性

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

支持

如果您遇到问题：

  1. 检查 故障排除 章节
  2. 审查 OPEN_WEBUI_SETUP.md 关于集成问题
  3. 审查 DOCKER_DEPLOYMENT.md Docker问题
  4. 检查服务器日志中的错误消息
  5. 验证PiNet API连接

面向构建类似MCP服务器的开发人员

如果您正在为Open WebUI实现自己的MCP服务器，请参阅我们的全面实施指南：

📘 MCP+开放式WebUI集成指南

本指南记录了：

  • ✅ 哪些有效，哪些无效（传输机制、网络配置）
  • ✅ 开发过程中遇到的所有问题及其解决方案
  • ✅ 通过代码示例逐步实现
  • ✅ Open WebUI集成前的测试策略
  • ✅ 常见的陷阱以及如何避免它们

基于该项目的实际实施经验。

路线图

未来的增强功能（不在当前范围内）：

  • []添加更多PiNet API端点作为工具
  • []为频繁的ping请求实现缓存
  • []添加指标/监控端点
  • []支持多个PiNet API实例
  • []为MCP服务器添加身份验证
  • []创建web仪表板
  • []添加CI/CD管道

相关 MCP