netexpert-mcp

netexpert-mcp

「ネットワーク上に何があるのか、接続は正常か、このマシンは安全か、X が遅いのはなぜか？」 — LAN 上で、AI が一度の会話で回答します。

netexpert は、AI クライアント（Claude Desktop、Claude Code、または MCP に対応する任意のクライアント）向けの、クロスプラットフォーム対応のローカルネットワーク診断・セキュリティ態勢確認 MCP サーバーです。Windows、Linux、macOS に対応し、正規化された JSON エンベロープを 1 種類に統一。ツールは 31 個で、初回実行時は設定不要、デフォルトでは読み取り専用です。

これはホームラボ用ツールキットの ローカルホスト＋LAN 側です。NAS 側は ugnas-mcp としてすでに存在し、両者を組み合わせて使えます。

MCP レジストリにも io.github.Omodaka9375/netexpert-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 は、IEEE-OUI のベンダー名と PTR ホスト名を付加した ARP インベントリを返します。
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）

設計上の保証

• エンベロープは 1 種類。 すべてのツールが同じ JSON 形式（ok、backend、data、warnings、または値が限定された error.code と実行可能な hint）を返します。生の netsh や ip の出力がモデルに渡ることはありません。
• プラットフォーム間で正規化。 Windows、Linux、macOS で同じフィールド名を使用し、プラットフォーム別の処理はサービスレイヤーより下に配置されています。
• すべてに上限を設定。 ポート数、ホスト数、バイト数、タイムアウト、トークンバケット方式のレート制限をコードで適用し、モデルの判断には委ねません。
• シェルは一切使用しません。 すべてのサブプロセスは引数配列（execFile 形式）で起動し、OS にアクセスする前に、すべての入力を zod で検証します。生のソケット、Npcap、Python は使用しません。
• デフォルトでは読み取り専用。 唯一の変更を行うツール（lan.wol）は、ドライランのプランと、1 回限り・有効期限 10 分の confirmToken を使用します。パラメーターはプラン作成時に固定されます。
• 機能を正直に提示。 ツールはデータを生成したバックエンド（偽の「ping」ではなく backend: "tcp-connect"）を報告します。net.health はこのホストで利用できる機能を明示し、利用できない機能にはインストール方法を案内します。
• テレメトリーなし。 外部への情報送信はありません。ただし、インターネットに関する 3 つのツール（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	OS が実際に使用する DNS サーバー（プラットフォーム別）
dns.propagation	システム＋信頼できるリゾルバー＋DoH で同じレコードを確認 — 差分テーブル
dns.hijackcheck	重要なチェック：既知の正常なドメインをシステム経由と信頼できる DoH 経由で確認。不一致または NXDOMAIN の場合は Finding{sev:high}

lan.* — デバイスとインベントリ

ツール	機能
lan.interfaces	NIC：名前、MAC、アドレス、種類、仮想フラグ
lan.gateway	デフォルトゲートウェイ＋インターフェース＋ローカルサブネット CIDR
lan.arp	解析済みの近隣キャッシュ。古いエントリは除外されます
lan.sweep	RFC1918 サブネットを ping でプローブ（≤1024 ホスト、レート制限は 1/30 秒）→ 稼働中のホスト一覧
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 ブロードキャストを 1 回実行

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 } を指定します。nmap がない場合はインストール方法のヒントが表示されるだけで、クラッシュすることはありません。
• 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