tunnel-mcp 0.1.1 → 0.1.3

package/CHANGELOG.md

@@ -11,6 +11,46 @@ 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
+
+- **`install-skill` command and automatic skill install.** `tunnel-mcp
+install-skill` copies the `tunnel-etiquette` skill into `~/.claude/skills`
+  (override with `--dir`/`$TUNNEL_SKILLS_DIR`, overwrite with `--force`), and a
+  global `npm install` now installs it best-effort via a postinstall script.
+  Set `TUNNEL_SKIP_SKILL_INSTALL=1` to opt out; the postinstall never fails an
+  install and is a no-op under `npx`, `--ignore-scripts`, and CI.
+- **`--help` and `--version` flags**, plus a one-line stderr startup banner, so
+  running the server by hand no longer looks like a silent hang. The server also
+  hints how to install the etiquette skill when it isn't present.
+- **`TUNNEL_SKIP_REACHABILITY_CHECK` escape hatch.** Opens a tunnel even when the
+  host can't reach `*.trycloudflare.com` itself — useful when only the guest's
+  network needs to reach the URL.
+
+### Fixed
+
+- The MCP server reported a hardcoded, stale version (`0.1.0`) in its handshake;
+  it now reports the real package version.
+- A failed cloudflared reachability probe surfaced a generic "never became
+  reachable" error. It now names the host and, when the failure is DNS
+  resolution, points at `*.trycloudflare.com` being blocked (a common
+  corporate/filtered-DNS cause) and mentions the escape hatch above.
+
 ## [0.1.1] - 2026-07-01
 
 ### Security
@@ -54,5 +94,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   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.0...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

@@ -50,13 +50,29 @@ npx tunnel-mcp
 Register it with Claude Code (both developers do this once):
 
 ```bash
-claude mcp add tunnel -- tunnel-mcp
+claude mcp add tunnel -- tunnel-mcp          # if globally installed
+# or, with no global install:
+claude mcp add tunnel -- npx -y tunnel-mcp
 ```
 
