happy-mcp-server 1.1.0 → 1.1.2

package/README.md

@@ -12,50 +12,66 @@ npm i -g happy-mcp-server
 
 ### 2. Authenticate
 
+**Option A: MCP-based authentication (Recommended for Claude Cowork)**
+
+Add the server to your MCP client configuration (see [MCP Configuration](#mcp-configuration) below), then call the `authentication_status` tool from within your MCP client. The tool returns a QR code and web URL for pairing. Once you scan the QR code with the Happy mobile app, tools activate automatically.
+
+**Option B: CLI authentication**
+
+```bash
+happy-mcp-server auth
+```
+
+Scan the QR code with the Happy mobile app to pair your account. This creates credentials at `~/.happy-mcp/credentials.json`.
+
+**Option C: Environment variable authentication**
+
+For ephemeral environments (Claude Cowork, Docker, CI/CD), set the `HAPPY_MCP_ACCOUNT_SECRET` environment variable:
+
 ```bash
-happy-mcp auth
+export HAPPY_MCP_ACCOUNT_SECRET=$(cat ~/.happy-mcp/credentials.json | jq -r .secret)
 ```
 
-Scan the QR code with the Happy mobile app to pair your account.
+When set, authentication happens instantly on startup with no QR code or credential file required.
 
 ### 3. Choose Your Transport
 
 **Option A: Stdio Transport (Default)**
 
-Configure `happy-mcp` in your MCP client. See [MCP Configuration](#mcp-configuration) below.
+Configure `happy-mcp-server` in your MCP client. See [MCP Configuration](#mcp-configuration) below.
 
 **Option B: HTTP Transport**
 
 Start the server with HTTP transport:
 
 ```bash
-happy-mcp serve
+happy-mcp-server serve
 # Or specify a port:
-happy-mcp serve --port 3000
+happy-mcp-server 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:
+`happy-mcp-server` 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. |
+| `happy-mcp-server` | 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-server 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-server 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-server 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-server auth login` | Force a new pairing flow, even if already authenticated. Use this to switch accounts or re-authenticate. |
+| `happy-mcp-server auth logout` | Remove saved credentials from `~/.happy-mcp/credentials.json`. |
+| `happy-mcp-server 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>]` |
+| **Command** | `happy-mcp-server` | `happy-mcp-server 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`) |
@@ -68,26 +84,29 @@ Environment variables customize server behavior:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `HAPPY_SERVER_URL` | `https://api.cluster-fluster.com` | Happy relay server URL. |
+| `HAPPY_MCP_ACCOUNT_SECRET` | (none) | Base64-encoded 32-byte account secret for instant authentication. When set, bypasses credential file and QR pairing. Obtain via: `cat ~/.happy-mcp/credentials.json \| jq -r .secret` |
 | `HAPPY_MCP_COMPUTERS` | `os.hostname()` | Comma-separated list of computer hostnames to filter sessions and machines. Use `*` to show all computers. |
 | `HAPPY_MCP_PROJECT_PATHS` | `process.cwd()` | Comma-separated list of project path prefixes to filter sessions. Use `*` to show all paths. |
+| `HAPPY_MCP_CREDENTIALS_PATH` | `~/.happy-mcp/credentials.json` | Path to credentials file |
 | `HAPPY_MCP_LOG_LEVEL` | `warn` | Log level: `debug`, `info`, `warn`, or `error`. Logs are written to stderr. |
+| `HAPPY_MCP_SESSION_CACHE_TTL` | `300` | Session cache TTL in seconds |
 | `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.
+When running `happy-mcp-server 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
+happy-mcp-server serve
 
 # Specify a port
-happy-mcp serve --port 3000
+happy-mcp-server serve --port 3000
 
 # With environment variables
-HAPPY_MCP_LOG_LEVEL=debug happy-mcp serve --port 8080
+HAPPY_MCP_LOG_LEVEL=debug happy-mcp-server serve --port 8080
 ```
 
 ### Server Endpoint
@@ -110,7 +129,7 @@ http://127.0.0.1:<port>/mcp
 
 ### 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.
+- **Authentication required**: You must run `happy-mcp-server auth` or set `HAPPY_MCP_ACCOUNT_SECRET` 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
@@ -130,7 +149,7 @@ curl -X POST http://127.0.0.1:3000/mcp \
 Add to `.mcp.json` in your project root or configure via CLI:
 
 ```bash
-claude mcp add --transport stdio happy -- happy-mcp
+claude mcp add --transport stdio happy -- happy-mcp-server
 ```
 
 Or manually add to `.mcp.json`:
@@ -140,7 +159,7 @@ Or manually add to `.mcp.json`:
   "mcpServers": {
     "happy": {
       "type": "stdio",
-      "command": "happy-mcp"
+      "command": "happy-mcp-server"
     }
   }
 }
@@ -153,7 +172,7 @@ Or manually add to `.mcp.json`:
   "mcpServers": {
     "happy": {
       "type": "stdio",
-      "command": "happy-mcp",
+      "command": "happy-mcp-server",
       "env": {
         "HAPPY_MCP_COMPUTERS": "*",
         "HAPPY_MCP_PROJECT_PATHS": "*"
@@ -178,7 +197,7 @@ Add to your Claude Desktop config:
   "mcpServers": {
     "happy": {
       "type": "stdio",
-      "command": "happy-mcp"
+      "command": "happy-mcp-server"
     }
   }
 }
@@ -195,7 +214,7 @@ Add to `.cursor/mcp.json` in your project or global config:
 {
   "mcpServers": {
     "happy": {
-      "command": "happy-mcp"
+      "command": "happy-mcp-server"
     }
   }
 }
@@ -212,7 +231,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 {
   "mcpServers": {
     "happy": {
-      "command": "happy-mcp"
+      "command": "happy-mcp-server"
     }
   }
 }
@@ -232,7 +251,7 @@ Add to `~/.continue/config.json`:
       {
         "transport": {
           "type": "stdio",
-          "command": "happy-mcp"
+          "command": "happy-mcp-server"
         }
       }
     ]

package/dist/auth/pairing-manager.d.ts

@@ -0,0 +1,41 @@
+import type { Credentials } from './crypto.js';
+import type { Config } from '../config.js';
+type PairingState = 'idle' | 'polling' | 'success';
+export declare class PairingManager {
+    private config;
+    private onSuccess;
+    private session;
+    private state;
+    private pollTimerId;
+    private pollDeadline;
+    private isRequestInFlight;
+    private pairingComplete;
+    private pendingCredentials;
+    private destroyed;
+    private initiatePromise;
+    constructor(config: Config, onSuccess: (credentials: Credentials) => Promise<void>);
+    get currentState(): PairingState;
+    get hasSession(): boolean;
+    /**
+     * Initiate pairing: generate keypair, POST to relay, generate QR, start polling.
+     * If already initiated, restarts the polling timer and returns cached QR.
+     */
+    initiate(): Promise<{
+        qrAscii: string;
+        webUrl: string;
+    }>;
+    private _doInitiate;
+    /**
+     * Start background polling. Fire-and-forget.
+     * If already polling, restarts the deadline timer.
+     */
+    private startPolling;
+    private schedulePollTick;
+    private pollTick;
+    private pollOnce;
+    /**
+     * Clean up timers on shutdown.
+     */
+    destroy(): void;
+}
+export {};

package/dist/auth/pairing-manager.js

@@ -0,0 +1,213 @@
+import nacl from 'tweetnacl';
+import axios from 'axios';
+import qrcode from 'qrcode-terminal';
+import { encodeBase64, encodeBase64Url, decodeBase64, decryptBoxBundle } from './crypto.js';
+import { writeCredentials, readCredentials } from './credentials.js';
+import { logger } from '../logger.js';
+import { AuthError } from '../errors.js';
+const POLL_INTERVAL = 1000;
+const AUTH_TIMEOUT = 120_000;
+export class PairingManager {
+    config;
+    onSuccess;
+    session = null;
+    state = 'idle';
+    pollTimerId = null;
+    pollDeadline = 0;
+    isRequestInFlight = false;
+    pairingComplete = false;
+    pendingCredentials = null;
+    destroyed = false;
+    initiatePromise = null;
+    constructor(config, onSuccess) {
+        this.config = config;
+        this.onSuccess = onSuccess;
+    }
+    get currentState() { return this.state; }
+    get hasSession() { return this.session !== null; }
+    /**
+     * Initiate pairing: generate keypair, POST to relay, generate QR, start polling.
+     * If already initiated, restarts the polling timer and returns cached QR.
+     */
+    async initiate() {
+        if (this.state === 'success') {
+            return { qrAscii: '', webUrl: '' }; // Already authenticated
+        }
+        // Coalesce concurrent calls
+        if (this.initiatePromise) {
+            return this.initiatePromise;
+        }
+        // Generate session if we don't have one
+        if (!this.session) {
+            this.initiatePromise = this._doInitiate();
+            try {
+                return await this.initiatePromise;
+            }
+            finally {
+                this.initiatePromise = null;
+            }
+        }
+        // Session already exists, restart polling
+        this.startPolling();
+        return { qrAscii: this.session.qrAscii, webUrl: this.session.webUrl };
+    }
+    async _doInitiate() {
+        const seed = nacl.randomBytes(32);
+        const keypair = nacl.box.keyPair.fromSecretKey(seed);
+        const publicKeyBase64 = encodeBase64(keypair.publicKey);
+        const publicKeyBase64Url = encodeBase64Url(keypair.publicKey);
+        // POST to relay
+        try {
+            await axios.post(`${this.config.serverUrl}/v1/auth/account/request`, {
+                publicKey: publicKeyBase64,
+            });
+        }
+        catch (err) {
+            if (axios.isAxiosError(err) && err.response) {
+                throw new AuthError(`Failed to initiate pairing: server returned ${err.response.status}`);
+            }
+            throw new AuthError('Failed to initiate pairing: network error');
+        }
+        // Generate ASCII QR code with timeout
+        const qrData = `happy:///account?${publicKeyBase64Url}`;
+        const qrPromise = new Promise((resolve) => {
+            qrcode.generate(qrData, { small: true }, (code) => {
+                resolve(code);
+            });
+        });
+        const timeoutPromise = new Promise((_, reject) => {
+            setTimeout(() => reject(new AuthError('QR code generation timed out')), 5000);
+        });
+        const qrAscii = await Promise.race([qrPromise, timeoutPromise]);
+        const webUrl = `https://app.happy.engineering/account/connect#key=${publicKeyBase64Url}`;
+        this.session = { keypair, publicKeyBase64, publicKeyBase64Url, qrAscii, webUrl };
+        this.startPolling();
+        return { qrAscii: this.session.qrAscii, webUrl: this.session.webUrl };
+    }
+    /**
+     * Start background polling. Fire-and-forget.
+     * If already polling, restarts the deadline timer.
+     */
+    startPolling() {
+        if (this.destroyed)
+            return;
+        // Clear existing timer
+        if (this.pollTimerId !== null) {
+            clearTimeout(this.pollTimerId);
+            this.pollTimerId = null;
+        }
+        this.state = 'polling';
+        this.pollDeadline = Date.now() + AUTH_TIMEOUT;
+        this.schedulePollTick();
+    }
+    schedulePollTick() {
+        this.pollTimerId = setTimeout(() => {
+            this.pollTick();
+        }, POLL_INTERVAL);
+    }
+    async pollTick() {
+        if (this.destroyed)
+            return;
+        // Check deadline
+        if (Date.now() > this.pollDeadline) {
+            this.state = 'idle'; // expired but session/QR preserved
+            this.pollTimerId = null;
+            logger.debug('Pairing poll deadline expired');
+            return;
+        }
+        // Don't overlap with in-flight request — wait for next interval
+        if (this.isRequestInFlight) {
+            this.pollTimerId = setTimeout(() => this.pollTick(), POLL_INTERVAL);
+            return;
+        }
+        this.isRequestInFlight = true;
+        try {
+            const authorized = await this.pollOnce();
+            if (authorized) {
+                return; // Success handled in pollOnce
+            }
+        }
+        catch (err) {
+            logger.debug('Pairing poll error:', err.message);
+        }
+        finally {
+            this.isRequestInFlight = false;
+        }
+        // Schedule next tick if still within deadline and still polling
+        if (this.state === 'polling' && Date.now() < this.pollDeadline) {
+            this.schedulePollTick();
+        }
+    }
+    async pollOnce() {
+        if (this.destroyed)
+            return false;
+        if (!this.session)
+            return false;
+        // Bug C2 fix: If pairing already completed, only retry activation
+        if (this.pairingComplete && this.pendingCredentials) {
+            try {
+                await this.onSuccess(this.pendingCredentials);
+            }
+            catch (err) {
+                logger.error('Activation retry failed:', err.message);
+                return false;
+            }
+            this.state = 'success';
+            this.pollTimerId = null;
+            this.session = null;
+            this.pendingCredentials = null;
+            logger.info('Pairing successful via MCP tool (retry)');
+            return true;
+        }
+        const res = await axios.post(`${this.config.serverUrl}/v1/auth/account/request`, {
+            publicKey: this.session.publicKeyBase64,
+        });
+        if (res.data.state === 'authorized') {
+            // Decrypt the account secret
+            const encryptedResponse = decodeBase64(res.data.response);
+            const accountSecret = decryptBoxBundle(encryptedResponse, this.session.keypair.secretKey);
+            if (!accountSecret) {
+                throw new AuthError('Failed to decrypt pairing response');
+            }
+            // Write credentials to disk
+            writeCredentials(this.config.credentialsPath, res.data.token, accountSecret, this.config.serverUrl);
+            // Read back to get full Credentials object
+            const creds = readCredentials(this.config.credentialsPath);
+            if (!creds) {
+                throw new AuthError('Failed to read back written credentials');
+            }
+            // Mark pairing as complete BEFORE calling onSuccess
+            this.pairingComplete = true;
+            this.pendingCredentials = creds;
+            // Fire callback FIRST (this triggers tool activation)
+            // State is set to 'success' only after onSuccess completes,
+            // so a failure leaves state as 'polling' and allows retry.
+            try {
+                await this.onSuccess(creds);
+            }
+            catch (err) {
+                logger.error('Pairing succeeded but activation failed:', err.message);
+                return false;
+            }
+            this.state = 'success';
+            this.pollTimerId = null;
+            this.session = null; // Clear keypair from memory
+            this.pendingCredentials = null;
+            logger.info('Pairing successful via MCP tool');
+            return true;
+        }
+        return false;
+    }
+    /**
+     * Clean up timers on shutdown.
+     */
+    destroy() {
+        this.destroyed = true;
+        if (this.pollTimerId !== null) {
+            clearTimeout(this.pollTimerId);
+            this.pollTimerId = null;
+        }
+        this.state = 'idle'; // Bug C1 fix: prevent in-flight requests from rescheduling
+        this.session = null; // Clear keypair from memory
+    }
+}

package/dist/auth/pairing.js

@@ -20,7 +20,7 @@ export async function loadOrPairCredentials(config) {
         logger.info('Loaded existing credentials');
         return creds;
     }
-    console.error('[happy-mcp] No credentials found. Starting pairing flow...');
+    console.error('[happy-mcp-server] No credentials found. Starting pairing flow...');
     return performPairing(config);
 }
 /**
@@ -72,7 +72,7 @@ export async function performPairing(config) {
                 }
                 // 6. Persist credentials
                 writeCredentials(config.credentialsPath, res.data.token, accountSecret, config.serverUrl);
-                console.error('[happy-mcp] Paired successfully!');
+                console.error('[happy-mcp-server] Paired successfully!');
                 const creds = readCredentials(config.credentialsPath);
                 if (!creds) {
                     throw new AuthError('Failed to read back written credentials');

package/dist/auth/secret-auth.d.ts

@@ -0,0 +1,12 @@
+import type { Credentials } from './crypto.js';
+/**
+ * Authenticate from a raw account secret (32 bytes) via Ed25519 challenge-response.
+ * This is used for environment-variable-based auth in ephemeral environments.
+ *
+ * Endpoint: POST /v1/auth
+ * Body: { challenge: base64, publicKey: base64, signature: base64 }
+ * Response: { success: boolean, token: string }
+ *
+ * Returns in-memory Credentials object (does NOT write to disk).
+ */
+export declare function authenticateFromSecret(secret: Uint8Array, serverUrl: string): Promise<Credentials>;

