happy-mcp-server 1.1.0 → 1.1.1

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

package/dist/index.js

@@ -4,12 +4,14 @@ import { loadConfig } from './config.js';
 import { setupLogger, logger } from './logger.js';
 import { performPairing } from './auth/pairing.js';
 import { readCredentials, validateFilePermissions, clearCredentials } from './auth/credentials.js';
+import { authenticateFromSecret } from './auth/secret-auth.js';
 import { decryptFromBase64 } from './auth/crypto.js';
 import { resolveSessionEncryptionCached, clearKeyCache } from './session/keys.js';
 import { SessionManager } from './session/manager.js';
 import { ApiClient } from './api/client.js';
 import { RelayClient } from './relay/client.js';
 import { createUnauthenticatedServer } from './server.js';
+import { PairingManager } from './auth/pairing-manager.js';
 import { startHttpServer } from './http.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -152,7 +154,7 @@ async function initializeAuthenticatedState(config, credentials) {
 // CLI Commands
 // ---------------------------------------------------------------------------
 function printHelp() {
-    console.error(`Usage: happy-mcp [command] [options]
+    console.error(`Usage: happy-mcp-server [command] [options]
 
 Commands:
   (no args)              Start the MCP server (stdio transport)
@@ -172,19 +174,19 @@ function parseServeFlags(argv) {
         if (argv[i] === '--port') {
             const raw = argv[i + 1];
             if (raw === undefined || raw.startsWith('-')) {
-                console.error('[happy-mcp] --port requires a port number. Example: happy-mcp serve --port 3000');
+                console.error('[happy-mcp-server] --port requires a port number. Example: happy-mcp-server serve --port 3000');
                 process.exit(1);
             }
             const parsed = Number(raw);
             if (!Number.isInteger(parsed) || parsed < 1 || parsed > 65535) {
-                console.error(`[happy-mcp] Invalid port '${raw}'. Must be an integer between 1 and 65535.`);
+                console.error(`[happy-mcp-server] Invalid port '${raw}'. Must be an integer between 1 and 65535.`);
                 process.exit(1);
             }
             port = parsed;
             i++;
         }
         else {
-            console.error(`[happy-mcp] Unknown flag '${argv[i]}'. Run \`happy-mcp help\` for help.`);
+            console.error(`[happy-mcp-server] Unknown flag '${argv[i]}'. Run \`happy-mcp-server help\` for help.`);
             process.exit(1);
         }
     }
@@ -194,9 +196,9 @@ async function runAuth() {
     const config = loadConfig();
     const creds = readCredentials(config.credentialsPath);
     if (creds) {
-        console.error('[happy-mcp] Already authenticated.');
-        console.error('  To login with a different account: happy-mcp auth login');
-        console.error('  To logout: happy-mcp auth logout');
+        console.error('[happy-mcp-server] Already authenticated.');
+        console.error('  To login with a different account: happy-mcp-server auth login');
+        console.error('  To logout: happy-mcp-server auth logout');
         process.exit(0);
     }
     await runAuthLogin();
@@ -205,7 +207,7 @@ async function runAuthLogin() {
     const config = loadConfig();
     setupLogger('info');
     await performPairing(config);
-    console.error('[happy-mcp] Authentication complete.');
+    console.error('[happy-mcp-server] Authentication complete.');
     process.exit(0);
 }
 async function runAuthLogout() {
@@ -213,12 +215,12 @@ async function runAuthLogout() {
     setupLogger(config.logLevel);
     const creds = readCredentials(config.credentialsPath);
     if (!creds) {
-        console.error('[happy-mcp] Not currently authenticated. Nothing to do.');
+        console.error('[happy-mcp-server] Not currently authenticated. Nothing to do.');
         process.exit(0);
     }
     clearCredentials(config.credentialsPath);
-    console.error('[happy-mcp] Logged out. Credentials removed.');
-    console.error('  To re-authenticate: happy-mcp auth login');
+    console.error('[happy-mcp-server] Logged out. Credentials removed.');
+    console.error('  To re-authenticate: happy-mcp-server auth login');
     process.exit(0);
 }
 // ---------------------------------------------------------------------------
@@ -227,7 +229,7 @@ async function runAuthLogout() {
 async function runServer() {
     const config = loadConfig();
     setupLogger(config.logLevel);
-    logger.info('Starting happy-mcp...');
+    logger.info('Starting happy-mcp-server...');
     const authState = {
         authenticated: false,
         activatingPromise: null,
@@ -235,33 +237,30 @@ async function runServer() {
         sessionManager: null,
     };
     let activateFn = null;
-    async function tryActivate() {
+    /**
+     * Shared activation logic: initialize authenticated state and swap in real tools.
+     * All auth paths (env var, file-based, MCP pairing) converge here.
+     */
+    async function performActivation(credentials) {
         if (authState.authenticated)
             return true;
         if (authState.activatingPromise)
             return authState.activatingPromise;
-        const creds = readCredentials(config.credentialsPath);
-        if (!creds)
-            return false;
-        try {
-            validateFilePermissions(config.credentialsPath);
-        }
-        catch (err) {
-            logger.debug('Credential file has unsafe permissions:', err.message);
-            return false;
-        }
         authState.activatingPromise = (async () => {
             try {
-                const state = await initializeAuthenticatedState(config, creds);
+                const state = await initializeAuthenticatedState(config, credentials);
+                if (!activateFn) {
+                    logger.error('activate function not ready yet');
+                    return false;
+                }
+                activateFn(state.api, state.relay, state.sessionManager);
                 authState.relay = state.relay;
                 authState.sessionManager = state.sessionManager;
-                activateFn(state.api, state.relay, state.sessionManager);
                 authState.authenticated = true;
-                logger.info('Lazy authentication complete -- tools are now active');
                 return true;
             }
             catch (err) {
-                logger.debug('Lazy auth failed:', err.message);
+                logger.debug('Activation failed:', err.message);
                 return false;
             }
             finally {
@@ -270,31 +269,78 @@ async function runServer() {
         })();
         return authState.activatingPromise;
     }
-    const { server, activate } = createUnauthenticatedServer(config, tryActivate);
+    async function tryActivate() {
+        if (authState.authenticated)
+            return true;
+        if (authState.activatingPromise)
+            return authState.activatingPromise;
+        const creds = readCredentials(config.credentialsPath);
+        if (!creds)
+            return false;
+        try {
+            validateFilePermissions(config.credentialsPath);
+        }
+        catch (err) {
+            logger.debug('Credential file has unsafe permissions:', err.message);
+            return false;
+        }
+        const result = await performActivation(creds);
+        if (result)
+            logger.info('Lazy authentication complete -- tools are now active');
+        return result;
+    }
+    // Create PairingManager for in-process QR pairing
+    const pairingManager = new PairingManager(config, async (credentials) => {
+        const result = await performActivation(credentials);
+        if (result) {
+            logger.info('MCP-based authentication complete — tools are now active');
+        }
+        else {
+            throw new Error('Activation failed after successful pairing');
+        }
+    });
+    const { server, activate } = createUnauthenticatedServer(config, tryActivate, pairingManager);
     activateFn = activate;
     // Connect stdio transport FIRST (Issue 1: prevent blocking)
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logger.info(`MCP server started — credentials path: ${config.credentialsPath}`);
-    // Then initialize auth state via tryActivate() only (consolidate startup path)
-    const initialCreds = readCredentials(config.credentialsPath);
-    if (initialCreds) {
+    // Priority 1: HAPPY_MCP_ACCOUNT_SECRET env var
+    if (config.accountSecret) {
         try {
-            validateFilePermissions(config.credentialsPath);
-            logger.info('Credentials found at startup, initializing...');
-            await tryActivate();
+            const creds = await authenticateFromSecret(config.accountSecret, config.serverUrl);
+            await performActivation(creds);
+            if (authState.authenticated) {
+                logger.info('Authenticated via HAPPY_MCP_ACCOUNT_SECRET');
+            }
         }
         catch (err) {
-            logger.debug('Failed to initialize with existing credentials:', err.message);
+            logger.warn('HAPPY_MCP_ACCOUNT_SECRET auth failed:', err.message);
+            // Fall through to file-based / QR auth
         }
     }
-    else {
-        logger.debug('No credentials found. Tools will attempt auth on each call.');
-        logger.debug('Run `happy-mcp auth` to authenticate.');
+    // Priority 2: Existing credentials file
+    if (!authState.authenticated) {
+        const initialCreds = readCredentials(config.credentialsPath);
+        if (initialCreds) {
+            try {
+                validateFilePermissions(config.credentialsPath);
+                logger.info('Credentials found at startup, initializing...');
+                await tryActivate();
+            }
+            catch (err) {
+                logger.debug('Failed to initialize with existing credentials:', err.message);
+            }
+        }
+        else {
+            logger.debug('No credentials found. Tools will attempt auth on each call.');
+            logger.debug('Run `happy-mcp-server auth` to authenticate.');
+        }
     }
     logger.info(`MCP server started (${authState.authenticated ? 'authenticated' : 'unauthenticated'} mode)`);
     const shutdown = async () => {
         logger.info('Shutting down...');
+        pairingManager.destroy();
         authState.relay?.disconnect();
         authState.sessionManager?.destroy();
         clearKeyCache();
@@ -318,19 +364,35 @@ async function runServer() {
 async function runHttpServer(port) {
     const config = loadConfig();
     setupLogger(config.logLevel);
-    const creds = readCredentials(config.credentialsPath);
-    if (!creds) {
-        console.error('[happy-mcp] No credentials found. Run `happy-mcp auth` first.');
-        process.exit(1);
+    // Priority 1: HAPPY_MCP_ACCOUNT_SECRET env var
+    let creds = null;
+    if (config.accountSecret) {
+        try {
+            creds = await authenticateFromSecret(config.accountSecret, config.serverUrl);
+            logger.info('HTTP server authenticated via HAPPY_MCP_ACCOUNT_SECRET');
+        }
+        catch (err) {
+            logger.warn('HAPPY_MCP_ACCOUNT_SECRET auth failed:', err.message);
+        }
     }
-    try {
-        validateFilePermissions(config.credentialsPath);
+    // Priority 2: Credentials file
+    if (!creds) {
+        creds = readCredentials(config.credentialsPath);
+        if (creds) {
+            try {
+                validateFilePermissions(config.credentialsPath);
+            }
+            catch (err) {
+                console.error('[happy-mcp-server] Credential file has unsafe permissions:', err.message);
+                process.exit(1);
+            }
+        }
     }
-    catch (err) {
-        console.error('[happy-mcp] Credential file has unsafe permissions:', err.message);
+    if (!creds) {
+        console.error('[happy-mcp-server] No credentials found. Run `happy-mcp-server auth` or set HAPPY_MCP_ACCOUNT_SECRET.');
         process.exit(1);
     }
-    logger.info('Starting happy-mcp HTTP server...');
+    logger.info('Starting happy-mcp-server HTTP server...');
     const state = await initializeAuthenticatedState(config, creds);
     let result;
     try {
@@ -339,17 +401,17 @@ async function runHttpServer(port) {
     catch (error) {
         const err = error;
         if (err.code === 'EADDRINUSE') {
-            console.error(`[happy-mcp] Port ${port} is already in use.`);
+            console.error(`[happy-mcp-server] Port ${port} is already in use.`);
         }
         else if (err.code === 'EACCES') {
-            console.error(`[happy-mcp] Permission denied binding to port ${port}. Try a port above 1023.`);
+            console.error(`[happy-mcp-server] Permission denied binding to port ${port}. Try a port above 1023.`);
         }
         else {
-            console.error(`[happy-mcp] Failed to start HTTP server: ${err.message ?? err}`);
+            console.error(`[happy-mcp-server] Failed to start HTTP server: ${err.message ?? err}`);
         }
         process.exit(1);
     }
-    console.error(`[happy-mcp] HTTP server listening on http://127.0.0.1:${result.port}/mcp`);
+    console.error(`[happy-mcp-server] HTTP server listening on http://127.0.0.1:${result.port}/mcp`);
     const shutdown = async () => {
         logger.info('Shutting down HTTP server...');
         await result.close();
@@ -367,14 +429,14 @@ async function runHttpServer(port) {
 const command = process.argv[2];
 if (!command) {
     runServer().catch((err) => {
-        console.error('[happy-mcp] Fatal:', err.message ?? err);
+        console.error('[happy-mcp-server] Fatal:', err.message ?? err);
         process.exit(1);
     });
 }
 else if (command === 'serve') {
     const flags = parseServeFlags(process.argv.slice(3));
     runHttpServer(flags.port).catch((err) => {
-        console.error('[happy-mcp] Fatal:', err.message ?? err);
+        console.error('[happy-mcp-server] Fatal:', err.message ?? err);
         process.exit(1);
     });
 }
@@ -382,24 +444,24 @@ else if (command === 'auth') {
     const subcommand = process.argv[3];
     if (!subcommand) {
         runAuth().catch((err) => {
-            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            console.error('[happy-mcp-server] Fatal:', err.message ?? err);
             process.exit(1);
         });
     }
     else if (subcommand === 'login') {
         runAuthLogin().catch((err) => {
-            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            console.error('[happy-mcp-server] Fatal:', err.message ?? err);
             process.exit(1);
         });
     }
     else if (subcommand === 'logout') {
         runAuthLogout().catch((err) => {
-            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            console.error('[happy-mcp-server] Fatal:', err.message ?? err);
             process.exit(1);
         });
     }
     else {
-        console.error(`[happy-mcp] Unknown auth command '${subcommand}'. Run \`happy-mcp help\` for help.`);
+        console.error(`[happy-mcp-server] Unknown auth command '${subcommand}'. Run \`happy-mcp-server help\` for help.`);
         process.exit(1);
     }
 }
@@ -408,6 +470,6 @@ else if (command === 'help') {
     process.exit(0);
 }
 else {
-    console.error(`[happy-mcp] Unknown command '${command}'. Run \`happy-mcp help\` for help.`);
+    console.error(`[happy-mcp-server] Unknown command '${command}'. Run \`happy-mcp-server help\` for help.`);
     process.exit(1);
 }

package/dist/logger.js

@@ -10,7 +10,7 @@ export function setupLogger(level) {
 }
 function log(level, ...args) {
     if (LEVELS[level] >= currentLevel) {
-        const prefix = `[happy-mcp] [${level.toUpperCase()}]`;
+        const prefix = `[happy-mcp-server] [${level.toUpperCase()}]`;
         console.error(prefix, ...args);
     }
 }

package/dist/server.d.ts

@@ -3,6 +3,7 @@ import type { ApiClient } from './api/client.js';
 import type { RelayClient } from './relay/client.js';
 import type { SessionManager } from './session/manager.js';
 import type { Config } from './config.js';
+import type { PairingManager } from './auth/pairing-manager.js';
 /**
  * Register all real tool handlers on an McpServer instance.
  * Used by both stdio (via activate()) and HTTP (directly).
@@ -18,4 +19,4 @@ export interface UnauthenticatedServer {
  * The callback should attempt authentication and return true on success.
  * Call activate() to swap in real tool handlers.
  */
-export declare function createUnauthenticatedServer(config: Config, onToolCallWhileUnauthenticated: () => Promise<boolean>): UnauthenticatedServer;
+export declare function createUnauthenticatedServer(config: Config, onToolCallWhileUnauthenticated: () => Promise<boolean>, pairingManager?: PairingManager): UnauthenticatedServer;

package/dist/server.js

@@ -13,7 +13,7 @@ const AUTH_ERROR = {
     isError: true,
     content: [{
             type: 'text',
-            text: 'Not authenticated. User must run `happy-mcp auth` in their terminal to authenticate before this tool is available. Have the user run this command and then try again.',
+            text: 'Not authenticated. Call the `authentication_status` tool to begin authentication.',
         }],
 };
 const AUTH_RETRY = {
@@ -57,15 +57,16 @@ export function registerAllTools(server, config, api, relay, sessionManager) {
  * The callback should attempt authentication and return true on success.
  * Call activate() to swap in real tool handlers.
  */
-export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticated) {
+export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticated, pairingManager) {
     const server = new McpServer({
-        name: 'happy-mcp',
+        name: 'happy-mcp-server',
         version: '0.1.0',
     });
     let stubRegistrations = [];
+    let activated = false;
     const stubHandler = async () => {
-        const activated = await onToolCallWhileUnauthenticated();
-        if (activated) {
+        const didActivate = await onToolCallWhileUnauthenticated();
+        if (didActivate) {
             return AUTH_RETRY;
         }
         return AUTH_ERROR;
@@ -81,10 +82,56 @@ export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticat
     }
     // Start with stubs
     registerStubs();
+    // Register authentication_status tool OUTSIDE of stubRegistrations
+    // so it is NOT removed by activate()
+    if (pairingManager) {
+        server.tool('authentication_status', 'Check authentication status. If not authenticated, returns a QR code to scan with the Happy mobile app. Display the QR code to the user. Background polling will automatically detect when authentication completes.', {}, async () => {
+            if (activated || pairingManager.currentState === 'success') {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: 'Authenticated. All tools are active.',
+                        }],
+                };
+            }
+            try {
+                const { qrAscii, webUrl } = await pairingManager.initiate();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: qrAscii,
+                        },
+                        {
+                            type: 'text',
+                            text: [
+                                'Scan the QR code above with the Happy mobile app to authenticate.',
+                                '',
+                                `Or visit: ${webUrl}`,
+                                '',
+                                'Authentication will complete automatically once scanned.',
+                                'You can then retry your previous request.',
+                            ].join('\n'),
+                        },
+                    ],
+                };
+            }
+            catch (err) {
+                return {
+                    isError: true,
+                    content: [{
+                            type: 'text',
+                            text: `Authentication failed: ${err.message}`,
+                        }],
+                };
+            }
+        });
+    }
     return {
         server,
         activate(api, relay, sessionManager) {
-            // Remove all stubs synchronously
+            activated = true;
+            // Remove all stubs synchronously (authentication_status is NOT in this array)
             for (const stub of stubRegistrations) {
                 stub.remove();
             }

package/dist/tools/answer_question.js

@@ -45,7 +45,7 @@ export function registerAnswerQuestion(server, api, relay, sessionManager) {
             const content = {
                 role: 'user',
                 content: { type: 'text', text: answerText },
-                meta: { sentFrom: 'happy-mcp' },
+                meta: { sentFrom: 'happy-mcp-server' },
             };
             const encrypted = encryptToBase64(session.encryption, content);
             await api.sendMessages(sessionId, [{ content: encrypted, localId: randomUUID() }]);

package/dist/tools/send_message.js

@@ -31,7 +31,7 @@ export function registerSendMessage(server, relay, sessionManager) {
                 role: 'user',
                 content: { type: 'text', text: message },
                 meta: {
-                    sentFrom: 'happy-mcp',
+                    sentFrom: 'happy-mcp-server',
                     ...(meta?.permissionMode ? { permissionMode: meta.permissionMode } : {}),
                     ...(meta?.allowedTools ? { allowedTools: meta.allowedTools } : {}),
                     ...(meta?.disallowedTools ? { disallowedTools: meta.disallowedTools } : {}),

package/dist/tools/watch_session.js

@@ -1,8 +1,8 @@
 import { z } from 'zod';
 const DEFAULT_TIMEOUT_SECONDS = 300; // 5 minutes
-const MAX_WAIT_MS = 30_000; // 30s, safely under 60s MCP timeout
+const MAX_WAIT_MS = 300_000; // 5 min max wait
 export function registerWatchSession(server, relay, sessionManager) {
-    return server.tool('watch_session', 'Watch one or more sessions for state changes. Returns immediately if any session is idle or has pending permissions. Otherwise waits up to 30 seconds for a state change. If sessions are still active, returns current status -- call again to continue watching.', {
+    return server.tool('watch_session', 'Watch one or more sessions for state changes. Returns immediately if any session is idle or has pending permissions. Otherwise waits up to 5 minutes for a state change. If sessions are still active, returns current status -- call again to continue watching.', {
         sessionIds: z.array(z.string()).describe('One or more session IDs to watch'),
         timeoutSeconds: z.number().optional().default(DEFAULT_TIMEOUT_SECONDS).describe('Max wait time in seconds (default 300)'),
     }, async ({ sessionIds, timeoutSeconds }, extra) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "happy-mcp-server",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "MCP server for observing and controlling Happy Coder sessions",
   "author": {
     "name": "Jared Spencer",
@@ -31,7 +31,7 @@
   "type": "module",
   "main": "dist/index.js",
   "bin": {
-    "happy-mcp": "dist/index.js"
+    "happy-mcp-server": "dist/index.js"
   },
   "scripts": {
     "build": "tsc && chmod +x dist/index.js",