netx/docs/MCP.md

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

---

前置条件

1. netx API 已启动且可访问：

   curl http://127.0.0.1:8890/health
   

2. Python 3.11+（与 MCP 宿主使用的 python 一致）。

3. 远端 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

验证：

python -m netx_mcp
# 另开终端发 JSON-RPC initialize（或见下文「自检」）
python -c "import netx_mcp; print('ok')"

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

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

固定分支或 tag 时在 .git 后加 @，例如 @main 或 @v0.2.0：

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

私有仓库需本机已配置 Git 凭据（或 SSH：git+ssh://git@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. 完成上文 §1（本机 pip install -e packages/netx-mcp）。
2. Admin → MCP → 安装 JSON，粘贴 mcp.json 全文。
3. Health → Sync Tools（应看到 12 个工具）。
4. 在 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 拉代码并重装包

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	在 MCP 宿主使用的 Python 上执行 pip install -e packages/netx-mcp
工具调用连不上 API	检查 NETX_API_URL、防火墙、远端 API 是否启动
Windows 乱码 / JSON 解析失败	配置里保留 PYTHONIOENCODING=utf-8、PYTHONUTF8=1（见 mcp.json）
oclaw 工具数为 0	Admin Sync Tools；确认 server_id=netx 已绑定专家
仍想用仓库脚本路径	未 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	子包速查