netexpert-mcp

netexpert-mcp

“我的网络上有哪些设备？连接正常吗？这台机器安全吗？为什么 X 这么慢？” — AI 在你的局域网中，通过一次对话给出答案。

netexpert 是一款跨平台的本地网络诊断与安全态势 MCP 服务，面向 AI 客户端（Claude Desktop、Claude Code，或任何支持 MCP 的客户端）。支持 Windows、Linux 和 macOS——使用统一的 JSON 封装，提供 31 个工具，首次运行无需配置，默认只读。

它是家庭实验室工具包中面向本地主机 + 局域网的部分——NAS 部分已有 ugnas-mcp，两者可组合使用。

它也已作为 io.github.Omodaka9375/netexpert-mcp 列入 MCP 注册表。

---

安装

此软件包已发布到 npm——无需克隆或构建：

# run once, on demand (no install)
npx -y netexpert-mcp

# or install globally
npm install -g netexpert-mcp
netexpert-mcp

将其接入你的 MCP 客户端（stdio）：

{
  "mcpServers": {
    "netexpert": {
      "command": "npx",
      "args": ["-y", "netexpert-mcp"]
    }
  }
}

就是这么简单——首次运行无需配置文件、环境变量或其他设置。询问客户端*“我的网络上有哪些设备？”*，它就能调用相应工具给出答案。

可选的 HTTP 传输（无状态，使用相同的 JSON-RPC 接口）：

NETEXPERT_HTTP_PORT=3100 netexpert-mcp
# POST http://127.0.0.1:3100/mcp     (tools/list, tools/call)
# GET  http://127.0.0.1:3100/health  (liveness)

---

30 秒快速体验

接入客户端后，试着问：

1. “我的设备暴露在网络上了吗？” → 客户端调用 sec.exposure——结合监听端口、防火墙状态和高风险端口知识库进行检查，并以 Finding 报告结果。
2. “我的网络上有哪些设备？” → lan.devices——通过 ARP 清单补充 IEEE-OUI 厂商名称和 PTR 主机名。
3. “我的 DNS 是否在欺骗我？” → dns.hijackcheck——通过系统解析器与可信 DoH 分别查询已知正常的域名；不匹配时会产生 Finding{severity:high}。
4. “我的 WiFi 信号好吗？” → wifi.health——解读 RSSI 质量等级、信道重叠和频段不匹配情况，并提供后续操作建议。

---

项目缘起

现有的网络 MCP 服务要么是已弃用的 Python 软件包，要么是要求安装 Nmap 的封装，要么是面向企业的路由器配置工具。它们都无法回答家庭实验室用户关心的问题：

问题	netexpert 的回答
我的网络上有哪些设备？有没有新设备？	lan.devices 会构建设备清单（ARP ∪ 扫描、OUI 厂商、PTR 主机名）；lan.newdevices 会将其与快照进行比较，并生成发现结果
我的 WiFi 信号到底好不好？	wifi.health 会解读 RSSI 等级、信道重叠和频段不匹配情况，并给出具体的后续操作建议，而不只是提供原始数字
这台机器暴露在网络上了吗？	sec.exposure 会交叉检查监听端口、防火墙状态和高风险端口知识库
我的 DNS 是否在欺骗我？	dns.hijackcheck 会将系统解析器与可信 DoH 的查询结果进行比较，检查已知正常的域名
为什么无法访问 X？	分层诊断——链路 → ARP → 路由/DNS → 端口 → 应用（docs/persona.md）

设计保证

