@dolusoft/claude-collab 1.7.1 → 1.8.0

package/README.md

@@ -7,57 +7,73 @@ Real-time collaboration between Claude Code terminals via MCP (Model Context Pro
 
 ## Overview
 
-Claude Collab lets multiple Claude Code terminals communicate with each other in real-time. One machine runs a lightweight hub server; everyone else connects to it — no firewall rules needed for clients.
+Claude Collab lets multiple Claude Code terminals communicate with each other in real-time. One machine starts a hub server via MCP tool — others on the same LAN auto-discover and connect via mDNS. No manual IP sharing, no terminal commands.
 
 ```
 alice ──outbound──→ ┌─────────────────┐ ←──outbound── bob
 charlie─outbound──→ │   hub server    │ ←──outbound── dave
-                    │ 192.168.1.5:9999│
+                    │ (auto-discover) │
                     └─────────────────┘
 ```
 
 ## Setup
 
-### Step 1 — Start the hub (one machine, one time)
-
-Pick any machine on your network. Run in a terminal:
+### Step 1 — Add to Claude Code (each machine, one time)
 
 ```bash
-npx @dolusoft/claude-collab --hub --port 9999
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name>
 ```
 
-Keep this terminal open. The hub routes messages between everyone.
+| Placeholder | What to put |
+|-------------|-------------|
+| `<your-name>` | Your identifier on the network (e.g. `alice`, `backend`, `frontend`) |
 
-### Step 2 — Add to Claude Code (each machine, one time)
+> Your name is saved permanently in Claude Code's MCP config. No server address needed — the hub is discovered automatically on the LAN.
+
+### Step 2 — One person starts the hub (via MCP tool)
+
+In Claude Code, call the `start_hub` tool:
 
-```bash
-claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name> --server <hub-ip>:<hub-port>
+```
+start_hub()           # uses default port 9999
+start_hub(port=8888)  # custom port
 ```
 
-| Placeholder | What to put |
-|-------------|-------------|
-| `<your-name>` | Your identifier on the network (e.g. `alice`, `backend`, `frontend`) |
-| `<hub-ip>` | IP address of the machine running the hub (e.g. `192.168.1.5`) |
-| `<hub-port>` | Port the hub is listening on (e.g. `9999`) |
+This will:
+1. Start the hub server on your machine
+2. Show a **Windows UAC prompt** once — click **Yes** to open the firewall port
+3. Advertise the hub on your LAN via mDNS
 
-> Your name and server address are saved permanently in Claude Code's MCP config. Every time Claude Code opens, it connects automatically — you never need to reconfigure.
+Everyone else will auto-connect within seconds. No IP address sharing needed.
 
-### With global install
+### Step 3 — Stop the hub when done
 
-```bash
-npm install -g @dolusoft/claude-collab
+```
+stop_hub()
+```
+
+This stops the server and removes the firewall rule (UAC prompt shown once).
+
+---
+
+### Manual / advanced mode
+
+If you prefer to manage the hub yourself (e.g. on a server), you can still use the legacy approach:
 
-# Hub:
-claude-collab --hub --port <hub-port>
+```bash
+# Start hub manually in a terminal:
+npx @dolusoft/claude-collab --hub --port 9999
 
-# Client (add to Claude Code):
-claude mcp add claude-collab -- claude-collab --name <your-name> --server <hub-ip>:<hub-port>
+# Add to Claude Code with explicit server address:
+claude mcp add claude-collab -- npx -y @dolusoft/claude-collab --name <your-name> --server <hub-ip>:<hub-port>
 ```
 
 ## MCP Tools
 
 | Tool | Description |
 |------|-------------|
+| `start_hub` | Start a hub server on this machine. Opens firewall via UAC, advertises on LAN via mDNS. |
+| `stop_hub` | Stop the running hub. Removes firewall rule via UAC. |
 | `ask` | Ask another peer a question by name. Waits up to 5 minutes for a response. |
 | `reply` | Reply to an incoming question (called automatically by Claude when a question arrives). |
 | `peers` | Show currently connected peers and your own name. |
@@ -83,10 +99,14 @@ src/
 │   ├── hub/
 │   │   ├── hub-server.ts    # WebSocket hub — routes messages by name
 │   │   ├── hub-client.ts    # Connects to hub, implements ICollabClient
+│   │   ├── hub-manager.ts   # Orchestrates hub + firewall + mDNS advertising
 │   │   └── hub-protocol.ts  # Wire protocol types
+│   ├── mdns/
+│   │   ├── mdns-advertiser.ts  # Broadcasts hub presence on LAN via mDNS
+│   │   └── mdns-discovery.ts   # Discovers hub on LAN via mDNS
 │   └── terminal-injector/   # Injects incoming questions into Claude Code
 └── presentation/
-    └── mcp/                 # MCP server + tools (ask, reply, peers, history)
+    └── mcp/                 # MCP server + tools (start_hub, stop_hub, ask, reply, peers, history)
 ```
 
 ## Development

package/dist/cli.js

@@ -3,10 +3,11 @@ import { Command } from 'commander';
 import { WebSocketServer, WebSocket } from 'ws';
 import { v4 } from 'uuid';
 import { EventEmitter } from 'events';
-import { execFile } from 'child_process';
+import { execFile, spawn } from 'child_process';
 import { unlinkSync } from 'fs';
 import { tmpdir } from 'os';
 import { join } from 'path';
+import { Bonjour } from 'bonjour-service';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
@@ -57,6 +58,15 @@ var HubServer = class {
       console.error("[hub] server error:", err.message);
     });
   }
+  stop() {
+    if (!this.wss) return;
+    for (const ws of this.clients.values()) ws.terminate();
+    this.clients.clear();
+    this.wsToName.clear();
+    this.wss.close();
+    this.wss = null;
+    console.log("claude-collab hub stopped");
+  }
   handleMessage(ws, msg) {
     switch (msg.type) {
       case "HELLO": {
@@ -363,7 +373,9 @@ var HubClient = class {
   }
   async join(name, displayName) {
     this.myName = name;
-    await this.connectAndHello();
+    if (this.serverUrl) {
+      await this.connectAndHello();
+    }
     return {
       memberId: v4(),
       teamId: name,
@@ -373,6 +385,10 @@ var HubClient = class {
       port: 0
     };
   }
+  async connectToHub(url) {
+    this.serverUrl = url;
+    await this.connectAndHello();
+  }
   async ask(toPeer, content, format) {
     const questionId = v4();
     const requestId = v4();
@@ -653,6 +669,85 @@ var HubClient = class {
     });
   }
 };
+var SERVICE_TYPE = "claude-collab";
+var MdnsAdvertiser = class {
+  bonjour = null;
+  start(port) {
+    this.bonjour = new Bonjour();
+    this.bonjour.publish({ name: "claude-collab-hub", type: SERVICE_TYPE, port });
+    console.error(`[mdns] advertising hub on port ${port}`);
+  }
+  stop() {
+    if (!this.bonjour) return;
+    this.bonjour.unpublishAll(() => {
+      this.bonjour?.destroy();
+    });
+    this.bonjour = null;
+    console.error("[mdns] stopped advertising");
+  }
+};
+
+// src/infrastructure/hub/hub-manager.ts
+var HubManager = class {
+  hubServer = null;
+  advertiser = null;
+  currentPort = null;
+  get isRunning() {
+    return this.hubServer !== null;
+  }
+  get port() {
+    return this.currentPort;
+  }
+  async start(port) {
+    if (this.isRunning) throw new Error("Hub is already running");
+    const server = new HubServer();
+    server.start(port);
+    this.hubServer = server;
+    this.currentPort = port;
+    await addFirewallRule(port);
+    const advertiser = new MdnsAdvertiser();
+    advertiser.start(port);
+    this.advertiser = advertiser;
+  }
+  async stop() {
+    if (!this.isRunning) throw new Error("Hub is not running");
+    if (this.advertiser) {
+      this.advertiser.stop();
+      this.advertiser = null;
+    }
+    const port = this.currentPort;
+    this.hubServer.stop();
+    this.hubServer = null;
+    this.currentPort = null;
+    await removeFirewallRule(port);
+  }
+};
+function runElevated(netshArgs) {
+  return new Promise((resolve, reject) => {
+    const ps = spawn("powershell", [
+      "-NoProfile",
+      "-Command",
+      `Start-Process -FilePath "netsh" -ArgumentList "${netshArgs}" -Verb RunAs -Wait`
+    ]);
+    ps.on("close", (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Firewall command failed (exit code ${code}). User may have cancelled the UAC prompt.`));
+    });
+    ps.on("error", (err) => {
+      reject(new Error(`Failed to launch PowerShell for firewall elevation: ${err.message}`));
+    });
+  });
+}
+async function addFirewallRule(port) {
+  await runElevated(
+    `advfirewall firewall add rule name="claude-collab-${port}" protocol=TCP dir=in localport=${port} action=allow`
+  );
+}
+async function removeFirewallRule(port) {
+  await runElevated(
+    `advfirewall firewall delete rule name="claude-collab-${port}"`
+  );
+}
 var askSchema = {
   peer: z.string().describe('Name of the peer to ask (e.g., "alice", "backend")'),
   question: z.string().describe("The question to ask (supports markdown)")
@@ -814,10 +909,101 @@ ${answerLine}`;
     };
   });
 }
+function registerStartHubTool(server, client, hubManager) {
+  server.tool(
+    "start_hub",
+    "Start a hub server on this machine. Opens a firewall rule (UAC prompt) and advertises on LAN via mDNS \u2014 peers connect automatically, no IP sharing needed.",
+    { port: z.number().min(1024).max(65535).optional().describe("Port to listen on (default: 9999)") },
+    async ({ port = 9999 }) => {
+      if (hubManager.isRunning) {
+        return {
+          content: [{
+            type: "text",
+            text: `Hub is already running on port ${hubManager.port}.`
+          }]
+        };
+      }
+      try {
+        await hubManager.start(port);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to start hub: ${msg}`
+          }]
+        };
+      }
+      try {
+        await client.connectToHub(`ws://localhost:${port}`);
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text",
+            text: `Hub started on port ${port}, but failed to self-connect: ${msg}`
+          }]
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Hub started on port ${port}.`,
+            `Firewall rule added (claude-collab-${port}).`,
+            `Others on the LAN will auto-discover and connect \u2014 no IP sharing needed.`,
+            `Use stop_hub when you are done to close the hub and remove the firewall rule.`
+          ].join("\n")
+        }]
+      };
+    }
+  );
+}
+
+// src/presentation/mcp/tools/stop-hub.tool.ts
+function registerStopHubTool(server, hubManager) {
+  server.tool(
+    "stop_hub",
+    "Stop the running hub server. Removes the firewall rule (UAC prompt) and stops LAN advertising. Connected peers will be disconnected.",
+    {},
+    async () => {
+      if (!hubManager.isRunning) {
+        return {
+          content: [{
+            type: "text",
+            text: "No hub is currently running on this machine."
+          }]
+        };
+      }
+      const port = hubManager.port;
+      try {
+        await hubManager.stop();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          content: [{
+            type: "text",
+            text: `Failed to stop hub: ${msg}`
+          }]
+        };
+      }
+      return {
+        content: [{
+          type: "text",
+          text: [
+            `Hub stopped (was on port ${port}).`,
+            `Firewall rule removed (claude-collab-${port}).`,
+            `All peers have been disconnected.`
+          ].join("\n")
+        }]
+      };
+    }
+  );
+}
 
 // src/presentation/mcp/server.ts
 function createMcpServer(options) {
-  const { client } = options;
+  const { client, hubManager } = options;
   const server = new McpServer({
     name: "claude-collab",
     version: "0.1.0"
@@ -826,6 +1012,8 @@ function createMcpServer(options) {
   registerReplyTool(server, client);
   registerPeersTool(server, client);
   registerHistoryTool(server, client);
+  registerStartHubTool(server, client, hubManager);
+  registerStopHubTool(server, hubManager);
   return server;
 }
 async function startMcpServer(options) {
@@ -860,9 +1048,10 @@ program.name("claude-collab").description("P2P collaboration between Claude Code
     }
     const url = options.server.startsWith("ws") ? options.server : `ws://${options.server}`;
     const client = new HubClient();
+    const hubManager = new HubManager();
     client.setServerUrl(url);
     await client.join(options.name, options.name);
-    await startMcpServer({ client });
+    await startMcpServer({ client, hubManager });
   }
 });
 program.parse();