happy-mcp-server 0.3.1 → 1.0.0

package/README.md

@@ -18,9 +18,48 @@ happy-mcp auth
 
 Scan the QR code with the Happy mobile app to pair your account.
 
-### 3. Configure Your MCP Client
+### 3. Choose Your Transport
 
-Add `happy-mcp` to your MCP client configuration. See [MCP Configuration](#mcp-configuration) below.
+**Option A: Stdio Transport (Default)**
+
+Configure `happy-mcp` in your MCP client. See [MCP Configuration](#mcp-configuration) below.
+
+**Option B: HTTP Transport**
+
+Start the server with HTTP transport:
+
+```bash
+happy-mcp serve
+# Or specify a port:
+happy-mcp serve --port 3000
+```
+
+The server will start at `http://127.0.0.1:<port>/mcp` (port auto-assigned if not specified).
+
+## Commands
+
+`happy-mcp` provides several commands for different modes and authentication:
+
+| Command | Description |
+|---------|-------------|
+| `happy-mcp` | Start the MCP server using stdio transport (default). Use this mode when configuring the server in MCP clients like Claude Desktop, Claude Code, Cursor, etc. |
+| `happy-mcp serve` | Start the MCP server using HTTP transport on an auto-assigned port. The server binds to `127.0.0.1` and reports the listening port and endpoint URL on startup. |
+| `happy-mcp serve --port <port>` | Start the HTTP server on a specific port (1-65535). Useful when you need a predictable port number for client configuration or firewall rules. |
+| `happy-mcp auth` | Check authentication status. If not authenticated, prompts you to scan a QR code with the Happy mobile app to pair your account. |
+| `happy-mcp auth login` | Force a new pairing flow, even if already authenticated. Use this to switch accounts or re-authenticate. |
+| `happy-mcp auth logout` | Remove saved credentials from `~/.happy-mcp/credentials.json`. |
+| `happy-mcp help` | Display help message with available commands. |
+
+### Transport Comparison
+
+| Feature | Stdio Transport | HTTP Transport |
+|---------|----------------|----------------|
+| **Use case** | MCP client integration (Claude Desktop, Cursor, etc.) | Custom clients, testing, or programmatic access |
+| **Command** | `happy-mcp` | `happy-mcp serve [--port <port>]` |
+| **Communication** | Standard input/output streams | HTTP POST/GET/DELETE to `/mcp` endpoint |
+| **Port** | N/A (uses stdio) | Auto-assigned or specified with `--port` |
+| **Accessibility** | Only via client process | HTTP endpoint on localhost (`127.0.0.1`) |
+| **Authentication** | Lazy (authenticates on first tool call if needed) | Required before startup (fails if credentials missing) |
 
 ## Configuration
 
@@ -34,6 +73,55 @@ Environment variables customize server behavior:
 | `HAPPY_MCP_LOG_LEVEL` | `warn` | Log level: `debug`, `info`, `warn`, or `error`. Logs are written to stderr. |
 | `HAPPY_MCP_ENABLE_START` | `true` | Set to `false` to disable the `start_session` tool. |
 
+## HTTP Transport
+
+When running `happy-mcp serve`, the server exposes MCP over HTTP instead of stdio. This mode is useful for custom clients, testing, or programmatic access.
+
+### Starting the HTTP Server
+
+```bash
+# Auto-assign port (reports actual port on startup)
+happy-mcp serve
+
+# Specify a port
+happy-mcp serve --port 3000
+
+# With environment variables
+HAPPY_MCP_LOG_LEVEL=debug happy-mcp serve --port 8080
+```
+
+### Server Endpoint
+
+The server exposes the MCP protocol at:
+
+```
+http://127.0.0.1:<port>/mcp
+```
+
+**Security:** The server binds to `127.0.0.1` (localhost only) and is not accessible from other machines. This prevents unauthorized network access to your Happy Coder sessions.
+
+### HTTP Methods
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| POST | `/mcp` | Initialize new MCP session or send requests |
+| GET | `/mcp` | Server-Sent Events (SSE) stream for notifications |
+| DELETE | `/mcp` | Terminate an MCP session |
+
+### Requirements
+
+- **Authentication required**: You must run `happy-mcp auth` before starting the HTTP server. The server will exit with an error if credentials are not found.
+- **Credential file permissions**: The credentials file must have `0600` permissions (readable only by owner).
+
+### Example: Testing with curl
+
+```bash
+# Initialize a new MCP session
+curl -X POST http://127.0.0.1:3000/mcp \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc": "2.0", "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}, "id": 1}'
+```
+
 ## MCP Configuration
 
 <details>

package/dist/relay/client.d.ts

@@ -27,6 +27,11 @@ export declare class RelayClient extends EventEmitter {
      * Response is encrypted with session key.
      */
     sessionRpc<R>(sessionId: string, method: string, params: unknown): Promise<R>;
+    /**
+     * Send a message to a session via Socket.io emit (fire-and-forget).
+     * Used by send_message tool.
+     */
+    sendMessage(sessionId: string, encryptedContent: string): void;
     /**
      * Encrypted RPC call to a machine.
      * Used for start_session (spawn-happy-session).

package/dist/relay/client.js

@@ -233,6 +233,19 @@ export class RelayClient extends EventEmitter {
         }
         return undefined;
     }
+    /**
+     * Send a message to a session via Socket.io emit (fire-and-forget).
+     * Used by send_message tool.
+     */
+    sendMessage(sessionId, encryptedContent) {
+        if (!this.connected || !this.socket) {
+            throw new RelayError('Relay not connected');
+        }
+        this.socket.emit('message', {
+            sid: sessionId,
+            message: encryptedContent,
+        });
+    }
     /**
      * Encrypted RPC call to a machine.
      * Used for start_session (spawn-happy-session).

package/dist/server.js

@@ -42,7 +42,7 @@ export function registerAllTools(server, config, api, relay, sessionManager) {
     registerListSessions(server, sessionManager, config);
     registerGetSession(server, api, sessionManager);
     registerWatchSession(server, relay, sessionManager);
-    registerSendMessage(server, api, sessionManager);
+    registerSendMessage(server, relay, sessionManager);
     registerApprovePermission(server, relay, sessionManager);
     registerDenyPermission(server, relay, sessionManager);
     registerInterruptSession(server, relay, sessionManager);

package/dist/tools/send_message.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
-import type { ApiClient } from '../api/client.js';
+import type { RelayClient } from '../relay/client.js';
 import type { SessionManager } from '../session/manager.js';
-export declare function registerSendMessage(server: McpServer, api: ApiClient, sessionManager: SessionManager): RegisteredTool;
+export declare function registerSendMessage(server: McpServer, relay: RelayClient, sessionManager: SessionManager): RegisteredTool;

package/dist/tools/send_message.js

@@ -1,8 +1,7 @@
 import { z } from 'zod';
-import { randomUUID } from 'crypto';
 import { encryptToBase64 } from '../auth/crypto.js';
 const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
-export function registerSendMessage(server, api, sessionManager) {
+export function registerSendMessage(server, relay, sessionManager) {
     return server.tool('send_message', 'Send a message to a Happy Coder session. The message will appear as a user message in the session. If the session is actively generating, the message will be queued and processed when the session is ready. Can optionally change the permission mode.', {
         sessionId: z.string().describe('The session ID to send the message to'),
         message: z.string().describe('The message text to send'),
@@ -13,6 +12,16 @@ export function registerSendMessage(server, api, sessionManager) {
         }).optional(),
     }, async ({ sessionId, message, meta }) => {
         try {
+            // Check relay connectivity
+            if (!relay.connected) {
+                const msg = relay.state === 'connecting'
+                    ? 'Relay is still connecting. Please try again in a few seconds.'
+                    : 'Relay is disconnected.';
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: relay.state === 'connecting' ? 'RelayConnecting' : 'RelayDisconnected',
+                                message: msg,
+                            }) }] };
+            }
             const session = sessionManager.get(sessionId);
             if (!session) {
                 return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'SessionNotFound', message: `Session ${sessionId} not found` }) }] };
@@ -28,17 +37,15 @@ export function registerSendMessage(server, api, sessionManager) {
                     ...(meta?.disallowedTools ? { disallowedTools: meta.disallowedTools } : {}),
                 },
             };
-            // Encrypt and send via V3 REST API
+            // Encrypt and send via Socket.io emit (fire-and-forget)
             const encrypted = encryptToBase64(session.encryption, content);
-            const localId = randomUUID();
-            const result = await api.sendMessages(sessionId, [{ content: encrypted, localId }]);
+            relay.sendMessage(sessionId, encrypted);
             return {
                 content: [{
                         type: 'text',
                         text: JSON.stringify({
                             success: true,
-                            messageId: result.messages?.[0]?.id,
-                            seq: result.messages?.[0]?.seq,
+                            dispatched: true,
                         }, null, 2),
                     }],
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "happy-mcp-server",
-  "version": "0.3.1",
+  "version": "1.0.0",
   "description": "MCP server for observing and controlling Happy Coder sessions",
   "author": {
     "name": "Jared Spencer",