Skip to content

Commit 21fdd74

Browse files
tsosunchiatsosunchia
authored
Merge pull request #366 from nxtrace/main
MCP / SKILL 支持
2 parents 3ba3d0f + d678ac8 commit 21fdd74

42 files changed

Lines changed: 5625 additions & 126 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -263,6 +263,47 @@
263263
- `server/trace_handler.go`：traceroute handler
264264
- `server/cache_handler.go`：缓存
265265

266+
## Deploy WebUI / MCP / Agent Skill（2026-04 追加）
267+
268+
- MCP 只属于完整版 `nexttrace`，`nexttrace-tiny` / `ntr` 不注册 WebUI/MCP flags。
269+
- `--mcp` 只能与 `--deploy` 同用；单独传 `--mcp` 必须报错。
270+
- `--deploy --mcp` 不提供 stdio MCP，只通过 deploy 网络服务在 `/mcp` 暴露 Streamable HTTP，使用官方 `github.com/modelcontextprotocol/go-sdk`。
271+
- `server.RunWithOptions(options, onReady)` 是 deploy 新入口；`server.Options` 包含 `ListenAddr`、`EnableMCP`、`AuthEnabled`、`DeployToken`。
272+
- deploy 鉴权规则：
273+
- 监听 `127.0.0.1`、`::1`、`localhost` 默认免 token。
274+
- 监听 `0.0.0.0`、`::`、非 loopback IP/host 时默认启用 token。
275+
- 外网监听且用户未提供 token 时启动生成随机 token 并输出到 stdout。
276+
- `--deploy-token` 优先于 `NEXTTRACE_DEPLOY_TOKEN`；手动 token 不回显。
277+
- `AuthEnabled=true` 但 token 为空时必须 fail closed。
278+
- WebUI 走 `/auth/login`，成功后写 HttpOnly cookie。
279+
- API/MCP/WS 支持 `Authorization: Bearer <token>`、`X-NextTrace-Token` 和 cookie。
280+
- 不支持 URL query token，尤其 WebSocket 不允许 query token。
281+
- auth middleware 覆盖 `/`、`/assets/*`、`/api/*`、`/ws/trace`、`/mcp`。
282+
- `/mcp` 不要用 `router.Any("/mcp")`，会与 Gin 的静态资源 wildcard `/*path` 冲突；当前只注册 `GET`、`POST`、`DELETE`。
283+
- MCP 与 Web 共用 `internal/service`，不要在 MCP tool 中拼 CLI 参数再反调 CLI。
284+
- MCP tool 输出以 `structuredContent` 为主；schema 要把参数状态分成 `supported`、`not_applicable`、`not_yet_supported`。
285+
- 当前 MCP tools：
286+
- `nexttrace_capabilities`
287+
- `nexttrace_traceroute`
288+
- `nexttrace_mtr_report`
289+
- `nexttrace_mtr_raw`
290+
- `nexttrace_mtu_trace`
291+
- `nexttrace_speed_test`
292+
- `nexttrace_annotate_ips`
293+
- `nexttrace_geo_lookup`
294+
- `nexttrace_globalping_trace`
295+
- `nexttrace_globalping_limits`
296+
- `nexttrace_globalping_get_measurement`
297+
- Globalping MCP 使用 service 专用模型，不复用 CLI `--from` 的单结果输出模型；`nexttrace_globalping_trace` 应返回 `measurement_id`、`status`、`probes_count` 和按 probe 展开的 `results[]`。
298+
- Globalping MCP 当前支持 `target`、`locations[]`、`limit`、`protocol`、`port`、`packets`、`ip_version`；不支持本地 `source/dev/dot_server/packet_size/tos/ttl_interval`。
299+
- Repo Skill 位于 `skills/nexttrace/`，入口是 `skills/nexttrace/SKILL.md`；更新 MCP tool 或参数时必须同步 skill references。
300+
- deploy/MCP 相关回归建议至少覆盖：
301+
- `go test ./...`
302+
- `node --test server/web/assets/*.test.cjs`
303+
- `go test -tags flavor_tiny ./cmd ./server`
304+
- `go test -tags flavor_ntr ./cmd ./server`
305+
- 本地 MCP smoke，traceroute 在 macOS 可显式传 `source_device`（例如 `en8`）。
306+
266307
## DoT 与 Geo DNS
267308

