mirror of https://github.com/hansjone/netx.git synced 2026-10-09 04:20:45 +08:00

oliver 651ee47842 docs(mcp): clarify oclaw install and same-python self-check

Co-authored-by: Cursor <cursoragent@cursor.com>

2026-05-30 23:42:44 +08:00

7.6 KiB

Raw Blame History

netx MCP — 安装与更新

netx 通过 stdio MCP 把告警/网元能力暴露给 Cursor、Claude Desktop、oclaw 等宿主。MCP 进程只做 HTTP 客户端，不直连数据库；数据来自已运行的 netx REST API。

MCP 宿主 (Cursor / oclaw)  →  stdio  netx_mcp  →  HTTP  NETX_API_URL  →  netx API

组件	部署位置	说明
netx API	本机或远端服务器	`python -m netx_api.main`，默认 `http://127.0.0.1:8890`
netx-mcp	与 MCP 宿主同机	`pip install` 轻量包，仅需 Python + httpx

前置条件

netx API 已启动且可访问：
```
curl http://127.0.0.1:8890/health
```
Python 3.11+（与 MCP 宿主使用的 python 一致）。
远端 API 时：记下 base URL（无尾部 /），例如 http://10.0.0.5:8890。

1. 安装 `netx-mcp` 包

在 运行 MCP 的那台机器上执行（不必安装整套 netx 服务依赖）：

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

验证（必须用 oclaw 启动时会调用的同一个 python，见下方说明）：

where python
python -c "import netx_mcp; print('ok')"
python -m netx_mcp

若你在 A 终端里 import netx_mcp 成功，但 oclaw Admin 安装/Health 无反应或失败，多半是 pip 装到了另一个 Python。请用 oclaw 实际用的解释器安装：

# 把路径换成 where python 的第一条，或 oclaw 服务 venv 里的 python.exe
C:\Path\To\Same\python.exe -m pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx-mcp"
C:\Path\To\Same\python.exe -c "import netx_mcp; print('ok')"

从 GitHub 安装（无本地仓库时，子目录必须是 packages/netx-mcp）：

pip install "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx-mcp"

开发者在 netx 仓库根目录也可 pip install -e .（含 API）；MCP 仍推荐只装 packages/netx-mcp。

2. 环境变量

变量	必填	默认	说明
`NETX_API_URL`	否	`http://127.0.0.1:8890`	netx REST 根地址，可指向远端
`NETX_API_TOKEN`	否	空	API 启用 Bearer 时填写
`NETX_LANG`	否	`zh`	`zh` / `en`，影响 API 文案

本机默认端口时 可不设任何变量。

3. 在 Cursor / Claude Desktop 中配置

复制仓库中的 mcp.json（或 packages/netx-mcp/mcp.json）到客户端 MCP 配置，例如 Cursor：.cursor/mcp.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",
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUTF8": "1"
      }
    }
  }
}

保存后 重启 Cursor/客户端，使 MCP 子进程重新拉起。

4. 在 oclaw Admin 中安装

与 Cursor 同一份 mcpServers JSON 即可，无需转成别的格式。

完成上文 §1（用 oclaw 同机同一个 python 安装 netx-mcp）。
Admin → MCP → 粘贴 mcp.json 全文 → 点击 Install from JSON（安装状态在下方一行小字）。
Health → Sync Tools（应看到 12 个工具）。
在 MCP 专家绑定 中为 ops 专家勾选 server_id=netx。

更细的 oclaw 说明（双轨内置工具、锚点注入等）见 oclaw 仓库：
oclaw/docs/NETX_MCP_INTEGRATION.md。

可选：oclaw 专用字段展开版 mcp_install_payload.json（与 mcp.json 等价）。

5. 暴露的 12 个工具

类别	工具名
UME 告警	`queryUmeAlarms`, `aggregateUmeAlarms`, `runUmeDiagnostics`
UME 网元	`queryUmeNeInventory`, `getUmeNe`
UME 原始/SQL	`queryUmeAlarmsRaw`, `aggregateUmeAlarmsRaw`, `listUmeAlarmFields`, `sqlQueryUme`
托管网元 CLI	`listManagedNe`, `getManagedNe`, `execManagedNe`

