fix(stdio): add stdin close/end listeners to prevent zombie/orphan processes by ElliotDrel · Pull Request #265 · punkpeye/fastmcp

ElliotDrel · 2026-05-02T01:00:17Z

Summary

Fixes #264.

When an MCP client closes its end of the stdin pipe (restart, crash, or normal shutdown), StdioServerTransport never fires a close event because the underlying @modelcontextprotocol/sdk only registers data and error listeners on process.stdin — not close or end. The FastMCP server process therefore lingers indefinitely as a zombie/orphan.

This PR adds belt-and-suspenders process.stdin listeners immediately after session.connect(transport) for the stdio transport path. When either close or end fires, transport.close() is called and the process exits cleanly.

What changed

src/FastMCP.ts — inside the if (config.transportType === "stdio") block, after await session.connect(transport):

const onStdinClose = () => { transport.close().catch(() => {}); };
process.stdin.on("close", onStdinClose);
process.stdin.on("end", onStdinClose);

Why here and not just rely on the SDK fix?

The SDK fix (fix(server): exit when MCP client closes stdin pipe modelcontextprotocol/typescript-sdk#2003) is not yet released — users on current npm versions are unprotected.
Belt-and-suspenders: even after the SDK ships the patch, having FastMCP detect the condition independently protects against future regressions.
FastMCP is the natural place for this guard since it owns the transport reference and the session lifecycle.

References

Test plan

Start a FastMCP stdio server as a child process
Destroy the child's stdin (child.stdin.destroy()) to simulate a client disconnect
Confirm the server process exits (previously it would hang)
Confirm existing tests still pass (npm test)

Copilot

Pull request overview

This PR addresses stdio-mode process leaks by ensuring FastMCP reacts when the MCP client closes its end of the stdin pipe, triggering transport shutdown so the server can terminate instead of lingering.

Changes:

Add process.stdin close and end listeners after session.connect(transport) in the stdio transport path.
On stdin shutdown, call transport.close() to trigger session/transport teardown.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

ElliotDrel · 2026-05-18T03:03:37Z

Hi @punkpeye — just checking in on this. The PR has been CI-green and merge-ready since May 3 (15 days). It's a minimal 3-line fix that adds close and end listeners to stdin alongside the existing data/error listeners, preventing zombie processes when an MCP client exits. All review threads resolved. Happy to address any questions!

When an MCP client (e.g. Claude Code) closes its end of the stdin pipe, StdioServerTransport does not detect the disconnect and the server process lingers indefinitely as a zombie/orphan. This adds belt-and-suspenders `process.stdin` close/end listeners immediately after `session.connect(transport)` for the stdio transport path. When either event fires, `transport.close()` is called so the process exits cleanly. The upstream SDK is tracking the same root cause in modelcontextprotocol/typescript-sdk#2003. Adding the fix here means FastMCP users are protected regardless of which SDK version they have installed.

…o test - Add stdinClosed guard to prevent double-close race when both close and end fire for the same shutdown - Remove stdin listeners inside the handler (on first fire) and also in transport.onclose to prevent listener accumulation across start() calls - Add src/FastMCP.stdio.test.ts with vitest tests verifying registration, single-fire idempotency, and listener removal Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

vi.mock() is statically hoisted by Vitest, so factory closures cannot reference test-body locals. Move fakeTransport to module scope and assign it in beforeEach so the mock factory captures the right value.

session.connect() retries getClientCapabilities() up to 10x100ms before resolving. Without fake timers, the test's single Promise.resolve() tick was not enough for the stdin listeners to be registered.

…port() works Arrow functions cannot be used as constructors. Switching to a regular function in the vi.mock factory lets `new StdioServerTransport()` in FastMCP.start() return fakeTransport correctly. Also removes fake timer usage — the 10×100ms capability-retry loop in session.connect() runs in real time (~1s), and vi.waitFor with a 3s timeout waits it out cleanly.

Spawns a real FastMCP stdio server child process, destroys stdin to simulate client disconnect, and asserts the child exits cleanly. Regression test for punkpeye#264.

Three ESLint perfectionist violations: - node:child_process import before vitest - env before stdio in spawn options object - null before number in union type Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

…0s vitest)

