Skip to content
Back to search

fleet-geo-mcp

Evidence-first MCP server: where does each model's inference physically run? Returns location with confidence - never a guess.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mindtalk69--fleet-geo-mcp/badge.svg)](/listings/mindtalk69--fleet-geo-mcp)

HTML

<a href="/listings/mindtalk69--fleet-geo-mcp"><img src="/api/listings/mindtalk69--fleet-geo-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Two routes - a DSH bundle or a single patch row - both in [INSTALL.md](INSTALL.md). Placeholders there map to `$env:DSH_NODE_EXECUTABLE`, `%USERPROFILE%\.dsh\profiles\<profile>`, and this checkout.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 289 lines
  1. # fleet-geo — an MCP that answers "where does this model actually run?"
  2. [![test](https://github.com/mindtalk69/fleet-geo-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/mindtalk69/fleet-geo-mcp/actions/workflows/test.yml)
  3. A zero-dependency MCP server (stdio, Node >= 20) that resolves the physical location of
  4. inference for each model in the Orca fleet, and refuses to guess.
  5. Written because a prompt rots: providers change, endpoints move, new lanes appear. A tool
  6. that re-derives the answer from live data does not.
  7. ```
  8. fleet-geo-mcp/
  9. server.mjs MCP stdio transport + 13 tools
  10. src/tcpip.mjs RFC 1792-modeled dual-stack TCP/UDP connection MIB & IPv4/IPv6 primitives
  11. src/geofeed.mjs RFC 8805 self-published IP geolocation feeds + RFC 9092/9632 RDAP discovery
  12. src/native.mjs optional Rust N-API loader with automatic pure-JS fallback
  13. native/fleet-geo-native Encore-style Rust N-API core (kernel sockets/processes, LPM radix trie, SNI/DNS)
  14. scripts/build-native.mjs compiles the Rust N-API cdylib to native/*.node (zero JS runtime deps)
  15. src/observe.mjs observe_endpoints: proxy, OS socket table (TCP+UDP), strace SNI/DNS
  16. src/doh.mjs DNS over HTTPS (ISP-independent dual-stack A/AAAA/CNAME evidence)
  17. src/sources.mjs Cymru ASN (IPv4+IPv6), RDAP, AWS/GCP IPv4+IPv6 prefix tables, PeeringDB, crt.sh, globalping, RFC 9293 edge timing/headers
  18. src/geo.mjs CIDR math (IPv4+IPv6), distance, RTT floor, region/IATA/city coordinates, hostname fingerprints
  19. src/classify.mjs evidence -> four planes -> confidence + two-layer mapPins + contradictions
  20. src/catalog.mjs the only hand-maintained data, plus record_fact
  21. catalog.json provider seeds, all marked hypothesis until cited
  22. fleet.json the lane table (W1-W7, C, B, T) - adding a lane is a one-line edit
  23. config.json entitled-host allowlist + limits
  24. test/selftest.mjs offline strict + online tolerant checks (IPv4 + IPv6)
  25. test/tcpip.test.mjs RFC 1792 dual-stack TCP/UDP MIB & address tests
  26. test/geofeed.test.mjs RFC 8805 geofeed, RFC 9293 edge timing, and two-layer mapPins tests
  27. test/observe.test.mjs observe_endpoints checks, offline on every OS
  28. test/native.test.mjs Rust N-API native core parity & kernel socket tests
  29. test/stdio-check.mjs protocol surface, replayed from a recorded session
  30. dsh-bundle/ the DSH wrapper, shipped with the server
  31. ```
  32. ## Runs on every OS (optional Rust N-API native core)
  33. Windows, macOS and Linux, on Node.js 20 or newer, with **zero npm dependencies**. Every tool
  34. uses only Node built-ins and public HTTPS/DNS sources, so it works out of the box with pure JS.
  35. For low-level kernel speed without subprocesses (an Encore-style Node + Rust N-API hybrid),
  36. build the optional Rust native core:
  37. ```bash
  38. npm run build:native # produces native/fleet-geo-native.<platform>-<arch>.node
  39. ```
  40. When present, `src/native.mjs` loads the compiled `.node` addon directly inside Node.js (still
  41. zero `node_modules`) and transparently accelerates:
  42. - **Kernel RFC 1792 socket & process snapshots (zero subprocesses)**: Linux `/proc/net/*` + `/proc/<pid>`, Windows `GetExtendedTcpTable` / `GetExtendedUdpTable` + `CreateToolhelp32Snapshot`, macOS `libproc`.
  43. - **Dual-stack IPv4 + IPv6 LPM radix trie**: sub-microsecond longest-prefix match for AWS/GCP prefix tables.
  44. - **Zero-copy protocol parsers**: bounds-checked Rust TLS `ClientHello` SNI, DNS question, and address normalizers.
  45. Set `FLEET_GEO_NATIVE=0` to force the pure-JS fallback at any time. `explain_rules` and
  46. `inspect_connections` report the active engine (`rust-napi` vs `js-fallback`).
  47. The only OS-specific part is `observe_endpoints`, which picks the native tool for each OS
  48. and never needs root or admin rights:
  49. | | Windows | macOS | Linux |
  50. |---|---|---|---|
  51. | all lookup tools (`locate_model`, `fleet_status`, ...) | yes | yes | yes |
  52. | `observe_endpoints` proxy layer | yes | yes | yes |
  53. | `observe_endpoints` / `inspect_connections` socket MIB (native Rust) | `GetExtendedTcpTable` / `GetExtendedUdpTable` + Toolhelp32 | `libproc` | `/proc/net/*` + `/proc/<pid>` |
  54. | `observe_endpoints` / `inspect_connections` socket MIB (JS fallback) | `netstat -ano` + PowerShell process tree | `lsof` + `ps` | `ss -tnupHa` + `ps` |
  55. | `observe_endpoints` SNI/DNS names | via the proxy | via the proxy | proxy + `strace` (if installed) |
  56. | CLI shims (`codex.cmd` etc.) | run through the shell | direct | direct |
  57. | process cleanup on timeout | `taskkill /T /F` | process group | process group |
  58. Per-OS differences in how a lane is launched live in `fleet.json` as
  59. `observe.argvByPlatform` (for example agy needs a pseudo-TTY via `script` on Linux and
  60. macOS). Shell examples below are PowerShell; the same commands work unchanged in bash or zsh.
  61. ## The one idea
  62. **Four planes, never merged.**
  63. | Plane | What it is | Why it matters |
  64. |---|---|---|
  65. | CONTROL | the base URL the CLI actually calls | may be a router, not the model author |
  66. | EDGE | where TLS terminates | nearest to *you*; almost never the model |
  67. | ORIGIN | where weights execute | **this is the answer** |
  68. | LEGAL | entity + residency commitment | what a DPO accepts; constrains origin |
  69. Every naive geolocation answer collapses these into one and reports the Cloudflare PoP
  70. down the street as "the datacenter".
  71. ## Tools
  72. | Tool | Use |
  73. |---|---|
  74. | `locate_model` | one lane: model / lane name / base_url -> full location card |
  75. | `fleet_status` | every lane in one sweep -> table + roll-up |
  76. | `fleet_map` | map-ready two-layer JSON feed (`EDGE` PoP pins + `ORIGIN` anchored pins + `unresolved`) for visualizers like `agent2mind` |
  77. | `trace_endpoint` | one hostname -> CNAME hops, ASN, cloud region, RDAP |
  78. | `lookup_prefix` | one IPv4 or IPv6 address -> ASN, published cloud region, RFC 8805 geofeed, PeeringDB facilities |
  79. | `lookup_geofeed` | query an operator's self-published RFC 8805 IP geofeed (discovered via RDAP, authority-verified) |
  80. | `find_regional_endpoints` | crt.sh subdomains (RFC 6962), regional & direct/origin leads surfaced |
  81. | `probe_latency` | distributed probes + the RTT floor falsifier |
  82. | `inspect_edge` | headers + RFC 9293 TCP SYN->SYN-ACK RTT vs TTFB from an **entitled** endpoint -> `EDGE` PoP pin only |
  83. | `record_fact` | cite a provider page with a quote -> tier-A anchor |
  84. | `observe_endpoints` | run a lane's one-line probe and record the hosts and IPs it really connects to |
  85. | `inspect_connections` | passive RFC 1792 dual-stack TCP/UDP connection & listener MIB snapshot with IP geolocation |
  86. | `explain_rules` | precedence, planes, confidence, falsifier |
  87. ### observe_endpoints
  88. Config files say what a CLI *should* call; this records what it *does* call. Each lane in
  89. `fleet.json` carries an `observe.argv` (with optional `argvByPlatform` and a `git` fixture
  90. for jev). With `run:true` the tool runs that one prompt and watches it through three layers:
  91. | Layer | Linux | macOS | Windows | Sees |
  92. |---|---|---|---|---|
  93. | logging CONNECT proxy (`HTTPS_PROXY`) | yes | yes | yes | hostname, port, bytes per tunnel |
  94. | RFC 1792 dual-stack TCP/UDP socket MIB | Rust `/proc/net` (fallback `ss -tnupHa`) | Rust `libproc` (fallback `lsof`) | Rust IP Helper API (fallback `netstat -ano`) | every IPv4/IPv6 remote TCP (all states) & UDP endpoint + listeners |
  95. | `strace -yy`, when installed | yes | - | - | TLS SNI hostname, DNS questions, every connect |
  96. Nothing is decrypted: the hostname comes from the CONNECT line, the cleartext SNI or the
  97. DNS question. Every destination IP then gets `lookup_prefix`-style facts and an `EDGE` /
  98. `ENDPOINT` label. The result is CONTROL-plane evidence, saved under `observations/`.
  99. It ends at the TLS edge and never proves the origin. Without `run:true` it only prints
  100. the commands, because each lane costs one model call. `relocate:true` re-classifies the
  101. IPs of each lane's latest saved run without running any CLI (no model calls); the original
  102. file is kept and a `-relocated.json` file is added. agent2mind reads these files to show
  103. which hosts each agent really calls.
  104. **Measured edge pins.** For each observed edge host (up to three per lane), the tool reads
  105. the PoP the CDN itself reports (`cf-ray`, `x-amz-cf-pop`, ...) with one credential-free
  106. request to a host that lane was seen calling, and maps it through `IATA_COORDS`. When no
  107. RFC 8805 geofeed pin exists, that measured PoP becomes `mapPins.edge` (`precision: "pop"`).
  108. It is where TLS ends, near the caller, never the inference origin; `mapPins.origin` stays
  109. null until the origin is anchored.
  110. **Documented origins.** A provider page that names only a country is recorded at country
  111. precision: `record_fact {provider, kind:"residency", country:"CN", source_url, quote}`
  112. (no region needed; the precision says `country`, never more). A cited fact outranks any
  113. unverified seed, and a bare API host (`api.deepseek.com`) matches its catalog provider, so
  114. `observe_endpoints` evidence picks the fact up. `mapPins.origin` then carries the point,
  115. `basis: "provider-documented"` and the quote. Recorded so far: DeepSeek, processing in China.
  116. **Gateway follow.** Some CLIs never leave the machine themselves: `hermes` hands each
  117. request to its own daemon on `127.0.0.1:34101`. When a CLI connects to a loopback port,
  118. the tool finds the process listening there (never its own proxy) and records that
  119. process's outbound connections, split into `newConnections` (opened during the run) and
  120. `preexisting` (pooled keep-alives open before it). New connections become this lane's
  121. evidence (`OBSERVED_VIA_GATEWAY`, via `gateway:<pid>`); pooled ones are listed and labelled
  122. but never counted as proof. A busy gateway may also be serving other clients, so treat
  123. its new connections as a strong hint, not exclusive attribution. Works on every OS through
  124. the same socket table (native core, `ss`, `lsof` or `netstat`).
  125. ### inspect_connections
  126. A passive, zero-model-call snapshot of the host's live dual-stack TCP and UDP sockets,
  127. modelled on **RFC 1792**'s four-table MIB:
  128. - `tcpConnTable`: active TCP 4-tuples (`synSent` through `timeWait`), with transient state tracking
  129. - `tcpUnspecConnTable` / `tcpListeners`: wildcard (`0.0.0.0`, `::`) and bound TCP listeners kept separate from active remotes
  130. - `udpTable` / `udpUnspecTable`: connected UDP flows (e.g., QUIC/HTTP3 on UDP/443, DNS) and wildcard UDP listeners
  131. Accepts optional `pid` (includes descendant process tree), `process`, `protocol` (`tcp`/`udp`/`all`),
  132. `family` (`ipv4`/`ipv6`/`all`), and `locate:true` to enrich remote IPv4/IPv6 endpoints with ASN,
  133. published cloud region, and `EDGE`/`ENDPOINT` plane labels. Reports `runtime.engine` (`rust-napi` or `js-fallback`).
  134. ## The answer shape
  135. ```jsonc
  136. {
  137. "planes": { "control": {...}, "edge": {...}, "origin": {...}, "legal": {...} },
  138. "location": { "country": "KR", "region": "ap-northeast-2", "facility": null,
  139. "precision": "region" }, // facility > metro > region > country > unknown
  140. "confidence": "ANCHORED", // ANCHORED | CORROBORATED | INDICATED | OPEN
  141. "confidenceWhy": "1 tier-A anchor(s): cloud-published-region",
  142. "contradictions": [], // e.g. an RTT below the fiber floor
  143. "evidence": [ { "id": "E2", "tier": "A", "source": "aws ip-ranges.json",
  144. "observed": "3.5.140.1 falls in 3.5.140.0/22, published as AWS region ap-northeast-2" } ],
  145. "nextProbes": ["Region is anchored. A facility needs documentary evidence: ..."]
  146. }
  147. ```
  148. `precision` is the honest word for "exact". A tool that returns a street address for a
  149. Cloudflare-fronted API is lying; one that returns `region: ap-northeast-2, precision:
  150. region, confidence: ANCHORED` is not.
  151. ## Precedence (highest first)
  152. 1. provider documentation (cited via `record_fact`) / region encoded in the hostname
  153. 2. the cloud's **own published prefix table** (AWS `ip-ranges.json`, gstatic `cloud.json`)
  154. 3. PeeringDB facility for the serving ASN
  155. 4. RDAP / ASN registration
  156. 5. commercial geoIP databases
  157. 6. latency inference
  158. Rule 2 is the sharpest trick: when an address falls inside a published AWS or GCP prefix,
  159. the cloud itself tells you which region owns it. That beats every geoIP product, and it
  160. costs nothing.
  161. ## The falsifier
  162. Fiber runs at ~200,000 km/s, so a round trip costs **~1 ms per 100 km** of path. Real
  163. paths are longer than the great circle, so measured RTT normally sits *above* the floor.
  164. A measurement far *below* it is physically impossible — and therefore a hard test:
  165. ```jsonc
  166. // probe_latency from Helsinki @1.4 ms, claimed origin Ashburn (7000 km)
  167. { "verdict": "FALSIFIED",
  168. "rows": [{ "impliedMaxDistanceKm": 140, "distanceToClaimedOriginKm": 7000,
  169. "floorMs": 70, "violation": { "floorMs": 70, "hardFloorMs": 53 } }] }
  170. ```
  171. It can only ever *disprove* a claim. That is exactly what a confident answer needs.
  172. ## Guardrails in code, not just in prose
  173. - **Entitlement gate.** `inspect_edge` refuses any host absent from `config.json`
  174. `entitledHosts`. Passive lookups stay open; traffic does not.
  175. - **Pacing.** Per-source minimum intervals. These are free shared services.
  176. - **Secret hygiene.** Auth headers are stripped before they can be echoed.
  177. - **Provenance gate.** `record_fact` rejects a fact without an `http(s)` URL and a >=12
  178. char verbatim quote. An agent cannot promote its own guess to a fact.
  179. - **No invasive technique.** DNS, RDAP, published tables, PeeringDB, crt.sh, ICMP from a
  180. third-party probe network. No port scanning, no whois TCP/43, no auth walls.
  181. ## Dynamic by construction
  182. Nothing about a provider is hardcoded except what only a human can supply: who publishes
  183. the model, and what their documentation claims.
  184. - New endpoint? `trace_endpoint` resolves it now.
  185. - New provider? `record_fact` with `publisher` + `match[]` adds it.
  186. - Provider moves? Live DNS and published ranges follow; the card changes.
  187. - Documentation ages? Every fact carries `verified_at`; `staleness()` flags anything past
  188. `staleAfterDays` (90) and prints "never verified" for the rest.
  189. ## Honest limits
  190. 1. For CDN-fronted APIs the origin is not externally observable — the card returns `OPEN`
  191. plus the exact probe that would settle it.
  192. 2. Azure publishes no queryable service-tag JSON any more, so Azure region comes from the
  193. resource itself (`az cognitiveservices account show ... --location`); the tool says so
  194. rather than guessing.
  195. 3. Passthrough aggregators (OpenRouter, Together, Fireworks) return a `provider` field per
  196. response. That is authoritative for the *serving entity*; the tool names it as the next
  197. probe instead of inventing it.
  198. 4. Dual-stack IPv4 and IPv6 addresses are both resolved through Team Cymru (`origin.asn.cymru.com` /
  199. `origin6.asn.cymru.com`), AWS/GCP published IPv4 + IPv6 prefix tables, and RDAP. If an address
  200. still yields neither ASN nor cloud-prefix data, `observe_endpoints` labels it `UNKNOWN` rather
  201. than presuming it is a unicast endpoint.
  202. 5. `observe_endpoints` sees where a CLI connects, which ends at the TLS edge. A CLI that
  203. hands traffic to a local gateway outside its process tree is followed to that gateway;
  204. if the gateway opens nothing new during the run, the lane stays `LOCAL_GATEWAY` with the
  205. gateway named, not a location.
  206. ## Develop
  207. ```powershell
  208. cd C:\DEV\fleet-geo-mcp
  209. npm test # selftest (44) + tcpip (8) + observe (14) + native (7)
  210. npm run build:native # optional: build Rust N-API core (native/*.node)
  211. FLEET_GEO_NATIVE=0 npm test # verify pure-JS fallback without native addon
  212. node server.mjs --tool inspect_connections --args '{"locate":false}'
  213. node server.mjs --tool lookup_prefix --args '{"ip":"2607:6bc0::10"}'
  214. node server.mjs --tool observe_endpoints --args '{"lane":"all"}' # plan only
  215. node server.mjs --tool observe_endpoints --args '{"lane":"W7","run":true}' # one model call
  216. node server.mjs --tool observe_endpoints --args '{"lane":"all","relocate":true}' # re-classify, no model calls
  217. node server.mjs --list-tools
  218. node server.mjs --tool fleet_status --args '{"limit":3}'
  219. node server.mjs --tool locate_model --args '{"lane":"W7"}'
  220. # full stdio session (shell redirection, not a piped child process)
  221. cmd /c "node server.mjs < test\fixtures\stdio-requests.jsonl > test\fixtures\stdio-responses.jsonl"
  222. node test/stdio-check.mjs
  223. ```
  224. ## Companion
  225. [`docs/PROMPT.md`](docs/PROMPT.md) is the analyst prompt this server replaced: a static spec
  226. that rots the moment a provider changes. Kept as the design rationale - the four planes, the
  227. evidence ladder, the falsification pass - for when the tool's output needs arguing in prose.
  228. ## Install
  229. Two routes - a DSH bundle or a single patch row - both in [INSTALL.md](INSTALL.md).
  230. Placeholders there map to `$env:DSH_NODE_EXECUTABLE`, `%USERPROFILE%\.dsh\profiles\<profile>`,
  231. and this checkout.
  232. ## License
  233. MIT - see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.