fix: handle container shutdown signals (#54)

* fix: handle container shutdown signals

Register SIGINT and SIGTERM handlers so the server closes its active transport before exiting. This lets HTTP and stdio deployments stop cleanly in containers instead of hanging on shutdown.

* changeste

* fix lint

Author: disintegrator

.changeset/khaki-mangos-speak.md

@@ -0,0 +1,5 @@
+---
+"@speakeasy-api/docs-mcp-server": patch
+---
+
+Register SIGINT and SIGTERM handlers so the server closes its active transport before exiting. This lets HTTP and stdio deployments stop cleanly in containers instead of hanging on shutdown.

packages/server/src/bin.ts

@@ -115,7 +115,7 @@ program
     );
 
     if (options.transport === "http") {
-      await startHttpServer(server, {
+      const { shutdown } = await startHttpServer(server, {
         port: options.port,
         ...(options.gitCommit || options.buildDate
           ? {
@@ -129,8 +129,10 @@ program
         pretty: options.logPretty,
         logLevel: options.logLevel,
       });
+      registerShutdown(shutdown);
     } else {
-      await startStdioServer(server);
+      const { shutdown } = await startStdioServer(server);
+      registerShutdown(shutdown);
     }
   });
 
@@ -151,3 +153,31 @@ function parseIntOption(value: string): number {
   }
   return parsed;
 }
+
+function registerShutdown(cleanup: () => Promise<void>): void {
+  let shuttingDown = false;
+
+  const shutdown = async (signal: string) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+
+    try {
+      await cleanup();
+    } catch (error) {
+      const message = error instanceof Error ? (error.stack ?? error.message) : String(error);
+      process.stderr.write(`Failed to shut down on ${signal}: ${message}\n`);
+      process.exitCode = 1;
+    } finally {
+      process.exit();
+    }
+  };
+
+  process.once("SIGINT", () => {
+    shutdown("SIGINT");
+  });
+  process.once("SIGTERM", () => {
+    shutdown("SIGTERM");
+  });
+}

packages/server/src/http.ts

@@ -52,6 +52,7 @@ export interface StartHttpServerOptions extends Pick<
 
 export interface HttpServerHandle {
   httpServer: http.Server;
+  shutdown: () => Promise<void>;
   fetch: (request: Request) => Response | Promise<Response>;
   port: number;
 }
@@ -86,7 +87,21 @@ export async function startHttpServer(
   const actualPort = await listenOnAvailablePort(httpServer, port);
   logger.info("started mcp server", { url: `http://localhost:${actualPort}/mcp` });
 
-  return { httpServer, fetch: app.fetch, port: actualPort };
+  const shutdown = async (): Promise<void> => {
+    return new Promise((resolve, reject) => {
+      logger.info("shutting down http server");
+
+      httpServer.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve();
+      });
+    });
+  };
+
+  return { httpServer, fetch: app.fetch, port: actualPort, shutdown };
 }
 
 interface SessionEntry {

packages/server/src/logging.ts

@@ -1,10 +1,9 @@
-import stream from "node:stream";
 import {
   configure,
+  getConsoleSink,
   getJsonLinesFormatter,
   getLogger,
   getLogLevels,
-  getStreamSink,
   type LogLevel,
 } from "@logtape/logtape";
 import { getPrettyFormatter } from "@logtape/pretty";
@@ -43,10 +42,7 @@ export async function configureDefaultLogger(
 
   await configure({
     sinks: {
-      console: getStreamSink(
-        stream.Writable.toWeb(process.stderr) as unknown as WritableStream<Uint8Array>,
-        { formatter },
-      ),
+      console: getConsoleSink({ formatter }),
     },
     loggers: [
       { category: ["logtape", "meta"], lowestLevel: "warning", sinks: ["console"] },

packages/server/src/stdio.ts

@@ -1,8 +1,25 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
-export async function startStdioServer(factory: () => McpServer): Promise<void> {
+export interface StdioServerHandle {
+  server: McpServer;
+  transport: StdioServerTransport;
+  shutdown: () => Promise<void>;
+}
+
+export async function startStdioServer(factory: () => McpServer): Promise<StdioServerHandle> {
   const transport = new StdioServerTransport();
   const server = factory();
   await server.connect(transport);
+
+  const shutdown = async () => {
+    await transport.close().catch((err) => {
+      if (err) console.error("Failed to close transport:", err);
+    });
+    await server.close().catch((err) => {
+      if (err) console.error("Failed to close mcp server:", err);
+    });
+  };
+
+  return { server, transport, shutdown };
 }