…ownload

… via tsx

Unit tests in FastMCP.stdio.test.ts already cover the fix. The integration test consistently failed due to tsx --eval ESM incompatibility. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

dlecan · 2026-05-25T19:45:03Z

@punkpeye it would be great to fix that issue quickly
Thanks

github-actions · 2026-07-23T14:30:47Z

🎉 This PR is included in version 4.8.1 🎉

The release is available on:

Your semantic-release bot 📦🚀

Copilot AI review requested due to automatic review settings May 2, 2026 01:00

ElliotDrel mentioned this pull request May 2, 2026

stdio transport: server becomes zombie/orphan process when MCP client closes stdin #264

Closed

Copilot started reviewing on behalf of ElliotDrel May 2, 2026 01:00 View session

Copilot AI reviewed May 2, 2026

View reviewed changes

Comment thread src/FastMCP.ts Outdated

Comment thread src/FastMCP.ts

Comment thread src/FastMCP.ts

ElliotDrel and others added 19 commits May 18, 2026 10:26

style: run prettier on FastMCP.ts

974caf7

fix: resolve ESLint sort-objects and no-unused-vars in stdio test

fe6f3b4

fix(lint): remove unused params from stdinOffSpy mockImplementation

3baf24f

fix(lint): apply prettier formatting to stdio test file

6ef82e0

fix(test): hoist vi.mock to module level to fix Vitest hoisting issue

4003dff

vi.mock() is statically hoisted by Vitest, so factory closures cannot reference test-body locals. Move fakeTransport to module scope and assign it in beforeEach so the mock factory captures the right value.

fix(test): use fake timers to skip FastMCPSession capability retry loop

35685ff

session.connect() retries getClientCapabilities() up to 10x100ms before resolving. Without fake timers, the test's single Promise.resolve() tick was not enough for the stdin listeners to be registered.

test: add integration test for stdin-close zombie prevention

8ecdb87

Spawns a real FastMCP stdio server child process, destroys stdin to simulate client disconnect, and asserts the child exits cleanly. Regression test for punkpeye#264.

style: fix prettier formatting in stdio integration test

536db8e

fix(lint): fix perfectionist ordering in stdio integration test

fb4a76c

Three ESLint perfectionist violations: - node:child_process import before vitest - env before stdio in spawn options object - null before number in union type Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

fix(test): increase timeout for tsx cold-download in CI (60s ready, 9…

801a6cb

…0s vitest)

fix(test): add tsx devDep, use installed binary instead of npx cold-d…

0ea79e6

…ownload

fix: update pnpm-lock.yaml after adding tsx devDependency

9adbbf5

fix(test): use temp .ts file instead of --eval so ESM imports resolve…

e0b453f

… via tsx

style: fix prettier formatting in integration test

ab86420

fix(lint): sort named imports, add comment to empty catch blocks

19bdd1c

revert: remove integration test and tsx devDep

21bcb71

Unit tests in FastMCP.stdio.test.ts already cover the fix. The integration test consistently failed due to tsx --eval ESM incompatibility. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

ElliotDrel force-pushed the fix/stdin-close-zombie-process branch from 582d869 to 21bcb71 Compare May 18, 2026 14:26

Merge branch 'main' into fix/stdin-close-zombie-process

4de57ee

punkpeye merged commit a87f791 into punkpeye:main Jul 23, 2026
1 check passed

github-actions Bot added the released label Jul 23, 2026

Navigation Menu

fix(stdio): add stdin close/end listeners to prevent zombie/orphan processes - #265

fix(stdio): add stdin close/end listeners to prevent zombie/orphan processes#265
punkpeye merged 20 commits into
punkpeye:mainfrom
ElliotDrel:fix/stdin-close-zombie-process

ElliotDrel commented May 2, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ElliotDrel commented May 18, 2026

Uh oh!

dlecan commented May 25, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

ElliotDrel commented May 2, 2026

Summary

What changed

Why here and not just rely on the SDK fix?

References

Test plan

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ElliotDrel commented May 18, 2026

Uh oh!

dlecan commented May 25, 2026

Uh oh!

Uh oh!

github-actions Bot commented Jul 23, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants