tunnel-mcp 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -11,6 +11,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [0.1.3] - 2026-07-01
+
+### Changed
+
+- **`tunnel_open` no longer hard-fails when the host can't reach
+  `*.trycloudflare.com`.** Because this is a cross-network tool, only the guest's
+  network has to reach the link — so a host-side reachability-probe failure
+  (blocked DNS, or a proxy Node's `fetch` ignores) now **opens the tunnel anyway
+  and returns a `reachabilityWarning`** by default, instead of blocking a tunnel
+  that would have worked for the guest. Behavior is configurable via
+  `TUNNEL_REACHABILITY`: `warn` (default), `strict` (previous hard-fail), or
+  `off` (skip the probe). This replaces the `TUNNEL_SKIP_REACHABILITY_CHECK` flag
+  from 0.1.2, which is still honored as `off` for backward compatibility.
+
 ## [0.1.2] - 2026-07-01
 
 ### Added
@@ -80,7 +94,8 @@ install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
   declaring a fix "confirmed".
 - Test suite of 109 tests built with vitest, developed test-first (TDD).
 
-[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.3...HEAD
+[0.1.3]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/zachlikefolio/tunnel-mcp/releases/tag/v0.1.0

package/README.md

@@ -178,15 +178,21 @@ an interactive CLI — with no arguments it starts and waits for an MCP client t
 connect over stdin/stdout. That's working as intended. Register it with a client
 (above), or run `tunnel-mcp --help`.
 
-**`tunnel_open` fails with "never became reachable" / can't resolve
-`*.trycloudflare.com`.** cloudflared reaches Cloudflare's edge over its own
-protocol, but the public `*.trycloudflare.com` hostname still has to resolve via
-normal DNS — and some networks (corporate/filtered networks, and a few public
-DNS resolvers) block `trycloudflare.com`. Both you **and your guest** need to be
-able to resolve it. Check with `dig +short <random>.trycloudflare.com` or
-`curl -sI https://<the-url>`. If only your guest's network needs to reach the
-URL, set `TUNNEL_SKIP_REACHABILITY_CHECK=1` to open the tunnel without the
-host-side reachability probe.
+**`tunnel_open` warns that this machine can't reach `*.trycloudflare.com`.**
+cloudflared reaches Cloudflare's edge over its own protocol, but the public
+`*.trycloudflare.com` hostname still has to resolve via normal DNS — and some
+networks (corporate/filtered networks, some public DNS resolvers, or a proxy that
+Node's `fetch` ignores) can't reach it from the host. Because only your
+**guest's** network truly has to reach the link, `tunnel_open` **opens anyway and
+returns a `reachabilityWarning` by default** — share the link and have your guest
+confirm they can open it. Control this with `TUNNEL_REACHABILITY`:
+
+- `warn` (default) — open, but warn when the host can't reach the URL
+- `strict` — fail `tunnel_open` unless the host can reach the URL first
+- `off` — skip the host-side reachability probe entirely
+
+Diagnose the host's DNS with `dig +short <random>.trycloudflare.com` or
+`curl -sI https://<the-url>`.
 
 ## Roadmap / not yet supported
 

package/dist/cli.js

@@ -60,10 +60,12 @@ export function helpText(version = readVersion()) {
         `  --force, -f      Overwrite an existing install`,
         ``,
         `Environment:`,
-        `  TUNNEL_SKILLS_DIR                 Override the skills directory`,
-        `  TUNNEL_SKIP_SKILL_INSTALL=1       Skip the automatic skill install on npm install`,
-        `  TUNNEL_SKIP_REACHABILITY_CHECK=1  Open a tunnel even if this machine can't reach`,
-        `                                    *.trycloudflare.com (your guest still must)`,
+        `  TUNNEL_SKILLS_DIR            Override the skills directory`,
+        `  TUNNEL_SKIP_SKILL_INSTALL=1  Skip the automatic skill install on npm install`,
+        `  TUNNEL_REACHABILITY         warn (default) | strict | off — how tunnel_open reacts`,
+        `                              when this host can't reach *.trycloudflare.com. Only the`,
+        `                              guest's network truly must reach it, so the default warns`,
+        `                              and opens anyway; strict fails; off skips the check.`,
         ``,
         `Docs: https://github.com/zachlikefolio/tunnel-mcp`,
     ].join('\n');

package/dist/cloudflared/tunnelProcess.d.ts

@@ -1,6 +1,8 @@
+import { ReachabilityMode } from '../env.js';
 export interface TunnelHandle {
     publicUrl: string;
     stop(): void;
+    reachabilityWarning?: string;
 }
 export interface StartOptions {
     timeoutMs?: number;
@@ -9,12 +11,13 @@ export interface StartOptions {
     intervalMs?: number;
     healthCheck?: (url: string) => Promise<boolean>;
     probeTimeoutMs?: number;
-    skipHealthCheck?: boolean;
+    reachability?: ReachabilityMode;
 }
 export declare function parsePublicUrl(line: string): string | null;
 export declare function describeProbeError(e: unknown): string;
 export declare function defaultHealthCheck(url: string): Promise<boolean>;
 export declare function unreachableMessage(url: string, attempts: number, lastReason?: string): string;
+export declare function reachabilityWarningMessage(url: string, lastReason?: string): string;
 /**
  * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
  * launched in place of `cloudflared tunnel --url ...`. Production passes none.

package/dist/cloudflared/tunnelProcess.js

@@ -35,12 +35,12 @@ async function reachabilityProbe(url, probeTimeoutMs) {
 export async function defaultHealthCheck(url) {
     return (await reachabilityProbe(url, DEFAULT_PROBE_TIMEOUT_MS)).ok;
 }
-// Builds the actionable "never became reachable" error. Names the host and,
-// when the failure looks like DNS resolution, points at *.trycloudflare.com
-// blocking — the single most common real-world cause. Always mentions the
-// escape hatch, since the guest's network (not the host's) is what must reach
-// the URL for messaging.
-export function unreachableMessage(url, attempts, lastReason) {
+// The shared DNS sentence: when a probe failure looks like name resolution,
+// point at *.trycloudflare.com being blocked — the single most common real-world
+// cause. Returns '' when the failure isn't DNS-shaped.
+function dnsHint(url, reason) {
+    if (!reason || !/ENOTFOUND|EAI_AGAIN|getaddrinfo|\bdns\b/i.test(reason))
+        return '';
     let host = url;
     try {
         host = new URL(url).host;
@@ -48,18 +48,31 @@ export function unreachableMessage(url, attempts, lastReason) {
     catch {
         /* keep the raw url */
     }
-    const dnsish = !!lastReason && /ENOTFOUND|EAI_AGAIN|getaddrinfo|\bdns\b/i.test(lastReason);
+    return (` This machine can't resolve ${host} — your DNS or network may be blocking *.trycloudflare.com` +
+        ` (common on filtered/corporate networks and some public DNS resolvers).`);
+}
+// Fatal error for `strict` mode: the host never confirmed the edge was routing.
+export function unreachableMessage(url, attempts, lastReason) {
     let msg = `cloudflared reported ${url} but it never became reachable from this machine after ${attempts} probe(s)`;
     if (lastReason)
         msg += ` (last error: ${lastReason})`;
-    msg += '.';
-    if (dnsish) {
-        msg +=
-            ` This machine can't resolve ${host} — your DNS or network may be blocking *.trycloudflare.com` +
-                ` (common on filtered/corporate networks and some public DNS resolvers). You and your guest both` +
-                ` need to be able to resolve it.`;
-    }
-    msg += ` If you're confident your guest's network can reach the URL, set TUNNEL_SKIP_REACHABILITY_CHECK=1 to open the tunnel anyway.`;
+    msg += '.' + dnsHint(url, lastReason);
+    msg +=
+        ` Both you and your guest must be able to reach it. Set TUNNEL_REACHABILITY=warn (the default) to` +
+            ` open anyway with a warning, or TUNNEL_REACHABILITY=off to skip this check entirely.`;
+    return msg;
+}
+// Non-fatal warning for `warn` mode: the tunnel is open, but this host couldn't
+// confirm reachability. Only the guest's network has to reach the URL, so this
+// is often a false alarm — but surface it so the human can sanity-check.
+export function reachabilityWarningMessage(url, lastReason) {
+    let msg = `Tunnel opened, but this machine could not reach ${url}`;
+    if (lastReason)
+        msg += ` (${lastReason})`;
+    msg += '.' + dnsHint(url, lastReason);
+    msg +=
+        ` Your guest still needs to reach the link — if they can't open it, check your DNS/proxy. Set` +
+            ` TUNNEL_REACHABILITY=strict to require host reachability, or =off to silence this check.`;
     return msg;
 }
 // Races a single probe against a per-attempt timeout so that a caller-supplied
@@ -142,10 +155,12 @@ export function startCloudflared(binPath, localPort, opts = {}) {
                 if (url && !settled) {
                     settled = true;
                     clearTimeout(timer);
-                    // Escape hatch: the reachability probe runs on the *host*, but only the
-                    // guest's network must reach the URL for messaging. A host on a filtered
-                    // network can opt to skip the probe and hand out the link regardless.
-                    if (opts.skipHealthCheck) {
+                    // The reachability probe runs on the *host*, but only the guest's
+                    // network must reach the URL for messaging. 'off' skips it entirely;
+                    // 'warn' (the product default) opens anyway and reports a warning;
+                    // 'strict' fails open() if the host can't confirm reachability.
+                    const mode = opts.reachability ?? 'strict';
+                    if (mode === 'off') {
                         resolve({ publicUrl: url, stop });
                         return;
                     }
@@ -153,6 +168,13 @@ export function startCloudflared(binPath, localPort, opts = {}) {
                         .then((res) => {
                         if (res.ok)
                             resolve({ publicUrl: url, stop });
+                        else if (mode === 'warn') {
+                            resolve({
+                                publicUrl: url,
+                                stop,
+                                reachabilityWarning: reachabilityWarningMessage(url, res.reason),
+                            });
+                        }
                         else {
                             stop();
                             reject(new Error(unreachableMessage(url, attempts, res.reason)));

package/dist/env.d.ts

@@ -5,3 +5,15 @@
  * truthiness check treats "0"/"false" as true).
  */
 export declare function envFlag(name: string): boolean;
+export type ReachabilityMode = 'warn' | 'strict' | 'off';
+/**
+ * How `tunnel_open` treats a host-side reachability-probe failure:
+ *   warn   (default) — open anyway, surface a warning; the guest is the real test
+ *   strict           — fail open() if the host can't reach the public URL
+ *   off              — skip the probe entirely
+ * Reads `TUNNEL_REACHABILITY`. Only when it is unset/blank does it fall back to
+ * the deprecated `TUNNEL_SKIP_REACHABILITY_CHECK` (== off) from 0.1.2 — an
+ * explicitly set (even mistyped) `TUNNEL_REACHABILITY` never defers to the alias.
+ * Any unrecognized value defaults to warn.
+ */
+export declare function reachabilityMode(): ReachabilityMode;

package/dist/env.js

@@ -11,3 +11,21 @@ export function envFlag(name) {
     const s = v.trim().toLowerCase();
     return s !== '' && s !== '0' && s !== 'false' && s !== 'no' && s !== 'off';
 }
+/**
+ * How `tunnel_open` treats a host-side reachability-probe failure:
+ *   warn   (default) — open anyway, surface a warning; the guest is the real test
+ *   strict           — fail open() if the host can't reach the public URL
+ *   off              — skip the probe entirely
+ * Reads `TUNNEL_REACHABILITY`. Only when it is unset/blank does it fall back to
+ * the deprecated `TUNNEL_SKIP_REACHABILITY_CHECK` (== off) from 0.1.2 — an
+ * explicitly set (even mistyped) `TUNNEL_REACHABILITY` never defers to the alias.
+ * Any unrecognized value defaults to warn.
+ */
+export function reachabilityMode() {
+    const raw = (process.env.TUNNEL_REACHABILITY ?? '').trim().toLowerCase();
+    if (raw === 'warn' || raw === 'strict' || raw === 'off')
+        return raw;
+    if (raw === '' && envFlag('TUNNEL_SKIP_REACHABILITY_CHECK'))
+        return 'off';
+    return 'warn';
+}

package/dist/session.d.ts

@@ -32,6 +32,7 @@ export declare class TunnelSession {
         joinLink: string;
         status: string;
         joinLinkExpiresInSec: number;
+        reachabilityWarning?: string;
     }>;
     join(joinLink: string, guestName: string): Promise<{
         tunnelId: string;

package/dist/session.js

@@ -7,12 +7,12 @@ import { GuestClient } from './relay/guestClient.js';
 import { ensureCloudflared as realEnsure } from './cloudflared/provision.js';
 import { startCloudflared as realStart } from './cloudflared/tunnelProcess.js';
 import { DEFAULT_LISTEN_TIMEOUT_MS, DEFAULT_IDLE_TEARDOWN_MS, DEFAULT_JOIN_LINK_TTL_MS, OPEN_RETRY_ATTEMPTS, } from './config.js';
-import { envFlag } from './env.js';
+import { reachabilityMode } from './env.js';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
-    // Read the escape hatch per-call (not at module load) so it can be set right
-    // before opening a tunnel.
-    startCloudflared: (bin, port) => realStart(bin, port, envFlag('TUNNEL_SKIP_REACHABILITY_CHECK') ? { skipHealthCheck: true } : {}),
+    // Resolve the reachability mode per-call (not at module load) so TUNNEL_REACHABILITY
+    // can be set right before opening a tunnel.
+    startCloudflared: (bin, port) => realStart(bin, port, { reachability: reachabilityMode() }),
 };
 export class TunnelSession {
     deps;
@@ -84,6 +84,9 @@ export class TunnelSession {
             joinLink,
             status: 'waiting_for_guest',
             joinLinkExpiresInSec: Math.round(joinTtlMs / 1000),
+            // Present only in 'warn' mode when the host couldn't confirm reachability;
+            // the agent should relay it to the human before sharing the link.
+            ...(tunnel.reachabilityWarning ? { reachabilityWarning: tunnel.reachabilityWarning } : {}),
         };
     }
     async join(joinLink, guestName) {

package/dist/tools.js

@@ -28,7 +28,7 @@ function register(server, name, schema, cb) {
 }
 export function registerTools(server, session, opts) {
     register(server, 'tunnel_open', {
-        description: 'Open a tunnel as host and get a join link to share. The link is a secret — share it over a trusted channel. It is single-use (works for exactly one guest) and expires (see joinLinkExpiresInSec in the result), so tell the human to share it promptly.',
+        description: 'Open a tunnel as host and get a join link to share. The link is a secret — share it over a trusted channel. It is single-use (works for exactly one guest) and expires (see joinLinkExpiresInSec in the result), so tell the human to share it promptly. If the result includes a reachabilityWarning, relay it to the human: this host could not confirm it can reach the link, so the guest should verify they can open it.',
         inputSchema: { goal: z.string() },
     }, async ({ goal }) => ok(await session.open(goal, opts.displayName)));
     register(server, 'tunnel_join', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {