happy-mcp-server 0.2.0 → 0.3.0

package/dist/http.d.ts

@@ -11,4 +11,4 @@ export interface HttpServerHandle {
  * 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): Promise<HttpServerHandle>;
+export declare function startHttpServer(config: Config, api: ApiClient, relay: RelayClient, sessionManager: SessionManager, port?: number): Promise<HttpServerHandle>;

package/dist/http.js

@@ -10,7 +10,7 @@ import { logger } from './logger.js';
  * 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) {
+export async function startHttpServer(config, api, relay, sessionManager, port = 0) {
     const app = createMcpExpressApp();
     const transports = new Map();
     // POST /mcp - handle initialization and subsequent requests
@@ -134,7 +134,7 @@ export async function startHttpServer(config, api, relay, sessionManager) {
     });
     // Start listening on auto-assigned port
     const httpServer = await new Promise((resolve, reject) => {
-        const server = app.listen(0, '127.0.0.1', (error) => {
+        const server = app.listen(port, '127.0.0.1', (error) => {
             if (error) {
                 reject(error);
             }
@@ -142,13 +142,14 @@ export async function startHttpServer(config, api, relay, sessionManager) {
                 resolve(server);
             }
         });
+        server.on('error', reject);
     });
     const addr = httpServer.address();
     if (!addr || typeof addr === 'string') {
         throw new Error('Failed to get server address');
     }
-    const port = addr.port;
-    logger.debug(`HTTP server listening on http://127.0.0.1:${port}/mcp`);
+    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...');
@@ -175,5 +176,5 @@ export async function startHttpServer(config, api, relay, sessionManager) {
         });
         logger.debug('HTTP server closed');
     };
-    return { port, close };
+    return { port: actualPort, close };
 }

package/dist/index.js

@@ -152,17 +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)
-  serve          Start the MCP server (HTTP transport, auto-picks port)
-  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);
@@ -288,7 +315,7 @@ async function runServer() {
 // ---------------------------------------------------------------------------
 // HTTP Server
 // ---------------------------------------------------------------------------
-async function runHttpServer() {
+async function runHttpServer(port) {
     const config = loadConfig();
     setupLogger(config.logLevel);
     const creds = readCredentials(config.credentialsPath);
@@ -305,11 +332,27 @@ async function runHttpServer() {
     }
     logger.info('Starting happy-mcp HTTP server...');
     const state = await initializeAuthenticatedState(config, creds);
-    const { port, close } = await startHttpServer(config, state.api, state.relay, state.sessionManager);
-    console.error(`[happy-mcp] HTTP server listening on http://127.0.0.1:${port}/mcp`);
+    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 close();
+        await result.close();
         state.relay.disconnect();
         state.sessionManager.destroy();
         clearKeyCache();
@@ -329,7 +372,8 @@ if (!command) {
     });
 }
 else if (command === 'serve') {
-    runHttpServer().catch((err) => {
+    const flags = parseServeFlags(process.argv.slice(3));
+    runHttpServer(flags.port).catch((err) => {
         console.error('[happy-mcp] Fatal:', err.message ?? err);
         process.exit(1);
     });

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,6 +30,7 @@ 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.'],
 ];
 /**
@@ -43,6 +45,7 @@ export function registerAllTools(server, config, api, 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);

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/package.json

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