happy-mcp-server 0.3.2 → 1.0.1

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.js

@@ -149,6 +149,10 @@ export class RelayClient extends EventEmitter {
                 : null;
             this.sessionManager.updateAgentState(sessionId, decrypted, agentState.version);
         }
+        // Handle active flag
+        if (body.active !== undefined) {
+            this.sessionManager.updateSessionActivity(sessionId, body.active);
+        }
         this.emit('session_update', sessionId);
     }
     handleUpdateMachine(body) {
@@ -202,6 +206,12 @@ export class RelayClient extends EventEmitter {
                     }
                 }
                 break;
+            case 'activity':
+                if (event.id && this.sessionManager.has(event.id)) {
+                    this.sessionManager.updateSessionActivity(event.id, event.active ?? false, event.activeAt, event.thinking);
+                    this.emit('session_update', event.id);
+                }
+                break;
             default:
                 logger.debug('Unhandled ephemeral type:', event.type);
         }

package/dist/session/manager.d.ts

@@ -13,6 +13,7 @@ export declare class SessionManager {
     remove(id: string): void;
     updateMetadata(id: string, metadata: SessionMetadata | null, version: number): void;
     updateAgentState(id: string, agentState: AgentState | null, version: number): void;
+    updateSessionActivity(id: string, active: boolean, activeAt?: number, thinking?: boolean): void;
     applyMessage(sessionId: string, messageId: string, seq: number, content: unknown, createdAt: number): void;
     getMessages(sessionId: string, limit?: number): DecryptedMessage[];
     getSessionStatus(sessionId: string): SessionStatus;

package/dist/session/manager.js

@@ -39,6 +39,9 @@ export class SessionManager {
             lastSeq: 0,
             lastActivity: Date.now(),
             active,
+            activeAt: Date.now(),
+            thinking: false,
+            thinkingAt: 0,
             createdAt,
             updatedAt,
         });
@@ -78,6 +81,20 @@ export class SessionManager {
             logger.debug(`Session ${id} agentState updated to v${version}`);
         }
     }
+    updateSessionActivity(id, active, activeAt, thinking) {
+        const session = this.sessions.get(id);
+        if (!session)
+            return;
+        session.active = active;
+        if (activeAt !== undefined)
+            session.activeAt = activeAt;
+        if (thinking !== undefined) {
+            session.thinking = thinking;
+            session.thinkingAt = Date.now();
+        }
+        session.lastActivity = Date.now();
+        logger.debug(`Session ${id} activity updated: active=${active}, thinking=${thinking ?? session.thinking}`);
+    }
     // --- Message Handling ---
     applyMessage(sessionId, messageId, seq, content, createdAt) {
         const session = this.sessions.get(sessionId);
@@ -104,13 +121,16 @@ export class SessionManager {
     // --- Status Derivation ---
     getSessionStatus(sessionId) {
         const session = this.sessions.get(sessionId);
-        if (!session?.agentState)
+        if (!session)
             return 'idle';
-        const state = session.agentState;
-        const hasRequests = state.requests && Object.keys(state.requests).length > 0;
-        if (hasRequests)
-            return 'waiting_permission';
-        if (state.controlledByUser)
+        // Permission requests take highest priority
+        if (session.agentState) {
+            const hasRequests = session.agentState.requests && Object.keys(session.agentState.requests).length > 0;
+            if (hasRequests)
+                return 'waiting_permission';
+        }
+        // Session is active if the relay says it's active or it's thinking
+        if (session.active || session.thinking)
             return 'active';
         return 'idle';
     }

package/dist/session/types.d.ts

@@ -52,6 +52,9 @@ export interface CachedSession {
     lastSeq: number;
     lastActivity: number;
     active: boolean;
+    activeAt: number;
+    thinking: boolean;
+    thinkingAt: number;
     createdAt: number;
     updatedAt: number;
 }

package/package.json

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