happy-mcp-server 0.1.0

package/dist/index.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+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 { 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';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function sessionMatchesFilters(metadata, config) {
+    if (!metadata)
+        return true; // can't filter without metadata
+    const matchesComputer = config.computers.some(c => c === '*' || c.toLowerCase() === (metadata.host ?? '').toLowerCase());
+    const matchesPath = config.projectPaths.some(p => p === '*' || (metadata.path ?? '').startsWith(p));
+    return matchesComputer && matchesPath;
+}
+/**
+ * Build the full authenticated runtime: API client, session manager, relay.
+ * Extracted so it can be called from both initial startup and hot auth.
+ */
+async function initializeAuthenticatedState(config, credentials) {
+    const sessionManager = new SessionManager(config.sessionCacheTtl);
+    const api = new ApiClient(credentials, config);
+    // Fetch initial sessions
+    try {
+        const rawSessions = await api.listActiveSessions();
+        logger.info(`Fetched ${rawSessions.length} active sessions`);
+        for (const raw of rawSessions) {
+            try {
+                const encryption = resolveSessionEncryptionCached(raw.dataEncryptionKey, credentials);
+                const metadata = raw.metadata
+                    ? decryptFromBase64(encryption, raw.metadata)
+                    : null;
+                const agentState = raw.agentState
+                    ? decryptFromBase64(encryption, raw.agentState)
+                    : null;
+                if (!sessionMatchesFilters(metadata, config)) {
+                    logger.debug(`Skipping session ${raw.id} -- doesn't match filters`);
+                    continue;
+                }
+                sessionManager.loadSession(raw.id, encryption, metadata, raw.metadataVersion, agentState, raw.agentStateVersion, raw.active, raw.createdAt, raw.updatedAt);
+            }
+            catch (err) {
+                logger.warn(`Failed to load session ${raw.id}:`, err.message);
+            }
+        }
+        logger.info(`Loaded ${sessionManager.getAll().length} sessions into cache`);
+    }
+    catch (err) {
+        logger.error('Failed to fetch initial sessions:', err.message);
+    }
+    // Fetch machines
+    try {
+        const rawMachines = await api.listMachines();
+        logger.info(`Fetched ${rawMachines.length} machines`);
+        for (const raw of rawMachines) {
+            try {
+                const encryption = resolveSessionEncryptionCached(raw.dataEncryptionKey ?? null, credentials);
+                const metadata = raw.metadata
+                    ? decryptFromBase64(encryption, raw.metadata)
+                    : null;
+                sessionManager.loadMachine({
+                    machineId: raw.id, metadata,
+                    metadataVersion: raw.metadataVersion,
+                    daemonState: null,
+                    daemonStateVersion: raw.daemonStateVersion ?? 0,
+                    encryption, active: raw.active, activeAt: raw.activeAt,
+                });
+            }
+            catch (err) {
+                logger.warn(`Failed to load machine ${raw.id}:`, err.message);
+            }
+        }
+        logger.info(`Loaded ${sessionManager.getAllMachines().length} machines into cache`);
+    }
+    catch (err) {
+        logger.error('Failed to fetch machines:', err.message);
+    }
+    // Connect relay
+    const relay = new RelayClient(credentials, sessionManager, config);
+    try {
+        await relay.connect();
+        logger.info('Relay connected');
+    }
+    catch (err) {
+        logger.error('Failed to connect relay:', err.message);
+    }
+    // Reconnection catch-up
+    relay.on('connected', async () => {
+        try {
+            const rawSessions = await api.listActiveSessions();
+            logger.info(`Reconnect catch-up: fetched ${rawSessions.length} sessions`);
+            for (const raw of rawSessions) {
+                try {
+                    const encryption = resolveSessionEncryptionCached(raw.dataEncryptionKey, credentials);
+                    const metadata = raw.metadata
+                        ? decryptFromBase64(encryption, raw.metadata)
+                        : null;
+                    const agentState = raw.agentState
+                        ? decryptFromBase64(encryption, raw.agentState)
+                        : null;
+                    if (!sessionMatchesFilters(metadata, config))
+                        continue;
+                    sessionManager.loadSession(raw.id, encryption, metadata, raw.metadataVersion, agentState, raw.agentStateVersion, raw.active, raw.createdAt, raw.updatedAt);
+                }
+                catch (err) {
+                    logger.warn(`Catch-up: failed to load session ${raw.id}:`, err.message);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn('Reconnect catch-up failed:', err.message);
+        }
+    });
+    relay.on('disconnected', () => {
+        relay.updateToken(credentials.token);
+    });
+    return { api, relay, sessionManager };
+}
+// ---------------------------------------------------------------------------
+// CLI Commands
+// ---------------------------------------------------------------------------
+function printHelp() {
+    console.error(`Usage: happy-mcp [command]
+
+Commands:
+  (no args)      Start the MCP server (stdio transport)
+  auth           Check auth status, or pair if not authenticated
+  auth login     Run the QR pairing flow (re-auth if already paired)
+  auth logout    Remove saved credentials
+  help           Show this help message
+`);
+}
+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');
+        process.exit(0);
+    }
+    await runAuthLogin();
+}
+async function runAuthLogin() {
+    const config = loadConfig();
+    setupLogger('info');
+    await performPairing(config);
+    console.error('[happy-mcp] Authentication complete.');
+    process.exit(0);
+}
+async function runAuthLogout() {
+    const config = loadConfig();
+    setupLogger(config.logLevel);
+    const creds = readCredentials(config.credentialsPath);
+    if (!creds) {
+        console.error('[happy-mcp] 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');
+    process.exit(0);
+}
+// ---------------------------------------------------------------------------
+// MCP Server
+// ---------------------------------------------------------------------------
+async function runServer() {
+    const config = loadConfig();
+    setupLogger(config.logLevel);
+    logger.info('Starting happy-mcp...');
+    const authState = {
+        authenticated: false,
+        activatingPromise: null,
+        relay: null,
+        sessionManager: null,
+    };
+    let activateFn = null;
+    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.error('Credential file has unsafe permissions:', err.message);
+            return false;
+        }
+        authState.activatingPromise = (async () => {
+            try {
+                const state = await initializeAuthenticatedState(config, creds);
+                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.error('Lazy auth failed:', err.message);
+                return false;
+            }
+            finally {
+                authState.activatingPromise = null;
+            }
+        })();
+        return authState.activatingPromise;
+    }
+    const { server, activate } = createUnauthenticatedServer(config, tryActivate);
+    activateFn = activate;
+    // Startup optimization: check for existing credentials
+    const initialCreds = readCredentials(config.credentialsPath);
+    if (initialCreds) {
+        try {
+            validateFilePermissions(config.credentialsPath);
+            logger.info('Credentials found at startup');
+            const state = await initializeAuthenticatedState(config, initialCreds);
+            authState.relay = state.relay;
+            authState.sessionManager = state.sessionManager;
+            activate(state.api, state.relay, state.sessionManager);
+            authState.authenticated = true;
+        }
+        catch (err) {
+            logger.error('Failed to initialize with existing credentials:', err.message);
+        }
+    }
+    else {
+        logger.warn('No credentials found. Tools will attempt auth on each call.');
+        logger.warn('Run `happy-mcp auth` to authenticate.');
+    }
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info(`MCP server started on stdio (${authState.authenticated ? 'authenticated' : 'unauthenticated'} mode)`);
+    const shutdown = async () => {
+        logger.info('Shutting down...');
+        authState.relay?.disconnect();
+        authState.sessionManager?.destroy();
+        clearKeyCache();
+        await server.close();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    process.on('uncaughtException', (err) => {
+        logger.error('Uncaught exception:', err.message);
+        process.exit(1);
+    });
+    process.on('unhandledRejection', (reason) => {
+        logger.error('Unhandled rejection:', reason);
+        process.exit(1);
+    });
+}
+// ---------------------------------------------------------------------------
+// CLI Router
+// ---------------------------------------------------------------------------
+const command = process.argv[2];
+if (!command) {
+    runServer().catch((err) => {
+        console.error('[happy-mcp] Fatal:', err.message ?? err);
+        process.exit(1);
+    });
+}
+else if (command === 'auth') {
+    const subcommand = process.argv[3];
+    if (!subcommand) {
+        runAuth().catch((err) => {
+            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            process.exit(1);
+        });
+    }
+    else if (subcommand === 'login') {
+        runAuthLogin().catch((err) => {
+            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            process.exit(1);
+        });
+    }
+    else if (subcommand === 'logout') {
+        runAuthLogout().catch((err) => {
+            console.error('[happy-mcp] Fatal:', err.message ?? err);
+            process.exit(1);
+        });
+    }
+    else {
+        console.error(`[happy-mcp] Unknown auth command '${subcommand}'. Run \`happy-mcp help\` for help.`);
+        process.exit(1);
+    }
+}
+else if (command === 'help') {
+    printHelp();
+    process.exit(0);
+}
+else {
+    console.error(`[happy-mcp] Unknown command '${command}'. Run \`happy-mcp help\` for help.`);
+    process.exit(1);
+}

