mirror of
https://github.com/hansjone/netx.git
synced 2026-10-08 23:33:21 +08:00
Add standalone topology MCP with skill, scopes UI, and opt-in live sync.
Splits canvas/Fabric tools into netx-topology-mcp, documents install and a companion Cursor skill, lets API keys grant ne:write explicitly, and adds optional topology live sync so operators can watch agent drawing without constant polling. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
parent
a95b96f648
commit
bf0dfd66d8
30 changed files with 2057 additions and 410 deletions
|
|
@ -113,7 +113,7 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
|
|||
|
||||
1. 完成上文 **§1**（用 **oclaw 同机同一个 `python`** 安装 `netx-mcp`）。
|
||||
2. Admin → MCP → 粘贴 `mcp.json` 全文 → 点击 **Install from JSON**（安装状态在下方一行小字）。
|
||||
3. **Health** → **Sync Tools**（应看到 **14** 个工具）。
|
||||
3. **Health** → **Sync Tools**（应看到 **13** 个工具）。
|
||||
4. 在 **MCP 专家绑定** 中为 ops 专家勾选 `server_id=netx`。
|
||||
|
||||
更细的 oclaw 说明（双轨内置工具、锚点注入等）见 oclaw 仓库：
|
||||
|
|
@ -121,6 +121,8 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
|
|||
|
||||
可选：oclaw 专用字段展开版 [`mcp_install_payload.json`](../mcp_install_payload.json)（与 `mcp.json` 等价）。
|
||||
|
||||
**拓扑画布 MCP**（独立安装/绑定）见 [`MCP_TOPOLOGY.md`](./MCP_TOPOLOGY.md)（`server_id=netx-topology`，13 个工具）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 暴露的工具
|
||||
|
|
@ -131,9 +133,8 @@ pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx
|
|||
| UME 网元 | `queryUmeNeInventory`, `getUmeNe` |
|
||||
| UME 原始/SQL | `queryUmeAlarmsRaw`, `aggregateUmeAlarmsRaw`, `listUmeAlarmFields`, `sqlQueryUme` |
|
||||
| 托管网元 CLI | `listManagedNe`, `getManagedNe`, `execManagedNe`, `listCliTargets` |
|
||||
| 拓扑 Fabric | `queryTopologyEdges`（`node_id` → A 的链路与 `peer_count` 互联网元数） |
|
||||
|
||||
物理拓扑仅 LLDP；分页查询，勿默认拉全图。oclaw 中名称带前缀：`mcp__netx__<toolName>`。
|
||||
拓扑 Fabric / 画布工具已拆到 **[`netx-topology-mcp`](./MCP_TOPOLOGY.md)**（含原 `queryTopologyEdges`）。oclaw 中名称带前缀：`mcp__netx__<toolName>`。
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
118
docs/MCP_TOPOLOGY.md
Normal file
118
docs/MCP_TOPOLOGY.md
Normal file
|
|
@ -0,0 +1,118 @@
|
|||
# netx Topology MCP — 安装与更新
|
||||
|
||||
与告警/CLI 的 [`netx-mcp`](./MCP.md) **分开**的 stdio MCP，只提供 **拓扑树、画布（views）、Fabric 边/邻接**。Agent 可只装本包，或与 `netx` 并存。
|
||||
|
||||
```
|
||||
MCP 宿主 → stdio netx_topology_mcp → HTTP NETX_API_URL → /v1/topology/*
|
||||
```
|
||||
|
||||
| 组件 | 说明 |
|
||||
|------|------|
|
||||
| **netx API** | 需已启动，拓扑数据在服务端 |
|
||||
| **netx-topology-mcp** | 轻量 HTTP 客户端，与宿主同机 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 安装
|
||||
|
||||
```powershell
|
||||
cd D:\project\chatgpt\netx
|
||||
pip install -e ./packages/netx-topology-mcp
|
||||
python -c "import netx_topology_mcp; print('ok')"
|
||||
python -m netx_topology_mcp
|
||||
```
|
||||
|
||||
从 GitHub：
|
||||
|
||||
```powershell
|
||||
pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx-topology-mcp"
|
||||
```
|
||||
|
||||
环境变量与 [`MCP.md`](./MCP.md) 相同：`NETX_API_URL`、`NETX_API_TOKEN` / `data/auth/mcp_token`、`NETX_LANG`。
|
||||
|
||||
---
|
||||
|
||||
## 2. Cursor / oclaw 配置
|
||||
|
||||
独立服务器 id：`netx-topology`（不要与 `netx` 混在同一个 command 里）。
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"netx-topology": {
|
||||
"command": "python",
|
||||
"args": ["-m", "netx_topology_mcp"],
|
||||
"env": {
|
||||
"NETX_API_URL": "http://127.0.0.1:8890",
|
||||
"NETX_LANG": "zh",
|
||||
"PYTHONIOENCODING": "utf-8",
|
||||
"PYTHONUTF8": "1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
样本：[`packages/netx-topology-mcp/mcp.json`](../packages/netx-topology-mcp/mcp.json)。
|
||||
|
||||
与告警 MCP 并存时，把两个 server 都放进 `mcpServers` 即可；未勾选/未安装的不会加载工具。
|
||||
|
||||
oclaw：Install from JSON → Health → Sync Tools（应看到 **13** 个工具）→ 专家绑定勾选 `server_id=netx-topology`。
|
||||
|
||||
配套 Agent Skill（画图流水线 / 安全约束）：[`.cursor/skills/netx-topology/SKILL.md`](../.cursor/skills/netx-topology/SKILL.md)。Cursor / oclaw 读 skill 后再调 MCP。
|
||||
|
||||
---
|
||||
|
||||
## 3. 工具一览
|
||||
|
||||
### 读
|
||||
|
||||
| 工具 | 作用 |
|
||||
|------|------|
|
||||
| `getTopologyTree` | 站点/区域文件夹树 + 下属画布 |
|
||||
| `listTopologyViews` / `getTopologyView` | 画布列表 / 单图（节点+边+坐标） |
|
||||
| `getTopologyFabricSummary` | Fabric 汇总 |
|
||||
| `listTopologyFabricNodes` / `searchTopologyFabricNodes` | 网元搜索 |
|
||||
| `queryTopologyNeighborhood` | 指定节点邻接 |
|
||||
| `queryTopologyEdges` | LLDP/手工链路（含 `peer_count`） |
|
||||
|
||||
### 写（只动画布，不污染 Fabric）
|
||||
|
||||
| 工具 | 作用 |
|
||||
|------|------|
|
||||
| `createTopologyView` | 在 folder 下新建画布 |
|
||||
| `addTopologyViewNodes` | **仅** `fabric_node_ids` 放到画布（拒绝 managed/UME，避免创建 Fabric 占位） |
|
||||
| `removeTopologyViewNodes` | 从画布移除（不删 Fabric） |
|
||||
| `updateTopologyViewPositions` | 设置坐标 |
|
||||
| `projectTopologyNeighbors` | 投影**已有** LLDP 邻居到画布 |
|
||||
|
||||
**刻意不提供：** 手工建链、`populate`（会经 managed 创建 Fabric 占位）、删 Fabric / 删整图。
|
||||
|
||||
写操作需要 token 具备 `ne:write`；只读为 `ne:read`。
|
||||
|
||||
**权限怎么开：** 网页 **系统 → API Key**（`/api-keys`）创建 Key 时勾选 scopes，或点「MCP + 拓扑写」。默认 bootstrap `data/auth/mcp_token` **没有** `ne:write`，Agent 的 `tools/list` **不会出现**写工具。把新 Key 配到 `NETX_API_TOKEN`（或写进 MCP env）后重启 MCP / Sync Tools。
|
||||
|
||||
**前端能否看着画：** 在拓扑页左侧树或右侧浏览区点 **「实时同步」**（默认关闭；**不需要先打开某张图**）。开启后树约每 5 秒、已打开的图约每 3 秒拉取，可看到 MCP 新建区域/画布并往上加点。有未保存本地拖动时不会覆盖你的编辑。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 netx-mcp 的关系
|
||||
|
||||
| 包 | server_id | 职责 |
|
||||
|----|-----------|------|
|
||||
| `netx-mcp` | `netx` | 告警、UME、托管网元 CLI（**13** 工具） |
|
||||
| `netx-topology-mcp` | `netx-topology` | 拓扑画布 / Fabric 只读 + 安全画图（**13** 工具） |
|
||||
|
||||
`queryTopologyEdges` 已从 `netx-mcp` **迁出**到本包，避免重复。
|
||||
|
||||
---
|
||||
|
||||
## 5. 更新
|
||||
|
||||
```powershell
|
||||
cd <netx 仓库>
|
||||
git pull
|
||||
pip install -e ./packages/netx-topology-mcp
|
||||
```
|
||||
|
||||
然后重启 MCP 宿主，并 Sync Tools。
|
||||
Loading…
Add table
Add a link
Reference in a new issue