mirror of
https://github.com/hansjone/netx.git
synced 2026-10-18 06:30:48 +08:00
oliver
52679a7cfc
- netx_api/mcp_remote: ops / topology / bizMonitor tools, Bearer auth, per-tool RBAC filtering, ?groups= filter, readOnlyHint and group meta. - Mount the official MCP Streamable HTTP app at /mcp (stateless); AuthAuditMiddleware is pure ASGI and skips /mcp. - Let uvicorn chunk MCP responses; some Windows LSPs rewrite Content-Length replies on */mcp* paths into broken chunked framing. - NETX_MCP_ALLOWED_HOSTS opts into DNS-rebinding checks (off by default so LAN and reverse-proxy hosts work; Bearer is the gate). - Remove the three stdio Python MCP packages; tests moved to /mcp, including real-TCP framing regressions. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
64 lines
2.1 KiB
Markdown
64 lines
2.1 KiB
Markdown
# netx 远程 MCP（Streamable HTTP）
|
||
|
||
netx API 在同一端口（默认 `8890`）提供 `/mcp` 端点，使用 MCP **Streamable HTTP** 传输。客户端（Claude Code、Codex、Cursor、DSH netxops）只需配置 URL 与 Bearer token，**无需安装 Python MCP 包**。
|
||
|
||
## 架构
|
||
|
||
```
|
||
MCP 宿主 → HTTP http://127.0.0.1:8890/mcp → netx_api.mcp_remote（进程内工具）
|
||
```
|
||
|
||
工具分组（查询参数 `groups`）：
|
||
|
||
| groups | 工具数 | 说明 |
|
||
|--------|--------|------|
|
||
| `ops` | 15 | 告警 / 网元 / 只读 CLI |
|
||
| `topology` | 16 | 拓扑树 / 画布 / Fabric / 布局 |
|
||
| `bizMonitor` | 8 | 割接与业务状态只读 |
|
||
| （省略） | 39 | 当前 token 有权限的全部工具 |
|
||
|
||
示例：`/mcp?groups=ops,bizMonitor`
|
||
|
||
## 鉴权
|
||
|
||
- Header：`Authorization: Bearer <token>`
|
||
- 接受 MCP 令牌（`NETX_AUTH_MCP_TOKEN_FILE`，bootstrap 写入）或用户 JWT
|
||
- 无 token / 无效 → HTTP **401**
|
||
- `tools/list` 只列出当前 token 有 scope 的工具；`tools/call` 再按 RBAC 校验
|
||
|
||
## 客户端配置
|
||
|
||
见根目录 [`mcp.all.json`](../mcp.all.json)。Claude Code 示例：
|
||
|
||
```bash
|
||
claude mcp add --transport http netx http://127.0.0.1:8890/mcp \
|
||
--header "Authorization: Bearer <token>"
|
||
```
|
||
|
||
仅 ops：
|
||
|
||
```text
|
||
http://127.0.0.1:8890/mcp?groups=ops
|
||
```
|
||
|
||
## 语言
|
||
|
||
- 环境变量 `NETX_LANG=zh|en`，或请求头 `Accept-Language`
|
||
- 工具 `description` / `inputSchema` 与历史 Python 包一致；`en` 时 API 查询附加 `lang=en`
|
||
|
||
## 安全
|
||
|
||
- `execManagedNe` 等写工具带 `annotations.readOnlyHint=false`
|
||
- CLI 硬门（`cli_guard`）：仅单行 `show`/`display`，拒绝 shell 与破坏性命令
|
||
- 异步 exec / layout job：先返回 job id，再用轮询工具查询
|
||
|
||
## 版本
|
||
|
||
`initialize.serverInfo.version` 使用 netx 包版本（`pyproject.toml` / `netx-ops`）。
|
||
|
||
无状态模式下不主动推送 `notifications/tools/list_changed`；客户端应在需要时重新 `tools/list`。
|
||
|
||
## 相关文档
|
||
|
||
- [MCP_TOPOLOGY.md](./MCP_TOPOLOGY.md) — topology 组工具说明
|
||
- [MCP_BIZMONITOR.md](./MCP_BIZMONITOR.md) — bizMonitor 组工具说明
|