Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 28 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand Down
11 changes: 8 additions & 3 deletions apps/mcp-app/PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 0 additions & 1 deletion apps/mcp-app/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
19 changes: 19 additions & 0 deletions apps/mcp-app/src/hosted-policy.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
13 changes: 8 additions & 5 deletions apps/mcp-app/src/hosted-policy.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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({
Expand Down Expand Up @@ -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),
};
},
Expand Down Expand Up @@ -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",
Expand Down
69 changes: 67 additions & 2 deletions apps/mcp-app/src/hosted-server.test.ts
Original file line number Diff line number Diff line change
@@ -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";
Expand All @@ -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,
Expand Down Expand Up @@ -91,10 +97,18 @@ const expectedHostedToolAnnotations = {
describe("hosted Starfetch MCP server", () => {
it("adds the portable table renderer and immutable widget resource", async () => {
const widgetHtml = "<!doctype html><title>Starfetch results</title>";
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),
Expand All @@ -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]),
Expand All @@ -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",
Expand Down Expand Up @@ -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({
Expand Down Expand Up @@ -209,3 +257,20 @@ describe("hosted Starfetch MCP server", () => {
}
});
});

function createVotable(rowCount: number): string {
const rows = Array.from(
{ length: rowCount },
(_, index) => `<TR><TD>${index + 1}</TD></TR>`,
).join("");
return `<?xml version="1.0"?>
<VOTABLE version="1.4">
<RESOURCE type="results">
<INFO name="QUERY_STATUS" value="OK">Successful query</INFO>
<TABLE>
<FIELD name="source_id" datatype="long" />
<DATA><TABLEDATA>${rows}</TABLEDATA></DATA>
</TABLE>
</RESOURCE>
</VOTABLE>`;
}
Loading