Skip to content

Pairing UI: show the expected @questdb/mcp-bridge version (install hint) and warn on version mismatch #573

Description

@emrberk

Each Web Console build is verified against a specific bridge version — EXPECTED_BRIDGE_VERSION (currently "0.1.0") in src/utils/mcp/protocolVersion.ts. On connect the console sends expectedBridgeVersion in the hello frame (src/utils/mcp/MCPBridgeClient.ts:261). The bridge compares majors: different major → WS close 4004 (terminal); same-major drift → it flags versionMismatch but only surfaces it to the coding agent via wait_for_pairing's userMessage (mcp-bridge/src/pairingTools.ts:128-137).

The console UI never tells the user which bridge version to install, nor shows a mismatch:

  • src/scenes/Footer/MCPBridgeStatus/PairPopover.tsx and src/providers/MCPBridgeProvider/PairingConsentModal.tsx display URL/token/status only.
  • The hello_ack frame carries the bridge's actual version in its v field (src/utils/mcp/types.ts:41-49), but the console ignores it — handleHelloAck and the provider's helloAck handler (src/providers/MCPBridgeProvider/index.tsx:219) don't read msg.v.

Ask

  1. In the Pair popover, always show the pinned version with a copy-paste install hint, e.g. npx @questdb/mcp-bridge@<EXPECTED_BRIDGE_VERSION> setup (the README already documents this pin).
  2. Capture the bridge's reported v on hello_ack; on same-major drift show a non-blocking warning in the popover/modal; on major mismatch the terminal 4004 error already fires — make its copy actionable with the same install hint.

Background — why versions must match

Tool schemas are duplicated in src/consts/shared-definitions.json and the bridge's copy, kept byte-identical by src/consts/shared-definitions.sync.test.ts. Codex caches the tool list at MCP init and ignores notifications/tools/list_changed, so the bridge must bundle its own copy instead of relying on the console's hello-sent tools. Mismatched versions → schema drift → broken tool calls.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Severity: 2enhancementNew feature or requestnotebooksIssues relevant to the notebooks featureweb-consoleIssues relevant to "web-console" package

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions