mcp-xray-pilot 0.10.1 → 0.14.0

package/README.md

@@ -10,8 +10,9 @@
 A Model Context Protocol (MCP) server that gives an LLM offline access to the
 official **xray-core** documentation, plus deep structural validation,
 best-practice lint, a protocol/transport/security compatibility matrix, a
-geosite/geoip catalogue, an alternative-stack suggester and a multi-config
-merge helper.
+**full v2fly geosite catalogue (~1500 categories)**, an alternative-stack
+suggester, REALITY keypair / shortId generators, a live SNI target validator,
+a curated SNI suggester per exit-country and a multi-config merge helper.
 
 ## What it does
 
@@ -29,12 +30,19 @@ merge helper.
   tun), per-transport `*Settings` schemas (raw / xhttp / grpc / ws / mkcp /
   httpupgrade / hysteria), TLS / REALITY security blocks, routing tag
   cross-references.
-- **Lints** ~20 best-practice rules: VLESS `decryption: "none"`, REALITY
+- **Lints** ~22 best-practice rules: VLESS `decryption: "none"`, REALITY
   pubkey/shortId/target syntax, XTLS vision flow compatibility, TLS
   fingerprint enum, ALPN collisions, geosite/geoip typo catcher, protocol
   × transport × security incompatibilities, `xhttp.path` leading slash,
