tunnel-mcp 0.1.8 → 0.1.9

package/CHANGELOG.md

@@ -11,6 +11,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Nothing yet.
 
+## [0.1.9] - 2026-07-02
+
+### Added
+
+- **`tunnel_open` now returns `invite`** — a ready-to-forward plain-text message
+  containing the one-time setup command (`claude mcp add tunnel -- npx -y
+tunnel-mcp`) and the join link, so the host's human can paste one message to
+  the other developer instead of explaining the install. The tool description
+  directs the agent to relay it verbatim.
+
 ## [0.1.8] - 2026-07-02
 
 ### Added
@@ -171,7 +181,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.8...HEAD
+[Unreleased]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.9...HEAD
+[0.1.9]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.8...v0.1.9
 [0.1.8]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.7...v0.1.8
 [0.1.7]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.6...v0.1.7
 [0.1.6]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.5...v0.1.6

package/README.md

@@ -96,11 +96,12 @@ it isn't already on your `PATH` — there's nothing extra to install.
 
 > "Open a tunnel to pair on debugging the checkout flow."
 
-Claude calls `tunnel_open({ goal })` and returns a join link. Share that link
-with the other developer over a trusted channel (Slack DM, etc.) — **it's a
-secret**, since it contains the encryption key for the session. The link is
-**single-use and expires after ~10 minutes** (`tunnel_open` reports
-`joinLinkExpiresInSec`), so share it promptly.
+Claude calls `tunnel_open({ goal })` and hands back a ready-to-forward
+**invite** — one plain-text message containing the one-time setup command and
+the join link. Paste it to the other developer over a trusted channel (Slack
+DM, etc.) — **the link is a secret**, since it contains the encryption key for
+the session. It is **single-use and expires after ~10 minutes**
+(`tunnel_open` reports `joinLinkExpiresInSec`), so share it promptly.
 
 **Guest** — paste the link and ask Claude to join:
 

package/dist/invite.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The ready-to-forward invite a host's human sends to the other developer.
+ * Every tunnel needs a second dev with tunnel-mcp installed — so the invite
+ * carries the one-time setup command alongside the join link, making each
+ * session recruit its own second participant with zero friction.
+ */
+export declare function buildInvite(opts: {
+    goal: string;
+    joinLink: string;
+    expiresInSec: number;
+}): string;

package/dist/invite.js

@@ -0,0 +1,19 @@
+/**
+ * The ready-to-forward invite a host's human sends to the other developer.
+ * Every tunnel needs a second dev with tunnel-mcp installed — so the invite
+ * carries the one-time setup command alongside the join link, making each
+ * session recruit its own second participant with zero friction.
+ */
+export function buildInvite(opts) {
+    const mins = Math.max(1, Math.ceil(opts.expiresInSec / 60));
+    return [
+        `You're invited to a Claude-agent tunnel — goal: "${opts.goal}"`,
+        ``,
+        `1) One-time setup (skip if you already have tunnel-mcp):`,
+        `   claude mcp add tunnel -- npx -y tunnel-mcp`,
+        `2) Then tell your Claude:`,
+        `   Join this tunnel: ${opts.joinLink}`,
+        ``,
+        `The link is single-use and expires in ~${mins} minute${mins === 1 ? '' : 's'}.`,
+    ].join('\n');
+}

package/dist/session.d.ts

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

package/dist/session.js

@@ -7,6 +7,7 @@ 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 { buildInvite } from './invite.js';
 const DEFAULT_DEPS = {
     ensureCloudflared: realEnsure,
     startCloudflared: (bin, port) => realStart(bin, port),
@@ -76,11 +77,13 @@ export class TunnelSession {
             void this.close();
         });
         relay.submitLocal(buildSystem('host', `tunnel opened — goal: ${goal}`));
+        const joinLinkExpiresInSec = Math.round(joinTtlMs / 1000);
         return {
             tunnelId,
             joinLink,
             status: 'waiting_for_guest',
-            joinLinkExpiresInSec: Math.round(joinTtlMs / 1000),
+            joinLinkExpiresInSec,
+            invite: buildInvite({ goal, joinLink, expiresInSec: joinLinkExpiresInSec }),
         };
     }
     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. The result includes `invite`: a ready-to-forward plain-text message with the one-time setup command and the join link — show it to your human verbatim so they can paste it straight to the other developer.',
         inputSchema: { goal: z.string() },
     }, async ({ goal }) => ok(await session.open(goal, opts.displayName)));
     register(server, 'tunnel_join', {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "tunnel-mcp",
   "mcpName": "io.github.zachlikefolio/tunnel-mcp",
-  "version": "0.1.8",
+  "version": "0.1.9",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {