From e7e75b5c3083518b58f078568b2365ecf63a7943 Mon Sep 17 00:00:00 2001 From: George Date: Sat, 18 Jul 2026 16:30:14 +0200 Subject: [PATCH] Improve interactive table result experience --- README.md | 48 +-- apps/mcp-app/PRIVACY.md | 11 +- apps/mcp-app/package.json | 1 - apps/mcp-app/src/hosted-policy.test.ts | 19 + apps/mcp-app/src/hosted-policy.ts | 13 +- apps/mcp-app/src/hosted-server.test.ts | 69 +++- apps/mcp-app/src/hosted-server.ts | 110 ++++++ apps/mcp-app/src/presentation-bounds.test.ts | 36 ++ apps/mcp-app/src/presentation-bounds.ts | 80 +++-- apps/mcp-app/src/presentation-contract.ts | 288 ++++++++------- apps/mcp-app/src/presentation.ts | 50 ++- apps/mcp-app/src/server.test.ts | 2 +- apps/mcp-app/web/src/app.tsx | 51 ++- apps/mcp-app/web/src/chatgpt-compat.test.ts | 46 +++ apps/mcp-app/web/src/chatgpt-compat.ts | 105 ++++++ apps/mcp-app/web/src/format-duration.ts | 3 + apps/mcp-app/web/src/host-ui.test.ts | 90 +++++ apps/mcp-app/web/src/host-ui.ts | 110 +++++- apps/mcp-app/web/src/paged-results.tsx | 358 +++++++++++++++++++ apps/mcp-app/web/src/result-actions.tsx | 169 +++++---- apps/mcp-app/web/src/result-details.tsx | 42 ++- apps/mcp-app/web/src/results-table.test.tsx | 142 +++++++- apps/mcp-app/web/src/results-table.tsx | 42 ++- apps/mcp-app/web/src/styles.css | 140 ++++++-- apps/mcp-app/web/src/test-host.ts | 55 ++- apps/mcp-app/web/src/virtualized-results.tsx | 231 ------------ apps/mcp-app/web/src/widget-state.test.ts | 11 + apps/mcp-app/web/src/widget-state.ts | 19 +- apps/mcp-app/web/tests/widget.spec.ts | 84 ++++- package-lock.json | 28 -- packages/mcp/src/index.ts | 10 +- packages/mcp/src/query-execution.ts | 72 ++++ packages/mcp/src/query-result.ts | 17 +- packages/mcp/src/results.ts | 20 +- packages/mcp/src/schemas.ts | 25 +- packages/mcp/src/tools.ts | 90 +---- 36 files changed, 1966 insertions(+), 721 deletions(-) create mode 100644 apps/mcp-app/web/src/chatgpt-compat.test.ts create mode 100644 apps/mcp-app/web/src/chatgpt-compat.ts create mode 100644 apps/mcp-app/web/src/format-duration.ts create mode 100644 apps/mcp-app/web/src/paged-results.tsx delete mode 100644 apps/mcp-app/web/src/virtualized-results.tsx create mode 100644 packages/mcp/src/query-execution.ts diff --git a/README.md b/README.md index cc74206..e54f5b6 100644 --- a/README.md +++ b/README.md @@ -467,12 +467,14 @@ npm run dev:http It serves MCP at `http://127.0.0.1:3000/mcp` and process health at `http://127.0.0.1:3000/health`. Each MCP request gets a fresh stateless -`@starfetch-js/mcp` server. The HTTP surface keeps the 12 canonical -Starfetch tools unchanged and adds `starfetch_render_table`, which presents an -existing bounded `StarfetchTableViewV1` through the immutable -`ui://starfetch/table/v1` MCP Apps resource. The renderer never submits TAP -requests; ordinary MCP clients can continue using the canonical text and -structured results without loading the widget. Configuration is +`@starfetch-js/mcp` server. The HTTP surface keeps the 12 canonical Starfetch +tools unchanged and adds two UI-linked tools through the immutable +`ui://starfetch/table/v1` MCP Apps resource. `starfetch_render_table` presents +an existing table view without submitting a TAP request. +`starfetch_query_table` runs a synchronous JSON query for the interactive +scientific table; its full loaded table is widget-only while the model receives +a 20-row preview. Ordinary MCP clients can continue using the canonical text +and structured results without loading the widget. Configuration is environment-only: - `HOST` defaults to `127.0.0.1`; set `0.0.0.0` explicitly for all interfaces. @@ -486,8 +488,11 @@ environment-only: The anonymous HTTP policy is a fixed, tested product profile rather than a set of independently tunable environment variables. It caps MCP requests at 2 -MiB, TAP responses at 8 MiB, inline uploads at 1 MiB, `MAXREC` at 100, redirects -at 3, outbound requests at 4 concurrent operations, and tools at 60 seconds. +MiB, TAP responses at 8 MiB, inline uploads at 1 MiB, `MAXREC` at 10,000, +redirects at 3, outbound requests at 4 concurrent operations, and tools at 60 +seconds. Canonical synchronous queries still default to `MAXREC=100`; the +interactive table query defaults to `MAXREC=1000` and caps its widget payload +at 6 MiB. Job waits default to 30 seconds, cap at 45 seconds, and poll between 1 and 10 seconds. The process admits 100 MCP requests per minute globally; deployments that need per-client limits should enforce them at a trusted HTTPS ingress. @@ -558,14 +563,17 @@ allow Inspector's browser origins explicitly when starting the app: ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274 npm run dev:http ``` -The widget is a portable MCP Apps client. It uses the standard host bridge for -tool results, theme variables, display-mode requests, clipboard access, and file -downloads, so the table has no direct dependency on a ChatGPT- or Claude-only -browser global. Its React UI uses semantic table markup, TanStack Table sorting, -TanStack Virtual row rendering for larger results, and fine-grained Shiki SQL -highlighting for exact ADQL. Inline mode exposes the complete bounded result -through a capped two-axis scroll viewport. A labeled `Show more` or `Show less` -control below the table requests the corresponding host display mode. The +The widget uses the standard MCP Apps host bridge for tool results, theme +variables, display-mode requests, model-context updates, and file downloads. +It also reads ChatGPT's initial tool globals when present and uses ChatGPT's +file APIs only as a download fallback. Its React UI uses semantic table markup, +global TanStack Table sorting, page-scoped row selection, 100-row client-side +pages, and fine-grained Shiki SQL highlighting for exact ADQL. The table uses a +capped two-axis scroll viewport. An icon-only control in +the action toolbar requests fullscreen or inline display mode. Another action +can expose selected rows or the current 100-row page to the model for the next +turn; it does not expose the whole loaded table. The action remains available, +and each press replaces the previously pending model-context snapshot. The resource declares no network or static-resource domains and requests only clipboard-write permission. @@ -587,10 +595,10 @@ The image workflow publishes immutable containers to For ChatGPT Developer Mode or another remote MCP Apps host, expose the local MCP endpoint through HTTPS, add the resulting `/mcp` URL to the host, call a -canonical Starfetch tool, then pass its bounded table view to -`starfetch_render_table`. Verify light and dark themes, `Show more` and `Show -less`, horizontal scrolling, sorting, highlighted ADQL and copying, and TSV, -CSV, and JSON copy and download actions. Host-specific visual differences +metadata tool to inspect the target, then call `starfetch_query_table`. Verify +light and dark themes, fullscreen and inline modes, horizontal scrolling, +sorting, paging, highlighted ADQL and copying, current-page model context, and +TSV, CSV, and JSON copy and download actions. Host-specific visual differences should be handled through the bridge theme variables rather than a second component implementation. diff --git a/apps/mcp-app/PRIVACY.md b/apps/mcp-app/PRIVACY.md index c21a753..ee058c5 100644 --- a/apps/mcp-app/PRIVACY.md +++ b/apps/mcp-app/PRIVACY.md @@ -98,9 +98,14 @@ from the remote TAP service. ## Table renderer The interactive table receives bounded structured content from the MCP host. -It declares no external network or static-resource domains and does not send -table data to another service. It can request clipboard access so the user can -copy displayed data. +Scientific table queries can load up to 10,000 rows within a 6 MiB widget +payload while exposing only a short preview to the model. The user can +explicitly expose selected rows or the current 100-row page to the model for a +later turn. Each use replaces the previously pending page or selection. The +widget declares no external network or static-resource domains and can request +clipboard access so the user can copy displayed data. When the standard MCP +Apps download method is unavailable, ChatGPT can temporarily store a generated +export file to provide its download URL. ## User choices diff --git a/apps/mcp-app/package.json b/apps/mcp-app/package.json index d2f5fa4..eaff089 100644 --- a/apps/mcp-app/package.json +++ b/apps/mcp-app/package.json @@ -28,7 +28,6 @@ "@shikijs/themes": "4.3.1", "@starfetch-js/mcp": "0.2.3", "@tanstack/react-table": "8.21.3", - "@tanstack/react-virtual": "3.14.6", "hono": "4.12.27", "ipaddr.js": "2.4.0", "lucide-react": "1.24.0", diff --git a/apps/mcp-app/src/hosted-policy.test.ts b/apps/mcp-app/src/hosted-policy.test.ts index 086c285..510f1bd 100644 --- a/apps/mcp-app/src/hosted-policy.test.ts +++ b/apps/mcp-app/src/hosted-policy.test.ts @@ -40,6 +40,25 @@ describe("hosted MCP execution policy", () => { ).toThrow("WAIT_LIMIT_EXCEEDED"); }); + it("uses each tool's fallback while allowing table queries up to 10,000 rows", () => { + expect( + policy.prepareQuery({ + fallbackMaxrec: 1_000, + incomingSignal, + requestedMaxrec: undefined, + uploads: undefined, + }).maxrec, + ).toBe(1_000); + expect( + policy.prepareQuery({ + fallbackMaxrec: 100, + incomingSignal, + requestedMaxrec: 10_000, + uploads: undefined, + }).maxrec, + ).toBe(10_000); + }); + it("issues non-expiring capabilities bound to one job", () => { const jobUrl = "https://example.test/tap/async/job-1"; const capability = policy.issueJobCapability(jobUrl); diff --git a/apps/mcp-app/src/hosted-policy.ts b/apps/mcp-app/src/hosted-policy.ts index fca91f5..f38b75b 100644 --- a/apps/mcp-app/src/hosted-policy.ts +++ b/apps/mcp-app/src/hosted-policy.ts @@ -18,7 +18,7 @@ export const hostedPolicyLimits = Object.freeze({ maxRedirects: 3, maxRequestBytes: 2_097_152, maxResponseBytes: 8_388_608, - maxrec: 100, + maxrec: 10_000, ratePerMinute: 100, toolTimeoutMs: 60_000, wait: Object.freeze({ @@ -60,13 +60,13 @@ export function createHostedStarfetchMcpPolicy(options: { prepareQuery(input) { assertUploadsAllowed(input.uploads); return { - maxrec: effectiveMaxrec(input.requestedMaxrec), + maxrec: effectiveMaxrec(input.requestedMaxrec, input.fallbackMaxrec), signal: signal(input.incomingSignal), }; }, prepareRegistry(input) { return { - maxrec: effectiveMaxrec(input.requestedMaxrec), + maxrec: effectiveMaxrec(input.requestedMaxrec, input.fallbackMaxrec), signal: signal(input.incomingSignal), }; }, @@ -103,8 +103,11 @@ class HostedMcpPolicyError extends Error { } } -function effectiveMaxrec(requested: number | undefined): number { - const value = requested ?? hostedPolicyLimits.maxrec; +function effectiveMaxrec( + requested: number | undefined, + fallback: number, +): number { + const value = requested ?? fallback; if (value > hostedPolicyLimits.maxrec) { throw new HostedMcpPolicyError( "MAXREC_EXCEEDED", diff --git a/apps/mcp-app/src/hosted-server.test.ts b/apps/mcp-app/src/hosted-server.test.ts index c6e7c20..848d3ee 100644 --- a/apps/mcp-app/src/hosted-server.test.ts +++ b/apps/mcp-app/src/hosted-server.test.ts @@ -1,6 +1,6 @@ import { Client } from "@modelcontextprotocol/sdk/client/index.js"; import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; -import { describe, expect, it } from "vitest"; +import { describe, expect, it, vi } from "vitest"; import { createHostedStarfetchMcpServer } from "./hosted-server.js"; import { createHostedStarfetchMcpPolicy } from "./hosted-policy.js"; @@ -26,6 +26,12 @@ const expectedHostedToolAnnotations = { openWorldHint: false, readOnlyHint: true, }, + starfetch_query_table: { + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + readOnlyHint: false, + }, starfetch_tap_availability: { destructiveHint: false, idempotentHint: true, @@ -91,10 +97,18 @@ const expectedHostedToolAnnotations = { describe("hosted Starfetch MCP server", () => { it("adds the portable table renderer and immutable widget resource", async () => { const widgetHtml = "Starfetch results"; + const tapFetch = vi.fn(async () => + Promise.resolve( + new Response(createVotable(125), { + headers: { "content-type": "application/x-votable+xml" }, + }), + ), + ); const server = createHostedStarfetchMcpServer({ loadWidgetHtml: async () => widgetHtml, publicOrigin: "https://starfetch-production.run.app", mcp: { + fetch: tapFetch, policy: createHostedStarfetchMcpPolicy({ jobCapabilities: createJobCapabilityIssuer({ secret: new Uint8Array(32).fill(4), @@ -114,7 +128,7 @@ describe("hosted Starfetch MCP server", () => { await client.connect(clientTransport); const tools = await client.listTools(); - expect(tools.tools).toHaveLength(13); + expect(tools.tools).toHaveLength(14); expect( Object.fromEntries( tools.tools.map((tool) => [tool.name, tool.annotations]), @@ -140,6 +154,16 @@ describe("hosted Starfetch MCP server", () => { }), }), ); + expect(tools.tools).toContainEqual( + expect.objectContaining({ + name: "starfetch_query_table", + _meta: expect.objectContaining({ + ui: expect.objectContaining({ + resourceUri: "ui://starfetch/table/v1", + }), + }), + }), + ); const view = createStarfetchTableView({ sourceTool: "starfetch_list_presets", @@ -168,6 +192,30 @@ describe("hosted Starfetch MCP server", () => { structuredContent: view, }); + const queryResult = await client.callTool({ + name: "starfetch_query_table", + arguments: { + query: "SELECT TOP 125 source_id FROM mock_source", + url: "https://example.test/tap", + }, + }); + expect(queryResult.isError).toBeUndefined(); + expect(queryResult.structuredContent).toMatchObject({ + clipping: { reasons: ["rows"], sourceRows: 125 }, + rows: expect.arrayContaining([{ source_id: "1" }]), + source: { effectiveMaxrec: 1_000 }, + }); + expect( + (queryResult.structuredContent as { rows: unknown[] }).rows, + ).toHaveLength(20); + expect( + ( + queryResult._meta?.starfetchTableDataset as { + view: { rows: unknown[] }; + } + ).view.rows, + ).toHaveLength(125); + const resources = await client.listResources(); expect(resources.resources).toContainEqual( expect.objectContaining({ @@ -209,3 +257,20 @@ describe("hosted Starfetch MCP server", () => { } }); }); + +function createVotable(rowCount: number): string { + const rows = Array.from( + { length: rowCount }, + (_, index) => `${index + 1}`, + ).join(""); + return ` + + + Successful query + + + ${rows} +
+
+
`; +} diff --git a/apps/mcp-app/src/hosted-server.ts b/apps/mcp-app/src/hosted-server.ts index 8b66824..47fdaa9 100644 --- a/apps/mcp-app/src/hosted-server.ts +++ b/apps/mcp-app/src/hosted-server.ts @@ -7,15 +7,46 @@ import { } from "@modelcontextprotocol/ext-apps/server"; import { createStarfetchMcpServer, + executeStarfetchTapQuery, + tapQueryInputShape, + tapTargetInputShape, + unrestrictedStarfetchMcpPolicy, type StarfetchMcpServerOptions, } from "@starfetch-js/mcp"; +import { z } from "zod/v4"; import { + createStarfetchTableView, + createStarfetchWidgetTableDataset, starfetchTableViewV1Schema, type StarfetchTableViewV1, } from "./presentation.js"; +import { hostedPolicyLimits } from "./hosted-policy.js"; export const STARFETCH_TABLE_RESOURCE_URI = "ui://starfetch/table/v1"; +const hostedTableDefaultMaxrec = 1_000; +const modelPreviewRows = 20; + +const hostedTableQueryInputSchema = z + .object({ + ...tapTargetInputShape, + query: tapQueryInputShape.query, + runId: tapQueryInputShape.runId, + format: z.literal("json").default("json"), + maxrec: z + .number() + .int() + .nonnegative() + .max(hostedPolicyLimits.maxrec) + .optional() + .describe( + `TAP MAXREC row limit for the interactive table. Defaults to ${hostedTableDefaultMaxrec.toLocaleString("en-US")} and cannot exceed ${hostedPolicyLimits.maxrec.toLocaleString("en-US")}.`, + ), + }) + .refine((input) => input.service !== undefined || input.url !== undefined, { + message: "Specify service or url.", + path: ["service"], + }); export type HostedStarfetchMcpServerOptions = Readonly<{ loadWidgetHtml?: () => Promise; @@ -27,6 +58,10 @@ export function createHostedStarfetchMcpServer( options: HostedStarfetchMcpServerOptions = {}, ): ReturnType { const server = createStarfetchMcpServer(options.mcp); + const queryExecutionOptions = { + ...options.mcp, + policy: options.mcp?.policy ?? unrestrictedStarfetchMcpPolicy, + }; const loadWidgetHtml = options.loadWidgetHtml ?? loadBuiltWidgetHtml; const resourceMeta = { csp: { @@ -73,6 +108,60 @@ export function createHostedStarfetchMcpServer( }), ); + registerAppTool( + server, + "starfetch_query_table", + { + title: "Query an interactive Starfetch table", + description: + "Run a metadata-backed synchronous TAP ADQL query and show up to 10,000 rows in an interactive table. Prefer this over starfetch_tap_query followed by starfetch_render_table when the user wants to inspect scientific rows. The model receives a small preview; the widget privately receives the loaded table.", + inputSchema: hostedTableQueryInputSchema, + outputSchema: starfetchTableViewV1Schema, + annotations: { + destructiveHint: false, + idempotentHint: true, + openWorldHint: true, + readOnlyHint: false, + }, + _meta: { + ui: { + resourceUri: STARFETCH_TABLE_RESOURCE_URI, + visibility: ["model"], + }, + }, + }, + async (input, extra) => { + const result = await executeStarfetchTapQuery( + input, + extra.signal, + queryExecutionOptions, + hostedTableDefaultMaxrec, + ); + if (result.isError || result.structuredContent === undefined) { + return result; + } + + const presentationSource = { + sourceTool: "starfetch_tap_query", + structuredContent: result.structuredContent, + } as const; + const dataset = createStarfetchWidgetTableDataset(presentationSource); + const preview = createModelPreview( + createStarfetchTableView(presentationSource), + ); + return { + content: [ + { + type: "text", + text: renderQueryNarration(dataset.view, preview.rows.length), + }, + ], + structuredContent: preview, + _meta: { starfetchTableDataset: dataset }, + }; + }, + ); + registerAppResource( server, "Starfetch results table", @@ -101,6 +190,27 @@ function renderNarration(view: StarfetchTableViewV1): string { return `Rendered ${count} ${count === 1 ? "row" : "rows"} in the Starfetch results table.`; } +function createModelPreview(view: StarfetchTableViewV1): StarfetchTableViewV1 { + if (view.rows.length <= modelPreviewRows) return view; + + return starfetchTableViewV1Schema.parse({ + ...view, + rows: view.rows.slice(0, modelPreviewRows), + clipping: { + ...view.clipping, + reasons: Array.from(new Set([...view.clipping.reasons, "rows"])), + }, + }); +} + +function renderQueryNarration( + view: StarfetchTableViewV1, + previewRows: number, +): string { + const loadedRows = view.rows.length; + return `Loaded ${loadedRows} ${loadedRows === 1 ? "row" : "rows"} in the interactive Starfetch table. The model-visible preview contains ${previewRows} ${previewRows === 1 ? "row" : "rows"}.`; +} + let widgetHtmlPromise: Promise | undefined; function loadBuiltWidgetHtml(): Promise { diff --git a/apps/mcp-app/src/presentation-bounds.test.ts b/apps/mcp-app/src/presentation-bounds.test.ts index 66e25ef..466a149 100644 --- a/apps/mcp-app/src/presentation-bounds.test.ts +++ b/apps/mcp-app/src/presentation-bounds.test.ts @@ -2,12 +2,48 @@ import { describe, expect, it } from "vitest"; import { createStarfetchTableView, + createStarfetchWidgetTableDataset, STARFETCH_TABLE_VIEW_LIMITS_V1, StarfetchPresentationError, starfetchTableViewV1Schema, + starfetchWidgetTableDatasetV1Schema, } from "./presentation.js"; describe("Starfetch table view bounds", () => { + it("keeps the model view small while retaining the widget-only dataset", () => { + const source = { + sourceTool: "starfetch_tap_query", + structuredContent: { + data: { + content: JSON.stringify( + Array.from({ length: 125 }, (_, index) => ({ id: String(index) })), + ), + fields: [{ name: "id" }], + format: "json", + }, + diagnostics: { + durationMs: 1, + effectiveMaxrec: 1_000, + format: "json", + query: "SELECT TOP 125 id FROM catalog", + requestFormat: "votable", + target: { baseUrl: "https://example.test/tap" }, + uploadCount: 0, + }, + }, + }; + + const modelView = createStarfetchTableView(source); + const dataset = createStarfetchWidgetTableDataset(source); + + expect(modelView.rows).toHaveLength(100); + expect(dataset.view.rows).toHaveLength(125); + expect(starfetchTableViewV1Schema.safeParse(dataset.view).success).toBe( + false, + ); + expect(starfetchWidgetTableDatasetV1Schema.parse(dataset)).toEqual(dataset); + }); + it("clips only whole trailing rows and columns in a deterministic order", () => { const sourceRow = Object.fromEntries( Array.from( diff --git a/apps/mcp-app/src/presentation-bounds.ts b/apps/mcp-app/src/presentation-bounds.ts index ab55816..52986e3 100644 --- a/apps/mcp-app/src/presentation-bounds.ts +++ b/apps/mcp-app/src/presentation-bounds.ts @@ -2,23 +2,49 @@ import { containsOverlongString, serializedByteLength, STARFETCH_TABLE_VIEW_LIMITS_V1, + STARFETCH_WIDGET_TABLE_LIMITS_V1, StarfetchPresentationError, starfetchTableViewV1Schema, + starfetchWidgetTableDatasetV1Schema, type StarfetchTableViewDraft, + type StarfetchTableViewLimits, type StarfetchTableViewV1, + type StarfetchWidgetTableDatasetV1, } from "./presentation-contract.js"; export function finalizeStarfetchTableView( draft: StarfetchTableViewDraft, +): StarfetchTableViewV1 { + return finalizeTableView(draft, STARFETCH_TABLE_VIEW_LIMITS_V1, (view) => + starfetchTableViewV1Schema.parse(view), + ); +} + +export function finalizeStarfetchWidgetTableDataset( + draft: StarfetchTableViewDraft, +): StarfetchWidgetTableDatasetV1 { + const view = finalizeTableView( + draft, + STARFETCH_WIDGET_TABLE_LIMITS_V1, + (candidate) => + starfetchWidgetTableDatasetV1Schema.parse({ + datasetVersion: 1, + view: candidate, + }).view, + ); + return { datasetVersion: 1, view }; +} + +function finalizeTableView( + draft: StarfetchTableViewDraft, + limits: StarfetchTableViewLimits, + parse: (view: StarfetchTableViewV1) => StarfetchTableViewV1, ): StarfetchTableViewV1 { const sourceColumns = draft.columns.length; const sourceRows = draft.rows.length; - let columns = draft.columns.slice( - 0, - STARFETCH_TABLE_VIEW_LIMITS_V1.maxColumns, - ); + let columns = draft.columns.slice(0, limits.maxColumns); let rows = draft.rows - .slice(0, STARFETCH_TABLE_VIEW_LIMITS_V1.maxRows) + .slice(0, limits.maxRows) .map((row) => selectColumns(row, columns)); const reasons: StarfetchTableViewV1["clipping"]["reasons"] = []; @@ -26,12 +52,15 @@ export function finalizeStarfetchTableView( if (rows.length < sourceRows) reasons.push("rows"); if ( - containsOverlongString({ - columns, - rows, - source: draft.source, - title: draft.title, - }) + containsOverlongString( + { + columns, + rows, + source: draft.source, + title: draft.title, + }, + limits.maxStringBytes, + ) ) { throw new StarfetchPresentationError( "VALUE_TOO_LONG", @@ -52,25 +81,26 @@ export function finalizeStarfetchTableView( state: sourceRows === 0 ? "empty" : "populated", }; - if ( - serializedByteLength(view) > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxSerializedBytes - ) { + if (serializedByteLength(view) > limits.maxSerializedBytes) { reasons.push("bytes"); - while ( - rows.length > 0 && - serializedByteLength(view) > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxSerializedBytes - ) { - rows = rows.slice(0, -1); - view.rows = rows; + let minimum = 0; + let maximum = rows.length; + while (minimum < maximum) { + const candidateLength = Math.ceil((minimum + maximum) / 2); + view.rows = rows.slice(0, candidateLength); + if (serializedByteLength(view) <= limits.maxSerializedBytes) { + minimum = candidateLength; + } else { + maximum = candidateLength - 1; + } } + rows = rows.slice(0, minimum); + view.rows = rows; while ( columns.length > 0 && - serializedByteLength(view) > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxSerializedBytes + serializedByteLength(view) > limits.maxSerializedBytes ) { columns = columns.slice(0, -1); rows = rows.map((row) => selectColumns(row, columns)); @@ -79,7 +109,7 @@ export function finalizeStarfetchTableView( } } - return starfetchTableViewV1Schema.parse(view); + return parse(view); } function selectColumns( diff --git a/apps/mcp-app/src/presentation-contract.ts b/apps/mcp-app/src/presentation-contract.ts index a3981f9..be012bd 100644 --- a/apps/mcp-app/src/presentation-contract.ts +++ b/apps/mcp-app/src/presentation-contract.ts @@ -8,6 +8,21 @@ export const STARFETCH_TABLE_VIEW_LIMITS_V1 = { maxStringBytes: 4_096, } as const; +export const STARFETCH_WIDGET_TABLE_LIMITS_V1 = { + ...STARFETCH_TABLE_VIEW_LIMITS_V1, + maxCells: 320_000, + maxRows: 10_000, + maxSerializedBytes: 6_291_456, +} as const; + +export type StarfetchTableViewLimits = Readonly<{ + maxCells: number; + maxColumns: number; + maxRows: number; + maxSerializedBytes: number; + maxStringBytes: number; +}>; + export type StarfetchPresentationErrorCode = | "INVALID_SOURCE" | "UNSUPPORTED_FORMAT" @@ -98,145 +113,154 @@ const resultKindByTool = { starfetch_tap_tables: "tables", } as const; -export const starfetchTableViewV1Schema = z - .object({ - contractVersion: z.literal(1), - resultKind: z.enum([ - "async-query-rows", - "columns", - "presets", - "query-rows", - "registry-services", - "tables", - ]), - title: z.string(), - columns: z - .array(tableColumnSchema) - .max(STARFETCH_TABLE_VIEW_LIMITS_V1.maxColumns), - rows: z - .array(z.record(z.string(), jsonScalarSchema)) - .max(STARFETCH_TABLE_VIEW_LIMITS_V1.maxRows), - source: sourceSchema, - state: z.enum(["empty", "populated"]), - clipping: z.object({ - reasons: z.array(z.enum(["bytes", "columns", "rows"])), - sourceRows: z.number().int().nonnegative(), - sourceColumns: z.number().int().nonnegative(), - }), - }) - .superRefine((view, context) => { - const expectedKind = resultKindByTool[view.source.tool]; - if (view.resultKind !== expectedKind) { - context.addIssue({ - code: "custom", - message: "Result kind does not match the source tool.", - path: ["resultKind"], - }); - } +function createTableViewSchema(limits: StarfetchTableViewLimits) { + return z + .object({ + contractVersion: z.literal(1), + resultKind: z.enum([ + "async-query-rows", + "columns", + "presets", + "query-rows", + "registry-services", + "tables", + ]), + title: z.string(), + columns: z.array(tableColumnSchema).max(limits.maxColumns), + rows: z.array(z.record(z.string(), jsonScalarSchema)).max(limits.maxRows), + source: sourceSchema, + state: z.enum(["empty", "populated"]), + clipping: z.object({ + reasons: z.array(z.enum(["bytes", "columns", "rows"])), + sourceRows: z.number().int().nonnegative(), + sourceColumns: z.number().int().nonnegative(), + }), + }) + .superRefine((view, context) => { + const expectedKind = resultKindByTool[view.source.tool]; + if (view.resultKind !== expectedKind) { + context.addIssue({ + code: "custom", + message: "Result kind does not match the source tool.", + path: ["resultKind"], + }); + } + + const columnKeys = view.columns.map((column) => column.key); + if (new Set(columnKeys).size !== columnKeys.length) { + context.addIssue({ + code: "custom", + message: "Table view column keys must be unique.", + path: ["columns"], + }); + } + for (const [index, row] of view.rows.entries()) { + if ( + Object.keys(row).length !== columnKeys.length || + columnKeys.some((key) => !(key in row)) + ) { + context.addIssue({ + code: "custom", + message: "Table view rows must match the ordered columns.", + path: ["rows", index], + }); + } + } + + const expectedState = + view.clipping.sourceRows === 0 ? "empty" : "populated"; + if (view.state !== expectedState) { + context.addIssue({ + code: "custom", + message: "Table view state does not match its source row count.", + path: ["state"], + }); + } + const rowClippingApplied = view.clipping.sourceRows > view.rows.length; + const columnClippingApplied = + view.clipping.sourceColumns > view.columns.length; + const clippingApplied = rowClippingApplied || columnClippingApplied; + const reasons = new Set(view.clipping.reasons); + const reasonsMatchClipping = + (!rowClippingApplied || reasons.has("rows") || reasons.has("bytes")) && + (!columnClippingApplied || + reasons.has("columns") || + reasons.has("bytes")) && + (rowClippingApplied || !reasons.has("rows")) && + (columnClippingApplied || !reasons.has("columns")) && + (clippingApplied || !reasons.has("bytes")); - const columnKeys = view.columns.map((column) => column.key); - if (new Set(columnKeys).size !== columnKeys.length) { - context.addIssue({ - code: "custom", - message: "Table view column keys must be unique.", - path: ["columns"], - }); - } - for (const [index, row] of view.rows.entries()) { if ( - Object.keys(row).length !== columnKeys.length || - columnKeys.some((key) => !(key in row)) + view.clipping.sourceRows < view.rows.length || + view.clipping.sourceColumns < view.columns.length || + reasons.size !== view.clipping.reasons.length || + !reasonsMatchClipping ) { context.addIssue({ code: "custom", - message: "Table view rows must match the ordered columns.", - path: ["rows", index], + message: "Table view clipping metadata is inconsistent.", + path: ["clipping"], }); } - } - const expectedState = - view.clipping.sourceRows === 0 ? "empty" : "populated"; - if (view.state !== expectedState) { - context.addIssue({ - code: "custom", - message: "Table view state does not match its source row count.", - path: ["state"], - }); - } - const rowClippingApplied = view.clipping.sourceRows > view.rows.length; - const columnClippingApplied = - view.clipping.sourceColumns > view.columns.length; - const clippingApplied = rowClippingApplied || columnClippingApplied; - const reasons = new Set(view.clipping.reasons); - const reasonsMatchClipping = - (!rowClippingApplied || reasons.has("rows") || reasons.has("bytes")) && - (!columnClippingApplied || - reasons.has("columns") || - reasons.has("bytes")) && - (rowClippingApplied || !reasons.has("rows")) && - (columnClippingApplied || !reasons.has("columns")) && - (clippingApplied || !reasons.has("bytes")); + if ( + (view.resultKind === "query-rows" || + view.resultKind === "async-query-rows") && + view.rows.some((row) => + Object.values(row).some( + (value) => value !== null && typeof value !== "string", + ), + ) + ) { + context.addIssue({ + code: "custom", + message: "Scientific row values must be strings or null.", + path: ["rows"], + }); + } + + if (view.rows.length * view.columns.length > limits.maxCells) { + context.addIssue({ + code: "custom", + message: "Table view exceeds the cell ceiling.", + path: ["rows"], + }); + } - if ( - view.clipping.sourceRows < view.rows.length || - view.clipping.sourceColumns < view.columns.length || - reasons.size !== view.clipping.reasons.length || - !reasonsMatchClipping - ) { - context.addIssue({ - code: "custom", - message: "Table view clipping metadata is inconsistent.", - path: ["clipping"], - }); - } + if (containsOverlongString(view, limits.maxStringBytes)) { + context.addIssue({ + code: "custom", + message: "Table view contains an overlong string.", + }); + } - if ( - (view.resultKind === "query-rows" || - view.resultKind === "async-query-rows") && - view.rows.some((row) => - Object.values(row).some( - (value) => value !== null && typeof value !== "string", - ), - ) - ) { - context.addIssue({ - code: "custom", - message: "Scientific row values must be strings or null.", - path: ["rows"], - }); - } + if (serializedByteLength(view) > limits.maxSerializedBytes) { + context.addIssue({ + code: "custom", + message: "Table view exceeds the serialized byte ceiling.", + }); + } + }); +} - if ( - view.rows.length * view.columns.length > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxCells - ) { - context.addIssue({ - code: "custom", - message: "Table view exceeds the cell ceiling.", - path: ["rows"], - }); - } +export const starfetchTableViewV1Schema = createTableViewSchema( + STARFETCH_TABLE_VIEW_LIMITS_V1, +); - if (containsOverlongString(view)) { - context.addIssue({ - code: "custom", - message: "Table view contains an overlong string.", - }); - } +const starfetchWidgetTableViewV1Schema = createTableViewSchema( + STARFETCH_WIDGET_TABLE_LIMITS_V1, +); - if ( - serializedByteLength(view) > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxSerializedBytes - ) { - context.addIssue({ - code: "custom", - message: "Table view exceeds the serialized byte ceiling.", - }); - } - }); +export const starfetchWidgetTableDatasetV1Schema = z.object({ + datasetVersion: z.literal(1), + view: starfetchWidgetTableViewV1Schema, +}); export type StarfetchTableViewV1 = z.infer; +export type StarfetchWidgetTableDatasetV1 = z.infer< + typeof starfetchWidgetTableDatasetV1Schema +>; +export type StarfetchWidgetTableViewV1 = StarfetchWidgetTableDatasetV1["view"]; export type StarfetchTableViewDraft = Pick< StarfetchTableViewV1, @@ -247,21 +271,23 @@ export function serializedByteLength(value: unknown): number { return new TextEncoder().encode(JSON.stringify(value)).byteLength; } -export function containsOverlongString(value: unknown): boolean { +export function containsOverlongString( + value: unknown, + maxStringBytes: number = STARFETCH_TABLE_VIEW_LIMITS_V1.maxStringBytes, +): boolean { if (typeof value === "string") { - return ( - new TextEncoder().encode(value).byteLength > - STARFETCH_TABLE_VIEW_LIMITS_V1.maxStringBytes - ); + return new TextEncoder().encode(value).byteLength > maxStringBytes; } if (Array.isArray(value)) { - return value.some(containsOverlongString); + return value.some((item) => containsOverlongString(item, maxStringBytes)); } return ( typeof value === "object" && value !== null && - Object.values(value).some(containsOverlongString) + Object.values(value).some((item) => + containsOverlongString(item, maxStringBytes), + ) ); } diff --git a/apps/mcp-app/src/presentation.ts b/apps/mcp-app/src/presentation.ts index 6d99b2d..6caeb59 100644 --- a/apps/mcp-app/src/presentation.ts +++ b/apps/mcp-app/src/presentation.ts @@ -4,18 +4,26 @@ import { } from "@starfetch-js/mcp"; import { z } from "zod/v4"; -import { finalizeStarfetchTableView } from "./presentation-bounds.js"; +import { + finalizeStarfetchTableView, + finalizeStarfetchWidgetTableDataset, +} from "./presentation-bounds.js"; import { StarfetchPresentationError, + type StarfetchTableViewDraft, type StarfetchTableViewV1, + type StarfetchWidgetTableDatasetV1, } from "./presentation-contract.js"; export { STARFETCH_TABLE_VIEW_LIMITS_V1, + STARFETCH_WIDGET_TABLE_LIMITS_V1, StarfetchPresentationError, starfetchTableViewV1Schema, + starfetchWidgetTableDatasetV1Schema, type StarfetchPresentationErrorCode, type StarfetchTableViewV1, + type StarfetchWidgetTableDatasetV1, } from "./presentation-contract.js"; type CanonicalScientificResult = Extract< @@ -44,8 +52,18 @@ const scientificRowsSchema = z.array( ); export function createStarfetchTableView(input: unknown): StarfetchTableViewV1 { + return finalizeStarfetchTableView(createStarfetchTableDraft(input)); +} + +export function createStarfetchWidgetTableDataset( + input: unknown, +): StarfetchWidgetTableDatasetV1 { + return finalizeStarfetchWidgetTableDataset(createStarfetchTableDraft(input)); +} + +function createStarfetchTableDraft(input: unknown): StarfetchTableViewDraft { try { - return createStarfetchTableViewUnchecked(input); + return createStarfetchTableDraftUnchecked(input); } catch (error) { if (error instanceof StarfetchPresentationError) { throw error; @@ -58,9 +76,9 @@ export function createStarfetchTableView(input: unknown): StarfetchTableViewV1 { } } -function createStarfetchTableViewUnchecked( +function createStarfetchTableDraftUnchecked( input: unknown, -): StarfetchTableViewV1 { +): StarfetchTableViewDraft { const result = parseStarfetchTablePresentationSource(input); switch (result.sourceTool) { @@ -78,13 +96,13 @@ function createStarfetchTableViewUnchecked( syncRequest: preset.syncRequest ?? null, })); - return finalizeStarfetchTableView({ + return { columns, resultKind: "presets", rows, source: { tool: result.sourceTool }, title: "Starfetch TAP service presets", - }); + }; } case "starfetch_registry_search": { @@ -105,7 +123,7 @@ function createStarfetchTableViewUnchecked( standardId: service.standardId, })); - return finalizeStarfetchTableView({ + return { columns, resultKind: "registry-services", rows, @@ -114,7 +132,7 @@ function createStarfetchTableViewUnchecked( tool: result.sourceTool, }, title: "TAP registry service matches", - }); + }; } case "starfetch_tap_tables": { @@ -130,13 +148,13 @@ function createStarfetchTableViewUnchecked( })); const target = result.structuredContent.diagnostics.target; - return finalizeStarfetchTableView({ + return { columns, resultKind: "tables", rows, source: { target, tool: result.sourceTool }, title: `${targetName(target)} tables`, - }); + }; } case "starfetch_tap_columns": { @@ -156,7 +174,7 @@ function createStarfetchTableViewUnchecked( })); const diagnostics = result.structuredContent.diagnostics; - return finalizeStarfetchTableView({ + return { columns, resultKind: "columns", rows, @@ -166,7 +184,7 @@ function createStarfetchTableViewUnchecked( tool: result.sourceTool, }, title: `${diagnostics.table} columns`, - }); + }; } case "starfetch_tap_query": { @@ -175,7 +193,7 @@ function createStarfetchTableViewUnchecked( const rows = parseScientificRows(data.content); assertScientificRowsMatchFields(rows, data.fields); - return finalizeStarfetchTableView({ + return { columns: scientificColumns(data.fields), resultKind: "query-rows", rows, @@ -193,7 +211,7 @@ function createStarfetchTableViewUnchecked( tool: result.sourceTool, }, title: `${targetName(diagnostics.target)} query results`, - }); + }; } case "starfetch_tap_job_fetch": { @@ -202,7 +220,7 @@ function createStarfetchTableViewUnchecked( const rows = parseScientificRows(data.content); assertScientificRowsMatchFields(rows, data.fields); - return finalizeStarfetchTableView({ + return { columns: scientificColumns(data.fields), resultKind: "async-query-rows", rows, @@ -217,7 +235,7 @@ function createStarfetchTableViewUnchecked( tool: result.sourceTool, }, title: `${targetName(diagnostics.target)} async job results`, - }); + }; } } diff --git a/apps/mcp-app/src/server.test.ts b/apps/mcp-app/src/server.test.ts index c400eb2..5514af0 100644 --- a/apps/mcp-app/src/server.test.ts +++ b/apps/mcp-app/src/server.test.ts @@ -130,7 +130,7 @@ describe("Starfetch MCP HTTP app", () => { const result = await client.callTool({ arguments: { format: "json", - maxrec: 101, + maxrec: 10_001, query: "SELECT TOP 1 source_id FROM source", url: "https://example.test/tap", }, diff --git a/apps/mcp-app/web/src/app.tsx b/apps/mcp-app/web/src/app.tsx index 25b8782..b10a2b9 100644 --- a/apps/mcp-app/web/src/app.tsx +++ b/apps/mcp-app/web/src/app.tsx @@ -5,6 +5,11 @@ import { } from "@modelcontextprotocol/ext-apps/react"; import { useEffect, useMemo, useState } from "react"; +import { + saveFileThroughChatGpt, + subscribeToChatGptToolResults, + writeClipboardWithFallback, +} from "./chatgpt-compat.js"; import { StarfetchHostSession, type HostContextListener, @@ -26,7 +31,7 @@ export function StarfetchApp() { setDecoded( result.isError ? { ok: false, message: "Starfetch could not render this result." } - : decodeTableView(result.structuredContent), + : decodeTableView(result.structuredContent, result._meta), ); }; createdApp.ontoolcancelled = () => { @@ -40,10 +45,37 @@ export function StarfetchApp() { }); useHostStyleVariables(app, app?.getHostContext()); + useEffect(() => { + if (!isConnected) return; + return subscribeToChatGptToolResults((snapshot) => { + const next = decodeTableView( + snapshot.structuredContent, + snapshot.metadata, + ); + if (next.ok) setDecoded(next); + }); + }, [isConnected]); + + useEffect(() => { + if (!isConnected || decoded !== undefined) return; + const timeout = window.setTimeout(() => { + setDecoded({ + ok: false, + message: + "The host did not provide a table result. Run the table query again.", + }); + }, 10_000); + return () => window.clearTimeout(timeout); + }, [decoded, isConnected]); + const host = useMemo( () => app - ? new StarfetchHostSession(createAppBridge(app), writeClipboard) + ? new StarfetchHostSession( + createAppBridge(app), + writeClipboardWithFallback, + saveFileThroughChatGpt, + ) : null, [app], ); @@ -83,19 +115,18 @@ function createAppBridge(app: App): StarfetchHostBridge { async requestDisplayMode(mode: StarfetchDisplayMode) { return (await app.requestDisplayMode({ mode })).mode; }, + updateModelContext: (params) => app.updateModelContext(params), }; } -function writeClipboard(value: string): Promise { - if (navigator.clipboard?.writeText === undefined) { - return Promise.reject(new Error("Clipboard unavailable")); - } - return navigator.clipboard.writeText(value); -} - function LoadingState({ message }: { message: string }) { return ( -
+
+

{message}

); diff --git a/apps/mcp-app/web/src/chatgpt-compat.test.ts b/apps/mcp-app/web/src/chatgpt-compat.test.ts new file mode 100644 index 0000000..333de16 --- /dev/null +++ b/apps/mcp-app/web/src/chatgpt-compat.test.ts @@ -0,0 +1,46 @@ +import { afterEach, describe, expect, it, vi } from "vitest"; + +import { + normalizeChatGptToolMetadata, + subscribeToChatGptToolResults, +} from "./chatgpt-compat.js"; + +afterEach(() => { + delete window.openai; +}); + +describe("ChatGPT compatibility adapter", () => { + it("normalizes only the supported metadata envelopes", () => { + const metadata = { starfetchTableDataset: { datasetVersion: 1 } }; + + expect(normalizeChatGptToolMetadata(metadata)).toBe(metadata); + expect( + normalizeChatGptToolMetadata({ + mcp_tool_result: { _meta: metadata }, + }), + ).toBe(metadata); + expect( + normalizeChatGptToolMetadata({ + call_tool_result: { _meta: metadata }, + }), + ).toBeUndefined(); + }); + + it("publishes the initial and every subsequent ChatGPT tool snapshot", () => { + const listener = vi.fn(); + window.openai = { toolOutput: { page: 1 } }; + const unsubscribe = subscribeToChatGptToolResults(listener); + + window.openai = { toolOutput: { page: 2 } }; + window.dispatchEvent(new Event("openai:set_globals")); + + expect(listener).toHaveBeenCalledTimes(2); + expect(listener).toHaveBeenNthCalledWith(1, { + structuredContent: { page: 1 }, + }); + expect(listener).toHaveBeenNthCalledWith(2, { + structuredContent: { page: 2 }, + }); + unsubscribe(); + }); +}); diff --git a/apps/mcp-app/web/src/chatgpt-compat.ts b/apps/mcp-app/web/src/chatgpt-compat.ts new file mode 100644 index 0000000..fdacd0b --- /dev/null +++ b/apps/mcp-app/web/src/chatgpt-compat.ts @@ -0,0 +1,105 @@ +export type ChatGptToolSnapshot = Readonly<{ + metadata?: Record; + structuredContent: unknown; +}>; + +type ChatGptOpenAi = Readonly<{ + getFileDownloadUrl?: (input: { + fileId: string; + }) => Promise<{ downloadUrl: string }>; + openExternal?: (input: { href: string }) => void; + toolOutput?: unknown; + toolResponseMetadata?: unknown; + uploadFile?: (file: File) => Promise<{ fileId: string }>; +}>; + +declare global { + interface Window { + openai?: ChatGptOpenAi; + } +} + +export function subscribeToChatGptToolResults( + listener: (snapshot: ChatGptToolSnapshot) => void, +): () => void { + const publish = () => { + const snapshot = readChatGptToolSnapshot(); + if (snapshot) listener(snapshot); + }; + publish(); + window.addEventListener("openai:set_globals", publish); + return () => window.removeEventListener("openai:set_globals", publish); +} + +export function normalizeChatGptToolMetadata( + value: unknown, +): Record | undefined { + if (!isRecord(value)) return undefined; + if ("starfetchTableDataset" in value) return value; + + const toolResult = value.mcp_tool_result; + if (!isRecord(toolResult) || !isRecord(toolResult._meta)) return undefined; + return toolResult._meta; +} + +export async function writeClipboardWithFallback(value: string): Promise { + try { + if (navigator.clipboard?.writeText !== undefined) { + await navigator.clipboard.writeText(value); + return; + } + } catch { + // Continue to the synchronous copy path allowed by older iframe hosts. + } + + const textarea = document.createElement("textarea"); + textarea.value = value; + textarea.setAttribute("readonly", ""); + textarea.style.position = "fixed"; + textarea.style.opacity = "0"; + document.body.append(textarea); + textarea.select(); + const copied = document.execCommand("copy"); + textarea.remove(); + if (!copied) throw new Error("Clipboard unavailable"); +} + +export async function saveFileThroughChatGpt( + filename: string, + mimeType: string, + text: string, +): Promise { + const openai = window.openai; + if ( + openai?.uploadFile === undefined || + openai.getFileDownloadUrl === undefined || + openai.openExternal === undefined + ) { + return false; + } + + try { + const { fileId } = await openai.uploadFile( + new File([text], filename, { type: mimeType }), + ); + const { downloadUrl } = await openai.getFileDownloadUrl({ fileId }); + openai.openExternal({ href: downloadUrl }); + return true; + } catch { + return false; + } +} + +function readChatGptToolSnapshot(): ChatGptToolSnapshot | undefined { + const openai = window.openai; + if (openai?.toolOutput === undefined) return undefined; + const metadata = normalizeChatGptToolMetadata(openai.toolResponseMetadata); + return { + structuredContent: openai.toolOutput, + ...(metadata === undefined ? {} : { metadata }), + }; +} + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null; +} diff --git a/apps/mcp-app/web/src/format-duration.ts b/apps/mcp-app/web/src/format-duration.ts new file mode 100644 index 0000000..bb799b0 --- /dev/null +++ b/apps/mcp-app/web/src/format-duration.ts @@ -0,0 +1,3 @@ +export function formatDurationMs(durationMs: number): string { + return `${Math.round(durationMs)} ms`; +} diff --git a/apps/mcp-app/web/src/host-ui.test.ts b/apps/mcp-app/web/src/host-ui.test.ts index 3320d63..8a5792b 100644 --- a/apps/mcp-app/web/src/host-ui.test.ts +++ b/apps/mcp-app/web/src/host-ui.test.ts @@ -95,6 +95,93 @@ describe("StarfetchHostSession", () => { }); expect(writeClipboard).not.toHaveBeenCalled(); }); + + it("falls back to the ChatGPT file flow when standard download is unavailable", async () => { + const saveFileFallback = vi.fn().mockResolvedValue(true); + const session = new StarfetchHostSession( + createBridge({ + context: { displayMode: "inline" }, + requestDisplayMode: vi.fn(), + }), + vi.fn(), + saveFileFallback, + ); + + await expect( + session.saveFile("starfetch-results.csv", "text/csv", "id\n42"), + ).resolves.toBe(true); + expect(saveFileFallback).toHaveBeenCalledWith( + "starfetch-results.csv", + "text/csv", + "id\n42", + ); + }); + + it("replaces model context with text rows when modalities are unspecified", async () => { + const updateModelContext = vi.fn().mockResolvedValue({}); + const session = new StarfetchHostSession( + createBridge({ + capabilities: { updateModelContext: {} }, + context: { displayMode: "inline" }, + requestDisplayMode: vi.fn(), + updateModelContext, + }), + vi.fn(), + ); + + await expect( + session.analyzeRows("Gaia results", 2, 4, "selection", [ + { source_id: "42" }, + ]), + ).resolves.toBe(true); + await expect( + session.analyzeRows("Gaia results", 3, 4, "page", [{ source_id: "84" }]), + ).resolves.toBe(true); + expect(updateModelContext).toHaveBeenCalledTimes(2); + expect(updateModelContext).toHaveBeenNthCalledWith(1, { + content: [ + expect.objectContaining({ + text: expect.stringContaining('"source_id": "42"'), + }), + ], + }); + expect(updateModelContext).toHaveBeenNthCalledWith(2, { + content: [ + expect.objectContaining({ + text: expect.stringContaining('"source_id": "84"'), + }), + ], + }); + }); + + it("uses structured rows when the host advertises structured context", async () => { + const updateModelContext = vi.fn().mockResolvedValue({}); + const session = new StarfetchHostSession( + createBridge({ + capabilities: { updateModelContext: { structuredContent: {} } }, + context: { displayMode: "inline" }, + requestDisplayMode: vi.fn(), + updateModelContext, + }), + vi.fn(), + ); + + await expect( + session.analyzeRows("Gaia results", 2, 4, "selection", [ + { source_id: "42" }, + ]), + ).resolves.toBe(true); + expect(updateModelContext).toHaveBeenCalledWith({ + structuredContent: { + page: 2, + pageCount: 4, + rowCount: 1, + rows: [{ source_id: "42" }], + scope: "selection", + title: "Gaia results", + }, + }); + }); }); function createBridge({ @@ -103,6 +190,7 @@ function createBridge({ context, downloadFile = vi.fn(), requestDisplayMode, + updateModelContext = vi.fn(), }: { capabilities?: StarfetchHostCapabilities; captureHostContextListener?: (listener: HostContextListener) => void; @@ -111,6 +199,7 @@ function createBridge({ requestDisplayMode: ( mode: StarfetchDisplayMode, ) => Promise; + updateModelContext?: StarfetchHostBridge["updateModelContext"]; }): StarfetchHostBridge { return { addHostContextListener: (listener) => @@ -120,5 +209,6 @@ function createBridge({ getHostContext: () => context, removeHostContextListener: vi.fn(), requestDisplayMode, + updateModelContext, }; } diff --git a/apps/mcp-app/web/src/host-ui.ts b/apps/mcp-app/web/src/host-ui.ts index dc55a16..8304966 100644 --- a/apps/mcp-app/web/src/host-ui.ts +++ b/apps/mcp-app/web/src/host-ui.ts @@ -18,19 +18,30 @@ export type StarfetchHostBridge = Readonly<{ getHostContext(): StarfetchHostContext | undefined; removeHostContextListener(listener: HostContextListener): void; requestDisplayMode(mode: StarfetchDisplayMode): Promise; + updateModelContext( + params: Parameters[0], + ): ReturnType; }>; export type StarfetchHostSnapshot = Readonly<{ + canAnalyze: boolean; canExpand: boolean; mode: StarfetchDisplayMode; }>; +export type AnalysisScope = "page" | "selection"; + export class StarfetchHostSession { readonly #bridge: StarfetchHostBridge; #context: StarfetchHostContext; readonly #listeners = new Set<() => void>(); #snapshot: StarfetchHostSnapshot; readonly #writeClipboard: (value: string) => Promise; + readonly #saveFileFallback: ( + filename: string, + mimeType: string, + text: string, + ) => Promise; readonly #updateContext = (context: StarfetchHostContext) => { this.#context = { ...this.#context, ...context }; this.#publish(); @@ -39,11 +50,20 @@ export class StarfetchHostSession { constructor( bridge: StarfetchHostBridge, writeClipboard: (value: string) => Promise, + saveFileFallback: ( + filename: string, + mimeType: string, + text: string, + ) => Promise = async () => false, ) { this.#bridge = bridge; this.#writeClipboard = writeClipboard; + this.#saveFileFallback = saveFileFallback; this.#context = bridge.getHostContext() ?? {}; - this.#snapshot = createSnapshot(this.#context); + this.#snapshot = createSnapshot( + this.#context, + bridge.getHostCapabilities(), + ); bridge.addHostContextListener(this.#updateContext); } @@ -88,7 +108,7 @@ export class StarfetchHostSession { text: string, ): Promise { if (this.#bridge.getHostCapabilities()?.downloadFile === undefined) { - return false; + return this.#saveFileFallback(filename, mimeType, text); } try { @@ -110,17 +130,97 @@ export class StarfetchHostSession { } } + async analyzeRows( + title: string, + page: number, + pageCount: number, + scope: AnalysisScope, + rows: ReadonlyArray>, + ): Promise { + const modalities = this.#bridge.getHostCapabilities()?.updateModelContext; + const supportsText = + modalities !== undefined && + (modalities.text !== undefined || Object.keys(modalities).length === 0); + const supportsStructured = modalities?.structuredContent !== undefined; + if ( + modalities === undefined || + (!supportsText && !supportsStructured) || + rows.length === 0 || + rows.length > 100 + ) { + return false; + } + + try { + const snapshot = { + page, + pageCount, + rowCount: rows.length, + rows, + scope, + title, + }; + const subject = + scope === "selection" + ? `${rows.length} selected rows from` + : "the visible rows on"; + const rowMeaning = + scope === "selection" + ? "the user's current selection" + : "the current page"; + const description = `The user chose to analyze ${subject} page ${page} of ${pageCount} in ${title}. Treat these rows as ${rowMeaning}, not the complete query result.`; + await this.#bridge.updateModelContext({ + ...(!supportsText + ? {} + : { + content: [ + { + type: "text" as const, + text: !supportsStructured + ? `${description}\n\nStarfetch table snapshot:\n${JSON.stringify(snapshot, null, 2)}` + : description, + }, + ], + }), + ...(!supportsStructured ? {} : { structuredContent: snapshot }), + }); + return true; + } catch { + return false; + } + } + #publish(): void { - this.#snapshot = createSnapshot(this.#context); + this.#snapshot = createSnapshot( + this.#context, + this.#bridge.getHostCapabilities(), + ); for (const listener of this.#listeners) { listener(); } } } -function createSnapshot(context: StarfetchHostContext): StarfetchHostSnapshot { +function createSnapshot( + context: StarfetchHostContext, + capabilities?: StarfetchHostCapabilities, +): StarfetchHostSnapshot { return { - canExpand: context.availableDisplayModes?.includes("fullscreen") ?? false, + canAnalyze: supportsTableContext(capabilities?.updateModelContext), + canExpand: + context.platform !== "mobile" && + (context.availableDisplayModes?.includes("fullscreen") ?? false), mode: context.displayMode ?? "inline", }; } + +function supportsTableContext( + modalities: StarfetchHostCapabilities["updateModelContext"], +): boolean { + return ( + modalities !== undefined && + (Object.keys(modalities).length === 0 || + modalities.text !== undefined || + modalities.structuredContent !== undefined) + ); +} diff --git a/apps/mcp-app/web/src/paged-results.tsx b/apps/mcp-app/web/src/paged-results.tsx new file mode 100644 index 0000000..e4f3c3d --- /dev/null +++ b/apps/mcp-app/web/src/paged-results.tsx @@ -0,0 +1,358 @@ +import { + flexRender, + getCoreRowModel, + getSortedRowModel, + useReactTable, + type ColumnDef, + type SortingState, +} from "@tanstack/react-table"; +import { + ArrowDown, + ArrowUp, + ChevronFirst, + ChevronLast, + ChevronLeft, + ChevronRight, + ChevronsUpDown, +} from "lucide-react"; +import { + useEffect, + useMemo, + useRef, + useState, + useSyncExternalStore, +} from "react"; + +import type { StarfetchTableViewV1 } from "../../src/presentation-contract.js"; +import { type StarfetchHostSession } from "./host-ui.js"; +import { ResultActions } from "./result-actions.js"; +import { ResultNotices } from "./result-details.js"; + +type TableRow = StarfetchTableViewV1["rows"][number]; +const pageSize = 100; + +export function PagedResults({ + host, + onStatus, + view, +}: Readonly<{ + host: StarfetchHostSession; + onStatus: (status: string) => void; + view: StarfetchTableViewV1; +}>) { + const [sorting, setSorting] = useState([]); + const [page, setPage] = useState(0); + const [selectedRowIds, setSelectedRowIds] = useState>( + () => new Set(), + ); + const scrollElement = useRef(null); + const hostSnapshot = useSyncExternalStore( + (listener) => host.subscribe(listener), + () => host.getSnapshot(), + ); + const columns = useMemo[]>( + () => + view.columns.map((column) => ({ + accessorFn: (row) => row[column.key] ?? undefined, + id: column.key, + header: column.label, + meta: column, + sortUndefined: "last", + sortingFn: isNumericDatatype(column.datatype) + ? compareNumericCells + : "alphanumeric", + })), + [view.columns], + ); + const table = useReactTable({ + columns, + data: view.rows, + getCoreRowModel: getCoreRowModel(), + getSortedRowModel: getSortedRowModel(), + onSortingChange(updater) { + setSelectedRowIds(new Set()); + setPage(0); + setSorting(updater); + }, + state: { sorting }, + }); + const sortedRows = table.getRowModel().rows; + const pageCount = Math.max(1, Math.ceil(sortedRows.length / pageSize)); + const currentPage = Math.min(page, pageCount - 1); + const pageRows = sortedRows.slice( + currentPage * pageSize, + (currentPage + 1) * pageSize, + ); + const selectedPageRows = pageRows.filter((row) => selectedRowIds.has(row.id)); + const analysisRows = ( + selectedPageRows.length > 0 ? selectedPageRows : pageRows + ).map((row) => row.original); + const analysisScope = selectedPageRows.length > 0 ? "selection" : "page"; + const allPageRowsSelected = + pageRows.length > 0 && selectedPageRows.length === pageRows.length; + const somePageRowsSelected = + selectedPageRows.length > 0 && !allPageRowsSelected; + useEffect(() => { + scrollElement.current?.scrollTo?.({ left: 0, top: 0 }); + }, [currentPage]); + + const changePage = (nextPage: number) => { + setSelectedRowIds(new Set()); + setPage(nextPage); + }; + const togglePageRows = () => { + setSelectedRowIds( + allPageRowsSelected ? new Set() : new Set(pageRows.map((row) => row.id)), + ); + }; + const toggleRow = (rowId: string) => { + setSelectedRowIds((current) => { + const next = new Set(current); + if (next.has(rowId)) next.delete(rowId); + else next.add(rowId); + return next; + }); + }; + + return ( + <> + row.original)} + view={view} + /> + +
+ + + {table.getHeaderGroups().map((headerGroup) => ( + + + {headerGroup.headers.map((header) => { + const column = view.columns.find( + (candidate) => candidate.key === header.column.id, + ); + const direction = header.column.getIsSorted(); + const nextDirection = + direction === "asc" ? "descending" : "ascending"; + return ( + + ); + })} + + ))} + + + {pageRows.map((row, index) => ( + + + {row.getVisibleCells().map((cell) => ( + + ))} + + ))} + +
+ + + + {column ? ( + + {formatColumnMeta(column)} + + ) : null} +
+ toggleRow(row.id)} + /> + {formatCellValue(cell.getValue())}
+
+ {pageCount > 1 ? ( + + ) : null} + + ); +} + +function SelectionCheckbox({ + checked, + indeterminate, + label, + onChange, +}: Readonly<{ + checked: boolean; + indeterminate: boolean; + label: string; + onChange: () => void; +}>) { + const input = useRef(null); + useEffect(() => { + if (input.current) input.current.indeterminate = indeterminate; + }, [indeterminate]); + + return ( + + ); +} + +function PageButton({ + children, + disabled, + label, + onClick, +}: Readonly<{ + children: React.ReactNode; + disabled: boolean; + label: string; + onClick: () => void; +}>) { + return ( + + ); +} + +function SortIcon({ direction }: { direction: false | "asc" | "desc" }) { + const iconProps = { + "aria-hidden": true, + className: "sort-icon", + size: 14, + strokeWidth: 1.75, + } as const; + if (direction === "asc") { + return ; + } + if (direction === "desc") { + return ; + } + return ; +} + +function formatColumnMeta( + column: StarfetchTableViewV1["columns"][number], +): string { + return [column.datatype, column.unit, column.ucd].filter(Boolean).join(" · "); +} + +function formatCellValue(value: unknown): string { + if (value === null || value === undefined) { + return "—"; + } + return String(value); +} + +const numericDatatypes = new Set([ + "bit", + "double", + "float", + "int", + "long", + "short", + "unsignedbyte", +]); + +function isNumericDatatype(datatype: string | undefined): boolean { + return datatype !== undefined && numericDatatypes.has(datatype.toLowerCase()); +} + +function compareNumericCells( + first: { getValue: (columnId: string) => unknown }, + second: { getValue: (columnId: string) => unknown }, + columnId: string, +): number { + const firstValue = Number(first.getValue(columnId)); + const secondValue = Number(second.getValue(columnId)); + if (Number.isFinite(firstValue) && Number.isFinite(secondValue)) { + return firstValue - secondValue; + } + return String(first.getValue(columnId)).localeCompare( + String(second.getValue(columnId)), + undefined, + { numeric: true }, + ); +} diff --git a/apps/mcp-app/web/src/result-actions.tsx b/apps/mcp-app/web/src/result-actions.tsx index 9ed4a4d..0690fd5 100644 --- a/apps/mcp-app/web/src/result-actions.tsx +++ b/apps/mcp-app/web/src/result-actions.tsx @@ -1,8 +1,16 @@ -import { ChevronsDown, ChevronsUp, Copy, Download } from "lucide-react"; -import { useState } from "react"; +import { + Check, + Copy, + Download, + Maximize2, + MessageSquareText, + Minimize2, +} from "lucide-react"; +import { useEffect, useState } from "react"; import type { StarfetchTableViewV1 } from "../../src/presentation-contract.js"; import { + type AnalysisScope, type StarfetchHostSession, type StarfetchHostSnapshot, } from "./host-ui.js"; @@ -11,28 +19,45 @@ import { createTableExport, type DataFormat } from "./table-export.js"; type ActionStatusHandler = (status: string) => void; type ResultActionsProps = Readonly<{ + analysisRows: StarfetchTableViewV1["rows"]; + analysisScope: AnalysisScope; host: StarfetchHostSession; + hostSnapshot: StarfetchHostSnapshot; onStatus: ActionStatusHandler; + page: number; + pageCount: number; rows: StarfetchTableViewV1["rows"]; view: StarfetchTableViewV1; }>; export function ResultActions({ + analysisRows, + analysisScope, host, + hostSnapshot, onStatus, + page, + pageCount, rows, view, }: ResultActionsProps) { const [openMenu, setOpenMenu] = useState<"copy" | "download" | null>(null); + const [copyConfirmation, setCopyConfirmation] = useState(0); + useEffect(() => { + if (copyConfirmation === 0) return; + const timeout = window.setTimeout(() => setCopyConfirmation(0), 1_500); + return () => window.clearTimeout(timeout); + }, [copyConfirmation]); const copyData = async (format: DataFormat) => { const tableExport = createTableExport(format, view.columns, rows); const copied = await host.copyText(tableExport.text); - onStatus( - copied - ? `Copied ${format.toUpperCase()}.` - : `Could not copy ${format.toUpperCase()}.`, - ); + if (copied) { + onStatus(""); + setCopyConfirmation((confirmation) => confirmation + 1); + } else { + onStatus(`Could not copy ${format.toUpperCase()}.`); + } }; const downloadData = async (format: DataFormat) => { @@ -42,11 +67,7 @@ export function ResultActions({ tableExport.mimeType, tableExport.text, ); - onStatus( - downloaded - ? `Downloaded ${format.toUpperCase()}.` - : `Could not download ${format.toUpperCase()}.`, - ); + onStatus(downloaded ? "" : `Could not download ${format.toUpperCase()}.`); }; const runMenuAction = (action: () => Promise) => { @@ -54,10 +75,42 @@ export function ResultActions({ void action(); }; + const expanded = hostSnapshot.mode === "fullscreen"; + const toggleFullscreen = async () => { + const changed = await host.setExpanded(!expanded); + onStatus( + changed + ? "" + : expanded + ? "Could not exit fullscreen." + : "Could not open fullscreen.", + ); + }; + + const analyzeRows = async () => { + const analyzed = await host.analyzeRows( + view.title, + page + 1, + pageCount, + analysisScope, + analysisRows, + ); + onStatus( + analysisStatus(analyzed, analysisScope, analysisRows.length, page + 1), + ); + }; + return (
); } -export function TableDisplayControl({ - host, - hostSnapshot, - onStatus, -}: Readonly<{ - host: StarfetchHostSession; - hostSnapshot: StarfetchHostSnapshot; - onStatus: ActionStatusHandler; -}>) { - if (!hostSnapshot.canExpand) { - return null; +function analysisStatus( + analyzed: boolean, + scope: AnalysisScope, + rowCount: number, + page: number, +): string { + if (!analyzed) { + return `Could not send ${scope === "selection" ? "the selection" : `page ${page}`} to chat.`; } - - const expanded = hostSnapshot.mode === "fullscreen"; - const toggleExpanded = async () => { - const changed = await host.setExpanded(!expanded); - onStatus( - changed - ? expanded - ? "Showing fewer rows." - : "Showing more rows." - : expanded - ? "Could not show fewer rows." - : "Could not show more rows.", - ); - }; - - return ( -
- -
- ); + if (scope === "page") return `Sent page ${page} to chat.`; + return `Sent ${rowCount} selected ${rowCount === 1 ? "row" : "rows"} to chat.`; } function ActionMenu({ + confirmed = false, icon, label, onDismiss, @@ -137,6 +182,7 @@ function ActionMenu({ onToggle, open, }: Readonly<{ + confirmed?: boolean; icon: React.ReactNode; label: "Copy data" | "Download data"; onDismiss: () => void; @@ -145,15 +191,16 @@ function ActionMenu({ open: boolean; }>) { const verb = label === "Copy data" ? "Copy as" : "Download"; + const buttonLabel = confirmed ? "Copied data" : label; return (
@@ -95,7 +104,7 @@ export function ResultNotices({ view }: ResultDetailsProps) {
   return (
     
- {overflow ? TAP overflow : null} + {overflow ? More rows available : null} {clipped ? Presentation clipped : null}
{clipped ? ( @@ -104,6 +113,13 @@ export function ResultNotices({ view }: ResultDetailsProps) { for display.

) : null} + {overflow ? ( +

+ {view.source.tool === "starfetch_tap_query" + ? `Increase the ${view.source.effectiveMaxrec}-row limit (maximum ${STARFETCH_WIDGET_TABLE_LIMITS_V1.maxRows.toLocaleString("en-US")}), or narrow the query.` + : "Narrow the query to retrieve a complete subset."} +

+ ) : null}
); } @@ -171,7 +187,10 @@ function SourceDetails({ source }: { source: StarfetchTableViewV1["source"] }) { value={formatName(source.requestFormat)} /> - + ) : null} @@ -184,7 +203,10 @@ function SourceDetails({ source }: { source: StarfetchTableViewV1["source"] }) { value={formatName(source.sourceFormat)} /> - + ) : null} diff --git a/apps/mcp-app/web/src/results-table.test.tsx b/apps/mcp-app/web/src/results-table.test.tsx index b212838..7af723e 100644 --- a/apps/mcp-app/web/src/results-table.test.tsx +++ b/apps/mcp-app/web/src/results-table.test.tsx @@ -9,7 +9,23 @@ import { ResultsTable } from "./results-table.js"; afterEach(cleanup); describe("ResultsTable", () => { - it("renders every bounded result through a virtualized inline viewport", () => { + it("rounds request durations to whole milliseconds", () => { + const view = createQueryView(1); + if (view.source.tool !== "starfetch_tap_query") { + throw new Error("Expected a TAP query fixture."); + } + const timedView: StarfetchTableViewV1 = { + ...view, + source: { ...view.source, durationMs: 4_143.163_209_000_602 }, + }; + + render(); + + expect(screen.getAllByText("4143 ms")).toHaveLength(2); + expect(screen.queryByText("4143.163209000602 ms")).toBeNull(); + }); + + it("renders the complete 100-row page in the inline viewport", () => { render(); expect( @@ -20,15 +36,14 @@ describe("ResultsTable", () => { expect(screen.queryByText(/rows shown/)).toBeNull(); const table = screen.getByRole("table", { name: "Gaia source results" }); - expect(table.parentElement?.dataset.virtualized).toBe("true"); - expect(within(table).getAllByRole("row").length).toBeLessThan(101); + expect(within(table).getAllByRole("row")).toHaveLength(101); expect( within(table).getByRole("button", { name: "Sort Source ID ascending", }), ).toBeTruthy(); expect(screen.getByText("long · meta.id;meta.main")).toBeTruthy(); - expect(screen.queryByText("source-99")).toBeNull(); + expect(screen.getByText("source-99")).toBeTruthy(); }); it("sorts without changing exact values and copies the sorted bounded rows", async () => { @@ -53,7 +68,8 @@ describe("ResultsTable", () => { /^source_id\tra\nsource-01\t50[\s\S]*source-12\t51\.1$/, ), ); - expect(screen.getByRole("status").textContent).toBe("Copied TSV."); + expect(screen.getByRole("button", { name: "Copied data" })).toBeTruthy(); + expect(screen.queryByRole("status")).toBeNull(); }); it("sorts scientific numeric strings numerically with missing values last", async () => { @@ -162,8 +178,8 @@ describe("ResultsTable", () => { expect(screen.getByRole("button", { name: "Copy data" })).toBeTruthy(); expect(screen.getByRole("button", { name: "Download data" })).toBeTruthy(); expect( - screen.queryByRole("button", { name: "Open fullscreen" }), - ).toBeNull(); + screen.getByRole("button", { name: "Open fullscreen" }), + ).toBeTruthy(); await user.click(screen.getByRole("button", { name: "Copy data" })); @@ -171,9 +187,13 @@ describe("ResultsTable", () => { expect(screen.getByRole("menuitem", { name: "Copy as TSV" })).toBeTruthy(); expect(screen.getByRole("menuitem", { name: "Copy as CSV" })).toBeTruthy(); expect(screen.getByRole("menuitem", { name: "Copy as JSON" })).toBeTruthy(); + + await user.click(screen.getByRole("menuitem", { name: "Copy as TSV" })); + expect(screen.getByRole("button", { name: "Copied data" })).toBeTruthy(); + expect(screen.queryByRole("status")).toBeNull(); }); - it("shows more and less rows through table controls below the table", async () => { + it("toggles fullscreen from an icon-only toolbar control", async () => { const user = userEvent.setup(); const requestDisplayMode = vi.fn( async (mode: "inline" | "fullscreen") => mode, @@ -191,18 +211,93 @@ describe("ResultsTable", () => { />, ); - const displayControls = screen.getByRole("group", { - name: "Table display", + await user.click(screen.getByRole("button", { name: "Open fullscreen" })); + expect(requestDisplayMode).toHaveBeenCalledWith("fullscreen"); + expect(screen.queryByRole("status")).toBeNull(); + + await user.click(screen.getByRole("button", { name: "Exit fullscreen" })); + expect(requestDisplayMode).toHaveBeenCalledWith("inline"); + expect(screen.queryByRole("status")).toBeNull(); + }); + + it("does not offer fullscreen on mobile hosts", () => { + render( + , + ); + + expect( + screen.queryByRole("button", { name: "Open fullscreen" }), + ).toBeNull(); + }); + + it("paginates the globally sorted table in 100-row pages", async () => { + const user = userEvent.setup(); + render(); + + expect(screen.getByText("Page 1 of 3 · rows 1–100 of 250")).toBeTruthy(); + await user.click(screen.getByRole("button", { name: "Last page" })); + expect(screen.getByText("Page 3 of 3 · rows 201–250 of 250")).toBeTruthy(); + await user.click(screen.getByRole("button", { name: "Previous page" })); + expect(screen.getByText("Page 2 of 3 · rows 101–200 of 250")).toBeTruthy(); + }); + + it("repeatedly analyzes the current page or selected rows", async () => { + const user = userEvent.setup(); + const updateModelContext = vi.fn().mockResolvedValue({}); + render( + , + ); + + const analyzePage = screen.getByRole("button", { + name: "Analyze this page", + }); + expect(analyzePage.textContent).toBe("Analyze this page"); + await user.click(analyzePage); + expect(updateModelContext).toHaveBeenNthCalledWith(1, { + content: [ + expect.objectContaining({ + text: expect.stringMatching(/"rowCount": 3[\s\S]*"scope": "page"/), + }), + ], }); + + await user.click(screen.getByRole("checkbox", { name: "Select row 1" })); await user.click( - within(displayControls).getByRole("button", { name: "Show more" }), + screen.getByRole("button", { name: "Analyze this selection" }), ); - expect(requestDisplayMode).toHaveBeenCalledWith("fullscreen"); + expect(updateModelContext).toHaveBeenNthCalledWith(2, { + content: [ + expect.objectContaining({ + text: expect.stringMatching( + /"rowCount": 1[\s\S]*"source_id": "source-01"[\s\S]*"scope": "selection"/, + ), + }), + ], + }); + await user.click(screen.getByRole("checkbox", { name: "Select row 2" })); await user.click( - within(displayControls).getByRole("button", { name: "Show less" }), + screen.getByRole("button", { name: "Analyze this selection" }), + ); + expect(updateModelContext).toHaveBeenCalledTimes(3); + expect(screen.getByRole("status").textContent).toBe( + "Sent 2 selected rows to chat.", ); - expect(requestDisplayMode).toHaveBeenCalledWith("inline"); }); it("presents a completed empty result without making it look like an error", () => { @@ -232,7 +327,12 @@ describe("ResultsTable", () => { } render(); - expect(screen.getByText("TAP overflow")).toBeTruthy(); + expect(screen.getByText("More rows available")).toBeTruthy(); + expect( + screen.getByText( + "Increase the 100-row limit (maximum 10,000), or narrow the query.", + ), + ).toBeTruthy(); expect(screen.getByText("Presentation clipped")).toBeTruthy(); expect( screen.getByText("12 of 20 source rows retained for display."), @@ -253,6 +353,10 @@ describe("ResultsTable", () => { expect(writeClipboard).toHaveBeenCalledWith( "SELECT TOP 100 source_id, ra FROM gaiadr3.gaia_source", ); + expect( + within(queryPanel).getByRole("button", { name: "Copied ADQL" }), + ).toBeTruthy(); + expect(screen.queryByText("Copied ADQL.")).toBeNull(); expect(screen.getByText("Request details")).toBeTruthy(); expect(screen.getByText("100 rows")).toBeTruthy(); @@ -261,7 +365,7 @@ describe("ResultsTable", () => { expect(screen.getByText("Unique Gaia source identifier.")).toBeTruthy(); }); - it("keeps the complete sorted row model virtualized in fullscreen", () => { + it("keeps the complete page visible in fullscreen", () => { render( { ); const table = screen.getByRole("table", { name: "Gaia source results" }); - expect(table.parentElement?.dataset.virtualized).toBe("true"); - expect(within(table).getAllByRole("row").length).toBeLessThan(101); + expect(within(table).getAllByRole("row")).toHaveLength(101); expect(screen.queryByText("10 of 100 rows shown")).toBeNull(); }); }); @@ -286,6 +389,7 @@ function createHost({ context = { displayMode: "inline" }, downloadFile = vi.fn(), requestDisplayMode = vi.fn(), + updateModelContext = vi.fn(), writeClipboard = vi.fn(), }: { capabilities?: NonNullable< @@ -294,6 +398,7 @@ function createHost({ context?: NonNullable>; downloadFile?: StarfetchHostBridge["downloadFile"]; requestDisplayMode?: StarfetchHostBridge["requestDisplayMode"]; + updateModelContext?: StarfetchHostBridge["updateModelContext"]; writeClipboard?: (value: string) => Promise; } = {}): StarfetchHostSession { const bridge: StarfetchHostBridge = { @@ -303,6 +408,7 @@ function createHost({ getHostContext: () => context, removeHostContextListener: vi.fn(), requestDisplayMode, + updateModelContext, }; return new StarfetchHostSession(bridge, writeClipboard); } diff --git a/apps/mcp-app/web/src/results-table.tsx b/apps/mcp-app/web/src/results-table.tsx index efebb17..680e798 100644 --- a/apps/mcp-app/web/src/results-table.tsx +++ b/apps/mcp-app/web/src/results-table.tsx @@ -1,9 +1,10 @@ -import { useState } from "react"; +import { useEffect, useState } from "react"; import type { StarfetchTableViewV1 } from "../../src/presentation-contract.js"; +import { formatDurationMs } from "./format-duration.js"; import { type StarfetchHostSession } from "./host-ui.js"; import { ExactQuery, ResultDetails, ResultNotices } from "./result-details.js"; -import { VirtualizedResults } from "./virtualized-results.js"; +import { PagedResults } from "./paged-results.js"; type ResultsTableProps = Readonly<{ host: StarfetchHostSession; @@ -12,6 +13,12 @@ type ResultsTableProps = Readonly<{ export function ResultsTable({ host, view }: ResultsTableProps) { const [actionStatus, setActionStatus] = useState(""); + const [queryCopyConfirmation, setQueryCopyConfirmation] = useState(0); + useEffect(() => { + if (queryCopyConfirmation === 0) return; + const timeout = window.setTimeout(() => setQueryCopyConfirmation(0), 1_500); + return () => window.clearTimeout(timeout); + }, [queryCopyConfirmation]); const serviceLabel = "target" in view.source ? view.source.target.label : null; const query = "query" in view.source ? view.source.query : null; @@ -19,7 +26,12 @@ export function ResultsTable({ host, view }: ResultsTableProps) { const copyQuery = async () => { if (query === null) return; const copied = await host.copyText(query); - setActionStatus(copied ? "Copied ADQL." : "Could not copy ADQL."); + if (copied) { + setActionStatus(""); + setQueryCopyConfirmation((confirmation) => confirmation + 1); + } else { + setActionStatus("Could not copy ADQL."); + } }; return ( @@ -30,10 +42,10 @@ export function ResultsTable({ host, view }: ResultsTableProps) { {serviceLabel ? {serviceLabel} : null} {view.clipping.sourceRows} source rows {"durationMs" in view.source ? ( - {view.source.durationMs} ms + {formatDurationMs(view.source.durationMs)} ) : null} {view.source.tool === "starfetch_tap_query" ? ( - {view.source.effectiveMaxrec} max + {view.source.effectiveMaxrec}-row request limit ) : null} {view.source.tool === "starfetch_tap_job_fetch" ? ( job {view.source.job.id} @@ -41,10 +53,16 @@ export function ResultsTable({ host, view }: ResultsTableProps) {
- void copyQuery()} view={view} /> -

- {actionStatus} -

+ 0} + onCopy={() => void copyQuery()} + view={view} + /> + {actionStatus ? ( +

+ {actionStatus} +

+ ) : null} {view.state === "empty" ? ( <> @@ -55,11 +73,7 @@ export function ResultsTable({ host, view }: ResultsTableProps) { ) : ( - + )}
diff --git a/apps/mcp-app/web/src/styles.css b/apps/mcp-app/web/src/styles.css index cac6d27..68c8806 100644 --- a/apps/mcp-app/web/src/styles.css +++ b/apps/mcp-app/web/src/styles.css @@ -58,7 +58,6 @@ body, margin: 0; min-width: 0; overflow-x: hidden; - background: var(--sf-surface); } body { @@ -158,12 +157,23 @@ h3 { .actions { display: flex; + flex-wrap: wrap; justify-content: flex-end; width: 100%; gap: 4px; margin-block: 12px 8px; } +.analyze-button { + display: inline-flex; + min-height: 30px; + padding: 4px 9px; + gap: 6px; + align-items: center; + background: var(--sf-header-surface); + border-color: var(--sf-border-subtle); +} + .action-group { position: relative; } @@ -272,6 +282,13 @@ h3 { font-weight: 600; } +.action-status { + margin-block: 6px; + color: var(--sf-muted); + font-size: 12px; + text-align: end; +} + .table-scroll { position: relative; max-width: 100%; @@ -279,7 +296,8 @@ h3 { overflow: auto; overscroll-behavior: contain; scrollbar-gutter: stable; - border-block: 1px solid var(--sf-border); + border: 1px solid var(--sf-border); + border-radius: var(--sf-radius); } .table-scroll[data-mode="fullscreen"] { @@ -287,33 +305,32 @@ h3 { overflow: auto; } -.table-display-controls { - display: flex; - justify-content: flex-end; - padding-block-start: 6px; +table { + width: max-content; + min-width: 100%; + border-collapse: collapse; + font-variant-numeric: tabular-nums; } -.table-display-button { - display: inline-flex; - min-height: 30px; - padding: 4px 8px; - gap: 6px; +.table-pagination { + display: grid; + grid-template-columns: auto minmax(0, 1fr) auto; + gap: 8px; align-items: center; + margin-block-start: 8px; color: var(--sf-muted); - background: transparent; - border-color: transparent; font-size: 12px; + text-align: center; } -.table-display-button svg { - flex: 0 0 auto; +.pagination-buttons { + display: flex; + gap: 4px; } -table { - width: max-content; - min-width: 100%; - border-collapse: collapse; - font-variant-numeric: tabular-nums; +.icon-button:disabled { + cursor: default; + opacity: 0.45; } th, @@ -326,6 +343,26 @@ td { border-block-end: 1px solid var(--sf-border-subtle); } +th.selection-column, +td.selection-column { + width: 38px; + min-width: 38px; + padding-inline: 10px 4px; +} + +.selection-column input { + display: block; + width: 15px; + height: 15px; + margin: 0; + accent-color: var(--sf-ring); + cursor: pointer; +} + +tbody tr[data-selected="true"] td { + background: var(--sf-hover); +} + th { position: sticky; top: 0; @@ -359,11 +396,6 @@ td { overflow-wrap: anywhere; } -.virtual-spacer td { - padding: 0; - border: 0; -} - .empty-state, .message-state { padding-block: 20px; @@ -375,6 +407,51 @@ td { color: var(--sf-muted); } +.loading-skeleton { + display: grid; + margin-block-end: 10px; + gap: 8px; +} + +.loading-skeleton span { + width: 100%; + height: 12px; + background: linear-gradient( + 90deg, + var(--sf-header-surface) 25%, + var(--sf-hover) 50%, + var(--sf-header-surface) 75% + ); + background-size: 200% 100%; + border-radius: var(--sf-radius); + animation: loading-shimmer 1.4s ease-in-out infinite; +} + +.loading-skeleton span:first-child { + width: min(42%, 220px); + height: 18px; +} + +.loading-skeleton span:last-child { + width: 72%; +} + +@keyframes loading-shimmer { + from { + background-position: 200% 0; + } + + to { + background-position: -200% 0; + } +} + +@media (prefers-reduced-motion: reduce) { + .loading-skeleton span { + animation: none; + } +} + .error-state h1 { margin-block-end: 6px; } @@ -486,6 +563,19 @@ pre { max-width: 18rem; padding-inline: 8px; } + + .table-pagination { + grid-template-columns: 1fr 1fr; + } + + .table-pagination > span { + grid-column: 1 / -1; + grid-row: 1; + } + + .pagination-buttons:last-child { + justify-content: flex-end; + } } @media (prefers-reduced-motion: reduce) { diff --git a/apps/mcp-app/web/src/test-host.ts b/apps/mcp-app/web/src/test-host.ts index be1a837..835cae2 100644 --- a/apps/mcp-app/web/src/test-host.ts +++ b/apps/mcp-app/web/src/test-host.ts @@ -7,6 +7,8 @@ declare global { interface Window { setTestTheme(theme: "light" | "dark"): void; testDownload?: unknown; + testModelContext?: unknown; + testModelContextUpdates?: number; } } @@ -14,6 +16,10 @@ const iframe = document.querySelector("iframe"); if (!(iframe instanceof HTMLIFrameElement) || iframe.contentWindow === null) { throw new Error("Expected the browser-test widget iframe."); } +const searchParams = new URLSearchParams(window.location.search); +const delayedGlobals = searchParams.has("delayed-globals"); +const globalsOnly = searchParams.has("globals") || delayedGlobals; +const mobileHost = searchParams.has("mobile"); type HostContext = NonNullable< NonNullable[3]>["hostContext"] @@ -22,12 +28,13 @@ type HostContext = NonNullable< let hostContext: HostContext = { availableDisplayModes: ["inline", "fullscreen"], displayMode: "inline", + platform: mobileHost ? "mobile" : "web", theme: "light", }; const bridge = new AppBridge( null, { name: "Starfetch browser test host", version: "1.0.0" }, - { downloadFile: {} }, + { downloadFile: {}, updateModelContext: {} }, { hostContext }, ); @@ -35,6 +42,11 @@ bridge.ondownloadfile = async (params) => { window.testDownload = params; return {}; }; +bridge.onupdatemodelcontext = async (params) => { + window.testModelContext = params; + window.testModelContextUpdates = (window.testModelContextUpdates ?? 0) + 1; + return {}; +}; bridge.onrequestdisplaymode = async ({ mode }) => { const actualMode = mode === "fullscreen" ? "fullscreen" : "inline"; hostContext = { @@ -46,10 +58,12 @@ bridge.onrequestdisplaymode = async ({ mode }) => { }; bridge.oninitialized = () => { void bridge.sendToolInput({ arguments: browserTestView }); - void bridge.sendToolResult({ - content: [], - structuredContent: browserTestView, - }); + if (!globalsOnly) { + void bridge.sendToolResult({ + content: [], + structuredContent: browserTestView, + }); + } }; window.setTestTheme = (theme) => { @@ -60,4 +74,35 @@ window.setTestTheme = (theme) => { await bridge.connect( new PostMessageTransport(iframe.contentWindow, iframe.contentWindow), ); +if (globalsOnly) { + iframe.addEventListener("load", () => { + if (iframe.contentWindow === null) return; + const publishCompleteGlobals = () => { + if (iframe.contentWindow === null) return; + iframe.contentWindow.openai = { + toolOutput: { contractVersion: 2 }, + toolResponseMetadata: { + mcp_tool_result: { + _meta: { + starfetchTableDataset: { + datasetVersion: 1, + view: browserTestView, + }, + }, + }, + }, + }; + iframe.contentWindow.dispatchEvent(new Event("openai:set_globals")); + }; + if (!delayedGlobals) { + publishCompleteGlobals(); + return; + } + iframe.contentWindow.openai = { + toolOutput: { contractVersion: 2 }, + }; + iframe.contentWindow.dispatchEvent(new Event("openai:set_globals")); + window.setTimeout(publishCompleteGlobals, 2_500); + }); +} iframe.src = "/dist/index.html"; diff --git a/apps/mcp-app/web/src/virtualized-results.tsx b/apps/mcp-app/web/src/virtualized-results.tsx deleted file mode 100644 index 8699ffe..0000000 --- a/apps/mcp-app/web/src/virtualized-results.tsx +++ /dev/null @@ -1,231 +0,0 @@ -import { - flexRender, - getCoreRowModel, - getSortedRowModel, - useReactTable, - type ColumnDef, - type SortingState, -} from "@tanstack/react-table"; -import { useVirtualizer } from "@tanstack/react-virtual"; -import { ArrowDown, ArrowUp, ChevronsUpDown } from "lucide-react"; -import { useMemo, useRef, useState, useSyncExternalStore } from "react"; - -import type { StarfetchTableViewV1 } from "../../src/presentation-contract.js"; -import { type StarfetchHostSession } from "./host-ui.js"; -import { ResultActions, TableDisplayControl } from "./result-actions.js"; -import { ResultNotices } from "./result-details.js"; - -type TableRow = StarfetchTableViewV1["rows"][number]; - -export function VirtualizedResults({ - host, - onStatus, - view, -}: Readonly<{ - host: StarfetchHostSession; - onStatus: (status: string) => void; - view: StarfetchTableViewV1; -}>) { - const [sorting, setSorting] = useState([]); - const scrollElement = useRef(null); - const hostSnapshot = useSyncExternalStore( - (listener) => host.subscribe(listener), - () => host.getSnapshot(), - ); - const columns = useMemo[]>( - () => - view.columns.map((column) => ({ - accessorFn: (row) => row[column.key] ?? undefined, - id: column.key, - header: column.label, - meta: column, - sortUndefined: "last", - sortingFn: isNumericDatatype(column.datatype) - ? compareNumericCells - : "alphanumeric", - })), - [view.columns], - ); - const table = useReactTable({ - columns, - data: view.rows, - getCoreRowModel: getCoreRowModel(), - getSortedRowModel: getSortedRowModel(), - onSortingChange: setSorting, - state: { sorting }, - }); - const sortedRows = table.getRowModel().rows; - const isVirtualized = sortedRows.length > 20; - const rowVirtualizer = useVirtualizer({ - count: sortedRows.length, - enabled: isVirtualized, - estimateSize: () => 40, - getScrollElement: () => scrollElement.current, - initialRect: { height: 400, width: 800 }, - overscan: 6, - }); - const virtualItems = rowVirtualizer.getVirtualItems(); - const renderedRows = isVirtualized - ? virtualItems.flatMap((item) => { - const row = sortedRows[item.index]; - return row ? [{ item, row }] : []; - }) - : sortedRows.map((row) => ({ item: undefined, row })); - const firstVirtualItem = virtualItems[0]; - const lastVirtualItem = virtualItems.at(-1); - const topSpacer = firstVirtualItem?.start ?? 0; - const bottomSpacer = lastVirtualItem - ? rowVirtualizer.getTotalSize() - lastVirtualItem.end - : 0; - - return ( - <> - row.original)} - view={view} - /> - -
- - - {table.getHeaderGroups().map((headerGroup) => ( - - {headerGroup.headers.map((header) => { - const column = view.columns.find( - (candidate) => candidate.key === header.column.id, - ); - const direction = header.column.getIsSorted(); - const nextDirection = - direction === "asc" ? "descending" : "ascending"; - return ( - - ); - })} - - ))} - - - {topSpacer > 0 ? ( - - - ) : null} - {renderedRows.map(({ item, row }) => ( - - {row.getVisibleCells().map((cell) => ( - - ))} - - ))} - {bottomSpacer > 0 ? ( - - - ) : null} - -
- - {column ? ( - - {formatColumnMeta(column)} - - ) : null} -
{formatCellValue(cell.getValue())}
-
- - - ); -} - -function SortIcon({ direction }: { direction: false | "asc" | "desc" }) { - const iconProps = { - "aria-hidden": true, - className: "sort-icon", - size: 14, - strokeWidth: 1.75, - } as const; - if (direction === "asc") { - return ; - } - if (direction === "desc") { - return ; - } - return ; -} - -function formatColumnMeta( - column: StarfetchTableViewV1["columns"][number], -): string { - return [column.datatype, column.unit, column.ucd].filter(Boolean).join(" · "); -} - -function formatCellValue(value: unknown): string { - if (value === null || value === undefined) { - return "—"; - } - return String(value); -} - -const numericDatatypes = new Set([ - "bit", - "double", - "float", - "int", - "long", - "short", - "unsignedbyte", -]); - -function isNumericDatatype(datatype: string | undefined): boolean { - return datatype !== undefined && numericDatatypes.has(datatype.toLowerCase()); -} - -function compareNumericCells( - first: { getValue: (columnId: string) => unknown }, - second: { getValue: (columnId: string) => unknown }, - columnId: string, -): number { - const firstValue = Number(first.getValue(columnId)); - const secondValue = Number(second.getValue(columnId)); - if (Number.isFinite(firstValue) && Number.isFinite(secondValue)) { - return firstValue - secondValue; - } - return String(first.getValue(columnId)).localeCompare( - String(second.getValue(columnId)), - undefined, - { numeric: true }, - ); -} diff --git a/apps/mcp-app/web/src/widget-state.test.ts b/apps/mcp-app/web/src/widget-state.test.ts index e3d97e0..7f9868c 100644 --- a/apps/mcp-app/web/src/widget-state.test.ts +++ b/apps/mcp-app/web/src/widget-state.test.ts @@ -17,6 +17,17 @@ describe("decodeTableView", () => { }; expect(decodeTableView(view)).toEqual({ ok: true, view }); + expect( + decodeTableView( + { contractVersion: 2 }, + { + starfetchTableDataset: { + datasetVersion: 1, + view, + }, + }, + ), + ).toEqual({ ok: true, view }); expect( decodeTableView({ contractVersion: 2, secret: "do not echo" }), ).toEqual({ diff --git a/apps/mcp-app/web/src/widget-state.ts b/apps/mcp-app/web/src/widget-state.ts index 84a397a..dee40ac 100644 --- a/apps/mcp-app/web/src/widget-state.ts +++ b/apps/mcp-app/web/src/widget-state.ts @@ -1,5 +1,6 @@ import { starfetchTableViewV1Schema, + starfetchWidgetTableDatasetV1Schema, type StarfetchTableViewV1, } from "../../src/presentation-contract.js"; @@ -7,7 +8,19 @@ export type DecodedTableView = | Readonly<{ ok: true; view: StarfetchTableViewV1 }> | Readonly<{ ok: false; message: string }>; -export function decodeTableView(value: unknown): DecodedTableView { +export function decodeTableView( + value: unknown, + metadata?: unknown, +): DecodedTableView { + const dataset = isRecord(metadata) + ? starfetchWidgetTableDatasetV1Schema.safeParse( + metadata.starfetchTableDataset, + ) + : undefined; + if (dataset?.success) { + return { ok: true, view: dataset.data.view }; + } + const parsed = starfetchTableViewV1Schema.safeParse(value); return parsed.success ? { ok: true, view: parsed.data } @@ -16,3 +29,7 @@ export function decodeTableView(value: unknown): DecodedTableView { message: "The host returned an invalid Starfetch table result.", }; } + +function isRecord(value: unknown): value is Record { + return typeof value === "object" && value !== null; +} diff --git a/apps/mcp-app/web/tests/widget.spec.ts b/apps/mcp-app/web/tests/widget.spec.ts index d1592dd..9d97b5c 100644 --- a/apps/mcp-app/web/tests/widget.spec.ts +++ b/apps/mcp-app/web/tests/widget.spec.ts @@ -17,7 +17,7 @@ test("builds parse-safe single-file HTML", async () => { expect(Array.from(html).some(isParseInvalid)).toBe(false); }); -test("renders virtualized bridge results with safe theme fallbacks", async ({ +test("renders paged bridge results with safe theme fallbacks", async ({ page, }) => { await page.goto("/test-host.html"); @@ -28,10 +28,7 @@ test("renders virtualized bridge results with safe theme fallbacks", async ({ ).toBeVisible(); await expect(widget.getByText("100 source rows")).toBeVisible(); await expect(widget.getByText(/rows shown/)).toHaveCount(0); - await expect(widget.locator(".table-scroll")).toHaveAttribute( - "data-virtualized", - "true", - ); + await expect(widget.locator("tbody tr")).toHaveCount(100); await expect .poll(() => page.evaluate( @@ -71,7 +68,7 @@ test("renders virtualized bridge results with safe theme fallbacks", async ({ return body ? getComputedStyle(body).backgroundColor : ""; }), ) - .toBe("rgb(31, 31, 29)"); + .toBe("rgba(0, 0, 0, 0)"); await expect .poll(() => sqlKeyword.evaluate((element) => getComputedStyle(element).color), @@ -79,6 +76,58 @@ test("renders virtualized bridge results with safe theme fallbacks", async ({ .not.toBe(lightKeywordColor); }); +test("hydrates from ChatGPT globals when no bridge result notification arrives", async ({ + page, +}) => { + await page.goto("/test-host.html?globals=1"); + const widget = page.frameLocator("iframe[title='Starfetch widget']"); + + await expect( + widget.getByRole("heading", { name: "Gaia source results" }), + ).toBeVisible(); + await expect(widget.getByText("100 source rows")).toBeVisible(); +}); + +test("keeps delayed partial host results loading on mobile until data arrives", async ({ + page, +}) => { + await page.goto("/test-host.html?mobile=1&delayed-globals=1"); + const widget = page.frameLocator("iframe[title='Starfetch widget']"); + + await expect(widget.getByLabel("Waiting for Starfetch results…")).toBeVisible( + { + timeout: 1_500, + }, + ); + await expect(widget.locator(".loading-skeleton")).toBeVisible(); + await expect( + widget.getByRole("heading", { name: "Unable to show Starfetch results" }), + ).toHaveCount(0); + await expect( + widget.getByRole("heading", { name: "Gaia source results" }), + ).toBeVisible(); + await expect( + widget.getByRole("table", { name: "Gaia source results" }), + ).toBeVisible(); +}); + +test("keeps mobile hosts inline instead of exposing a broken fullscreen path", async ({ + page, +}) => { + await page.goto("/test-host.html?mobile=1"); + const widget = page.frameLocator("iframe[title='Starfetch widget']"); + + await expect( + widget.getByRole("heading", { name: "Gaia source results" }), + ).toBeVisible(); + await expect( + widget.getByRole("button", { name: "Open fullscreen" }), + ).toHaveCount(0); + await expect( + widget.getByRole("table", { name: "Gaia source results" }), + ).toBeVisible(); +}); + test("supports keyboard actions, host downloads, and table expansion", async ({ context, page, @@ -98,6 +147,9 @@ test("supports keyboard actions, host downloads, and table expansion", async ({ await expect .poll(() => page.evaluate(() => navigator.clipboard.readText())) .toBe(browserTestQuery); + await expect( + widget.getByRole("button", { name: "Copied ADQL" }), + ).toBeVisible(); await widget.getByRole("button", { name: "Download data" }).click(); await widget.getByRole("menuitem", { name: "Download JSON" }).click(); @@ -114,12 +166,12 @@ test("supports keyboard actions, host downloads, and table expansion", async ({ ) .toContain(`"source_id": "${browserTestView.rows[0]?.source_id}"`); - await widget.getByRole("button", { name: "Show more" }).click(); + await widget.getByRole("button", { name: "Open fullscreen" }).click(); await expect(widget.locator(".table-scroll")).toHaveAttribute( "data-mode", "fullscreen", ); - await widget.getByRole("button", { name: "Show less" }).click(); + await widget.getByRole("button", { name: "Exit fullscreen" }).click(); await expect(widget.locator(".table-scroll")).toHaveAttribute( "data-mode", "inline", @@ -138,6 +190,22 @@ test("supports keyboard actions, host downloads, and table expansion", async ({ ), ) .toBe(true); + + await widget.getByRole("button", { name: "Analyze this page" }).click(); + await widget.getByRole("button", { name: "Analyze this page" }).click(); + await expect + .poll(() => + page.evaluate(() => { + const context = window.testModelContext as + | { content?: Array<{ text?: string }> } + | undefined; + return context?.content?.[0]?.text; + }), + ) + .toContain(`"source_id": "${browserTestView.rows[0]?.source_id}"`); + await expect + .poll(() => page.evaluate(() => window.testModelContextUpdates)) + .toBe(2); }); function isParseInvalid(character: string): boolean { diff --git a/package-lock.json b/package-lock.json index 1c5d784..16114f0 100644 --- a/package-lock.json +++ b/package-lock.json @@ -40,7 +40,6 @@ "@shikijs/themes": "4.3.1", "@starfetch-js/mcp": "0.2.3", "@tanstack/react-table": "8.21.3", - "@tanstack/react-virtual": "3.14.6", "hono": "4.12.27", "ipaddr.js": "2.4.0", "lucide-react": "1.24.0", @@ -3841,23 +3840,6 @@ "react-dom": ">=16.8" } }, - "node_modules/@tanstack/react-virtual": { - "version": "3.14.6", - "resolved": "https://registry.npmjs.org/@tanstack/react-virtual/-/react-virtual-3.14.6.tgz", - "integrity": "sha512-4+Uq8m0/gzO4kMCHUEpTtGX1RnONK0C+g88b2ltwPMWUBiaVarBuWKoPJaz7gj1cKCVRAdyu+U8GcKhwCc2beA==", - "license": "MIT", - "dependencies": { - "@tanstack/virtual-core": "3.17.4" - }, - "funding": { - "type": "github", - "url": "https://github.com/sponsors/tannerlinsley" - }, - "peerDependencies": { - "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0", - "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0" - } - }, "node_modules/@tanstack/table-core": { "version": "8.21.3", "resolved": "https://registry.npmjs.org/@tanstack/table-core/-/table-core-8.21.3.tgz", @@ -3871,16 +3853,6 @@ "url": "https://github.com/sponsors/tannerlinsley" } }, - "node_modules/@tanstack/virtual-core": { - "version": "3.17.4", - "resolved": "https://registry.npmjs.org/@tanstack/virtual-core/-/virtual-core-3.17.4.tgz", - "integrity": "sha512-nGm5KteqxasUdThLc2izl6dHUqLv0LQj7Nuyo5gYalTPf/U8a9ermvsl7reT+6ioBW1l8WfpP/mcU338nLXpqw==", - "license": "MIT", - "funding": { - "type": "github", - "url": "https://github.com/sponsors/tannerlinsley" - } - }, "node_modules/@testing-library/dom": { "version": "10.4.1", "resolved": "https://registry.npmjs.org/@testing-library/dom/-/dom-10.4.1.tgz", diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts index 2ad9c1d..1fc2c52 100644 --- a/packages/mcp/src/index.ts +++ b/packages/mcp/src/index.ts @@ -5,13 +5,21 @@ import { fileURLToPath } from "node:url"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { createStarfetchMcpServer } from "./server.js"; - export { createStarfetchMcpServer, type JobCapabilityOperation, type StarfetchMcpPolicy, type StarfetchMcpServerOptions, } from "./server.js"; +export { unrestrictedStarfetchMcpPolicy } from "./policy.js"; +export { + tapQueryInputShape, + tapQueryInputSchema, + tapTargetInputShape, + type TapQueryInput, + type TapQueryOutput, +} from "./schemas.js"; +export { executeStarfetchTapQuery } from "./query-execution.js"; export { parseStarfetchTablePresentationSource, type StarfetchTablePresentationSource, diff --git a/packages/mcp/src/query-execution.ts b/packages/mcp/src/query-execution.ts new file mode 100644 index 0000000..763c73d --- /dev/null +++ b/packages/mcp/src/query-execution.ts @@ -0,0 +1,72 @@ +import { + tapRequestFormatForOutput, + type QueryOptions, + type TapSyncFormat, +} from "@starfetch-js/core"; + +import { createTapQueryData } from "./query-result.js"; +import { + runTool, + success, + targetDiagnostics, + type ToolResult, +} from "./results.js"; +import type { TapQueryInput, TapQueryOutput } from "./schemas.js"; +import type { StarfetchMcpRuntimeOptions } from "./server.js"; +import { createTapClient, createTapUploads } from "./tap-client.js"; + +export const DEFAULT_TAP_QUERY_MAXREC = 100; + +export function executeStarfetchTapQuery( + input: TapQueryInput, + incomingSignal: AbortSignal, + options: StarfetchMcpRuntimeOptions, + fallbackMaxrec = DEFAULT_TAP_QUERY_MAXREC, +): Promise> { + return runTool(async () => { + const startedAt = performance.now(); + const client = createTapClient(input, options); + const format = input.format; + const requestFormat = tapRequestFormatForOutput(format); + const prepared = options.policy.prepareQuery({ + fallbackMaxrec, + incomingSignal, + requestedMaxrec: input.maxrec, + uploads: input.uploads, + }); + const maxrec = prepared.maxrec; + const result = await client.query( + input.query, + createTapQueryOptions(input, requestFormat, maxrec, prepared.signal), + ); + const data = await createTapQueryData(result, format); + + const diagnostics: TapQueryOutput["diagnostics"] = { + durationMs: performance.now() - startedAt, + effectiveMaxrec: maxrec, + format, + requestFormat, + query: input.query, + target: targetDiagnostics(client.target), + uploadCount: input.uploads?.length ?? 0, + ...(input.runId === undefined ? {} : { runId: input.runId }), + }; + + return success(data, diagnostics); + }); +} + +function createTapQueryOptions( + input: TapQueryInput, + format: TapSyncFormat, + maxrec: number, + signal: AbortSignal, +): QueryOptions { + const queryOptions: QueryOptions = { format, maxrec, signal }; + + if (input.runId !== undefined) queryOptions.runId = input.runId; + const uploads = createTapUploads(input.uploads); + if (uploads !== undefined) queryOptions.uploads = uploads; + + return queryOptions; +} diff --git a/packages/mcp/src/query-result.ts b/packages/mcp/src/query-result.ts index ab738bb..de52f66 100644 --- a/packages/mcp/src/query-result.ts +++ b/packages/mcp/src/query-result.ts @@ -5,12 +5,17 @@ import { type TapResultField, } from "@starfetch-js/core"; -export type TapQueryData = { - content: string; - format: TapOutputFormat; - fields?: TapResultField[]; - overflow?: boolean; -}; +export type TapQueryData = + | { + content: string; + fields: TapResultField[]; + format: "json" | "jsonl"; + overflow?: boolean; + } + | { + content: string; + format: Exclude; + }; export async function createTapQueryData( result: TapResult, diff --git a/packages/mcp/src/results.ts b/packages/mcp/src/results.ts index 92a4d4e..875c21f 100644 --- a/packages/mcp/src/results.ts +++ b/packages/mcp/src/results.ts @@ -1,14 +1,18 @@ import { StarfetchError, type ResolvedTapTarget } from "@starfetch-js/core"; -export type ToolResult = { +export type ToolResult< + TStructuredContent extends Record = Record, +> = { content: [{ type: "text"; text: string }]; isError?: true; - structuredContent?: Record; + structuredContent?: TStructuredContent; }; -export async function runTool( - callback: () => Promise, -): Promise { +export async function runTool< + TStructuredContent extends Record, +>( + callback: () => Promise>, +): Promise> { try { return await callback(); } catch (error) { @@ -19,7 +23,7 @@ export async function runTool( export function success>( data: TData, diagnostics: TDiagnostics, -): ToolResult { +): ToolResult<{ data: TData; diagnostics: TDiagnostics }> { const structuredContent = { data, diagnostics }; return { @@ -47,7 +51,9 @@ export function targetDiagnostics( return diagnostics; } -function toolError(error: unknown): ToolResult { +function toolError>( + error: unknown, +): ToolResult { const message = formatToolError(error); return { diff --git a/packages/mcp/src/schemas.ts b/packages/mcp/src/schemas.ts index 38931e4..2fb1512 100644 --- a/packages/mcp/src/schemas.ts +++ b/packages/mcp/src/schemas.ts @@ -9,7 +9,7 @@ import { z } from "zod/v4"; const textSchema = z.string().trim().min(1); const optionalTextSchema = textSchema.optional(); -const targetFields = { +export const tapTargetInputShape = { service: optionalTextSchema.describe( "Known Starfetch TAP service preset selected for this workflow; use this or url.", ), @@ -18,10 +18,12 @@ const targetFields = { ), }; -export const targetInputSchema = z.object(targetFields).refine(hasTapTarget, { - message: "Specify service or url.", - path: ["service"], -}); +export const targetInputSchema = z + .object(tapTargetInputShape) + .refine(hasTapTarget, { + message: "Specify service or url.", + path: ["service"], + }); export type TargetInput = z.infer; export const registrySearchInputSchema = z.object({ @@ -37,7 +39,7 @@ export const registrySearchInputSchema = z.object({ export const columnsInputSchema = z .object({ - ...targetFields, + ...tapTargetInputShape, table: textSchema.describe( "Exact TAP table name returned by prior metadata inspection.", ), @@ -72,7 +74,7 @@ const uploadsSchema = z "TAP uploads forwarded to the service; local file paths are not supported.", ); -const tapQueryFields = { +export const tapQueryInputShape = { format: z.enum(tapOutputFormats).describe("MCP result output format."), maxrec: maxrecSchema.optional(), query: textSchema.describe( @@ -84,8 +86,8 @@ const tapQueryFields = { export const tapQueryInputSchema = z .object({ - ...targetFields, - ...tapQueryFields, + ...tapTargetInputShape, + ...tapQueryInputShape, }) .refine(hasTapTarget, { message: "Specify service or url.", @@ -102,7 +104,7 @@ const waitMsSchema = z .describe("Wait duration in milliseconds."); const tapJobTargetFields = { - ...targetFields, + ...tapTargetInputShape, jobIdOrUrl: textSchema.describe("TAP async job id or absolute job URL."), }; @@ -115,7 +117,7 @@ const hostedTapJobTargetFields = { export const tapJobSubmitInputSchema = z .object({ - ...targetFields, + ...tapTargetInputShape, maxrec: maxrecSchema.optional(), query: textSchema.describe( "Exact metadata-backed ADQL query text. Use TOP for a query-level bound; do not use LIMIT.", @@ -380,6 +382,7 @@ export const tapQueryOutputSchema = z }); } }); +export type TapQueryOutput = z.infer; export const tapJobFetchOutputSchema = z .object({ diff --git a/packages/mcp/src/tools.ts b/packages/mcp/src/tools.ts index 00e924a..5cb5185 100644 --- a/packages/mcp/src/tools.ts +++ b/packages/mcp/src/tools.ts @@ -3,12 +3,8 @@ import { defaultRegistryUrl, defaultTapPresets, registry, - tapRequestFormatForOutput, - type QueryOptions, - type TapOutputFormat, type TapRegistryOptions, type TapRegistrySearchOptions, - type TapSyncFormat, } from "@starfetch-js/core"; import { z } from "zod/v4"; @@ -26,19 +22,19 @@ import { targetInputSchema, tapQueryInputSchema, tapQueryOutputSchema, - type TapQueryInput, } from "./schemas.js"; +import { + DEFAULT_TAP_QUERY_MAXREC, + executeStarfetchTapQuery, +} from "./query-execution.js"; import { runTool, success, targetDiagnostics } from "./results.js"; -import { createTapQueryData } from "./query-result.js"; -import type { StarfetchMcpRuntimeOptions } from "./server.js"; -import { createTapClient, createTapUploads } from "./tap-client.js"; +import { type StarfetchMcpRuntimeOptions } from "./server.js"; +import { createTapClient } from "./tap-client.js"; import { readOnlyLocalAnnotations, readOnlyNetworkAnnotations, } from "./tool-annotations.js"; -const defaultTapQueryMaxrec = 100; - export function registerStarfetchTools( server: McpServer, options: StarfetchMcpRuntimeOptions, @@ -103,7 +99,7 @@ function registerRegistryTools( } const prepared = options.policy.prepareRegistry({ - fallbackMaxrec: defaultTapQueryMaxrec, + fallbackMaxrec: DEFAULT_TAP_QUERY_MAXREC, incomingSignal: extra.signal, requestedMaxrec: maxrec, }); @@ -248,70 +244,12 @@ function registerQueryTools( outputSchema: tapQueryOutputSchema, title: "Run bounded TAP query", }, - async (input, extra) => - runTool(async () => { - const startedAt = performance.now(); - const client = createTapClient(input, options); - const format = input.format; - const requestFormat = tapRequestFormatForOutput(format); - const prepared = options.policy.prepareQuery({ - fallbackMaxrec: defaultTapQueryMaxrec, - incomingSignal: extra.signal, - requestedMaxrec: input.maxrec, - uploads: input.uploads, - }); - const maxrec = prepared.maxrec; - const result = await client.query( - input.query, - createTapQueryOptions(input, requestFormat, maxrec, prepared.signal), - ); - const data = await createTapQueryData(result, format); - - const diagnostics: { - durationMs: number; - effectiveMaxrec: number; - format: TapOutputFormat; - requestFormat: TapSyncFormat; - query: string; - runId?: string; - target: ReturnType; - uploadCount: number; - } = { - durationMs: performance.now() - startedAt, - effectiveMaxrec: maxrec, - format, - requestFormat, - query: input.query, - target: targetDiagnostics(client.target), - uploadCount: input.uploads?.length ?? 0, - }; - - if (input.runId !== undefined) { - diagnostics.runId = input.runId; - } - - return success(data, diagnostics); - }), + (input, extra) => + executeStarfetchTapQuery( + input, + extra.signal, + options, + DEFAULT_TAP_QUERY_MAXREC, + ), ); } - -function createTapQueryOptions( - input: TapQueryInput, - format: TapSyncFormat, - maxrec: number, - signal: AbortSignal, -): QueryOptions { - const queryOptions: QueryOptions = { format, maxrec, signal }; - - if (input.runId !== undefined) { - queryOptions.runId = input.runId; - } - - const uploads = createTapUploads(input.uploads); - - if (uploads !== undefined) { - queryOptions.uploads = uploads; - } - - return queryOptions; -}