• 统一封装。 所有工具都返回相同的 JSON 结构（ok、backend、data、warnings / 固定集合中的 error.code + 可执行的 hint）——netsh 或 ip 的原始输出绝不会传给模型。
• 平台归一化。 Windows、Linux 和 macOS 使用相同的字段名称；平台分派逻辑位于服务层之下。
• 所有操作都有边界。 端口数、主机数、字节数上限、超时和令牌桶速率限制均由代码强制执行——绝不交由模型自行判断。
• 绝不调用 shell。 所有子进程都通过参数数组启动（execFile 风格）；所有输入在访问操作系统前都经过 zod 验证。不使用原始套接字、Npcap 或 Python。
• 默认只读。 唯一会修改状态的工具（lan.wol）采用试运行计划 + 单次使用、有效期为 10 分钟的 confirmToken——参数在生成计划时即被冻结。
• 如实说明能力。 工具会报告数据由哪个后端生成（backend: "tcp-connect"，而非虚构的“ping”）；net.health 会说明此主机上哪些功能可用，并为不可用的功能提供安装提示。
• 无遥测。 不会主动向外发送数据——但明确用于访问互联网的三个工具除外（net.publicip、sec.speedtest，以及 dns.hijackcheck 中的 DoH）；只有在你主动调用时才会使用它们。

工具目录（31）

net.* — 连通性

工具	功能
net.health	版本、平台、能力矩阵（此主机上有哪些后端，以及安装提示）
net.ping	ICMP 丢包率／延迟统计；ping 不可用时，诚实地回退到 TCP 连接测试
net.trace	路由跟踪跳数，并在 tracert／traceroute／tracepath 之间统一格式
net.httpcheck	GET/HEAD，细分计时：dns／connect／ttfb／total
net.portcheck	单次 TCP 连接测试 — 开放／关闭状态及延迟
net.portscan	有界连接扫描（≤256 个端口，默认扫描最常见的前 20 个）
net.ssl	TLS 证书：主题、SAN、颁发者、证书链、剩余天数、到期等级
net.publicip	你的公网 IPv4 + ASN／组织（先用 ipify，失败时回退到 ipinfo）
net.deepscan	可选的 nmap 适配器 — 仅主动启用：必须安装二进制文件，且在配置中设置 nmap.enabled；仅限 RFC1918 目标

dns.* — 名称解析

工具	功能
dns.lookup	A/AAAA/CNAME/MX/TXT/NS/SRV/PTR 查询，可选覆盖名称服务器
dns.reverse	查询 IP 的 PTR 名称
dns.resolvers	操作系统实际使用的 DNS 服务器（按平台区分）
dns.propagation	对比系统、可信解析器和 DoH 上的同一记录 — 差异表
dns.hijackcheck	关键检查：通过系统与可信 DoH 查询已知正常的域名；不匹配或 NXDOMAIN ⇒ Finding{sev:high}

lan.* — 设备与资产清单

工具	功能
lan.interfaces	网卡：名称、MAC、地址、类型、是否为虚拟网卡
lan.gateway	默认网关 + 接口 + 本地子网 CIDR
lan.arp	解析后的邻居缓存，并过滤过期条目
lan.sweep	对 RFC1918 子网进行 Ping 探测（≤1024 台主机，每 30 秒限速 1 次）→ 在线设备集合
lan.devices	资产清单：ARP ∩ RFC1918，补充厂商信息（4 万条记录的 IEEE OUI 数据库）+ PTR 主机名
lan.hostname	IP 的所有已知名称：PTR + NetBIOS（win）
lan.snapshot	将设备资产清单保存到带日期的快照；或列出快照
lan.newdevices	比较实时数据与基线 ⇒ 发现项（新 MAC、IP 对应的 MAC 已更改）；首次运行时自动保存基线
lan.wol	Wake-on-LAN 魔术包 — 先生成演练计划 → confirmToken → 发送一次 UDP 广播

wifi.* — 链路健康状况

工具	功能
wifi.status	当前链路：SSID、BSSID、频段、信道、RSSI、PHY 速率、0–100 的质量评分
wifi.networks	扫描附近的 AP，并推断频段
wifi.health	状况解读：RSSI 区间（≥−50 … <−78 时不可用）、2.4 GHz 信道重叠、频段不匹配、PHY 速率过低 — 每项均为一个 Finding，并附带下一步工具调用

sec.* — 主机安全状况

工具	功能
sec.connections	带所属 PID 的活动套接字
sec.listening	按进程列出监听端口；标记 0.0.0.0／:: 暴露
sec.firewall	Get-NetFirewallProfile / ufw→nft / socketfilterfw
sec.exposure	概览报告：暴露的监听端口 × 防火墙状态 × 高风险端口表（445、3389、23、135–139、5357、5900）⇒ Finding[]
sec.speedtest	有界 Cloudflare 下载；网速较慢时报告下限，而非失败

