happy-mcp-server 0.1.1 → 0.3.0

package/dist/http.d.ts

@@ -0,0 +1,14 @@
+import type { Config } from './config.js';
+import type { ApiClient } from './api/client.js';
+import type { RelayClient } from './relay/client.js';
+import type { SessionManager } from './session/manager.js';
+export interface HttpServerHandle {
+    port: number;
+    close: () => Promise<void>;
+}
+/**
+ * Start an HTTP server for MCP over HTTP transport.
+ * Creates a new McpServer instance per client session.
+ * All sessions share the same relay/sessionManager/api singletons.
+ */
+export declare function startHttpServer(config: Config, api: ApiClient, relay: RelayClient, sessionManager: SessionManager, port?: number): Promise<HttpServerHandle>;

package/dist/http.js

@@ -0,0 +1,180 @@
+import { randomUUID } from 'node:crypto';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { createMcpExpressApp } from '@modelcontextprotocol/sdk/server/express.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { registerAllTools } from './server.js';
+import { logger } from './logger.js';
+/**
+ * Start an HTTP server for MCP over HTTP transport.
+ * Creates a new McpServer instance per client session.
+ * All sessions share the same relay/sessionManager/api singletons.
+ */
+export async function startHttpServer(config, api, relay, sessionManager, port = 0) {
+    const app = createMcpExpressApp();
+    const transports = new Map();
+    // POST /mcp - handle initialization and subsequent requests
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    app.post('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId) {
+            logger.debug(`Received MCP request for session: ${sessionId}`);
+        }
+        try {
+            let transportInfo;
+            if (sessionId && transports.has(sessionId)) {
+                // Reuse existing transport for this session
+                transportInfo = transports.get(sessionId);
+            }
+            else if (!sessionId && isInitializeRequest(req.body)) {
+                // New initialization request - create new transport + server
+                logger.debug('New initialization request received');
+                const transport = new StreamableHTTPServerTransport({
+                    sessionIdGenerator: () => randomUUID(),
+                    onsessioninitialized: (sid) => {
+                        logger.debug(`Session initialized with ID: ${sid}`);
+                        transports.set(sid, transportInfo);
+                    },
+                });
+                // Set up cleanup handler
+                transport.onclose = () => {
+                    const sid = transport.sessionId;
+                    if (sid && transports.has(sid)) {
+                        logger.debug(`Transport closed for session ${sid}, removing from map`);
+                        const info = transports.get(sid);
+                        if (info) {
+                            info.server.close().catch((err) => {
+                                logger.debug(`Error closing server for session ${sid}:`, err);
+                            });
+                        }
+                        transports.delete(sid);
+                    }
+                };
+                // Create a new McpServer instance for this session
+                const server = new McpServer({
+                    name: 'happy-mcp',
+                    version: '0.1.0',
+                });
+                // Register all tools on this server instance
+                registerAllTools(server, config, api, relay, sessionManager);
+                // Store the transport info (before connect so onsessioninitialized can access it)
+                transportInfo = { transport, server };
+                // Connect the transport to the server
+                await server.connect(transport);
+                // Handle the initialization request
+                await transport.handleRequest(req, res, req.body);
+                return;
+            }
+            else {
+                // Invalid request - no session ID or not initialization request
+                res.status(400).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32000,
+                        message: 'Bad Request: No valid session ID provided',
+                    },
+                    id: null,
+                });
+                return;
+            }
+            // Handle request with existing transport
+            await transportInfo.transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            logger.debug('Error handling MCP POST request:', error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32603,
+                        message: 'Internal server error',
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    // GET /mcp - SSE stream for notifications
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    app.get('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!sessionId || !transports.has(sessionId)) {
+            res.status(400).send('Invalid or missing session ID');
+            return;
+        }
+        const lastEventId = req.headers['last-event-id'];
+        if (lastEventId) {
+            logger.debug(`Client reconnecting with Last-Event-ID: ${lastEventId}`);
+        }
+        else {
+            logger.debug(`Establishing new SSE stream for session ${sessionId}`);
+        }
+        const transportInfo = transports.get(sessionId);
+        await transportInfo.transport.handleRequest(req, res);
+    });
+    // DELETE /mcp - session termination
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    app.delete('/mcp', async (req, res) => {
+        const sessionId = req.headers['mcp-session-id'];
+        if (!sessionId || !transports.has(sessionId)) {
+            res.status(400).send('Invalid or missing session ID');
+            return;
+        }
+        logger.debug(`Received session termination request for session ${sessionId}`);
+        try {
+            const transportInfo = transports.get(sessionId);
+            await transportInfo.transport.handleRequest(req, res);
+        }
+        catch (error) {
+            logger.debug('Error handling session termination:', error);
+            if (!res.headersSent) {
+                res.status(500).send('Error processing session termination');
+            }
+        }
+    });
+    // Start listening on auto-assigned port
+    const httpServer = await new Promise((resolve, reject) => {
+        const server = app.listen(port, '127.0.0.1', (error) => {
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve(server);
+            }
+        });
+        server.on('error', reject);
+    });
+    const addr = httpServer.address();
+    if (!addr || typeof addr === 'string') {
+        throw new Error('Failed to get server address');
+    }
+    const actualPort = addr.port;
+    logger.debug(`HTTP server listening on http://127.0.0.1:${actualPort}/mcp`);
+    // Cleanup function
+    const close = async () => {
+        logger.debug('Closing HTTP server...');
+        // Close all active transports and servers
+        for (const [sessionId, info] of transports.entries()) {
+            try {
+                logger.debug(`Closing transport for session ${sessionId}`);
+                await info.transport.close();
+                await info.server.close();
+            }
+            catch (error) {
+                logger.debug(`Error closing session ${sessionId}:`, error);
+            }
+        }
+        transports.clear();
+        // Close HTTP server
+        await new Promise((resolve, reject) => {
+            httpServer.close((err) => {
+                if (err)
+                    reject(err);
+                else
+                    resolve();
+            });
+        });
+        logger.debug('HTTP server closed');
+    };
+    return { port: actualPort, close };
+}

