feat: add upgrade command, sync notebook tool surface, lazy-start ws server

[emrberk]

• Adds npx @questdb/mcp-bridge upgrade to re-pin existing coding-agent configs to the running bridge version, and points the version-mismatch pairing flow at it (with assistantNextActions to surface the command).
• Syncs the notebook tool surface from questdb/ui #586
• Opens the pairing deep link automatically from the MCP bridge using the cross-platform open package, while still returning the manual deep link / WebSocket URL / token fallback.
• Starts WS server only after first get_pairing_credentials call.
• Updates the tool guidance so apply_notebook_state is framed for bulk multi-cell edits or notebook creation, with update_cell / set_cell_* called out for small operations.

Tandem PR: questdb/ui#586

[emrberk]

Code Review — bridge v0.2.0 (joint release with QuestDB Web Console)

Target: unstaged changes on master (bridge) evaluated together with the
uncommitted ~/Desktop/questdb/ui working tree — they ship as one release.
Level: 3 (full pass) · Date: 2026-06-29
Verdict: Approve — consistent with the paired Web Console changes; remaining
items are Minor hardening on the new upgrade command and its tests.

Quality gates: yarn typecheck, yarn build, yarn lint clean; 202 tests pass.

---

Cross-repo consistency (bridge v0.2.0 ↔ Web Console)

Verified the seams that would break a joint release. All consistent.

Seam	Result
Vendored shared-definitions.json	Bridge copy is byte-identical to the UI working copy (sha c4675af8…). The console builds hello.tools from the same file (ui/src/utils/tools/tools.ts → MCPBridgeClient hello.tools), so the bridge's Ajv validators and tools/list surface are consistent with the console by construction.
Version negotiation	UI EXPECTED_BRIDGE_VERSION bumped 0.1.0→0.2.0 in lockstep with the bridge's package.json. New-bridge ↔ new-UI pairs cleanly with no spurious version_mismatch warning.
New / renamed tool handlers	set_cell_name, set_cell_view_maximized, string-interval set_cell_autorefresh, and apply_notebook_state (name / is_view_maximized / string auto_refresh) all implemented in ui/.../dispatch.ts. Old set_cell_chart_maximized / is_chart_maximized are fully removed from the UI.
Limits & enums	Schema maxLength:100 == UI MAX_CELL_NAME_LENGTH=100 (> boundary, 100 allowed); interval enum ["1s","5s","10s","30s","1m"] == UI isAutoRefresh. chart_config.name removal matches the UI (no code reads a title from chart_config.name; the cell name is now the chart title).
Degradation (new bridge ↔ old console)	Graceful: an unadvertised tool has no validator in toolValidators, so the bridge skips validation and forwards; the old console returns a clean Unknown tool error. No crash.

No regressions to the session/timer/disconnect machinery — this change set does
not touch bridgeSession.ts / wsServer.ts / types.ts, and no changed symbol
is consumed there. The no-duplicate-DML disconnect-grace contract is untouched.

---

Open issues

#	Issue	Severity	Location	Description	Suggested fix
1	rewriteBridgePin regex matches name prefixes / drops build metadata	Minor (latent)	in-diff — runUpgrade.ts:16	@questdb/mcp-bridge(@[\w.\-]+)? matches the bare name even as a prefix of a longer id. Empirically: @questdb/mcp-bridge-cli@1.0.0 → @questdb/mcp-bridge@0.2.0-cli@1.0.0 (corrupted); @…@1.0.0+build.5 → @…@0.2.0+build.5 (stale +build tail). Unreachable with any config today (no @questdb/mcp-bridge-* sibling exists; npm specs don't carry +build), but becomes a corruption bug the moment a sibling package ships.	Anchor the tail and allow +: …(@[\w.\-+]+)?(?![\w/-]). Add a sibling-name test case.
2	upgrade can miss a non-primary OpenCode config	Minor	in-diff — runUpgrade.ts:35	OpenCode has 4 candidate config paths; resolveConfigPath returns only the first that exists. If the bridge spec lives in a later candidate while an earlier one exists without it, upgrade reports absent and never re-pins the real file → on restart the old bridge still launches. Edge case (matches setup's single-file model; only bites a hand-multi-configured user).	For upgrade, iterate all existing configPaths that contain the package, not just the first.
3	Removed functional-tool count assertion	Minor	in-diff — bundledTools.test.ts	The toHaveLength(30) assertion was deleted rather than updated. It was a cheap guard against an unintended vendored sync adding / dropping / duplicating tools — exactly the risk this change exercises. Current count is 31.	Restore as expect(BUNDLED_FUNCTIONAL_TOOLS).toHaveLength(31) (or assert the exact name set).

---

False-positives (verified non-issues)

Claim	Why dismissed
attachVersionMismatch clobbers a pre-existing assistantNextActions	Not reachable. All three callsites (pairingTools.ts:199, :269, :286) build a fresh payload literal with no assistantNextActions key before calling it. Shape stays {content:[{type:"text",text}]}; buildIncompatiblePayload still sets isError:true.
set_cell_name missing from PER_TOOL_TIMEOUT_MS is a bug	Intentional/harmless. It falls to the ?? 15_000 default — identical to every sibling set_cell_* write, and many tools (get_tables, validate_query, …) already rely on the default. The table is not exhaustive by design.
upgrade could start the server / open the log / allocate a port / create a config	Verified correct. parseCli maps upgrade and index.ts handles it before new Logger() / parsePort / server start; runUpgrade only does fs + console.log and never writes a file that didn't already contain the spec; exit code failed>0?1:0 propagates.

---

Summary

• Approve. The bridge changes line up with the paired Web Console changes —
  schema, version negotiation, tool handlers, limits, and the degradation path
  all match. Safe to ship the two together.
• The pairing refactor (attachVersionMismatch + buildVersionMismatchActions)
  is a clean, additive improvement: it now also emits assistantNextActions on
  the paired-with-mismatch payloads and steers users to the new upgrade
  command. Correct at all callsites.
• Remaining items are all Minor hardening on the new upgrade command and
  its test coverage; none block the release. feat: add upgrade command, sync notebook tool surface, lazy-start ws server #1 and #3 are one-liners worth
  doing.