---

配置（均为可选）

~/.netexpert-mcp/config.json — 使用合理默认值，因此首次运行无需配置：

{
  "defaults":  { "pingCount": 4, "traceMaxHops": 20 },
  "resolvers": { "trusted": ["1.1.1.1", "8.8.8.8"],
                 "dohUrl": "https://cloudflare-dns.com/dns-query" },
  "caps":      { "portscan": { "maxPorts": 256 }, "sweep": { "maxHosts": 1024 } },
  "rate":      { "sweep": 30, "portscan": 10, "speedtest": 60, "httpCheck": 2 },
  "nmap":      { "enabled": false }   // deep scans are opt-in by design
}

不变条件：

• 限制值均为上限 — 工具输入可以更低，但不能更高
• 通过 NETEXPERT_* 环境变量覆盖：NETEXPERT_MCP_CONFIG（配置路径）、NETEXPERT_HTTP_PORT、NETEXPERT_WIFI_IF（Linux wlan 接口）
• 绝不使用凭据 — 加载时会拒绝任何包含 password／token／secret／credential 的配置键

可选扩展：

• nmap 深度扫描 — 安装 nmap（winget install Insecure.Nmap / sudo apt install nmap），然后在配置中设置 "nmap": { "enabled": true }。未安装时只会提供安装提示，绝不会导致崩溃。
• OUI 厂商数据库 — 随软件包提供；运行时不会获取。

无需守护进程的监控

netexpert 保持请求／响应模式；定期检查由你的 MCP 客户端负责：

New-device tripwire   lan.newdevices    every 15 min   fire on Finding[] beyond the info baseline
Gateway reachability  net.ping <gw>    every 60 s      fire on lossPct > 0
DNS integrity         dns.hijackcheck   hourly          fire on sev=high
WiFi degradation      wifi.health       every 10 min    fire on severity ≥ med

AI 使用 — docs/persona.md

服务提供双手，角色提供判断。docs/persona.md 中的规则包为你的 AI 客户端提供：

1. 分诊阶梯（链路 → ARP → IP/DNS → 端口 → 应用 — 始终说明哪个层级排除了问题或指出了问题），
2. “可疑”基准（没有匹配厂商的新 MAC、不是 NAS 的 RFC1918 主机在 445/3389 端口上、解析器 ≠ DoH、ARP 抖动），
3. 发现格式——每个回答都以具体的下一步工具调用结尾，绝不倾倒数据。

---

开发

git clone https://github.com/Omodaka9375/netexpert-mcp.git
cd netexpert-mcp
pnpm install

pnpm typecheck     # strict TS (Kai/Claude Code runs this after edits)
pnpm test          # 50 fixture-driven tests (fake runner, zero real network in units)
pnpm build         # → dist/
pnpm smoke         # build → stdio → tools/list → net.health
pnpm smoke:http     # HTTP transport check
node scripts/gen-oui.mjs   # regenerate the OUI db (rarely needed)

项目结构：

src/
  exec/        LocalExecutor (execFile, arg arrays) + per-platform CommandMaps (win32/linux/darwin)
  parse/       pure parsers (arp, ping, traceroute, netsh, iw, nmap -oG) — fixture-tested
  services/    coreService dnsService lanService wifiService secService nmapService
  safety/      caps.ts (bounds + token-bucket rate limiter) · confirm.ts (dry-run/confirmToken)
  data/        oui.json (40k IEEE OUI entries, committed)
  mcp/         toolset.ts (31 tools, zod inputs) · createServer.ts
scripts/       gen-oui.mjs · smoke.mjs · http-smoke.mjs
docs/          persona.md · index.html (the docs page)
tests/         fixtures/ + 50 tests across 6 files

许可证： MIT — 参见 LICENSE。 npm： netexpert-mcp · MCP 注册表： io.github.Omodaka9375/netexpert-mcp 源代码与问题反馈： GitHub