package/dist/index.js

@@ -10,6 +10,7 @@ import { SessionManager } from './session/manager.js';
 import { ApiClient } from './api/client.js';
 import { RelayClient } from './relay/client.js';
 import { createUnauthenticatedServer } from './server.js';
+import { startHttpServer } from './http.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -151,16 +152,44 @@ async function initializeAuthenticatedState(config, credentials) {
 // CLI Commands
 // ---------------------------------------------------------------------------
 function printHelp() {
-    console.error(`Usage: happy-mcp [command]
+    console.error(`Usage: happy-mcp [command] [options]
 
 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
+  (no args)              Start the MCP server (stdio transport)
+  serve [--port <port>]  Start the MCP server (HTTP 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
+
+Options for serve:
+  --port <port>          Bind to a specific port (default: auto-assign)
 `);
 }
+function parseServeFlags(argv) {
+    let port;
+    for (let i = 0; i < argv.length; i++) {
+        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');
+                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.`);
+                process.exit(1);
+            }
+            port = parsed;
+            i++;
+        }
+        else {
+            console.error(`[happy-mcp] Unknown flag '${argv[i]}'. Run \`happy-mcp help\` for help.`);
+            process.exit(1);
+        }
+    }
+    return { port };
+}
 async function runAuth() {
     const config = loadConfig();
     const creds = readCredentials(config.credentialsPath);
@@ -246,7 +275,7 @@ async function runServer() {
     // Connect stdio transport FIRST (Issue 1: prevent blocking)
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    logger.info('MCP server stdio transport connected');
+    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) {
@@ -284,6 +313,55 @@ async function runServer() {
     });
 }
 // ---------------------------------------------------------------------------