oclaw 中名称带前缀：mcp__netx__<toolName>。

6. 更新 MCP

MCP 代码在 packages/netx-mcp（版本见 packages/netx-mcp/pyproject.toml）。更新步骤：

6.1 重装 `netx-mcp` 包

远程 MCP 机 / 无本地 netx 仓库（不必 git pull，每次更新执行一条即可）：

pip install --upgrade "git+https://github.com/hansjone/netx.git#subdirectory=packages/netx-mcp"

本机有 netx 仓库（开发）：

cd D:\project\chatgpt\netx
git pull
pip install -e ./packages/netx-mcp

确认版本（可选）：

pip show netx-mcp

6.2 重启 MCP 宿主

宿主	操作
Cursor / Claude	完全退出客户端后重开，或重载 MCP
oclaw	重启 gateway/主进程；Admin 对 `netx` 再点 Health → Sync Tools

仅改 NETX_API_URL 等 env 时，同样需重启 MCP 子进程（或 oclaw 整进程）。

6.3 无需改配置的情况

只改 netx API 业务逻辑、未改 MCP 工具名/参数：重装 netx-mcp 可选；API 部署后 MCP 自动走新 API。
改了 工具列表或 JSON schema：必须重装 netx-mcp 并在宿主 Sync Tools。

6.4 从旧入口迁移

旧方式	新方式
`python -m netx_api.mcp`	`python -m netx_mcp`（推荐）
`NETX_MCP_MODE=db` 直连库	已废弃；使用 HTTP 模式

根目录 python -m netx_api.mcp 仍会委托到 netx_mcp，新环境请只装 netx-mcp 包。

7. 自检

API：

curl http://127.0.0.1:8890/health

MCP 工具列表（需已 pip install -e packages/netx-mcp）：

cd D:\project\chatgpt\netx
python -m pytest packages/netx-mcp/tests/test_mcp_http.py -q

手动 stdio（PowerShell 示例）：

$env:NETX_API_URL = "http://127.0.0.1:8890"
$p = Start-Process python -ArgumentList "-m","netx_mcp" -RedirectStandardInput pipe -RedirectStandardOutput pipe -NoNewWindow -PassThru
# 向 stdin 写入一行 JSON-RPC initialize / tools/list（见 packages/netx-mcp/tests）

8. 常见问题

现象	处理
`ModuleNotFoundError: netx_mcp`	用 oclaw 同机同一个 `python.exe` 执行 pip 安装（见 §1 验证）
oclaw Admin 点安装「没反应」	1) 必须点 Install from JSON（只粘贴不点按钮无效） 2) 看安装区下方 install status 一行字（应出现 `[json] installing...` 或错误） 3) 浏览器 F12 → Console 是否有红色报错 4) 确认 JSON 为完整 `mcpServers` 或 `mcp_install_payload.json` 格式
oclaw preflight `mcp_python_module_missing`	`python` 在 PATH 里但无 `netx_mcp`；对该 python 执行 git+pip 安装
工具调用连不上 API	检查 `NETX_API_URL`、防火墙、远端 API 是否启动
Windows 乱码 / JSON 解析失败	配置里保留 `PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`（见 `mcp.json`）
oclaw 工具数为 0	Admin Health → Sync Tools；确认 `server_id=netx` 已绑定 ops 专家
仍想用仓库脚本路径	未 pip 安装时可临时 `"args": ["D:/.../netx_api/mcp_server.py"]`（开发用）

文件	用途
`packages/netx-mcp/`	MCP 实现与 `pyproject.toml`
`mcp.json`	Cursor / oclaw 粘贴用配置
`mcp_install_payload.json`	oclaw 字段展开版（可选）
`packages/netx-mcp/README.md`	子包速查

7.6 KiB Raw Blame History Unescape Escape