-  `geoip:private` block rule, sniffing on 80/443 etc.
-- **Geo catalogue**: search ~500 known geoip/geosite tags by substring.
+  `geoip:private` block rule, sniffing on 80/443, **DNS-over-proxy leaks
+  on `.ru` direct routing** (v0.12), **`geosite:` categories absent from
+  xray-core release `geosite.dat`** (v0.12) etc.
+- **Geo catalogue**: search ~1500 known geoip/geosite tags by substring (full
+  v2fly/domain-list-community catalogue, hydrated from `data/geocatalogue.json`).
+- **REALITY toolbelt**: `xray_generate_reality_keypair` (drop-in replacement
+  for `xray x25519`), `xray_generate_short_ids` (cryptographically random,
+  legacy-empty prefix), `xray_validate_sni_target` (live TLS 1.3 + h2 probe),
+  `xray_suggest_sni_for_country` (curated REALITY fronts per exit-country).
 - **Compares protocols**: side-by-side table of vless/vmess/trojan/ss/
   hysteria2/wireguard on transports, security, anti-DPI, mobile, battery.
 - **Recommends a stack** for a stated goal (anti-DPI in RU/IR/CN, low
@@ -50,14 +58,115 @@ merge helper.
 | `xray_fetch_topic`         | Fetch one topic as markdown. Network → fall back to bundled cache → update cache.     |
 | `xray_search`              | Full-text search over all cached docs. Returns ranked hits + snippets.                |
 | `xray_validate_config`     | Structural+schema validation of an xray JSON config (Zod under the hood).             |
-| `xray_lint`                | ~20 best-practice lint rules. Returns issues with severity, rule id, JSON-pointer.    |
-| `xray_geo_search`          | Substring search over the embedded geosite/geoip catalogue.                           |
+| `xray_lint`                | ~22 best-practice lint rules. Returns issues with severity, rule id, JSON-pointer.    |
+| `xray_geo_search`          | Substring search over the embedded geosite/geoip catalogue (~1500 tags).              |
 | `xray_diff_protocols`      | Side-by-side feature table for two protocols.                                         |
 | `xray_suggest_alternative` | Recommend protocol+transport+security for a goal (anti-DPI / battery / latency / …). |
+| `xray_generate_short_ids`  | Cryptographically random REALITY shortIds (default `[4,8,16]` bytes, legacy empty prefix). |
+| `xray_generate_reality_keypair` | Fresh REALITY X25519 keypair, base64url 43 chars — drop-in for `xray x25519`. |
+| `xray_validate_sni_target` | Live TLS 1.3 + ALPN h2 + HTTP probe of a candidate REALITY target host.               |
+| `xray_test_reality_live`   | Spin up real local xray server+client, run a full REALITY handshake against the target, probe HTTPS through the cascade. Strictly stronger than `xray_validate_sni_target`. |
+| `xray_whitelist_sni_candidates` | Pull a public RU-traffic whitelist (default: hxehex/russia-mobile-internet-whitelist) and TLS-validate the top N hosts as REALITY SNI front candidates. Returns ranked, sorted by ok desc, latency asc. |
+| `xray_suggest_sni_for_country` | Curated REALITY SNI/target hosts per exit-country (DE/PL/NL/FR/LV/SE/FI/US/UK/JP/SG/AU/CA). |
 | `xray_merge_configs`       | Merge N xray configs with tag-collision resolution and conflict warnings.             |
 | `xray_github_search`       | Search issues/PRs/discussions across XTLS GitHub repos (Xray-core/REALITY/docs).      |
 | `xray_github_fetch_issue`  | Fetch one issue/PR/discussion with full body + top comments.                          |
-| `xray_refresh_cache`       | Bulk re-fetch cached docs (`scope: all/stale/category`). Optional `discover` for new upstream slugs. |
+| `xray_refresh_cache`       | Bulk re-fetch cached docs (`scope: all/stale/category`). Optional `discover` for new upstream slugs. Optional `refresh_geocatalogue: true` to also re-pull the v2fly category list. |
+
+Total: **18 tools**.
+
+### Quick toolbelt
+
+Generate a REALITY keypair (server-side priv + client-side pub):
+
+```jsonc
+// xray_generate_reality_keypair {}
+{
+  "privateKey": "MNCibkT-h5bCF6iknJG0rJdHdfUjT7VugHgSX9BRWUY",
+  "publicKey": "ffvf0eNwnLhgK-axt3rajJIAoHKv0rX4xkw5KyImn38",
+  "note": "Server: paste privateKey into inbound realitySettings.privateKey. Clients: paste publicKey into outbound realitySettings.publicKey. Format matches `xray x25519` output exactly."
+}
+```
+
+Live-check a candidate REALITY SNI:
+
+```jsonc
+// xray_validate_sni_target { "host": "www.onet.pl" }
+{
+  "host": "www.onet.pl", "port": 443, "ok": true,
+  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200,
+  "cert_subject": "www.onet.pl", "cert_san_count": 4,
+  "latency_ms": 312, "issues": []
+}
+```
+
+Live REALITY handshake (catches what `xray_validate_sni_target` cannot):
+
+```jsonc
+// xray_test_reality_live { "target_host": "2gis.ru" }
+{
+  "ok": true,
+  "target": "2gis.ru:443",
+  "reality_handshake_complete": true,
+  "client_received_real_cert": false,
+  "http_probe_status": 200,
+  "latency_ms": 824,
+  "issues": [],
+  "used_keypair": { "privateKey": "...", "publicKey": "...", "shortId": "a1b2c3d4" },
+  "cached": false,
+  "cached_at": "2026-05-06T12:30:00.000Z"
+}
+```
+
+> Verdicts are persisted to `data/reality-verdicts.json` (LRU cap 50, TTL 24h,
+> key `host:port`). Subsequent calls with the same target return instantly with
+> `cached: true`. Pass `force_refresh: true` to bypass the cache and rerun xray.
+
+Compare a list of candidates in one shot — runs sequentially, each entry hits
+the cache, results are sorted by `ok desc, latency_ms asc`:
+
+```jsonc
+// xray_test_reality_live {
+//   "multi_targets": ["2gis.ru", "yandex.ru", "vk.com", "mail.ru"]
+// }
+{
+  "results": [
+    { "target": "2gis.ru:443",   "ok": true,  "latency_ms": 824, "cached": true,  "cached_at": "..." },
+    { "target": "mail.ru:443",   "ok": true,  "latency_ms": 1102, "cached": false, "cached_at": "..." },
+    { "target": "yandex.ru:443", "ok": false, "latency_ms": 0,    "cached": false, "cached_at": "...", "issues": ["client received a real certificate ..."] },
+    { "target": "vk.com:443",    "ok": false, "latency_ms": 0,    "cached": false, "cached_at": "...", "issues": ["target unreachable"] }
+  ],
+  "summary": { "ok_count": 2, "total": 4 }
+}
+```
+
+Pull a public RU-traffic whitelist and rank live SNI candidates for an
+inbound RU-relay node:
+
+```jsonc
+// xray_whitelist_sni_candidates { "max_candidates": 10 }
+{
+  "source_url": "https://raw.githubusercontent.com/hxehex/russia-mobile-internet-whitelist/main/whitelist.txt",
+  "fetched_at": "2026-05-06T12:34:00.000Z",
+  "total_domains": 412,
+  "tested": 10,
+  "candidates": [
+    { "host": "ya.ru",      "ok": true,  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200, "latency_ms": 41,  "cert_subject": "ya.ru",      "issues": [] },
+    { "host": "vk.com",     "ok": true,  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200, "latency_ms": 78,  "cert_subject": "*.vk.com",   "issues": [] },
+    { "host": "ozon.ru",    "ok": false, "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200, "latency_ms": 134, "cert_subject": "*.ozon.ru",  "issues": [] }
+  ],
+  "summary": { "ok_count": 8, "failed_count": 2 },
+  "cache":   { "used": false, "age_seconds": null },
+  "notes":   ["latency_ms is measured from the MCP host (your laptop), not from the relay node — re-test from the node for geo-accurate values"]
+}
+```
+
+> The whitelist body is cached on disk in `data/whitelist-cache.json`
+> (default TTL 24h, override via `cache_ttl_hours`). Verdicts are NOT cached
+> — every call re-probes its slice live so latency numbers stay fresh.
+> NB: the probe runs from your laptop, not from the РФ relay; for
+> geo-accurate latency, use `xray_test_reality_live` from the actual
+> node (or ssh + curl on it).
 
 It also exposes a single MCP **resource**: `xray://docs/index` — the raw
 `_index.json` of cached topics.
@@ -258,7 +367,7 @@ warning in the response.
 
 ## Roadmap
 
-See [ROADMAP.md](./ROADMAP.md). All v0.1–v0.10 milestones are checked off.
+See [ROADMAP.md](./ROADMAP.md). All v0.1–v0.11 milestones are checked off.
 
 ## License
 
@@ -290,12 +399,19 @@ MCP-сервер, дающий LLM офлайн-доступ к официаль
   tun), per-transport `*Settings` (raw / xhttp / grpc / ws / mkcp /
   httpupgrade / hysteria), security блоки TLS/REALITY, routing tag
   cross-references.