package/dist/logger.d.ts

@@ -0,0 +1,8 @@
+import type { LogLevel } from './config.js';
+export declare function setupLogger(level: LogLevel): void;
+export declare const logger: {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};

package/dist/logger.js

@@ -0,0 +1,22 @@
+const LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+let currentLevel = LEVELS.warn;
+export function setupLogger(level) {
+    currentLevel = LEVELS[level] ?? LEVELS.warn;
+}
+function log(level, ...args) {
+    if (LEVELS[level] >= currentLevel) {
+        const prefix = `[happy-mcp] [${level.toUpperCase()}]`;
+        console.error(prefix, ...args);
+    }
+}
+export const logger = {
+    debug: (...args) => log('debug', ...args),
+    info: (...args) => log('info', ...args),
+    warn: (...args) => log('warn', ...args),
+    error: (...args) => log('error', ...args),
+};

package/dist/relay/client.d.ts

@@ -0,0 +1,34 @@
+import { EventEmitter } from 'events';
+import type { Credentials } from '../auth/crypto.js';
+import type { SessionManager } from '../session/manager.js';
+import type { Config } from '../config.js';
+export declare class RelayClient extends EventEmitter {
+    private socket;
+    private credentials;
+    private sessionManager;
+    private config;
+    private _connected;
+    constructor(credentials: Credentials, sessionManager: SessionManager, config: Config);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    private waitForConnect;
+    private handleUpdate;
+    private handleNewMessage;
+    private handleUpdateSession;
+    private handleUpdateMachine;
+    private handleDeleteSession;
+    /**
+     * Encrypted RPC call to a session.
+     * Event: 'rpc-call' (NOT 'rpc-request' -- asymmetric names)
+     * Params are encrypted with session key.
+     * Response is encrypted with session key.
+     */
+    sessionRpc<R>(sessionId: string, method: string, params: unknown): Promise<R>;
+    /**
+     * Encrypted RPC call to a machine.
+     * Used for start_session (spawn-happy-session).
+     */
+    machineRpc<R>(machineId: string, method: string, params: unknown): Promise<R>;
+    updateToken(newToken: string): void;
+    disconnect(): void;
+}