package/dist/auth/secret-auth.js

@@ -0,0 +1,40 @@
+import axios from 'axios';
+import { authChallenge, encodeBase64, deriveContentKeyPair } from './crypto.js';
+import { logger } from '../logger.js';
+import { AuthError } from '../errors.js';
+/**
+ * Authenticate from a raw account secret (32 bytes) via Ed25519 challenge-response.
+ * This is used for environment-variable-based auth in ephemeral environments.
+ *
+ * Endpoint: POST /v1/auth
+ * Body: { challenge: base64, publicKey: base64, signature: base64 }
+ * Response: { success: boolean, token: string }
+ *
+ * Returns in-memory Credentials object (does NOT write to disk).
+ */
+export async function authenticateFromSecret(secret, serverUrl) {
+    logger.info('Authenticating via HAPPY_MCP_ACCOUNT_SECRET...');
+    const { challenge, publicKey, signature } = authChallenge(secret);
+    try {
+        const res = await axios.post(`${serverUrl}/v1/auth`, {
+            challenge: encodeBase64(challenge),
+            publicKey: encodeBase64(publicKey),
+            signature: encodeBase64(signature),
+        });
+        if (!res.data.success || !res.data.token) {
+            throw new AuthError('Secret auth failed: server returned unsuccessful response');
+        }
+        const token = res.data.token;
+        const contentKeyPair = deriveContentKeyPair(secret);
+        logger.info('Secret authentication successful');
+        return { token, secret, contentKeyPair };
+    }
+    catch (err) {
+        if (err instanceof AuthError)
+            throw err;
+        if (axios.isAxiosError(err) && err.response) {
+            throw new AuthError(`Secret auth failed: server returned ${err.response.status}`);
+        }
+        throw new AuthError('Secret auth failed: network error');
+    }
+}

