Skip to content

fix(mcp): use NDJSON stdio framing and flush passthrough stdout - #449

Open
Stoufiler wants to merge 1 commit into
rest-sh:mainfrom
Stoufiler:fix/mcp-stdio-ndjson-flush
Open

Stoufiler wants to merge 1 commit into
rest-sh:mainfrom
Stoufiler:fix/mcp-stdio-ndjson-flush

Conversation

@Stoufiler

Copy link
Copy Markdown

Fixes #388. Alternative to #394 that also covers the second half of the bug.

Problem

restish mcp serve hangs with MCP clients that speak the current stdio transport. Two independent bugs, both required:

  1. Framing mismatch. The plugin reads/writes Content-Length header frames (spec revision 2024-11-05), while the current spec (2025-06-18 and later) defines stdio messages as newline-delimited JSON. Both reference SDKs (Python mcp, TypeScript) send NDJSON, so readFrame waits forever for a Content-Length header that never comes.
  2. Parent stdout buffered until exit. When stdout is not a TTY (always true under an MCP client), the CLI wraps it in a 64KB bufio.Writer flushed only on exit (internal/cli/cli.go, cascadingFlushWriter). Plugin stdout data relayed in command_plugin_handlers.go is never flushed in between, so even a framing-compatible client receives no response until the process exits. Measured: with a Content-Length client on stock v2.3.0, the initialize response arrives only after stdin EOF. The flush suggested in restish mcp serve hangs with NDJSON stdio MCP clients #388's body is therefore mandatory, not optional — and it must happen in the parent relay (internal/cli/command_plugin_handlers.go), not only in the plugin-side writer.

Changes

  • cmd/restish-mcp/server.go: readFrame now reads one NDJSON message per call (blank lines skipped, 64MiB message cap preserved, trailing message without newline accepted); writeFrame emits <json>\n. Header-specific constants removed.
  • internal/cli/command_plugin_handlers.go: flush stdout after relaying each stdout-data message from a passthrough plugin.
  • Tests updated to NDJSON (cmd/restish-mcp/mcp_test.go line-limit/framing-error cases incl. blank-line and no-trailing-newline coverage; internal/cli/mcp_plugin_test.go frame helpers).

Verification

  • go build ./..., go test ./... (unit) and go test -tags integration ./internal/cli/ -run TestMCP pass locally.
  • End-to-end against the real Python MCP SDK (mcp 2.0.0) as client, serving three registered APIs (171 tools):
    • initialize → ~0.5s (previously: infinite hang)
    • tools/list → all tools discovered
    • 20 consecutive tools/call (HTTP-delegated) → all OK, ~0.15s each after warmup
    • 10s idle after calls → process stable

One observation for follow-up (not addressed here): a single fatal error: all goroutines are asleep - deadlock! was seen once right after a cold first tools/call whose delegated HTTP request took ~4.6s (TLS setup). Not reproduced across 25+ subsequent calls, but the plugin's idle wait after a slow Do() round trip may deserve a stress test.

Note: three pre-existing test failures in internal/cli (TestRetrySucceedsAfterTransientFailures, TestRetryAfterHeaderRespected, TestAPIRetryMaxWaitCapsRetryAfter, all "exit code 5") reproduce identically on unmodified main (79c3d88) on my machine — unrelated to this change.

The MCP stdio transport in spec revision 2025-06-18 and later carries
newline-delimited JSON messages; readFrame/writeFrame still spoke the
older Content-Length header framing, so NDJSON clients (the reference
Python and TypeScript SDKs) hung waiting for a header line that never
arrived (rest-sh#388).

Additionally, when stdout is not a terminal the CLI wraps it in a 64KB
buffered writer flushed only on exit. Plugin stdout-data relayed by the
command plugin handler was never flushed in between, so even a
framing-compatible client received no response until the process exited.
Flush after each relayed stdout chunk.

Tests updated to NDJSON, with coverage for blank lines, oversized
messages, and trailing messages without a newline.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

restish mcp serve hangs with NDJSON stdio MCP clients

1 participant