PiNet MCP服务器

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

](https://www.python.org/downloads/) ![License](LICENSE) ![MCP](https://modelcontextprotocol.io/)

______________________________________________________________________

概述

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

数据流：

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

______________________________________________________________________

先决条件

必需

Python 3.7+ （用于地方发展）
码头工人 （用于集装箱化部署）
PiNet API实例 运行和可访问

- 默认端口：5000 - 需要API密钥

用于开放式WebUI集成

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

______________________________________________________________________

安装

地方发展

克隆存储库：

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

创建虚拟环境：

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

安装依赖项：

   pip install -e .

配置环境：

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

启动服务器：

   python -m mcp_pinet_server

Docker部署

看了解全面的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 获取详细的集成说明。

快速摘要：

启动MCP服务器
打开WebUI管理面板→ 设置→ 外部工具
添加连接：

- 类型： MCP Streamable HTTP - 网址： http://localhost:8000/mcp （或您的服务器IP） - 认证：无

保存并启用连接
开始和你的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

______________________________________________________________________

故障排除

服务器无法启动

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

解决：

检查 .env 文件存在并且具有正确的值
验证Python版本是否为3.7+
检查端口尚未使用：

   # Windows
   netstat -ano | findstr :8000

   # Linux/Mac
   lsof -i :8000

检查是否可以访问PiNet API：

   curl http://YOUR_PINET_IP:5000/

打开WebUI无法连接

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

解决：

验证MCP服务器是否正在运行（检查终端/日志）
检查防火墙设置是否允许端口8000
使用正确的URL格式： http://SERVER_IP:8000/mcp （注意 /mcp 端点）
测试连接性：

   curl -X POST http://localhost:8000/mcp \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

工具返回错误

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

常见错误：

“无法访问PiNet API”

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

“身份验证失败”

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

“无效的IP/MAC格式”

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

调试LLM参数问题

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

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

启用调试日志记录：

编辑您的 .env 文件：

   LOG_LEVEL=DEBUG

重新启动服务器：

   python -m mcp_pinet_server

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特定的故障排除。

______________________________________________________________________

项目结构

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/

添加新工具

在中添加工具功能 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)}

在中添加测试 tests/test_server.py

更新文档

______________________________________________________________________

贡献

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

分叉存储库
创建要素分支：

   git checkout -b feature/your-feature-name

进行更改

- 为新功能添加测试 - 更新文档 - 遵循现有代码样式

运行测试：

   pytest

以明确的信息承诺：

   git commit -m "Add: description of your changes"

推你的叉子：

   git push origin feature/your-feature-name

打开拉取请求

开发指南

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

______________________________________________________________________

许可证

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

______________________________________________________________________

致谢

内置 FastMCP 框架
与集成打开WebUI
连接到 PiNet API

______________________________________________________________________

支持

如果您遇到问题：

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

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

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

📘 MCP+开放式WebUI集成指南

本指南记录了：

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

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

______________________________________________________________________

路线图

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

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

PiNet MCP Server

快速接入

详细介绍

PiNet MCP服务器

目录

概述

特性

建筑

先决条件

必需

用于开放式WebUI集成

安装

地方发展

Docker部署

配置

配置选项

用法

启动服务器

测试工具

与Open WebUI集成

可用工具

1. ping_host

2. wake_device

故障排除

服务器无法启动

打开WebUI无法连接

工具返回错误

调试LLM参数问题

Docker容器问题

项目结构

发展

运行测试

代码的风格

添加新工具

贡献

开发指南

许可证

致谢

支持

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

路线图

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `ping_host`

2. `wake_device`