tunnel-mcp 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -11,6 +11,24 @@ 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
+
+- `mcpName` (`io.github.zachlikefolio/tunnel-mcp`) in `package.json`, the
+  ownership-verification field required to list the server in the official
+  MCP Registry (registry.modelcontextprotocol.io). No functional changes.
+
 ## [0.1.7] - 2026-07-01
 
 ### Security
@@ -163,7 +181,9 @@ 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.7...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
 [0.1.5]: https://github.com/zachlikefolio/tunnel-mcp/compare/v0.1.4...v0.1.5

package/README.md

@@ -4,8 +4,21 @@
 
 [![CI](https://github.com/zachlikefolio/tunnel-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zachlikefolio/tunnel-mcp/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/tunnel-mcp)](https://www.npmjs.com/package/tunnel-mcp)
+[![npm downloads](https://img.shields.io/npm/dm/tunnel-mcp)](https://www.npmjs.com/package/tunnel-mcp)
 ![node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)
 
+![tunnel-mcp demo — two agents talking through a real encrypted tunnel](docs/demo.gif)
+
+**Reproduce that yourself in 30 seconds** — clone the repo and:
+
+```bash
+npm ci && npm run demo
+```
+
+That opens a real encrypted tunnel through Cloudflare's edge, joins it as a
+guest, exchanges end-to-end-encrypted messages, proves the join link is
+single-use, and tears everything down.
+
 When two developers each run a Claude agent and need those agents to collaborate,
 the usual workaround is a human sitting in the middle, copy-pasting messages from
 one chat window to the other. **tunnel-mcp** removes that human. It's an MCP
@@ -83,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,6 +1,7 @@
 {
   "name": "tunnel-mcp",
-  "version": "0.1.7",
+  "mcpName": "io.github.zachlikefolio/tunnel-mcp",
+  "version": "0.1.9",
   "description": "Let two developers' Claude agents talk directly through an ephemeral, end-to-end-encrypted tunnel.",
   "type": "module",
   "bin": {
@@ -30,6 +31,7 @@
     "format:check": "prettier --check .",
     "dev": "tsx src/index.ts",
     "e2e": "tsx scripts/e2e-two-agents.ts",
+    "demo": "tsx scripts/demo.ts",
     "postinstall": "node postinstall.mjs",
     "prepublishOnly": "npm run build"
   },
@@ -66,14 +68,14 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.109.0",
-    "@types/node": "^20.14.0",
+    "@types/node": "^26.1.0",
     "@types/ws": "^8.5.10",
     "@vitest/coverage-v8": "^4.1.9",
-    "eslint": "^9.9.0",
+    "eslint": "^10.6.0",
     "fast-check": "^4.8.0",
     "prettier": "^3.3.0",
     "tsx": "^4.16.0",
-    "typescript": "^5.5.0",
+    "typescript": "^6.0.3",
     "typescript-eslint": "^8.0.0",
     "vitest": "^4.1.9"
   }