hansjone/oclaw
1
0
Fork 0
mirror of https://github.com/hansjone/oclaw.git synced 2026-10-09 03:30:48 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(mcp): integrate netx via netx_mcp and improve MCP install

Browse source 
- 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>
This commit is contained in:
oliver 2026-05-30 15:44:34 +08:00
parent bbd7b0300f
commit a0a3f4b65f
17 changed files with 408 additions and 536 deletions
Download patch file Download diff file Expand all files Collapse all files

149
docs/NETX_MCP_INTEGRATION.md
View file

@ -1,10 +1,10 @@
# netx MCP Integration (same-host)
# netx MCP Integration
This guide wires `oclaw` to the independent ops tool in:
Wire **oclaw** (or any MCP host) to the standard **netx HTTP MCP** in `D:/project/chatgpt/netx`.
- `D:/project/chatgpt/netx`
netx 侧通用安装/更新说明：`D:/project/chatgpt/netx/docs/MCP.md`。
Assumption: `oclaw` and `netx` run on the same host.
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
@ -24,82 +24,127 @@ Health check:
curl http://127.0.0.1:8890/health
```
## 2) Register netx MCP in oclaw Admin
## 2) Install netx MCP in oclaw Admin
Use MCP install payload from:
**推荐：直接粘贴与 Cursor 相同的 `mcpServers` JSON**（与 `netx/mcp.json` 一致），在 Admin → MCP → 安装 JSON 粘贴后安装，无需再手写 `entry_command` / `entry_args`：
```json
{
"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:
Equivalent manual values（与上面 `mcpServers` 同义）：
- `source_type`: `local`
- `source_ref`: `netx-local-mcp`
- `server_id`: `netx-local`
- `entry_command`: `python`
- `entry_args`: `["D:/project/chatgpt/netx/netx_api/mcp_server.py"]`
- `timeout_s`: `30`
| 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` |
Then run:
**两件事情要分开：**
1. `Health`
2. `Sync Tools`
| 组件 | 跑在哪 | 配置 |
|------|--------|------|
| **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` |
Expected tools:
远端只部署 **netx 服务** 时：把 `NETX_API_URL` 改成远端地址即可；**不需要** `NETX_REPO_ROOT`。
- `queryAlarms`
- `aggregateAlarms`
- `getImportBatch`
- `runDiagnostics`
本机开发若未 `pip install`，可临时用脚本路径（二选一）：
```json
"entry_args": ["D:/project/chatgpt/netx/netx_api/mcp_server.py"]
```
或在 oclaw 机执行一次（推荐，与远端 API 无关）：
```powershell
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 MCP specialist binding, include `netx-local` for your ops specialist/workspace.
In Admin **MCP specialist binding**, include server **`netx`** for the ops workspace/specialist.
## 4) Use from chat
## 4) Dual-track: builtin vs MCP
After binding, model can call namespaced tools like:
| 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 |
- `mcp__netx-local__queryAlarms`
- `mcp__netx-local__aggregateAlarms`
- `mcp__netx-local__getImportBatch`
- `mcp__netx-local__runDiagnostics`
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) External link in Admin
## 5) Cursor / Claude Desktop
`oclaw` admin sidebar includes an external link:
与 §2 相同：直接复制 `D:/project/chatgpt/netx/mcp.json` 到 Cursor 配置即可；oclaw Admin 粘贴同一份 JSON 安装。
- `Open netx ops tool` -> `http://127.0.0.1:5173/`
## 6) External link in Admin
If your netx host/port differs, update the link in:
Admin sidebar **Open netx ops tool** → `http://127.0.0.1:5173/` (edit in `interfaces/admin/static/index.html` if host/port differs).
- `interfaces/admin/static/index.html`
## 6) netx -> oclaw AP analyze auth
## 7) netx → oclaw AP analyze auth
`netx` can call:
- `POST /admin/api/ops-ai/analyze-sync`
- `GET /admin/api/ops-ai/health`
Recommended auth:
Shared token:
1. Set shared token in `oclaw` runtime env:
- `OCLAW_OPS_AI_SHARED_TOKEN=<your_token>`
2. Set same token in `netx`:
- `NETX_OCLAW_ANALYZE_TOKEN=<your_token>`
1. oclaw: `OCLAW_OPS_AI_SHARED_TOKEN=<token>`
2. netx: `NETX_OCLAW_ANALYZE_TOKEN=<token>`
Then `netx /v1/ap/analyze` can invoke `oclaw` synchronously.
Timeouts: set `NETX_OCLAW_ANALYZE_READ_TIMEOUT_SEC` (default `180`) in netx if analyze-sync is slow.
**Timeouts:** `netx` → `oclaw` uses HTTP; `analyze-sync` often exceeds old ~35s limits. In netx set `NETX_OCLAW_ANALYZE_READ_TIMEOUT_SEC` (default `180` in `netx_api/config.py`) if you still see read timeouts on slow models or multi-tool turns.
Integration status: `GET http://127.0.0.1:8890/v1/integrations/status`
Integration health in netx:
## 8) Observe AP calls in oclaw
- `GET http://127.0.0.1:8890/v1/integrations/status`
## 7) Observe AP calls in oclaw
Recent ops-ai analyze calls can be fetched from:
- `GET /admin/api/ops-ai/logs?limit=50&offset=0`
Permission: `admin:user:write` (same as admin audit access).
- `GET /admin/api/ops-ai/logs?limit=50&offset=0` (requires `admin:user:write`)