268309
- `--dot-server` 不仅影响目标域名解析，也影响 GeoIP API / LeoMoe FastIP 的域名解析链路。
@@ -321,6 +362,10 @@
321362
- MTR TUI 颜色：`printer/mtr_tui_color.go`
322363
- WS handler：`server/ws_handler.go`（~449 行）
323364
- 前端：`server/web/assets/app.js`
365+
- deploy auth：`server/auth.go`
366+
- deploy MCP：`server/mcp.go`
367+
- Web/MCP 共享服务层：`internal/service/`
368+
- Repo Agent Skill：`skills/nexttrace/`
324369
- Geo DoT 解析：`util/dns_resolver.go`
325370
- Geo HTTP 客户端：`util/http_client_geo.go`
326371
- FastIP：`util/latency.go`

‎README.md‎

Lines changed: 78 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -186,7 +186,7 @@ Starting from this release, NextTrace is published in **three flavors** under th
186186
| MTR wide (`-w`) | ✅ | — | ✅ |
187187
| MTR raw (`--raw`) | ✅ | — | ✅ |
188188
| Globalping (`--from`) | ✅ | — | — |
189-
| WebUI (`--deploy`) | ✅ | — | — |
189+
| WebUI (`--deploy`) / MCP (`--deploy --mcp`) | ✅ | — | — |
190190
| Fast Trace (`-F`) | ✅ | ✅ | — |
191191
| Default mode | traceroute | traceroute | MTR TUI |
192192
| Binary name | `nexttrace` | `nexttrace-tiny` | `ntr` |
@@ -195,9 +195,9 @@ Starting from this release, NextTrace is published in **three flavors** under th
195195
196196
### Feature Matrix
197197
198-
- **`nexttrace`** — Full-featured build. Includes traceroute, standalone MTU, CDN speed test, IP annotation, MTR, Globalping, Fast Trace, and WebUI.
199-
- **`nexttrace-tiny`** — Lightweight build. Keeps normal traceroute, standalone MTU, and Fast Trace. No CDN speed test / IP annotation / MTR / Globalping / WebUI. Suitable for embedded or minimal environments.
200-
- **`ntr`** — MTR-focused build. Runs MTR TUI by default. No normal traceroute mode, standalone `--mtu`, CDN speed test, IP annotation, Globalping, Fast Trace, or WebUI.
198+
- **`nexttrace`** — Full-featured build. Includes traceroute, standalone MTU, CDN speed test, IP annotation, MTR, Globalping, Fast Trace, WebUI, and deploy MCP.
199+
- **`nexttrace-tiny`** — Lightweight build. Keeps normal traceroute, standalone MTU, and Fast Trace. No CDN speed test / IP annotation / MTR / Globalping / WebUI / MCP. Suitable for embedded or minimal environments.
200+
- **`ntr`** — MTR-focused build. Runs MTR TUI by default. No normal traceroute mode, standalone `--mtu`, CDN speed test, IP annotation, Globalping, Fast Trace, WebUI, or MCP.
201201
202202
### Manual Build
203203
@@ -701,6 +701,7 @@ NextTrace currently reads the following environment variables. For boolean switc
701701
| `NEXTTRACE_TOKEN` | unset | Pre-supplied LeoMoeAPI bearer token; when present, token fetching via PoW is skipped. |
702702
| `NEXTTRACE_POWPROVIDER` | `api.nxtrace.org` | Select the PoW provider. The built-in non-default alias is `sakura`. |
703703
| `NEXTTRACE_DEPLOY_ADDR` | unset | Default listen address for `--deploy` when `--listen` is not provided. |
704+
| `NEXTTRACE_DEPLOY_TOKEN` | unset | Token for `--deploy` WebUI/API/WebSocket/MCP access. CLI `--deploy-token` takes precedence. |
704705
| `NEXTTRACE_ALLOW_CROSS_ORIGIN` | `0` | Only for `--deploy`: allow cross-origin browser access to the Web UI / API. Disabled by default for safety. |
705706