-Install the etiquette skill so each agent knows how to behave inside a tunnel
-(treat the peer as untrusted input, check with its human before acting on
-anything the peer says). Copy `skill/tunnel-etiquette/` from this repo into your
-`~/.claude/skills/` directory (or your plugin's skills directory).
+> `tunnel-mcp` is a stdio MCP server, not an interactive CLI. Launching it by
+> hand just waits silently for a client — that's expected. Run
+> `tunnel-mcp --help` for usage, or `tunnel-mcp --version`.
+
+The **tunnel-etiquette skill** teaches each agent how to behave inside a tunnel
+(treat the peer as untrusted input, and check with its human before acting on
+anything the peer says). Installing the package copies it into `~/.claude/skills/`
+automatically (best-effort). If install scripts are disabled
+(`npm install --ignore-scripts`), or you want it in a custom directory or force an
+update, run it explicitly:
+
+```bash
+npx tunnel-mcp install-skill                       # into ~/.claude/skills
+npx tunnel-mcp install-skill --dir <path> --force  # elsewhere / overwrite
+```
+
+Set `TUNNEL_SKILLS_DIR` to change the default target, or
+`TUNNEL_SKIP_SKILL_INSTALL=1` to opt out of the automatic copy.
 
 `cloudflared` is auto-downloaded to `~/.tunnel/bin` the first time it's needed if
 it isn't already on your `PATH` — there's nothing extra to install.
@@ -146,7 +162,7 @@ vulnerability.
 
 ```bash
 npm ci                  # install dependencies
-npm test                # run the test suite (109 tests, TDD)
+npm test                # run the test suite (136 tests, TDD)
 npm run build           # compile TypeScript
 npm run lint            # eslint
 npm run format:check    # prettier --check .
@@ -155,6 +171,29 @@ npm run test:coverage   # vitest run --coverage
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) for how to propose changes.
 
+## Troubleshooting
+
+**`tunnel-mcp` / `npx tunnel-mcp` "does nothing".** It's a stdio MCP server, not
+an interactive CLI — with no arguments it starts and waits for an MCP client to
+connect over stdin/stdout. That's working as intended. Register it with a client
+(above), or run `tunnel-mcp --help`.
+
+**`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
 
 This is an MVP. The following are explicitly out of scope for now:
@@ -162,7 +201,7 @@ This is an MVP. The following are explicitly out of scope for now:
 - Host-offline / asynchronous messaging
 - More than two participants in a session
 - Alternative transports (ngrok, WebRTC)
-- Join-link rotation or one-time tokens
+- Join-link rotation (re-issuing a fresh link mid-session; note that links are already single-use and expiring — see the security model above)
 - Encrypting the goal or other metadata
 
 ## License

package/dist/cli.d.ts

@@ -0,0 +1,21 @@
+export type ParsedArgs = {
+    mode: 'serve';
+} | {
+    mode: 'help';
+} | {
+    mode: 'version';
+} | {
+    mode: 'install-skill';
+    dir?: string;
+    force: boolean;
+} | {
+    mode: 'error';
+    message: string;
+};
+export declare function parseArgs(argv: string[]): ParsedArgs;
+export declare function helpText(version?: string): string;
+/** Runs the `install-skill` command. Returns a process exit code. */
+export declare function runInstallSkill(args: {
+    dir?: string;
+    force: boolean;
+}, out: (msg: string) => void): number;

package/dist/cli.js

@@ -0,0 +1,89 @@
+import { installSkill, readVersion } from './skillInstall.js';
+export function parseArgs(argv) {
+    if (argv.length === 0)
+        return { mode: 'serve' };
+    const [cmd, ...rest] = argv;
+    if (cmd === '--help' || cmd === '-h' || cmd === 'help')
+        return { mode: 'help' };
+    if (cmd === '--version' || cmd === '-v')
+        return { mode: 'version' };
+    if (cmd === 'install-skill') {
+        let dir;
+        let force = false;
+        for (let i = 0; i < rest.length; i++) {
+            const a = rest[i];
+            if (a === '--force' || a === '-f')
+                force = true;
+            else if (a === '--dir') {
+                const next = rest[++i];
+                // Guard against `--dir --force` (eats the flag) and a trailing `--dir`.
+                if (next === undefined || next.startsWith('-')) {
+                    return { mode: 'error', message: '--dir requires a path' };
+                }
+                dir = next;
+            }
+            else if (a.startsWith('--dir=')) {
+                dir = a.slice('--dir='.length);
+                if (dir === '')
+                    return { mode: 'error', message: '--dir requires a path' };
+            }
+            else
+                return { mode: 'error', message: `unknown option for install-skill: ${a}` };
+        }
+        return { mode: 'install-skill', dir, force };
+    }
+    return { mode: 'error', message: `unknown command: ${cmd}` };
+}
+export function helpText(version = readVersion()) {
+    return [
+        `tunnel-mcp v${version}`,
+        `An MCP server that lets two developers' Claude agents talk directly through an`,
+        `ephemeral, end-to-end-encrypted tunnel.`,
+        ``,
+        `This is a stdio MCP server, NOT an interactive CLI. With no arguments it starts`,
+        `the server and waits for an MCP client to connect over stdin/stdout, so running`,
+        `it by hand in a terminal will look like it "does nothing" — that's expected.`,
+        `You add it to an MCP client instead:`,
+        ``,
+        `  claude mcp add tunnel -- npx -y tunnel-mcp          # Claude Code (this project)`,
+        `  claude mcp add -s user tunnel -- npx -y tunnel-mcp  # ...available everywhere`,
+        ``,
+        `Commands:`,
+        `  (no args)        Start the MCP server on stdio (for an MCP client to launch)`,
+        `  install-skill    Install the tunnel-etiquette skill into your skills directory`,
+        `  --help, -h       Show this help and exit`,
+        `  --version, -v    Print the version and exit`,
+        ``,
+        `install-skill options:`,
+        `  --dir <path>     Target skills directory (default: ~/.claude/skills or`,
+        `                   $TUNNEL_SKILLS_DIR)`,
+        `  --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_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');
+}
+/** Runs the `install-skill` command. Returns a process exit code. */
+export function runInstallSkill(args, out) {
+    try {
+        const res = installSkill({ skillsDir: args.dir, overwrite: args.force });
+        if (res.installed) {
+            out(`Installed the tunnel-etiquette skill to ${res.target}${res.updated ? ' (overwrote the existing copy)' : ''}.`);
+        }
+        else {
+            out(`The tunnel-etiquette skill is already present at ${res.target}. Re-run with --force to overwrite it.`);
+        }
+        return 0;
+    }
+    catch (e) {
+        out(`Failed to install the skill: ${e instanceof Error ? e.message : String(e)}`);
+        return 1;
+    }
+}

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,9 +11,13 @@ export interface StartOptions {
     intervalMs?: number;
     healthCheck?: (url: string) => Promise<boolean>;
     probeTimeoutMs?: number;
+    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

@@ -8,49 +8,108 @@ export function parsePublicUrl(line) {
     const m = line.match(URL_RE);
     return m ? m[0] : null;
 }
-// Any HTTP response (even 404/502/426) means the Cloudflare edge is routing to us.
+// undici (Node's global fetch) reports the real network error on `.cause`, e.g.
+// a DNS failure surfaces as `cause.code === 'ENOTFOUND'`. Pull that out so the
+// caller can tell "DNS can't resolve the host" apart from "edge not ready yet".
+export function describeProbeError(e) {
+    const err = e;
+    const code = err?.cause?.code;
+    if (code)
+        return err.cause?.message ? `${code}: ${err.cause.message}` : code;
+    if (err?.name === 'TimeoutError')
+        return 'probe timed out';
+    return err?.message || 'unknown error';
+}
+// Any HTTP response (even 404/502/426) means the Cloudflare edge is routing to
+// us. A thrown error carries why it failed (DNS, TLS, refused, timeout).
+async function reachabilityProbe(url, probeTimeoutMs) {
+    try {
+        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(probeTimeoutMs) });
+        return { ok: true };
+    }
+    catch (e) {
+        return { ok: false, reason: describeProbeError(e) };
+    }
+}
+// Back-compat boolean probe (kept for external callers/tests).
 export async function defaultHealthCheck(url) {
+    return (await reachabilityProbe(url, DEFAULT_PROBE_TIMEOUT_MS)).ok;
+}
+// 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 {
-        await fetch(url, { method: 'GET', signal: AbortSignal.timeout(DEFAULT_PROBE_TIMEOUT_MS) });
-        return true;
+        host = new URL(url).host;
     }
     catch {
-        return false; // network/DNS error/timeout → edge not ready yet
+        /* keep the raw url */
     }
+    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 += '.' + 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;
 }
-// Races a single health-check attempt against a per-attempt timeout so that a
-// caller-supplied `check` that throws, rejects, or simply never resolves can
-// never leave the loop (and therefore the outer startCloudflared promise)
-// hanging. Any failure mode here just counts as "not healthy yet".
-function probeOnce(url, check, probeTimeoutMs) {
+// 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
+// `check` that throws, rejects, or simply never resolves can never leave the
+// loop (and therefore the outer startCloudflared promise) hanging.
+function probeOnce(url, probe, probeTimeoutMs) {
     return new Promise((resolve) => {
         let settled = false;
-        const finish = (ok) => {
+        const finish = (r) => {
             if (!settled) {
                 settled = true;
-                resolve(ok);
+                resolve(r);
             }
         };
-        const timer = setTimeout(() => finish(false), probeTimeoutMs);
+        const timer = setTimeout(() => finish({ ok: false, reason: 'probe timed out' }), probeTimeoutMs);
         Promise.resolve()
-            .then(() => check(url))
-            .then((ok) => {
+            .then(() => probe(url))
+            .then((r) => {
             clearTimeout(timer);
-            finish(ok);
+            finish(r);
         })
-            .catch(() => {
+            .catch((err) => {
             clearTimeout(timer);
-            finish(false);
+            finish({ ok: false, reason: describeProbeError(err) });
         });
     });
 }
-async function waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs) {
+async function waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs) {
+    let lastReason;
     for (let i = 0; i < attempts; i++) {
-        if (await probeOnce(url, check, probeTimeoutMs))
-            return true;
-        await new Promise((r) => setTimeout(r, intervalMs));
+        const r = await probeOnce(url, probe, probeTimeoutMs);
+        if (r.ok)
+            return r;
+        lastReason = r.reason;
+        await new Promise((res) => setTimeout(res, intervalMs));
     }
-    return false;
+    return { ok: false, reason: lastReason };
 }
 /**
  * `extraArgs` exists for tests: it lets a fake binary (e.g. `node fake.mjs`) be
@@ -63,8 +122,13 @@ export function startCloudflared(binPath, localPort, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? CLOUDFLARED_URL_TIMEOUT_MS;
     const attempts = opts.attempts ?? CLOUDFLARED_HEALTH_ATTEMPTS;
     const intervalMs = opts.intervalMs ?? CLOUDFLARED_HEALTH_INTERVAL_MS;
-    const check = opts.healthCheck ?? defaultHealthCheck;
     const probeTimeoutMs = opts.probeTimeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+    // A caller-supplied boolean healthCheck carries no failure reason; the default
+    // probe does. Adapt the former into a ProbeResult either way.
+    const custom = opts.healthCheck;
+    const probe = custom
+        ? async (u) => ({ ok: await custom(u) })
+        : (u) => reachabilityProbe(u, probeTimeoutMs);
     return new Promise((resolve, reject) => {
         const child = spawn(binPath, args, { stdio: ['ignore', 'pipe', 'pipe'] });
         let settled = false;
@@ -91,13 +155,29 @@ export function startCloudflared(binPath, localPort, opts = {}) {
                 if (url && !settled) {
                     settled = true;
                     clearTimeout(timer);
-                    waitHealthy(url, attempts, intervalMs, check, probeTimeoutMs)
-                        .then((ok) => {
-                        if (ok)
+                    // 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;
+                    }
+                    waitHealthy(url, attempts, intervalMs, probe, probeTimeoutMs)
+                        .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('cloudflared tunnel never became reachable'));
+                            reject(new Error(unreachableMessage(url, attempts, res.reason)));
                         }
                     })
                         .catch((err) => {

package/dist/env.d.ts

@@ -0,0 +1,19 @@
+/**
+ * True only when an env var is set to a meaningfully "on" value. Unset, '', '0',
+ * 'false', 'no', and 'off' (any case, trimmed) all read as off — so `FOO=0`
+ * disables a flag instead of accidentally enabling it (a plain `process.env.FOO`
+ * 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

@@ -0,0 +1,31 @@
+/**
+ * True only when an env var is set to a meaningfully "on" value. Unset, '', '0',
+ * 'false', 'no', and 'off' (any case, trimmed) all read as off — so `FOO=0`
+ * disables a flag instead of accidentally enabling it (a plain `process.env.FOO`
+ * truthiness check treats "0"/"false" as true).
+ */
+export function envFlag(name) {
+    const v = process.env[name];
+    if (v === undefined)
+        return false;
+    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/index.js

@@ -3,35 +3,71 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { TunnelSession } from './session.js';
 import { registerTools, defaultDisplayName } from './tools.js';
-const session = new TunnelSession();
-const server = new McpServer({ name: 'tunnel', version: '0.1.0' });
-registerTools(server, session, { displayName: defaultDisplayName() });
-let closing = false;
-async function teardown() {
-    if (closing)
-        return;
-    closing = true;
-    try {
-        await session.close('process exit');
+import { parseArgs, helpText, runInstallSkill } from './cli.js';
+import { readVersion, isSkillInstalled } from './skillInstall.js';
+// Write a one-shot command's output, then exit only once it has flushed — a bare
+// write()+exit() can truncate output piped to another process.
+function writeThenExit(stream, text, code) {
+    stream.write(text.endsWith('\n') ? text : text + '\n', () => process.exit(code));
+}
+async function main() {
+    const version = readVersion();
+    const parsed = parseArgs(process.argv.slice(2));
+    // One-shot commands print and exit without ever opening the JSON-RPC channel.
+    if (parsed.mode === 'help')
+        return writeThenExit(process.stdout, helpText(version), 0);
+    if (parsed.mode === 'version')
+        return writeThenExit(process.stdout, version, 0);
+    if (parsed.mode === 'error') {
+        return writeThenExit(process.stderr, `tunnel-mcp: ${parsed.message}\n\n${helpText(version)}`, 2);
+    }
+    if (parsed.mode === 'install-skill') {
+        const lines = [];
+        const code = runInstallSkill({ dir: parsed.dir, force: parsed.force }, (m) => lines.push(m));
+        // Success → stdout; failure → stderr.
+        return writeThenExit(code === 0 ? process.stdout : process.stderr, lines.join('\n'), code);
+    }
+    // Serve. stdout is reserved for the JSON-RPC transport, so all human-facing
+    // output goes to stderr (MCP clients capture it into their logs).
+    const session = new TunnelSession();
+    const server = new McpServer({ name: 'tunnel', version });
+    registerTools(server, session, { displayName: defaultDisplayName() });
+    let closing = false;
+    async function teardown() {
+        if (closing)
+            return;
+        closing = true;
+        try {
+            await session.close('process exit');
+        }
+        catch {
+            /* best effort */
+        }
+        process.exit(0);
     }
-    catch {
-        /* best effort */
+    process.on('SIGINT', teardown);
+    process.on('SIGTERM', teardown);
+    const transport = new StdioServerTransport();
+    // The host holds an HTTP/WS listener + a cloudflared child, so the event loop
+    // never drains and `beforeExit` would never fire. Drive teardown off the stdio
+    // pipe closing instead, which is how an MCP client actually ends the server.
+    transport.onclose = () => {
+        void teardown();
+    };
+    process.stdin.on('end', () => {
+        void teardown();
+    });
+    process.stdin.on('close', () => {
+        void teardown();
+    });
+    // Startup banner so a human who runs this by hand isn't staring at a silent,
+    // seemingly-hung process (this is a server, not an interactive CLI).
+    process.stderr.write(`tunnel-mcp v${version} ready on stdio — this is an MCP server, not an interactive CLI. ` +
+        `Add it to an MCP client (run \`tunnel-mcp --help\`).\n`);
+    if (!isSkillInstalled()) {
+        process.stderr.write(`tip: run \`npx tunnel-mcp install-skill\` to install the tunnel-etiquette skill ` +
+            `(teaches agents to treat the peer as untrusted input).\n`);
     }
-    process.exit(0);
+    await server.connect(transport);
 }
-process.on('SIGINT', teardown);
-process.on('SIGTERM', teardown);
-const transport = new StdioServerTransport();
-// The host holds an HTTP/WS listener + a cloudflared child, so the event loop
-// never drains and `beforeExit` would never fire. Drive teardown off the stdio
-// pipe closing instead, which is how an MCP client actually ends the server.
-transport.onclose = () => {
-    void teardown();
-};
-process.stdin.on('end', () => {
-    void teardown();
-});
-process.stdin.on('close', () => {
-    void teardown();
-});
-await server.connect(transport);
+void main();

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,9 +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 { reachabilityMode } from './env.js';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
-    startCloudflared: (bin, port) => realStart(bin, port),
+    // 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;
@@ -81,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/skillInstall.d.ts

@@ -0,0 +1,23 @@
+export declare function bundledSkillDir(): string;
+export declare function readVersion(): string;
+export declare function defaultSkillsDir(): string;
+/** Precedence: explicit arg → $TUNNEL_SKILLS_DIR → ~/.claude/skills. */
+export declare function resolveSkillsDir(explicit?: string): string;
+export declare function isSkillInstalled(skillsDir?: string): boolean;
+export interface InstallResult {
+    installed: boolean;
+    updated: boolean;
+    target: string;
+    source: string;
+}
+export declare function installSkill(opts?: {
+    skillsDir?: string;
+    overwrite?: boolean;
+}): InstallResult;
+/**
+ * Called from the postinstall script. Best-effort by contract: it must never
+ * throw (a failed skill copy must not fail `npm install`), it only installs
+ * when absent (never clobbers a user's copy on reinstall), and it bows out
+ * under CI or when the user opts out.
+ */
+export declare function installSkillBestEffort(log?: (msg: string) => void): void;

package/dist/skillInstall.js

@@ -0,0 +1,69 @@
+import { cpSync, existsSync, readFileSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { envFlag } from './env.js';
+const SKILL_NAME = 'tunnel-etiquette';
+// dist/skillInstall.js → package root is one level up. During tests (tsx runs
+// src/skillInstall.ts) this resolves to the repo root, which has the same
+// `skill/` and `package.json` layout as the published package.
+function packageRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+}
+export function bundledSkillDir() {
+    return path.join(packageRoot(), 'skill', SKILL_NAME);
+}
+export function readVersion() {
+    try {
+        const pkg = JSON.parse(readFileSync(path.join(packageRoot(), 'package.json'), 'utf8'));
+        return typeof pkg.version === 'string' ? pkg.version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function defaultSkillsDir() {
+    return path.join(os.homedir(), '.claude', 'skills');
+}
+/** Precedence: explicit arg → $TUNNEL_SKILLS_DIR → ~/.claude/skills. */
+export function resolveSkillsDir(explicit) {
+    return explicit || process.env.TUNNEL_SKILLS_DIR || defaultSkillsDir();
+}
+function targetDir(skillsDir) {
+    return path.join(skillsDir, SKILL_NAME);
+}
+export function isSkillInstalled(skillsDir = resolveSkillsDir()) {
+    return existsSync(path.join(targetDir(skillsDir), 'SKILL.md'));
+}
+export function installSkill(opts = {}) {
+    const source = bundledSkillDir();
+    if (!existsSync(path.join(source, 'SKILL.md'))) {
+        throw new Error(`bundled tunnel-etiquette skill not found at ${source}`);
+    }
+    const skillsDir = resolveSkillsDir(opts.skillsDir);
+    const target = targetDir(skillsDir);
+    const existed = existsSync(path.join(target, 'SKILL.md'));
+    if (existed && !opts.overwrite) {
+        return { installed: false, updated: false, target, source };
+    }
+    cpSync(source, target, { recursive: true });
+    return { installed: true, updated: existed, target, source };
+}
+/**
+ * Called from the postinstall script. Best-effort by contract: it must never
+ * throw (a failed skill copy must not fail `npm install`), it only installs
+ * when absent (never clobbers a user's copy on reinstall), and it bows out
+ * under CI or when the user opts out.
+ */
+export function installSkillBestEffort(log = () => { }) {
+    if (envFlag('TUNNEL_SKIP_SKILL_INSTALL') || envFlag('CI'))
+        return;
+    try {
+        const res = installSkill({ overwrite: false });
+        if (res.installed)
+            log(`tunnel-mcp: installed the tunnel-etiquette skill to ${res.target}`);
+    }
+    catch {
+        /* never break an install */
+    }
+}

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.1",
+  "version": "0.1.3",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {
@@ -11,6 +11,7 @@
   "files": [
     "dist",
     "skill",
+    "postinstall.mjs",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
@@ -29,6 +30,7 @@
     "format:check": "prettier --check .",
     "dev": "tsx src/index.ts",
     "e2e": "tsx scripts/e2e-two-agents.ts",
+    "postinstall": "node postinstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "keywords": [

package/postinstall.mjs

@@ -0,0 +1,13 @@
+// Best-effort: install the tunnel-etiquette skill into ~/.claude/skills when the
+// package is installed. This MUST never fail an install and is deliberately a
+// no-op in the cases where it can't or shouldn't run:
+//   - `npm install --ignore-scripts` (and hosts that disable scripts) skip it
+//   - CI, or TUNNEL_SKIP_SKILL_INSTALL=1, opt out (see installSkillBestEffort)
+//   - a dev checkout before `npm run build` has no dist/ yet → import throws → ignored
+// It IS idempotent, so running again (e.g. npx populating its cache) is harmless.
+try {
+  const { installSkillBestEffort } = await import('./dist/skillInstall.js');
+  installSkillBestEffort((m) => console.error(m));
+} catch {
+  /* dist not built yet, or any other error — never break the install */
+}