package/dist/relay/client.js

@@ -0,0 +1,242 @@
+import { io } from 'socket.io-client';
+import { EventEmitter } from 'events';
+import { decodeBase64, decrypt, encrypt, encodeBase64, decryptFromBase64 } from '../auth/crypto.js';
+import { logger } from '../logger.js';
+import { RelayError } from '../errors.js';
+export class RelayClient extends EventEmitter {
+    socket = null;
+    credentials;
+    sessionManager;
+    config;
+    _connected = false;
+    constructor(credentials, sessionManager, config) {
+        super();
+        this.credentials = credentials;
+        this.sessionManager = sessionManager;
+        this.config = config;
+    }
+    get connected() {
+        return this._connected;
+    }
+    async connect() {
+        this.socket = io(this.config.serverUrl, {
+            path: '/v1/updates',
+            transports: ['websocket'],
+            auth: {
+                token: this.credentials.token,
+                clientType: 'user-scoped',
+            },
+            reconnection: true,
+            reconnectionAttempts: Infinity,
+            reconnectionDelay: 1000,
+            reconnectionDelayMax: 5000,
+            autoConnect: false,
+        });
+        this.socket.on('connect', () => {
+            this._connected = true;
+            logger.info('Relay connected');
+            this.emit('connected');
+        });
+        this.socket.on('disconnect', (reason) => {
+            this._connected = false;
+            logger.warn('Relay disconnected:', reason);
+            // Session cache is PRESERVED -- do NOT clear sessionManager
+            this.emit('disconnected', reason);
+        });
+        this.socket.on('connect_error', (err) => {
+            logger.error('Relay connection error:', err.message);
+        });
+        this.socket.on('update', (data) => {
+            try {
+                this.handleUpdate(data);
+            }
+            catch (err) {
+                logger.error('Error handling update:', err.message);
+            }
+        });
+        this.socket.connect();
+        await this.waitForConnect(10_000);
+    }
+    async waitForConnect(timeoutMs) {
+        if (this._connected)
+            return;
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                reject(new RelayError(`Relay connection timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.socket.once('connect', () => {
+                clearTimeout(timeout);
+                resolve();
+            });
+            this.socket.once('connect_error', (err) => {
+                clearTimeout(timeout);
+                reject(new RelayError(`Relay connection failed: ${err.message}`));
+            });
+        });
+    }
+    handleUpdate(data) {
+        const container = data;
+        const body = container?.body;
+        if (!body?.t)
+            return;
+        switch (body.t) {
+            case 'new-message':
+                this.handleNewMessage(body);
+                break;
+            case 'update-session':
+                this.handleUpdateSession(body);
+                break;
+            case 'update-machine':
+                this.handleUpdateMachine(body);
+                break;
+            case 'new-session':
+                this.emit('new_session', body);
+                break;
+            case 'delete-session':
+                this.handleDeleteSession(body);
+                break;
+            default:
+                logger.debug('Unhandled update type:', body.t);
+        }
+    }
+    handleNewMessage(body) {
+        const sessionId = body.sid;
+        if (!sessionId)
+            return;
+        const session = this.sessionManager.get(sessionId);
+        if (!session)
+            return;
+        const message = body.message;
+        if (!message?.content || message.content.t !== 'encrypted' || !message.content.c)
+            return;
+        const decrypted = decrypt(session.encryption.key, session.encryption.variant, decodeBase64(message.content.c));
+        if (decrypted === null) {
+            logger.warn(`Failed to decrypt message ${message.id} for session ${sessionId}`);
+            return;
+        }
+        this.sessionManager.applyMessage(sessionId, message.id ?? '', message.seq ?? 0, decrypted, message.createdAt ?? Date.now());
+        this.emit('message', sessionId, decrypted);
+    }
+    handleUpdateSession(body) {
+        const sessionId = body.id;
+        if (!sessionId)
+            return;
+        const session = this.sessionManager.get(sessionId);
+        if (!session)
+            return;
+        // Handle versioned metadata
+        const metadata = body.metadata;
+        if (metadata?.version != null && metadata.version > session.metadataVersion && metadata.value) {
+            const decrypted = decryptFromBase64(session.encryption, metadata.value);
+            this.sessionManager.updateMetadata(sessionId, decrypted, metadata.version);
+        }
+        // Handle versioned agentState
+        const agentState = body.agentState;
+        if (agentState?.version != null && agentState.version > session.agentStateVersion) {
+            const decrypted = agentState.value
+                ? decryptFromBase64(session.encryption, agentState.value)
+                : null;
+            this.sessionManager.updateAgentState(sessionId, decrypted, agentState.version);
+        }
+        this.emit('session_update', sessionId);
+    }
+    handleUpdateMachine(body) {
+        const machineId = body.machineId;
+        if (!machineId)
+            return;
+        const machine = this.sessionManager.getMachine(machineId);
+        if (!machine)
+            return;
+        const metadata = body.metadata;
+        if (metadata?.version != null && machine.encryption) {
+            const decrypted = metadata.value
+                ? decryptFromBase64(machine.encryption, metadata.value)
+                : null;
+            this.sessionManager.updateMachineMetadata(machineId, decrypted, metadata.version);
+        }
+        const daemonState = body.daemonState;
+        if (daemonState?.version != null && machine.encryption) {
+            const decrypted = daemonState.value
+                ? decryptFromBase64(machine.encryption, daemonState.value)
+                : null;
+            this.sessionManager.updateMachineDaemonState(machineId, decrypted, daemonState.version);
+        }
+        if (body.active !== undefined)
+            machine.active = body.active;
+        if (body.activeAt !== undefined)
+            machine.activeAt = body.activeAt;
+        this.emit('machine_update', machineId);
+    }
+    handleDeleteSession(body) {
+        const sessionId = body.id;
+        if (sessionId) {
+            this.sessionManager.remove(sessionId);
+            this.emit('session_deleted', sessionId);
+        }
+    }
+    /**
+     * Encrypted RPC call to a session.
+     * Event: 'rpc-call' (NOT 'rpc-request' -- asymmetric names)
+     * Params are encrypted with session key.
+     * Response is encrypted with session key.
+     */
+    async sessionRpc(sessionId, method, params) {
+        if (!this._connected || !this.socket) {
+            throw new RelayError('Relay not connected');
+        }
+        const session = this.sessionManager.get(sessionId);
+        if (!session) {
+            throw new RelayError(`Session ${sessionId} not found in cache`);
+        }
+        const encryptedParams = encodeBase64(encrypt(session.encryption.key, session.encryption.variant, params));
+        const result = await this.socket.emitWithAck('rpc-call', {
+            method: `${sessionId}:${method}`,
+            params: encryptedParams,
+        });
+        if (!result?.ok) {
+            throw new RelayError(`RPC ${method} failed for session ${sessionId}: ${result?.error ?? 'unknown error'}`);
+        }
+        if (result.result) {
+            return decrypt(session.encryption.key, session.encryption.variant, decodeBase64(result.result));
+        }
+        return undefined;
+    }
+    /**
+     * Encrypted RPC call to a machine.
+     * Used for start_session (spawn-happy-session).
+     */
+    async machineRpc(machineId, method, params) {
+        if (!this._connected || !this.socket) {
+            throw new RelayError('Relay not connected');
+        }
+        const machine = this.sessionManager.getMachine(machineId);
+        if (!machine?.encryption) {
+            throw new RelayError(`Machine ${machineId} not found or no encryption key`);
+        }
+        const encryptedParams = encodeBase64(encrypt(machine.encryption.key, machine.encryption.variant, params));
+        const result = await this.socket.emitWithAck('rpc-call', {
+            method: `${machineId}:${method}`,
+            params: encryptedParams,
+        });
+        if (!result?.ok) {
+            throw new RelayError(`Machine RPC ${method} failed: ${result?.error ?? 'unknown error'}`);
+        }
+        if (result.result) {
+            return decrypt(machine.encryption.key, machine.encryption.variant, decodeBase64(result.result));
+        }
+        return undefined;
+    }
+    updateToken(newToken) {
+        if (this.socket) {
+            this.socket.auth.token = newToken;
+        }
+    }
+    disconnect() {
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.disconnect();
+            this.socket = null;
+        }
+        this._connected = false;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,16 @@
+import { McpServer } 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';
+import type { Config } from './config.js';
+export interface UnauthenticatedServer {
+    server: McpServer;
+    activate: (api: ApiClient, relay: RelayClient, sessionManager: SessionManager) => void;
+}
+/**
+ * Create an MCP server in unauthenticated mode.
+ * All tools are registered as stubs that call the provided callback when invoked.
+ * 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;