oclaw/docs/NETX_MCP_INTEGRATION.md

netx MCP Integration

Wire oclaw (or any MCP host) to the standard netx HTTP MCP in D:/project/chatgpt/netx.

netx 侧通用安装/更新说明：D:/project/chatgpt/netx/docs/MCP.md。

Default path: stdio MCP → netx REST API (NETX_API_URL). oclaw also uses the same REST base for ops context inject and ume_alarm_xlsx_report via shared netx_http.

1) Start netx API

In D:/project/chatgpt/netx:

python -m pip install -r requirements.txt
$env:NETX_DATABASE_URL = "postgresql+psycopg://netx:netx@127.0.0.1:5432/netx"
$env:NETX_HOST = "127.0.0.1"
$env:NETX_PORT = "8890"
python -m netx_api.main

Health check:

curl http://127.0.0.1:8890/health

2) Install netx MCP in oclaw Admin

推荐：直接粘贴与 Cursor 相同的 mcpServers JSON（与 netx/mcp.json 一致），在 Admin → MCP → 安装 JSON 粘贴后安装，无需再手写 entry_command / entry_args：

{
  "mcpServers": {
    "netx": {
      "command": "python",
      "args": ["-m", "netx_mcp"],
      "env": {
        "NETX_API_URL": "http://127.0.0.1:8890",
        "NETX_API_TOKEN": "",
        "NETX_LANG": "zh"
      }
    }
  }
}

oclaw 会把 command → entry_command、args → entry_args，env → 注册表 env_schema（含 default，运行时传给 MCP 子进程）；stdio 条目默认 source_type=local。与下文「install payload」等价。

本机默认 http://127.0.0.1:8890 时，env 可省略（netx_mcp 代码内也有相同默认）；远端 API 或 Token 时在 JSON 的 env 里写即可，不必再单独维护 mcp_install_payload.json。

也可用 oclaw 专用 install payload（字段展开版，便于脚本/文档引用）：

• D:/project/chatgpt/netx/mcp_install_payload.json

Equivalent manual values（与上面 mcpServers 同义）：

Field	Value
source_type	local
source_ref	netx-mcp-http
server_id	netx
entry_command	python
entry_args	["-m", "netx_mcp"]
timeout_s	120
MCP env	NETX_API_URL（可指向远端）、可选 NETX_API_TOKEN、NETX_LANG

两件事情要分开：

组件	跑在哪	配置
netx REST API（告警/网元数据）	本机或远端服务器	NETX_API_URL，例如 http://10.0.0.5:8890
netx MCP 子进程（stdio，给 oclaw 调工具）	必须与 oclaw 同机（或 oclaw 能 python 到的环境）	pip install -e <netx>/packages/netx-mcp 后 python -m netx_mcp

远端只部署 netx 服务 时：把 NETX_API_URL 改成远端地址即可；不需要 NETX_REPO_ROOT。

本机开发若未 pip install，可临时用脚本路径（二选一）：

"entry_args": ["D:/project/chatgpt/netx/netx_api/mcp_server.py"]

或在 oclaw 机执行一次（推荐，与远端 API 无关）：

pip install -e D:/project/chatgpt/netx/packages/netx-mcp

注意：source_type=local 表示跳过 npm/pypi 的「安装包」步骤，但 oclaw 机上仍须能 import netx_mcp（通过上面的 pip 安装）。

Then run Health → Sync Tools.

Expected MCP tools (13)

MCP tool	oclaw namespaced	Legacy builtin (if enabled)
queryUmeAlarms	mcp__netx__queryUmeAlarms	netx_query_ume_alarms
aggregateUmeAlarms	mcp__netx__aggregateUmeAlarms	netx_aggregate_ume_alarms
runUmeDiagnostics	mcp__netx__runUmeDiagnostics	netx_run_ume_diagnostics
queryUmeNeInventory	mcp__netx__queryUmeNeInventory	netx_query_ume_ne_inventory
getUmeNe	mcp__netx__getUmeNe	netx_get_ume_ne
queryUmeAlarmsRaw	mcp__netx__queryUmeAlarmsRaw	netx_query_ume_alarms_raw
aggregateUmeAlarmsRaw	mcp__netx__aggregateUmeAlarmsRaw	netx_aggregate_ume_alarms_raw
listUmeAlarmFields	mcp__netx__listUmeAlarmFields	netx_list_ume_alarm_fields
sqlQueryUme	mcp__netx__sqlQueryUme	netx_sql_query_ume
listManagedNe	mcp__netx__listManagedNe	netx_list_managed_ne
getManagedNe	mcp__netx__getManagedNe	netx_get_managed_ne
execManagedNe	mcp__netx__execManagedNe	netx_exec_managed_ne
listCliTargets	mcp__netx__listCliTargets	—

execManagedNe accepts ne_id (managed NE) or ume_ne_id (UME inventory NE). For UME lazy exec, configure CLI profile at netx UI UME → CLI 连接 (/ume tab) before running show commands.

不暴露（已废弃 Excel 导入批次链路）：netx_query_alarms、netx_list_import_batches、netx_sql_query（带 batch_id）等。

3) Bind to ops specialist

In Admin MCP specialist binding, include server netx for the ops workspace/specialist.

4) Shared REST helpers in oclaw

oclaw keeps a small HTTP client (runtime/tools/experts/network_ops/netx_http.py) for:

• ops system-context anchor inject (OCLAW_OPS_NETX_CONTEXT_INJECT)
• always-on ume_alarm_xlsx_report (Excel export shortcut)

Interactive alarm/NE tools are MCP only (mcp__netx__*). Inline netx_* expert tools were removed.

Runtime anchor inject still needs netx API reachable at NETX_API_URL / OCLAW_NETX_BASE_URL.

5) Cursor / Claude Desktop

与 §2 相同：直接复制 D:/project/chatgpt/netx/mcp.json 到 Cursor 配置即可；oclaw Admin 粘贴同一份 JSON 安装。

6) External link in Admin

Admin sidebar Open netx ops tool → http://127.0.0.1:5173/ (edit in interfaces/admin/static/index.html if host/port differs).

7) netx → oclaw AP analyze auth

netx can call:

• POST /admin/api/ops-ai/analyze-sync
• GET /admin/api/ops-ai/health

Shared token:

1. oclaw: OCLAW_OPS_AI_SHARED_TOKEN=<token>
2. netx: NETX_OCLAW_ANALYZE_TOKEN=<token>

Timeouts: set NETX_OCLAW_ANALYZE_READ_TIMEOUT_SEC (default 180) in netx if analyze-sync is slow.

Integration status: GET http://127.0.0.1:8890/v1/integrations/status

8) Observe AP calls in oclaw

• GET /admin/api/ops-ai/logs?limit=50&offset=0 (requires admin:user:write)