+// HTTP Server
+// ---------------------------------------------------------------------------
+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);
+    }
+    try {
+        validateFilePermissions(config.credentialsPath);
+    }
+    catch (err) {
+        console.error('[happy-mcp] Credential file has unsafe permissions:', err.message);
+        process.exit(1);
+    }
+    logger.info('Starting happy-mcp HTTP server...');
+    const state = await initializeAuthenticatedState(config, creds);
+    let result;
+    try {
+        result = await startHttpServer(config, state.api, state.relay, state.sessionManager, port ?? 0);
+    }
+    catch (error) {
+        const err = error;
+        if (err.code === 'EADDRINUSE') {
+            console.error(`[happy-mcp] 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.`);
+        }
+        else {
+            console.error(`[happy-mcp] 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`);
+    const shutdown = async () => {
+        logger.info('Shutting down HTTP server...');
+        await result.close();
+        state.relay.disconnect();
+        state.sessionManager.destroy();
+        clearKeyCache();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+}
+// ---------------------------------------------------------------------------
 // CLI Router
 // ---------------------------------------------------------------------------
 const command = process.argv[2];
@@ -293,6 +371,13 @@ if (!command) {
         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);
+        process.exit(1);
+    });
+}
 else if (command === 'auth') {
     const subcommand = process.argv[3];
     if (!subcommand) {

package/dist/server.d.ts

@@ -3,6 +3,11 @@ 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';
+/**
+ * Register all real tool handlers on an McpServer instance.
+ * Used by both stdio (via activate()) and HTTP (directly).
+ */
+export declare function registerAllTools(server: McpServer, config: Config, api: ApiClient, relay: RelayClient, sessionManager: SessionManager): void;
 export interface UnauthenticatedServer {
     server: McpServer;
     activate: (api: ApiClient, relay: RelayClient, sessionManager: SessionManager) => void;

package/dist/server.js

@@ -8,6 +8,7 @@ import { registerApprovePermission } from './tools/approve_permission.js';
 import { registerDenyPermission } from './tools/deny_permission.js';
 import { registerAnswerQuestion } from './tools/answer_question.js';
 import { registerStartSession } from './tools/start_session.js';
+import { registerInterruptSession } from './tools/interrupt_session.js';
 const AUTH_ERROR = {
     isError: true,
     content: [{
@@ -29,8 +30,27 @@ const TOOL_STUBS = [
     ['send_message', 'Send a message to a session.'],
     ['approve_permission', 'Approve a pending permission request.'],
     ['deny_permission', 'Deny a pending permission request.'],
+    ['interrupt_session', 'Interrupt a running session to stop its current activity.'],
     ['answer_question', 'Answer a question from a session.'],
 ];
+/**
+ * Register all real tool handlers on an McpServer instance.
+ * Used by both stdio (via activate()) and HTTP (directly).
+ */
+export function registerAllTools(server, config, api, relay, sessionManager) {
+    registerListComputers(server, sessionManager, config);
+    registerListSessions(server, sessionManager, config);
+    registerGetSession(server, api, sessionManager);
+    registerWatchSession(server, relay, sessionManager);
+    registerSendMessage(server, api, sessionManager);
+    registerApprovePermission(server, relay, sessionManager);
+    registerDenyPermission(server, relay, sessionManager);
+    registerInterruptSession(server, relay, sessionManager);
+    registerAnswerQuestion(server, api, relay, sessionManager);
+    if (config.enableStart) {
+        registerStartSession(server, api, relay, sessionManager, config);
+    }
+}
 /**
  * Create an MCP server in unauthenticated mode.
  * All tools are registered as stubs that call the provided callback when invoked.
@@ -59,19 +79,6 @@ export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticat
             stubRegistrations.push(server.tool('start_session', 'Start a new Happy Coder session.', {}, stubHandler));
         }
     }
-    function registerReal(api, relay, sessionManager) {
-        registerListComputers(server, sessionManager, config);
-        registerListSessions(server, sessionManager, config);
-        registerGetSession(server, api, sessionManager);
-        registerWatchSession(server, relay, sessionManager);
-        registerSendMessage(server, api, sessionManager);
-        registerApprovePermission(server, relay, sessionManager);
-        registerDenyPermission(server, relay, sessionManager);
-        registerAnswerQuestion(server, api, relay, sessionManager);
-        if (config.enableStart) {
-            registerStartSession(server, api, relay, sessionManager);
-        }
-    }
     // Start with stubs
     registerStubs();
     return {
@@ -83,7 +90,7 @@ export function createUnauthenticatedServer(config, onToolCallWhileUnauthenticat
             }
             stubRegistrations = [];
             // Register real tools
-            registerReal(api, relay, sessionManager);
+            registerAllTools(server, config, api, relay, sessionManager);
         },
     };
 }

package/dist/tools/interrupt_session.d.ts

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

package/dist/tools/interrupt_session.js

@@ -0,0 +1,31 @@
+import { z } from 'zod';
+import { logger } from '../logger.js';
+export function registerInterruptSession(server, relay, sessionManager) {
+    return server.tool('interrupt_session', 'Interrupt a running Claude Code session to stop its current activity. This sends an abort signal equivalent to pressing Escape — the session stays alive and can accept new messages afterward. Use this when a session is actively generating output and you need it to stop.', {
+        sessionId: z.string().describe('The session ID to interrupt'),
+    }, async ({ sessionId }) => {
+        try {
+            if (!relay.connected) {
+                const msg = relay.state === 'connecting'
+                    ? 'Relay is still connecting. Please try again in a few seconds.'
+                    : 'Relay is disconnected.';
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: relay.state === 'connecting' ? 'RelayConnecting' : 'RelayDisconnected',
+                                message: msg,
+                            }) }] };
+            }
+            const session = sessionManager.get(sessionId);
+            if (!session) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'SessionNotFound', message: `Session ${sessionId} not found` }) }] };
+            }
+            await relay.sessionRpc(sessionId, 'abort', {
+                reason: "The user doesn't want to proceed with this tool use. The tool use was rejected (eg. if it was a file edit, the new_string was NOT written to the file). STOP what you are doing and wait for the user to tell you how to proceed.",
+            });
+            logger.info(`[audit] Session INTERRUPTED: session=${sessionId}`);
+            return { content: [{ type: 'text', text: JSON.stringify({ success: true, sessionId, message: 'Interrupt signal sent. The session will stop its current activity.' }, null, 2) }] };
+        }
+        catch (err) {
+            return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'InterruptFailed', message: err.message }) }] };
+        }
+    });
+}

package/dist/tools/start_session.d.ts

@@ -2,4 +2,5 @@ import type { McpServer, RegisteredTool } from '@modelcontextprotocol/sdk/server
 import type { ApiClient } from '../api/client.js';
 import type { RelayClient } from '../relay/client.js';
 import type { SessionManager } from '../session/manager.js';
-export declare function registerStartSession(server: McpServer, _api: ApiClient, relay: RelayClient, sessionManager: SessionManager): RegisteredTool;
+import type { Config } from '../config.js';
+export declare function registerStartSession(server: McpServer, _api: ApiClient, relay: RelayClient, sessionManager: SessionManager, config: Config): RegisteredTool;

package/dist/tools/start_session.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
 const PERMISSION_MODES = ['default', 'acceptEdits', 'bypassPermissions', 'plan', 'read-only', 'safe-yolo', 'yolo'];
-export function registerStartSession(server, _api, relay, sessionManager) {
+export function registerStartSession(server, _api, relay, sessionManager, config) {
     return server.tool('start_session', 'Start a new Happy Coder session on a remote machine. Requires the machine to be online. Use list_computers to find available machines.', {
         computer: z.string().describe('The machine ID (from list_computers)'),
-        projectPath: z.string().describe('The working directory for the new session'),
+        projectPath: z.string().describe(config.projectPaths.includes('*')
+            ? 'The working directory for the new session'
+            : `The working directory for the new session. Allowed paths: ${config.projectPaths.join(', ')}`),
         initialMessage: z.string().optional().describe('Initial message to send after session starts'),
         permissionMode: z.enum(PERMISSION_MODES).optional().describe('Permission mode for the session'),
         agent: z.enum(['claude', 'codex', 'gemini']).optional().default('claude').describe('The AI agent to use'),
@@ -18,12 +20,31 @@ export function registerStartSession(server, _api, relay, sessionManager) {
                                 message: msg,
                             }) }] };
             }
-            const machine = sessionManager.getMachine(computer);
-            if (!machine) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'MachineNotFound', message: `Machine ${computer} not found` }) }] };
+            // Build the list of allowed online computers (same filter as list_computers)
+            const allowedOnline = sessionManager.getAllMachines().filter(m => {
+                if (!m.active)
+                    return false;
+                const host = (m.metadata?.host ?? '').toLowerCase();
+                return config.computers.some(c => c === '*' || c.toLowerCase() === host);
+            });
+            const match = allowedOnline.find(m => m.machineId === computer);
+            if (!match) {
+                const available = allowedOnline.map(m => ({
+                    machineId: m.machineId,
+                    hostname: m.metadata?.host ?? 'unknown',
+                }));
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: 'ComputerNotAvailable',
+                                message: `Computer ${computer} is not available. Use list_computers to see available machines.`,
+                                availableComputers: available,
+                            }) }] };
             }
-            if (!machine.active) {
-                return { isError: true, content: [{ type: 'text', text: JSON.stringify({ error: 'MachineOffline', message: `Machine ${computer} is not online` }) }] };
+            if (!config.projectPaths.includes('*') && !config.projectPaths.includes(projectPath)) {
+                return { isError: true, content: [{ type: 'text', text: JSON.stringify({
+                                error: 'PathNotAllowed',
+                                message: `Project path ${projectPath} is not in the allowed project paths.`,
+                                allowedPaths: config.projectPaths,
+                            }) }] };
             }
             const result = await relay.machineRpc(computer, 'spawn-happy-session', {
                 type: 'spawn-in-directory',

package/package.json

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