feat(tools): configure_popup_modal_layer + slash-prompt for custom popup modal feature

[romer8]

Summary

Adds an MCP surface for the custom popup-modal feature shipped on the tethysdash side 2026-05-13 (Aquaveo/tethysapp-tethys_dash#124). Before this PR the popup modal was UI-only — there was no MCP-tool path for the chatbox to configure it. The new tool emits a single-op {patch_update} envelope and re-uses the existing apply_patch dispatch path; no chatbox-core/engine changes.

Closes the surface gap diagnosed in /ce-debug 2026-05-21.

• New @mcp.tool configure_popup_modal_layer(map_uuid, layer_index, popup_config) — emits {patch_update: {uuid, source: "Map", ops: [single add op at /args/layers/<N>/popupConfig]}}
• New @mcp.prompt configure_popup_modal_layer slash-command counterpart
• 3 Pydantic models (_PopupConfigPayload, _PopupConfigPosition, _PopupConfigGridItemInput) with extra="forbid" to catch LLM old-shape leaks
• Server-side normalization mirrors PopupLayoutEditor.js's canonical persisted shape (mint uuid4/i/id: None, stringify args → args_string, stringify metadata → metadata_string)
• Structured {error, fix_hint, errors[]} envelope on validation failure for one-cycle LLM repair
• Tool catalog: 25 → 26

Design rationale

Settled in docs/plans/2026-05-21-002-feat-tethysdash-mcps-popup-modal-surface-plan.md (with full doc-review):

• Dedicated tool, not popup_options extension on 11 add_*_layer tools — the popupConfig envelope is shape-invariant across source types; only one shared tool is needed. The t3-split lesson applies inside gridItems (per-source-type args), not at the envelope.
• layer_index: int not layer_name: str — the standalone MCP server is stateless re: dashboard contents and can't resolve a name to an index. The LLM reads the index from dashboard_state (same pattern as patch_visualization).
• Canonical persisted shape on the wire (not a "friendly" shape with server-side translation) — eliminates a translation layer; round-trip parity with the React UI is trivial.
• Inline gridItems list, single-call — popups in practice carry 1-3 gridItems; multi-call composability deferred to v2.
• ${feature.<key>} syntax named abstractly in field descriptions — no concrete example values per feedback_no_examples_in_tool_descriptions.md.

Tool description carries (load-bearing prose, pinned by tests)

• Mutual-exclusion clause: "DO NOT use this tool to edit fields on an existing popupConfig — use patch_visualization on the specific sub-path instead. Re-calling this tool REPLACES the entire popupConfig."
• Same-turn race constraint: "Configure the popup in a turn AFTER add_*_layer lands."
• ${feature.<key>} syntax named (no concrete example values)
• Pointers to all 3 discovery surfaces for gridItems[].source: list_available_visualizations, list_intake_plugins, register_runtime_plugin

Known v1 trade-offs (documented in plan)

• Destructive replace on re-call — server mints fresh uuid4 per gridItem; any popup-internal cross-references (e.g., variable_input bindings nested inside the popup) silently break. Mutual-exclusion clause in description is the v1 mitigation. v2: optional replace: true guard if observed in smoke.
• Engine rejectedPatches categorization at lib/chatbox-core/engine/index.js:1037-1047 is name-keyed to toolName === 'patch_visualization'. The new tool's {error} envelopes reach the LLM repair loop but do NOT populate the user-facing _buildWhitelistWarning banner. Accepted v1 gap.
• No per-source-type args validation — runtime errors on bad args shapes surface via the existing per-tile error boundary. v2: strict validation against the registered viz type's schema if observed failure rate justifies.
• Cheap registry-membership check on gridItems[].source was planned (KTD feat: dev runbook + setup-mcp.sh for running alongside tethysdash #2) but dropped during implementation — implementing it properly requires a network call to list_intake_plugins (HTTP-backed), which contradicts the stateless-server premise. Deferred to v2.

Tests

51 new tests in test_mcp/test_popup_modal_layer.py:

• TestPydanticModels (13 tests) — shape validation: minimal payload, full payload, position range, gridItem ranges, empty gridItems rejected, mode literal, extra-field rejection
• TestToolHappyPath (12 tests) — patch_update envelope shape, single-op atomicity, layer_index path interpolation, JSON-string popup_config coercion, default position/metadata/titleTemplate, ${feature.*} + ${variable_name} preservation through json.dumps
• TestToolErrorPaths (7 tests) — invalid uuid, empty gridItems, mode='carousel', popup_config=None / "" / non-dict, negative layer_index
• TestEnvelopeContract (7 tests) — canonical persisted gridItem fields, no LLM-input-shape leak, args_string/metadata_string are valid JSON, uuid is str(uuid4), id is None, re-call mints fresh UUIDs
• TestWhitelistCoverage (5 tests) — /args/layers prefix admits all deeper popupConfig paths
• TestSlashPrompt (2 tests) — prompt scaffolds the tool call
• TestToolDescription (5 tests) — regression guards for mutual-exclusion + same-turn-race + abstract ${feature.<key>} + discovery-tool pointers + "replaces" overwrite semantic

Full suite: 890 passed, zero regressions.

Test plan

• pytest test_mcp/ --no-cov -q → 890 passed
• Pydantic models compile + import cleanly
• FastMCP registers the new tool + prompt (catalog grows 25 → 26)
• Manual smoke (Unit 6 of plan, deferred to follow-up): GEOGLOWS Demo prompt from /ce-debug 2026-05-21 against a real LLM, with no manual UI fallback step
• Tethysdash-side Unit 5 (preview UX fix for findUnresolvedFeatureTokens guard in the Edit Visualization sub-modal): deferred to separate PR in tethysapp-tethys_dash on feature/tethysdash-mcp-server

Plan

docs/plans/2026-05-21-002-feat-tethysdash-mcps-popup-modal-surface-plan.md