-- **Lint** ~20 правил: VLESS `decryption: "none"`, REALITY pubkey/shortId/
+- **Lint** ~22 правил: VLESS `decryption: "none"`, REALITY pubkey/shortId/
   target syntax, XTLS vision flow compatibility, TLS fingerprint enum,
   ALPN collisions, geo typo catcher, protocol × transport × security
   несовместимости, `xhttp.path` слеш, `geoip:private` block, sniffing на
-  80/443 и т.д.
-- **Geo catalogue**: поиск по ~500 известным geoip/geosite тегам.
+  80/443, **утечка DNS через прокси ломает `.ru` direct routing** (v0.12),
+  **`geosite:` категории, которых нет в xray-core release `geosite.dat`**
+  (v0.12) и т.д.
+- **Geo catalogue**: поиск по ~1500 известным geoip/geosite тегам (полный
+  v2fly/domain-list-community каталог, гидратируется из `data/geocatalogue.json`).
+- **REALITY toolbelt**: `xray_generate_reality_keypair` (drop-in замена
+  `xray x25519`), `xray_generate_short_ids` (криптослучайные, с empty-prefix
+  для легаси), `xray_validate_sni_target` (live TLS 1.3 + h2 проба),
+  `xray_suggest_sni_for_country` (курируемые REALITY-фронты по стране exit'а).
 - **Сравнение протоколов**: таблица vless/vmess/trojan/ss/hysteria2/
   wireguard по transports, security, anti-DPI, mobile, battery.
 - **Рекомендует стек** под цель (anti-DPI в РФ/Иране/КНР, low-latency,
@@ -312,13 +428,113 @@ MCP-сервер, дающий LLM офлайн-доступ к официаль
 | `xray_search`              | Полнотекстовый поиск по докам. Хиты + сниппеты.                                         |
 | `xray_validate_config`     | Структурная валидация + Zod-схемы по протоколу/transport/security.                      |
 | `xray_lint`                | ~20 правил best-practice. Issues с severity, rule id, JSON-pointer.                     |
-| `xray_geo_search`          | Поиск по embedded каталогу geosite/geoip по подстроке.                                  |
+| `xray_geo_search`          | Поиск по embedded каталогу geosite/geoip по подстроке (~1500 тегов).                    |
 | `xray_diff_protocols`      | Side-by-side таблица фич двух протоколов.                                               |
 | `xray_suggest_alternative` | Рекомендация protocol+transport+security под цель.                                      |
+| `xray_generate_short_ids`  | Криптослучайные REALITY shortIds (default `[4,8,16]` байт, с empty-prefix для легаси).  |
+| `xray_generate_reality_keypair` | Свежая X25519 пара REALITY, base64url 43 chars — drop-in для `xray x25519`.        |
+| `xray_validate_sni_target` | Live проба TLS 1.3 + ALPN h2 + HTTP кандидата на REALITY target.                        |
+| `xray_test_reality_live`   | Поднимает локальную пару xray (server+client), реально гоняет REALITY handshake к target, probe HTTPS сквозь каскад. Строго сильнее `xray_validate_sni_target`. |
+| `xray_whitelist_sni_candidates` | Тянет публичный whitelist РФ-трафика (default: hxehex/russia-mobile-internet-whitelist), TLS-валидирует топ-N как REALITY SNI-кандидаты. Сортировка ok desc, latency asc. |
+| `xray_suggest_sni_for_country` | Курируемые REALITY-фронты по стране exit'а (DE/PL/NL/FR/LV/SE/FI/US/UK/JP/SG/AU/CA). |
 | `xray_merge_configs`       | Слить N конфигов с разрешением коллизий тегов.                                          |
 | `xray_github_search`       | Поиск issues/PR/discussions по XTLS GitHub репозиториям.                                |
 | `xray_github_fetch_issue`  | Получить одну issue/PR/discussion с полным body + топ комментариев.                     |
-| `xray_refresh_cache`       | Bulk перезатяжка кеша доков (`scope: all/stale/category`). Опц. `discover` для новых slug'ов. |
+| `xray_refresh_cache`       | Bulk перезатяжка кеша доков (`scope: all/stale/category`). Опц. `discover` + `refresh_geocatalogue: true` (заодно перетянет v2fly категории). |
+
+Всего: **18 тулов**.
+
+### Quick toolbelt
+
+Сгенерить REALITY keypair (priv для сервера, pub для клиентов):
+
+```jsonc
+// xray_generate_reality_keypair {}
+{
+  "privateKey": "MNCibkT-h5bCF6iknJG0rJdHdfUjT7VugHgSX9BRWUY",
+  "publicKey": "ffvf0eNwnLhgK-axt3rajJIAoHKv0rX4xkw5KyImn38",
+  "note": "Format matches `xray x25519` output exactly."
+}
+```
+
+Live-проверить кандидата на REALITY SNI:
+
+```jsonc
+// xray_validate_sni_target { "host": "www.onet.pl" }
+{
+  "host": "www.onet.pl", "port": 443, "ok": true,
+  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200,
+  "cert_subject": "www.onet.pl", "cert_san_count": 4,
+  "latency_ms": 312, "issues": []
+}
+```
+
+> ⚠️ Проба идёт с локальной машины, где запущен `mcp-xray-pilot`. Для решения «работает ли SNI из РФ» — гоняй с РФ-IP отдельно.
+
+Реальный REALITY handshake (ловит то, что `xray_validate_sni_target` пропускает):
+
+```jsonc
+// xray_test_reality_live { "target_host": "2gis.ru" }
+{
+  "ok": true,
+  "target": "2gis.ru:443",
+  "reality_handshake_complete": true,
+  "client_received_real_cert": false,
+  "http_probe_status": 200,
+  "latency_ms": 824,
+  "issues": [],
+  "used_keypair": { "privateKey": "...", "publicKey": "...", "shortId": "a1b2c3d4" },
+  "cached": false,
+  "cached_at": "2026-05-06T12:30:00.000Z"
+}
+```
+
+> При первом вызове скачивает xray-binary в `~/.cache/mcp-xray-pilot/xray-bin/` (~30MB), дальше переиспользует. Если REALITY несовместим с target (как `outlook.live.com` или `www.ozon.ru` — реальные кейсы Flare VPN), `client_received_real_cert: true` и `ok: false`.
+
+> Вердикты пишутся на диск в `data/reality-verdicts.json` (LRU 50, TTL 24h, ключ `host:port`). Повторный вызов на тот же таргет возвращается мгновенно с `cached: true`. Чтобы прогнать заново — `force_refresh: true`.
+
+Сравнить пачку кандидатов одним вызовом — запускаются последовательно, каждый через кэш, сорт `ok desc, latency_ms asc`:
+
+```jsonc
+// xray_test_reality_live {
+//   "multi_targets": ["2gis.ru", "yandex.ru", "vk.com", "mail.ru"]
+// }
+{
+  "results": [
+    { "target": "2gis.ru:443",   "ok": true,  "latency_ms": 824, "cached": true },
+    { "target": "mail.ru:443",   "ok": true,  "latency_ms": 1102, "cached": false },
+    { "target": "yandex.ru:443", "ok": false, "issues": ["client received a real certificate ..."] },
+    { "target": "vk.com:443",    "ok": false, "issues": ["target unreachable"] }
+  ],
+  "summary": { "ok_count": 2, "total": 4 }
+}
+```
+
+Затянуть публичный whitelist РФ-трафика и проранжировать кандидатов на REALITY SNI для inbound РФ-relay-ноды:
+
+```jsonc
+// xray_whitelist_sni_candidates { "max_candidates": 10 }
+{
+  "source_url": "https://raw.githubusercontent.com/hxehex/russia-mobile-internet-whitelist/main/whitelist.txt",
+  "fetched_at": "2026-05-06T12:34:00.000Z",
+  "total_domains": 412,
+  "tested": 10,
+  "candidates": [
+    { "host": "ya.ru",   "ok": true,  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200, "latency_ms": 41,  "cert_subject": "ya.ru",     "issues": [] },
+    { "host": "vk.com",  "ok": true,  "tls_version": "TLSv1.3", "alpn": "h2", "http_status": 200, "latency_ms": 78,  "cert_subject": "*.vk.com",  "issues": [] }
+  ],
+  "summary": { "ok_count": 8, "failed_count": 2 },
+  "cache":   { "used": false, "age_seconds": null },
+  "notes":   ["latency_ms is measured from the MCP host (your laptop), not from the relay node — re-test from the node for geo-accurate values"]
+}
+```
+
+> Тело whitelist кешируется на диск в `data/whitelist-cache.json` (TTL по
+> умолчанию 24h, переопределение через `cache_ttl_hours`). Verdicts НЕ
+> кешируются — каждый вызов делает свежие пробы на своём срезе. NB:
+> latency меряется с тачки где запущен MCP, а НЕ с РФ-relay-ноды; для
+> гео-релевантной задержки используй `xray_test_reality_live` прямо с
+> ноды (или ssh + curl на ней).
 
 Также один MCP **ресурс**: `xray://docs/index`.
 
@@ -500,7 +716,7 @@ $env:GITHUB_TOKEN = "ghp_xxx"         # PowerShell
 
 ## Roadmap
 
-См. [ROADMAP.md](./ROADMAP.md) — все вехи v0.1–v0.10 закрыты.
+См. [ROADMAP.md](./ROADMAP.md) — все вехи v0.1–v0.11 закрыты.
 
 ## Лицензия