Skip to content

Restore server capabilities on resumed sessions so list commands work - #492

Open
sepehrasgarian wants to merge 1 commit into
apify:mainfrom
sepehrasgarian:fix/resumed-session-lists
Open

sepehrasgarian wants to merge 1 commit into
apify:mainfrom
sepehrasgarian:fix/resumed-session-lists

Conversation

@sepehrasgarian

Copy link
Copy Markdown

Fixes #484

Problem

After a bridge crash, the restarted bridge resumes the server-side session with its MCP-Session-Id. On that connection tools-list, prompts-list, resources-list and resources-templates-list all return [] with exit code 0, and tools-get echo says the tool doesn't exist. restart brings everything back.

The cause is that the SDK client skips the handshake when the transport already has a session ID, so _serverCapabilities is never set. listTools() and the other three list methods then return an empty list without sending a request. Two other things break for the same reason. The SDK never registers its list-changed handlers. And because no tools/list result is cached, callTool() has no output schema to validate against, so on a resumed session a tool result that violates its outputSchema is accepted when it should be rejected.

Fix

The issue suggested two ways to fix this. I went with seeding the SDK client's capabilities, not routing the four list calls through client.request().

  • New McpClient.restoreServerCapabilities(capabilities) method. When the SDK client has no capabilities of its own, it sets them from the values sessions.json saved at the original connect. It then calls the SDK's _setupListChangedHandlers with the client's listChanged config, the same call the handshake makes. If the SDK client already has capabilities, it does nothing.
  • The bridge calls it in the resume branch, where resumedHandshakeDetails is already built. That is before the tools cache is pre-populated, so the first listAllTools after a resume is no longer cached as empty.

Why seed rather than bypass: with the SDK's own list methods working again, its response cache, the output-schema validators and the list-changed handlers all behave exactly as on a fresh connection. mcpc's own capability reads (completion-complete, tasks support, the skills extension) also see the restored values, with no extra code. A bypass would only have fixed the four list calls, and would have duplicated the SDK's page walking.

The downside is that _serverCapabilities, _listChangedConfig and _setupListChangedHandlers are private in SDK 2.3.1. All three are touched in a single method, behind a small interface type. The new unit suite runs against the real SDK client and server rather than the stub, so an SDK upgrade that renames or drops them fails the tests instead of quietly bringing the bug back.

Not covered here (follow-up)

A resumed Streamable HTTP connection never opens the standalone GET SSE stream. The SDK transport opens it only when it sends notifications/initialized, and resumption skips that. So server-initiated notifications (list_changed, resources/updated) don't reach a resumed bridge, even with the handlers now registered. The existing "resources-subscribe works after resume" e2e test only checks the subscribe pre-check, not that files stay in sync. This needs a transport-level fix and its own e2e test, so I'd rather file it separately.

Testing

  • test/e2e/suites/sessions/resume.test.sh: after the crash, asserts that tools-list, prompts-list, resources-list and resources-templates-list return the test server's items, and that tools-get echo succeeds. It fails on main ("tools-list should include echo") and passes with this change.

  • test/unit/core/resume-capabilities.test.ts (new): uses the real SDK client and an SDK Server over InMemoryTransport, with a session ID on the client transport so the handshake is skipped. It covers:

    • empty lists before the restore
    • lists after the restore
    • the list-changed handler firing
    • rejection of a result that violates the output schema
    • no overwrite of existing capabilities

    Removing either the capability assignment or the handler registration fails the corresponding tests.

  • pnpm run test:unit: 1368 passed.

  • pnpm run lint: 0 errors. The 24 warnings are the same as on main.

  • ./test/e2e/run.sh --parallel 8: legacy has 56 passed and 3 skipped; modern has 54 passed and 5 skipped. basic/remote-open fails in both, and it also fails on unmodified main in my environment, because mcp.apify.com answers "Authentication required" from there.

After a crashed bridge resumed its MCP session by session ID, tools-list,
prompts-list, resources-list and resources-templates-list all returned an
empty list with exit code 0, and tools-get reported the tool missing. The
SDK client skips the handshake on resumption and so never learns the
server's capabilities, and its list methods return an empty list without
sending a request when the capability is not advertised.

- McpClient.restoreServerCapabilities() seeds the SDK client with the
  capabilities persisted at connect, and registers the list-changed
  handlers the handshake would have registered. It does nothing when the
  SDK client already has capabilities of its own.
- The bridge calls it when it resumes a session.
- Since listTools() goes through the SDK again, the tools/list cache is
  written and tool results are checked against their output schema again
  on resumed sessions.
- The SDK exposes no public API for this, so the fields are set directly;
  a new unit suite runs against the real SDK client and server and fails
  if those internals change.
- resume.test.sh now asserts the list commands and tools-get after the
  crash; it fails without the fix.
- CHANGELOG entry under Fixed

Fixes apify#484

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.

Resumed sessions list no tools, prompts or resources until restart

1 participant