oliver
9085cac742
- New packages/netx-bizmonitor-mcp: 8 read-only cutover/biz-state tools mirroring the netxops bizMonitor group. - Align netx-mcp (15) and netx-topology-mcp (16) with backend HTTP contracts; surface partial batch failures as tool errors. - CLI hard gate: single-line show/display only; exec job IDs, path containment, owner and ne:exec checks. - Cisco IOSv collection: stable prompt/echo handling over CR. - Remove legacy netx_api/mcp and mcp_server.py; add mcp.all.json; sync skills and docs. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
|---|---|---|
| .. | ||
| src/netx_mcp | ||
| tests | ||
| mcp.json | ||
| pyproject.toml | ||
| README.md | ||
| SKILLS.md | ||
netx-mcp
轻量 stdio MCP 客户端，通过 HTTP 调用 netx REST API。装在 Cursor、oclaw、Claude Desktop 等 MCP 宿主所在机器；NETX_API_URL 可指向本机或远端 API。
安装、更新、各宿主配置、排错 → 仓库主文档 docs/MCP.md（请优先阅读）。
Skills（唯一真源在仓库根 skills/） — 本包不镜像 skills。
速查：安装
# 在 netx 仓库根目录
pip install -e ./packages/netx-mcp
python -c "import netx_mcp; print('ok')"
要求 Python 3.11+，且 netx API 已运行（GET /health）。
速查：更新
cd <netx 仓库>
git pull
pip install -e ./packages/netx-mcp
然后 重启 MCP 宿主（Cursor 重开；oclaw 重启后在 Admin 对 netx 执行 Health → Sync Tools）。
运行
$env:NETX_API_URL = "http://127.0.0.1:8890"
python -m netx_mcp
# 或: netx-mcp
配置
mcp.json — command: python，args: ["-m", "netx_mcp"]，env 见文件。
工具（15）— skill 组 ops（netx-ops）
NMS（模型面通用名；当前适配器 zte-ume，REST 仍 /v1/ume/*）：
queryNmsAlarms, aggregateNmsAlarms, runNmsDiagnostics, queryNmsNeInventory, getNmsNe, queryNmsAlarmsRaw, aggregateNmsAlarmsRaw, listNmsAlarmFields, sqlQueryNms
Managed CLI + paths（问「能否登录」必须走这里，不要只查 inventory）：
listManagedNe, getManagedNe, execManagedNe, getNeExecJob, listCliTargets, findTopologyPaths
0.3.1：getNmsNe 可直接传 host_name/IP；输出统一 nms_ne_id / source=nms；参数类型错误返回工具错误而非协议崩溃。
参数使用 nms_ne_id / nms_ne_ids，路径端点使用 from_nms_ne_id / to_nms_ne_id；getManagedNe 只接受 ne_id。旧 ume_*、managed_ne_id、id、告警 ne_name 别名已删除，未知参数会返回工具错误。REST 适配器内部的 ume_* 字段不变。
NMS 查询（含 inventory）按当前 HTTP 权限规则需要 alarms:read；托管资源、CLI 目标和路径查询需要 ne:read；执行与轮询需要 ne:exec；SQL 需要 sql:query。所有工具返回递归裁剪结构化口令、令牌等凭据，但 CLI 原文输出仍需调用者判断是否敏感。
拓扑画布 / Fabric → skill topology / netx-topology-mcp（见 docs/MCP_TOPOLOGY.md）。
业务监控 / 割接 → netx-bizmonitor-mcp。三组统一配置见根 mcp.all.json，均不依赖 netxops。
本包的 execManagedNe 独立强制只读 show/display；即使后端设备开放 shell，也拒绝配置、命令拼接、重定向和多行脚本。getManagedNe.capability 描述后端能力，不能作为 MCP 脚本许可；Linux/RouterOS 原生 CLI 当前未暴露。异步 ack 返回 poll_after_ms=5000；单台核对 terminal/result.ok，批量还须核对 summary.failed=0 和每个 results[].ok。作业 succeeded 仍可能有单台失败，须分别报告，勿整批重跑已成功设备。失败 job 作为工具错误返回，保留原始失败证据。
同 IP 多条纳管记录须按厂商/驱动选 ID。connect_status 为历史连接测试状态，不替代当前执行结果；有正常业务正文才算查询通过，不能把空正文或仅命令头当作成功。后端的 Cisco IOS SSH 驱动使用 CR 换行并等待命令回显和完整提示符；不影响其它厂商或 Telnet 的默认换行。
Breaking (0.3.0)
模型工具名从 *Ume* 改为 *Nms*（与 dsh-netxops 对齐）。请更新 skills / 提示词并重启 MCP 宿主。
入口
只保留独立 netx-mcp 包入口：python -m netx_mcp / netx-mcp。旧 netx_api.mcp、netx_api/mcp_server.py 和直连数据库模式已删除；配置需迁移到本包。
旧 DB 模式的导入告警查询/聚合/批次/诊断、同步触发和历史告警查询未纳入本包 15 工具，相关 HTTP API 仍保留。