package/dist/config.d.ts

@@ -7,5 +7,6 @@ export interface Config {
     logLevel: LogLevel;
     sessionCacheTtl: number;
     enableStart: boolean;
+    accountSecret: Uint8Array | null;
 }
 export declare function loadConfig(): Config;

package/dist/config.js

@@ -9,5 +9,22 @@ export function loadConfig() {
     const logLevel = (process.env.HAPPY_MCP_LOG_LEVEL ?? 'warn');
     const sessionCacheTtl = parseInt(process.env.HAPPY_MCP_SESSION_CACHE_TTL ?? '300', 10);
     const enableStart = process.env.HAPPY_MCP_ENABLE_START !== 'false';
-    return { serverUrl, computers, projectPaths, credentialsPath, logLevel, sessionCacheTtl, enableStart };
+    // Parse HAPPY_MCP_ACCOUNT_SECRET env var (non-fatal: warn and ignore if invalid)
+    const accountSecretEnv = process.env.HAPPY_MCP_ACCOUNT_SECRET;
+    let accountSecret = null;
+    if (accountSecretEnv) {
+        if (!/^[A-Za-z0-9+/]*={0,2}$/.test(accountSecretEnv)) {
+            console.error('[happy-mcp-server] WARNING: HAPPY_MCP_ACCOUNT_SECRET is not valid base64, ignoring');
+        }
+        else {
+            const decoded = Buffer.from(accountSecretEnv, 'base64');
+            if (decoded.length !== 32) {
+                console.error('[happy-mcp-server] WARNING: HAPPY_MCP_ACCOUNT_SECRET is not 32 bytes, ignoring');
+            }
+            else {
+                accountSecret = new Uint8Array(decoded);
+            }
+        }
+    }
+    return { serverUrl, computers, projectPaths, credentialsPath, logLevel, sessionCacheTtl, enableStart, accountSecret };
 }

package/dist/http.js

@@ -52,7 +52,7 @@ export async function startHttpServer(config, api, relay, sessionManager, port =
                 };
                 // Create a new McpServer instance for this session
                 const server = new McpServer({
-                    name: 'happy-mcp',
+                    name: 'happy-mcp-server',
                     version: '0.1.0',
                 });
                 // Register all tools on this server instance