oliver
a0a3f4b65f
- Gate builtin netx tools; ops docs/skills use mcp__netx__* - Import Cursor mcpServers JSON; pass env_schema defaults to subprocess - Allow source_type=local; UTF-8 MCP stdio on Windows Co-authored-by: Cursor <cursoragent@cursor.com>
5.8 KiB
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). Legacy inline HTTP tools in oclaw are opt-in via OCLAW_NETX_BUILTIN_TOOLS=1.
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 (12)
| 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 |
不暴露（已废弃 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) Dual-track: builtin vs MCP
| Setting | Effect |
|---|---|
OCLAW_NETX_BUILTIN_TOOLS=0 (default) |
Only MCP tools (mcp__netx__*); no duplicate inline netx_* in catalog |
OCLAW_NETX_BUILTIN_TOOLS=1 |
Registers legacy inline HTTP tools and MCP if installed — avoid binding both unless testing migration |
Runtime anchor inject (OCLAW_OPS_NETX_CONTEXT_INJECT=1) still works without builtin tools; it only 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-syncGET /admin/api/ops-ai/health
Shared token:
- oclaw:
OCLAW_OPS_AI_SHARED_TOKEN=<token> - 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(requiresadmin:user:write)