706707
#### IP Database / Third-Party Providers
@@ -738,8 +739,9 @@ Usage: nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp]
738739
[-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map]
739740
[-e|--disable-mpls] [-V|--version]
740741
[-s|--source "<value>"] [--source-port <integer>] [-D|--dev
741-
"<value>"] [--listen "<value>"] [--deploy] [-z|--send-time
742-
<integer>] [-i|--ttl-time <integer>] [--timeout <integer>]
742+
"<value>"] [--listen "<value>"] [--deploy-token "<value>"]
743+
[--mcp] [--deploy] [-z|--send-time <integer>]
744+
[-i|--ttl-time <integer>] [--timeout <integer>]
743745
[--psize <integer>] [--dot-server
744746
(dnssb|aliyun|dnspod|google|cloudflare)] [-g|--language
745747
(en|cn)] [-C|--no-color] [--from "<value>"] [-t|--mtr]
@@ -822,6 +824,10 @@ Arguments:
822824
interface
823825
--listen Set listen address for web console (e.g.
824826
127.0.0.1:30080)
827+
--deploy-token Set bearer token for --deploy
828+
WebUI/API/WebSocket/MCP access
829+
--mcp Enable MCP endpoint under --deploy at
830+
/mcp
825831
--deploy Start the Gin powered web console
826832
-z --send-time Advanced: per-packet gap [ms] inside the
827833
same TTL group. Lower is faster; raise to
@@ -895,6 +901,72 @@ For WebSocket continuous tracing, MTR now streams per-event payloads with `type:
895901
896902
[https://github.com/nxtrace/nexttracewebapi](https://github.com/nxtrace/nexttracewebapi)
897903
904+
## Deploy WebUI and MCP
905+
906+
The full `nexttrace` binary can expose the local WebUI/API/WebSocket server:
907+
908+
```bash
909+
nexttrace --deploy
910+
```
911+
912+
MCP is a deploy submode and is exposed over the same network stack at `/mcp`:
913+
914+
```bash
915+
nexttrace --deploy --mcp
916+
nexttrace --deploy --mcp --listen 0.0.0.0:1080 --deploy-token "$TOKEN"
917+
```
918+
919+
Loopback listen addresses (`127.0.0.1`, `::1`, `localhost`) are tokenless by default. External listen addresses require a token; if none is set with `--deploy-token` or `NEXTTRACE_DEPLOY_TOKEN`, NextTrace generates one and prints it to stdout. API, WebSocket, and MCP clients may use `Authorization: Bearer <token>` or `X-NextTrace-Token`; browser WebUI users can sign in at `/auth/login`.
920+
921+
### Register MCP in Agent clients
922+
923+
Start NextTrace first. The MCP endpoint is Streamable HTTP, not stdio:
924+
925+
```text
926+
http://127.0.0.1:1080/mcp
927+
```
928+
929+
For external listeners or manually configured tokens, pass the token in an HTTP header. Do not put deploy tokens in URL query strings.
930+
931+
Generic MCP client config:
932+
933+
```json
934+
{
935+
"mcp": {
936+
"servers": {
937+
"nexttrace": {
938+
"url": "http://127.0.0.1:1080/mcp",
939+
"transport": "streamable-http",
940+
"headers": {
941+
"Authorization": "Bearer <token>"
942+
}
943+
}
944+
}
945+
}
946+
}
947+
```
948+
949+
OpenClaw can save the same server definition with [`openclaw mcp set`](https://docs.openclaw.ai/cli/mcp):
950+
951+
```bash
952+
openclaw mcp set nexttrace '{
953+
"url": "http://127.0.0.1:1080/mcp",
954+
"transport": "streamable-http",
955+
"headers": {
956+
"Authorization": "Bearer <token>"
957+
}
958+
}'
959+
```
960+
961+
`openclaw mcp set` only saves the MCP server definition. It does not start NextTrace or verify that the endpoint is reachable, so run `nexttrace --deploy --mcp` first.
962+
963+
Useful first tool calls for Agents:
964+
965+
- `nexttrace_capabilities`
966+
- `nexttrace_traceroute`
967+
- `nexttrace_globalping_trace`
968+
- `nexttrace_globalping_limits`
969+
898970
## NextTraceroute
899971
900972
`NextTraceroute` is a root-free Android route tracing application that defaults to using the `NextTrace API`, developed by @surfaceocean.

‎README_zh_CN.md‎

Lines changed: 80 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -187,7 +187,7 @@ Document Language: [English](README.md) | 简体中文
187187
| MTR 宽报告（`-w`） | ✅ | — | ✅ |
188188
| MTR 原始输出（`--raw`） | ✅ | — | ✅ |
189189
| Globalping（`--from`） | ✅ | — | — |
190-
| WebUI（`--deploy`） | ✅ | — | — |
190+
| WebUI（`--deploy`）/ MCP（`--deploy --mcp`） | ✅ | — | — |
191191
| 快速跟踪（`-F`） | ✅ | ✅ | — |
192192
| 默认运行模式 | traceroute | traceroute | MTR TUI |
193193
| 二进制名 | `nexttrace` | `nexttrace-tiny` | `ntr` |
@@ -196,9 +196,9 @@ Document Language: [English](README.md) | 简体中文
196196

197197
### 功能对比
198198

199-
- **`nexttrace`** — 完整版。包含 traceroute、独立 MTU、CDN 测速、IP 文本标注、MTR、Globalping、Fast Trace 与 WebUI。
200-
- **`nexttrace-tiny`** — 精简版。保留常规 traceroute、独立 MTU 和 Fast Trace；不含 CDN 测速 / IP 文本标注 / MTR / Globalping / WebUI。适合嵌入式或极简环境。
201-
- **`ntr`** — MTR 专用版。默认启动 MTR TUI。不含常规 traceroute、独立 `--mtu`、CDN 测速、IP 文本标注、Globalping、Fast Trace 与 WebUI。
199+
- **`nexttrace`** — 完整版。包含 traceroute、独立 MTU、CDN 测速、IP 文本标注、MTR、Globalping、Fast Trace、WebUI（`--deploy`）与 MCP（`--deploy --mcp`）。
200+
- **`nexttrace-tiny`** — 精简版。保留常规 traceroute、独立 MTU 和 Fast Trace；不含 CDN 测速 / IP 文本标注 / MTR / Globalping / WebUI / MCP。适合嵌入式或极简环境。
201+
- **`ntr`** — MTR 专用版。默认启动 MTR TUI。不含常规 traceroute、独立 `--mtu`、CDN 测速、IP 文本标注、Globalping、Fast Trace、WebUI 或 MCP。
202202

203203
### 手动编译
204204

@@ -677,6 +677,7 @@ NextTrace 当前会读取下列环境变量。对于布尔开关，只识别 `1`
677677
| `NEXTTRACE_TOKEN` | 未设置 | 预置 LeoMoeAPI Bearer Token；设置后将跳过 PoW 取 token 流程。 |
678678
| `NEXTTRACE_POWPROVIDER` | `api.nxtrace.org` | 指定 PoW 服务提供方；当前内置的非默认别名为 `sakura`。 |
679679
| `NEXTTRACE_DEPLOY_ADDR` | 未设置 | `--deploy` 模式下，当未传 `--listen` 时使用的默认监听地址。 |
680+
| `NEXTTRACE_DEPLOY_TOKEN` | 未设置 | `--deploy` WebUI/API/WebSocket/MCP 访问 token。CLI `--deploy-token` 优先级更高。 |
680681
| `NEXTTRACE_ALLOW_CROSS_ORIGIN` | `0` | 仅对 `--deploy` 生效：是否允许跨站浏览器访问 Web UI / API。默认关闭以保证安全。 |
681682

682683
#### IP 数据库 / 第三方服务
@@ -714,8 +715,9 @@ Usage: nexttrace [-h|--help] [--init] [-4|--ipv4] [-6|--ipv6] [-T|--tcp]
714715
[-j|--json] [-c|--classic] [-f|--first <integer>] [-M|--map]
715716
[-e|--disable-mpls] [-V|--version]
716717
[-s|--source "<value>"] [--source-port <integer>] [-D|--dev
717-
"<value>"] [--listen "<value>"] [--deploy] [-z|--send-time
718-
<integer>] [-i|--ttl-time <integer>] [--timeout <integer>]
718+
"<value>"] [--listen "<value>"] [--deploy-token "<value>"]
719+
[--mcp] [--deploy] [-z|--send-time <integer>]
720+
[-i|--ttl-time <integer>] [--timeout <integer>]
719721
[--psize <integer>] [--dot-server
720722
(dnssb|aliyun|dnspod|google|cloudflare)] [-g|--language
721723
(en|cn)] [-C|--no-color] [--from "<value>"] [-t|--mtr]
@@ -798,6 +800,10 @@ Arguments:
798800
interface
799801
--listen Set listen address for web console (e.g.
800802
127.0.0.1:30080)
803+
--deploy-token Set bearer token for --deploy
804+
WebUI/API/WebSocket/MCP access
805+
--mcp Enable MCP endpoint under --deploy at
806+
/mcp
801807
--deploy Start the Gin powered web console
802808
-z --send-time Advanced: per-packet gap [ms] inside the
803809
same TTL group. Lower is faster; raise to
@@ -895,6 +901,74 @@ nexttrace --pow-provider sakura
895901
896902
[https://github.com/nxtrace/nexttracewebapi](https://github.com/nxtrace/nexttracewebapi)
897903
904+
## Deploy WebUI 与 MCP
905+
906+
完整版 `nexttrace` 可以启动本机 WebUI/API/WebSocket 服务：
907+
908+
```bash
909+
nexttrace --deploy
910+
```
911+
912+
MCP 是 deploy 的子模式，复用同一套网络服务栈并暴露在 `/mcp`：
913+
914+
```bash
915+
nexttrace --deploy --mcp
916+
nexttrace --deploy --mcp --listen 0.0.0.0:1080 --deploy-token "$TOKEN"
917+
```
918+
919+
监听 loopback 地址（`127.0.0.1`、`::1`、`localhost`）时默认免 token。监听外网地址时必须启用 token；如果没有通过 `--deploy-token` 或 `NEXTTRACE_DEPLOY_TOKEN` 设置，NextTrace 会启动时随机生成 token 并输出到 stdout。若 stdout 会被日志系统、CI 控制台或平台采集，建议通过 `--deploy-token` 或 `NEXTTRACE_DEPLOY_TOKEN` 显式提供 token，避免泄漏。API、WebSocket 与 MCP 客户端可使用 `Authorization: Bearer <token>` 或 `X-NextTrace-Token`；浏览器 WebUI 用户可访问 `/auth/login` 登录。
920+
921+
### 在 Agent 客户端注册 MCP
922+
923+
先启动 NextTrace。MCP endpoint 是 Streamable HTTP，不是 stdio：
924+
925+
```text
926+
http://127.0.0.1:1080/mcp
927+
```
928+
929+
监听外网地址或手动配置 token 时，把 token 放在 HTTP header 中。不要把 deploy token 放进 URL query。
930+
931+
通用 MCP 客户端配置示例：
932+
933+
```json
934+
{
935+
"mcp": {
936+
"servers": {
937+
"nexttrace": {
938+
"url": "http://127.0.0.1:1080/mcp",
939+
"transport": "streamable-http",
940+
"headers": {
941+
"Authorization": "Bearer <token>"
942+
}
943+
}
944+
}
945+
}
946+
}
947+
```
948+
949+
也可以把 `headers` 改为使用 `X-NextTrace-Token: <token>`，与 `Authorization: Bearer <token>` 等价。
950+
951+
OpenClaw 可通过 [`openclaw mcp set`](https://docs.openclaw.ai/zh-CN/cli/mcp) 保存同样的 server 定义：
952+
953+
```bash
954+
openclaw mcp set nexttrace '{
955+
"url": "http://127.0.0.1:1080/mcp",
956+
"transport": "streamable-http",
957+
"headers": {
958+
"Authorization": "Bearer <token>"
959+
}
960+
}'
961+
```
962+
963+
`openclaw mcp set` 只保存 MCP server 定义；它不会启动 NextTrace，也不会验证 endpoint 是否可达，所以需要先运行 `nexttrace --deploy --mcp`。
964+
965+
下面列出的项为 MCP 协议中 `tools[].name` 的工具名/ID，客户端在 MCP Tool Calling 中引用这些 ID，而不是把它们当作 HTTP path。Agent 接入后可先调用：
966+
967+
- `nexttrace_capabilities`
968+
- `nexttrace_traceroute`
969+
- `nexttrace_globalping_trace`
970+
- `nexttrace_globalping_limits`
971+
898972
## NextTraceroute
899973
900974
`NextTraceroute`，一款默认使用`NextTrace API`的免`root`安卓版路由跟踪应用，由 @surfaceocean 开发。

0 commit comments

Comments
 (0)