Added clean shutdown + tests

[jerome3o-anthropic]

Motivation and Context

#113

When closing a StdioServerTransport, the process would hang indefinitely due to unclosed stdin/stdout streams and lingering event listeners. This was particularly noticeable in server implementations that needed to shut down cleanly. The fix ensures proper cleanup of all resources, preventing process hangs.

How Has This Been Tested?

• Added unit test in src/server/stdio.test.ts verifying proper cleanup of stream resources and event listeners
• Added integration test in src/integration-tests/process-cleanup.test.ts that confirms the process exits cleanly after transport closure
• Manually verified fix using a minimal reproduction case that previously demonstrated the hang

Breaking Changes

None. This is a bug fix that maintains the existing API contract.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

The fix involves three key changes in StdioServerTransport.close():

1. Removing all event listeners, including 'drain' listeners that were previously overlooked
2. Explicitly destroying both stdin and stdout streams
3. Maintaining existing cleanup of the read buffer and onclose callback

The integration test was added to prevent regression, as unit tests alone didn't catch this issue due to the asynchronous nature of Node.js stream cleanup.

[jspahrsummers]

Thanks for working on this! Some blocking discussion, but this is definitely important

[jspahrsummers]

I'm a bit surprised that this has any effect on termination, but then reading about Node.js readable streams, I'm like 😵

It feels a bit janky to do things this way, but I don't really have a better idea…

[davidfiala]

Per top-level PR comment, I don't see how both MCP and anything else can co-exist on the same stdin stream.

[jspahrsummers]

Certainly not while messages are streaming in. The only question is whether there'd ever be a reason for a server implementation to want to read from stdin after terminating the normal MCP stuff. Probably not? But it's always hard to anticipate how people will use a library.

[davidfiala]

I believe that since you are communicating a specific protocol over stdin/stdout, then it does assume you have permanently taken over both STDIO FDs.

This has interesting implications that I've had to work around. Specifically, wouldn't a console.log or console.info effectively corrupt your communication stream, if it occurs during any part of the server execution?

Here was an approximate workaround that I put at the top of servers to route the most common occurences to stderr instead:

// make console.log and console.info go to STDERR because MCP is going to take over STDOUT
const onlyStderr = new Console({ stdout: process.stderr, stderr: process.stderr });
console.info = onlyStderr.info;
console.log = onlyStderr.log;

In this case, I'd argue that yes it's fine/expected for you to end the stdin/stdout streams. It should be clearly documented that this behavior occurs IMHO. Likewise, perhaps you should hotpatch the console logs in your server.connect() on StdioServerTransport. The thing is, if the user happens to console.log BEFORE getting to your constructor, then there'd already be corruption-worthy output that the MCP client would be exposed to when it begins to read stdout. There's worse workarounds for that as well (ie, a shared sentinel to broadcast the true beginning of the MCP stream), but that is a breaking protocol change.

[jspahrsummers]

This has interesting implications that I've had to work around. Specifically, wouldn't a console.log or console.info effectively corrupt your communication stream, if it occurs during any part of the server execution?

Yes, this is discussed here: https://modelcontextprotocol.io/docs/tools/debugging#server-side-logging

[Nedomas]

Even though the fix here is for stdio specifically, I’m wondering isn’t the same leak happening in the SSE transport too?

I can’t seem to be getting rid of the active connection even with doing this:

const client = new Client({
  name: 'superinterface-mcp-client',
  version: '1.0.0',
}, {
  capabilities: {}
})

const transport =  ew SSEClientTransport(
  new URL('some-url')
)
await client.connect(transport)

await client.close()
await transport.close()

But might be an unrelated bug?

[jerome3o-anthropic]

seem to be getting rid of the active connection even with doing

That's odd - likely a separate issue. Going to merge this now and follow up on the SSE bug later