feat(server): add host process watchdog to StdioServerTransport

When clientProcessId is provided, the transport periodically checks if
the host process is still alive using signal 0 and self-terminates if
it is gone. This prevents orphaned server processes when the host
crashes or is killed without cleanly shutting down the server.

Follows the pattern used by vscode-languageserver-node as described
in the issue.

Addresses review feedback:
- Rebased onto main (integrates _closed guard, _onstdouterror, new send())
- Treat EPERM as process-still-alive in watchdog catch block
- Add kill() stub to shimsWorkerd.ts for workerd compatibility
- Export StdioServerTransportOptions from packages/server/src/index.ts

Fixes #208

Co-Authored-By: windro-xdd <windro-xdd@users.noreply.github.com>
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

.changeset/server-host-watchdog.md

@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/server': minor
+---
+
+Add host process watchdog to StdioServerTransport. When `clientProcessId` is provided via the new options object constructor, the transport periodically checks if the host process is still alive and self-terminates if it is gone, preventing orphaned server processes.

packages/server/src/index.ts

@@ -28,6 +28,7 @@ export type { HostHeaderValidationResult } from './server/middleware/hostHeaderV
 export { hostHeaderValidationResponse, localhostAllowedHostnames, validateHostHeader } from './server/middleware/hostHeaderValidation.js';
 export type { ServerOptions } from './server/server.js';
 export { Server } from './server/server.js';
+export type { StdioServerTransportOptions } from './server/stdio.js';
 export { StdioServerTransport } from './server/stdio.js';
 export type {
     EventId,

packages/server/src/server/stdio.ts

@@ -4,6 +4,37 @@ import type { JSONRPCMessage, Transport } from '@modelcontextprotocol/core';
 import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/core';
 import { process } from '@modelcontextprotocol/server/_shims';
 
+/**
+ * Options for configuring `StdioServerTransport`.
+ */
+export interface StdioServerTransportOptions {
+    /**
+     * The readable stream to use for input. Defaults to `process.stdin`.
+     */
+    stdin?: Readable;
+
+    /**
+     * The writable stream to use for output. Defaults to `process.stdout`.
+     */
+    stdout?: Writable;
+
+    /**
+     * The PID of the client (host) process. When set, the transport periodically
+     * checks if the host process is still alive and self-terminates if it is gone.
+     *
+     * This prevents orphaned server processes when the host crashes or is killed
+     * without cleanly shutting down the server. Follows the same pattern used by
+     * the Language Server Protocol in vscode-languageserver-node.
+     */
+    clientProcessId?: number;
+
+    /**
+     * How often (in milliseconds) to check if the host process is alive.
+     * Only used when `clientProcessId` is set. Defaults to 3000 (3 seconds).
+     */
+    watchdogIntervalMs?: number;
+}
+
 /**
  * Server transport for stdio: this communicates with an MCP client by reading from the current process' `stdin` and writing to `stdout`.
  *
@@ -20,11 +51,29 @@ export class StdioServerTransport implements Transport {
     private _readBuffer: ReadBuffer = new ReadBuffer();
     private _started = false;
     private _closed = false;
-
-    constructor(
-        private _stdin: Readable = process.stdin,
-        private _stdout: Writable = process.stdout
-    ) {}
+    private _clientProcessId?: number;
+    private _watchdogInterval?: ReturnType<typeof setInterval>;
+    private _watchdogIntervalMs: number;
+    private _stdin: Readable;
+    private _stdout: Writable;
+
+    constructor(options?: StdioServerTransportOptions);
+    constructor(stdin?: Readable, stdout?: Writable);
+    constructor(stdinOrOptions?: Readable | StdioServerTransportOptions, stdout?: Writable) {
+        if (stdinOrOptions && typeof stdinOrOptions === 'object' && !('read' in stdinOrOptions)) {
+            // Options object form
+            const options = stdinOrOptions as StdioServerTransportOptions;
+            this._stdin = options.stdin ?? process.stdin;
+            this._stdout = options.stdout ?? process.stdout;
+            this._clientProcessId = options.clientProcessId;
+            this._watchdogIntervalMs = options.watchdogIntervalMs ?? 3000;
+        } else {
+            // Legacy positional args form
+            this._stdin = (stdinOrOptions as Readable) ?? process.stdin;
+            this._stdout = stdout ?? process.stdout;
+            this._watchdogIntervalMs = 3000;
+        }
+    }
 
     onclose?: () => void;
     onerror?: (error: Error) => void;
@@ -41,7 +90,7 @@ export class StdioServerTransport implements Transport {
     _onstdouterror = (error: Error) => {
         this.onerror?.(error);
         this.close().catch(() => {
-            // Ignore errors during close — we're already in an error path
+            // Ignore errors during close -- we're already in an error path
         });
     };
 
@@ -59,6 +108,43 @@ export class StdioServerTransport implements Transport {
         this._stdin.on('data', this._ondata);
         this._stdin.on('error', this._onerror);
         this._stdout.on('error', this._onstdouterror);
+        this._startHostWatchdog();
+    }
+
+    private _startHostWatchdog(): void {
+        if (this._clientProcessId === undefined || this._watchdogInterval) {
+            return;
+        }
+
+        const pid = this._clientProcessId;
+        this._watchdogInterval = setInterval(() => {
+            try {
+                // Signal 0 does not kill the process; it checks if it exists.
+                process.kill(pid, 0);
+            } catch (error: unknown) {
+                // ESRCH means the process does not exist: host is gone.
+                // EPERM means permission denied but the process is still alive
+                // (some platforms return EPERM instead of ESRCH for signal 0).
+                if ((error as NodeJS.ErrnoException).code === 'EPERM') {
+                    return;
+                }
+                // Host process is gone. Self-terminate.
+                this._stopHostWatchdog();
+                void this.close();
+            }
+        }, this._watchdogIntervalMs);
+
+        // Ensure the watchdog timer does not prevent the process from exiting.
+        if (typeof this._watchdogInterval === 'object' && 'unref' in this._watchdogInterval) {
+            this._watchdogInterval.unref();
+        }
+    }
+
+    private _stopHostWatchdog(): void {
+        if (this._watchdogInterval) {
+            clearInterval(this._watchdogInterval);
+            this._watchdogInterval = undefined;
+        }
     }
 
     private processReadBuffer() {
@@ -81,6 +167,7 @@ export class StdioServerTransport implements Transport {
             return;
         }
         this._closed = true;
+        this._stopHostWatchdog();
 
         // Remove our event listeners first
         this._stdin.off('data', this._ondata);

packages/server/src/shimsWorkerd.ts

@@ -19,5 +19,8 @@ export const process = {
     },
     get stdout(): never {
         return notSupported();
+    },
+    kill(): never {
+        return notSupported();
     }
 };

packages/server/test/server/stdio.test.ts

@@ -1,8 +1,10 @@
+import process from 'node:process';
 import { Readable, Writable } from 'node:stream';
 
 import type { JSONRPCMessage } from '@modelcontextprotocol/core';
 import { ReadBuffer, serializeMessage } from '@modelcontextprotocol/core';
 
+import type { StdioServerTransportOptions } from '../../src/server/stdio.js';
 import { StdioServerTransport } from '../../src/server/stdio.js';
 
 let input: Readable;
@@ -179,3 +181,79 @@ test('should fire onerror before onclose on stdout error', async () => {
 
     expect(events).toEqual(['error', 'close']);
 });
+
+test('should accept options object constructor', async () => {
+    const server = new StdioServerTransport({ stdin: input, stdout: output });
+    server.onerror = error => {
+        throw error;
+    };
+
+    let didClose = false;
+    server.onclose = () => {
+        didClose = true;
+    };
+
+    await server.start();
+    await server.close();
+    expect(didClose).toBeTruthy();
+});
+
+describe('host process watchdog', () => {
+    test('should close transport when host process is gone', async () => {
+        // Use a PID that does not exist
+        const deadPid = 2147483647;
+        const server = new StdioServerTransport({
+            stdin: input,
+            stdout: output,
+            clientProcessId: deadPid,
+            watchdogIntervalMs: 100
+        });
+
+        const closed = new Promise<void>(resolve => {
+            server.onclose = () => resolve();
+        });
+
+        await server.start();
+
+        // Watchdog should detect the dead PID and close
+        await closed;
+    }, 10000);
+
+    test('should not close when host process is alive', async () => {
+        // Use our own PID, which is always alive
+        const server = new StdioServerTransport({
+            stdin: input,
+            stdout: output,
+            clientProcessId: process.pid,
+            watchdogIntervalMs: 100
+        });
+
+        let didClose = false;
+        server.onclose = () => {
+            didClose = true;
+        };
+
+        await server.start();
+
+        // Wait for several watchdog cycles
+        await new Promise(resolve => setTimeout(resolve, 350));
+        expect(didClose).toBe(false);
+
+        await server.close();
+    });
+
+    test('should stop watchdog on close', async () => {
+        const server = new StdioServerTransport({
+            stdin: input,
+            stdout: output,
+            clientProcessId: process.pid,
+            watchdogIntervalMs: 100
+        });
+
+        await server.start();
+        await server.close();
+
+        // If watchdog was not stopped, it would keep running. Verify no errors after close.
+        await new Promise(resolve => setTimeout(resolve, 300));
+    });
+});