diff --git a/.agents/skills/verify-toolkit/SKILL.md b/.agents/skills/verify-toolkit/SKILL.md index 799b77a47f..ada5bcf55d 100644 --- a/.agents/skills/verify-toolkit/SKILL.md +++ b/.agents/skills/verify-toolkit/SKILL.md @@ -89,6 +89,15 @@ node .agents/skills/verify-toolkit/scripts/check-results.mjs subset WIDE_DIR DIR node .agents/skills/verify-toolkit/scripts/check-results.mjs local DIR ``` +`scripts/mcp-apps-host.mjs` acts as an MCP Apps host for +`render_sentry_chart` on the mock server: it reads the tool's `ui://` view, +mounts it in headless Chromium through the ext-apps `AppBridge`, and writes +screenshots, `host-log.json`, and `checks.txt` to `--out`: + +```bash +node .agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs --out DIR +``` + `scripts/sentry-offline.mjs` runs one CLI command with the same offline env, and writes `command.txt`, `stdout.txt`, `stderr.txt`, and `exit-code.txt`: diff --git a/.agents/skills/verify-toolkit/map/README.md b/.agents/skills/verify-toolkit/map/README.md index 8ab5a451d5..54a2ad8a0b 100644 --- a/.agents/skills/verify-toolkit/map/README.md +++ b/.agents/skills/verify-toolkit/map/README.md @@ -57,5 +57,7 @@ out of the map. - `mcp-access.md` covers who can start `sentry mcp` and what a session reaches: login, skills, and org scope. - `cli.md` covers CLI behavior with no login and with a token. +- `mcp-apps.md` covers what an MCP Apps host gets for `render_sentry_chart`: + the `ui://` view, rendering, theme, and calls back through the host. - `sentry-local.md` covers `sentry local`: verifying an app's SDK, querying a retained session, hiding session credentials, and stopping the daemon. diff --git a/.agents/skills/verify-toolkit/map/mcp-apps.md b/.agents/skills/verify-toolkit/map/mcp-apps.md new file mode 100644 index 0000000000..fa63746853 --- /dev/null +++ b/.agents/skills/verify-toolkit/map/mcp-apps.md @@ -0,0 +1,44 @@ +# MCP Apps chart view + +What an MCP Apps host (Claude, VS Code, ChatGPT) gets for `render_sentry_chart`: +the tool names a `ui://` view in `tools/list`, the view reads back as one +self-contained HTML document, and the view renders the tool result, follows +the host theme, and calls the tool again through the host. The goals are in +`design/mcp-apps.md`. + +## Claims + +- `tool-meta` `render_sentry_chart` sets `_meta.ui.resourceUri` to a `ui://` URI and `_meta["openai/outputTemplate"]` to the same URI, with no deprecated flat `ui/resourceUri` key. Proof: `drive`. +- `view-resource` `resources/list` lists that URI, and `resources/read` returns it with mime type `text/html;profile=mcp-app` and an HTML document. Proof: `drive`. +- `view-listing` A session that cannot call `render_sentry_chart`, including every stable (non-experimental) session, lists no resources and no resources capability. Proof: `test` with `pnpm --filter @sentry/mcp-core exec vitest run src/server.ui-resources.test.ts`. +- `view-renders` Mounted through the ext-apps AppBridge, which also checks the view's hand-written MCP Apps bridge against the reference host, the view draws the series, shows a tooltip on hover, and hides its empty state. Proof: `drive`. +- `view-theme` The view follows the host's light or dark theme. Proof: `drive`. +- `range-roundtrip` The range picker calls `render_sentry_chart` through the host with the new period and redraws without remounting. Proof: `drive`. +- `open-link` "Open in Sentry" asks the host to open the result's Sentry URL with `ui/open-link`. Proof: `drive`. +- `grouped` A `groupBy` result draws one series per top group, with a legend. Proof: `drive`. +- `lifecycle` The view follows a `host-context-changed` theme change, shows a cancelled state on `ui/notifications/tool-cancelled`, and answers `ui/resource-teardown`. Proof: `drive`. +- `default-csp` The view loads and runs under the spec's default CSP with no console errors, so it needs no `csp` domains. Proof: `drive`. + +## How to get to it + +- An MCP Apps host that lists `render_sentry_chart` and reads its `ui://` resource, over stdio (`sentry mcp --experimental`, `npx @sentry/mcp-server --experimental`) or remote HTTP in experimental mode. Stable sessions list neither the tool nor the view. +- A host with no MCP Apps support gets the same tool with a text and structured result only. + +## Driving it with mcp-apps-host.mjs + +Preconditions: + +- Launch from `../SKILL.md` has run on this checkout, and `$VERIFY_RUN` is set. +- A Chromium build for playwright-core is installed. If the script cannot launch it, run `pnpm --filter @sentry/mcp-core exec playwright-core install chromium-headless-shell`. + +- **Every `drive` claim: act as the host.** Run `node .agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs --out "$VERIFY_RUN/mcp-apps"`. It starts the mock server, calls the tool, reads the view, and mounts it in headless Chromium inside a host page that uses `AppBridge`. Every line it prints, also in `checks.txt`, is `PASS`. The screenshots `chart-light.png`, `chart-dark.png`, `chart-range-7d.png`, and `chart-grouped-dark.png` show each state. `host-log.json` holds the view's `tools/call` and `ui/open-link` requests to the host. + +## Gotchas + +- The mock server answers from built packages. Rerun `pnpm run build` after changing mcp-core or the mocks, or the script drives stale code. +- The view is generated. After changing `packages/mcp-core/chart-app/`, run `pnpm --filter @sentry/mcp-core generate-chart-app`, then build. +- The host page sets the default CSP with a meta tag in `srcdoc`. Real hosts serve the view from a sandbox origin with CSP headers. + +## Gaps + +- `real-hosts` Rendering in Claude, VS Code, ChatGPT, and Codex desktop needs those apps with a live server; this map drives only the reference AppBridge. Use `mcp-qa` for real hosts. diff --git a/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs b/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs new file mode 100644 index 0000000000..c322708d1f --- /dev/null +++ b/.agents/skills/verify-toolkit/scripts/mcp-apps-host.mjs @@ -0,0 +1,331 @@ +#!/usr/bin/env node +// Act as an MCP Apps host for render_sentry_chart, with no LLM: start the mock +// stdio server, call the tool, read its `ui://` view, and mount the view in a +// headless browser through the ext-apps AppBridge, the way Claude or VS Code +// does. Screenshots the chart in light and dark, after the range picker calls +// the tool again through the host, and split by an attribute. Writes evidence +// and one PASS or FAIL line per check to checks.txt in --out. See ../SKILL.md. +import { appendFileSync, mkdirSync, writeFileSync } from "node:fs"; +import { createRequire } from "node:module"; +import { dirname, join, resolve } from "node:path"; +import { fileURLToPath, pathToFileURL } from "node:url"; +import { offlineEnv } from "./offline-env.mjs"; + +const repo = resolve(dirname(fileURLToPath(import.meta.url)), "../../../.."); +const argv = process.argv.slice(2); +const out = argv[argv.indexOf("--out") + 1]; +if (!argv.includes("--out") || !out) { + console.error("usage: mcp-apps-host.mjs --out DIR"); + process.exit(2); +} +mkdirSync(out, { recursive: true }); + +// The MCP client SDK is a dependency of the test client; esbuild, the +// AppBridge, and playwright-core are dev dependencies of mcp-core. +const fromClient = createRequire( + join(repo, "packages/mcp-test-client/package.json"), +); +const fromCore = createRequire(join(repo, "packages/mcp-core/package.json")); +const load = (require, id) => import(pathToFileURL(require.resolve(id)).href); +const { Client } = await load( + fromClient, + "@modelcontextprotocol/sdk/client/index.js", +); +const { StdioClientTransport } = await load( + fromClient, + "@modelcontextprotocol/sdk/client/stdio.js", +); +const { build } = await load(fromCore, "esbuild"); +const { chromium } = fromCore("playwright-core"); + +const TOOL = "render_sentry_chart"; +const ORG = "sentry-mcp-evals"; +const ERRORS_CHART = { + organizationSlug: ORG, + dataset: "errors", + query: "level:error", + yAxis: "count()", + period: "24h", +}; +const GROUPED_CHART = { + organizationSlug: ORG, + dataset: "spans", + query: "is_transaction:true", + yAxis: "p95(span.duration)", + groupBy: "release", + period: "7d", +}; +// The spec's default view CSP: no network, no eval. +const DEFAULT_CSP = + "default-src 'none'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; media-src 'self' data:; connect-src 'none'"; + +const write = (name, value) => + writeFileSync( + join(out, name), + typeof value === "string" ? value : `${JSON.stringify(value, null, 2)}\n`, + ); +let failures = 0; +function check(id, ok, detail) { + const line = `${ok ? "PASS" : "FAIL"} mcp-apps#${id}: ${detail}`; + if (!ok) failures++; + console.log(line); + appendFileSync(join(out, "checks.txt"), `${line}\n`); +} + +// A minimal host page: mounts the view in a sandboxed iframe under the +// default CSP and bridges it with AppBridge. Tool calls from the view go to +// Node (window.mcpCallTool), which forwards them to the real server. +const hostScript = ( + await build({ + stdin: { + resolveDir: join(repo, "packages/mcp-core"), + contents: ` + import { AppBridge, PostMessageTransport } from "@modelcontextprotocol/ext-apps/app-bridge"; + window.hostLog = []; + window.mountView = async ({ html, theme, toolArgs, toolResult }) => { + document.body.dataset.theme = theme; + const iframe = document.createElement("iframe"); + iframe.setAttribute("sandbox", "allow-scripts"); + document.getElementById("host").replaceChildren(iframe); + const bridge = new AppBridge( + null, + { name: "verify-toolkit host", version: "0.0.0" }, + { openLinks: {}, serverTools: {} }, + { hostContext: { theme, locale: "en-US", timeZone: "UTC", platform: "web", displayMode: "inline", containerDimensions: { width: 720, maxHeight: 900 } } }, + ); + bridge.oncalltool = async (params) => { + window.hostLog.push({ method: "tools/call", params }); + return await window.mcpCallTool(params); + }; + bridge.onopenlink = async (params) => { + window.hostLog.push({ method: "ui/open-link", params }); + return {}; + }; + bridge.onsizechange = ({ height }) => { + if (height) iframe.style.height = height + "px"; + }; + window.bridge = bridge; + const initialized = new Promise((done) => { bridge.oninitialized = done; }); + await bridge.connect(new PostMessageTransport(iframe.contentWindow, iframe.contentWindow)); + iframe.srcdoc = html.replace("", ${JSON.stringify(``)}); + await initialized; + await bridge.sendToolInput({ arguments: toolArgs }); + await bridge.sendToolResult(toolResult); + }; + `, + }, + bundle: true, + format: "iife", + write: false, + }) +).outputFiles[0].text; +const hostPage = `
`; + +const { env, cleanup } = offlineEnv({ token: true }); +delete env.SENTRY_HOST; +const transport = new StdioClientTransport({ + command: process.execPath, + args: [ + "--experimental-strip-types", + "--import", + join(repo, "scripts/strip-types-resolve.mjs"), + join(repo, "packages/mcp-server-evals/src/bin/start-mock-stdio.ts"), + ], + env, + cwd: repo, + stderr: "pipe", +}); +let stderr = ""; +transport.stderr?.on("data", (chunk) => { + stderr += chunk; +}); +const client = new Client({ + name: "verify-toolkit-apps-host", + version: "0.0.0", +}); +let browser; +try { + await client.connect(transport); + const { tools } = await client.listTools(); + const tool = tools.find((t) => t.name === TOOL); + write("tool.json", tool ?? null); + const uri = tool?._meta?.ui?.resourceUri; + check( + "tool-meta", + typeof uri === "string" && + uri.startsWith("ui://") && + tool._meta["openai/outputTemplate"] === uri && + !("ui/resourceUri" in tool._meta), + `${TOOL} _meta.ui.resourceUri=${uri}, openai/outputTemplate=${tool?._meta?.["openai/outputTemplate"]}`, + ); + + const { resources } = await client.listResources(); + const { contents } = await client.readResource({ uri }); + const view = contents[0]; + write("resources-list.json", resources); + write("resource-read.json", { + ...view, + text: `<${view?.text?.length ?? 0} chars, see view.html>`, + }); + write("view.html", view?.text ?? ""); + check( + "view-resource", + resources.some((r) => r.uri === uri) && + view?.mimeType === "text/html;profile=mcp-app" && + view.text.startsWith(""), + `resources/read ${uri}: ${view?.mimeType}, ${Math.round((view?.text?.length ?? 0) / 1024)} KiB HTML`, + ); + + const calls = []; + const callTool = async (params) => { + const result = await client.callTool(params); + calls.push({ request: params, result }); + return result; + }; + const errorsResult = await callTool({ name: TOOL, arguments: ERRORS_CHART }); + const groupedResult = await callTool({ + name: TOOL, + arguments: GROUPED_CHART, + }); + + browser = await chromium.launch(); + const page = await browser.newPage({ + viewport: { width: 768, height: 520 }, + deviceScaleFactor: 2, + }); + const consoleErrors = []; + page.on("console", (msg) => { + if (msg.type() === "error") consoleErrors.push(msg.text()); + }); + await page.exposeFunction("mcpCallTool", callTool); + await page.setContent(hostPage); + const frame = page.frameLocator("iframe"); + const mount = async (theme, toolArgs, toolResult) => { + await page.evaluate((input) => window.mountView(input), { + html: view.text, + theme, + toolArgs, + toolResult, + }); + await frame.locator("svg path").first().waitFor(); + // Let the view report its size and the host resize the iframe. + await page.waitForTimeout(300); + }; + const shot = async (name) => { + await page.locator("#host").screenshot({ path: join(out, name) }); + return join(out, name); + }; + + await mount("light", ERRORS_CHART, errorsResult); + const svgBox = await frame.locator("svg").boundingBox(); + await page.mouse.move( + svgBox.x + svgBox.width * 0.7, + svgBox.y + svgBox.height / 2, + ); + const tooltip = await frame.locator(".tooltip").innerText(); + const light = await shot("chart-light.png"); + const lightBg = await frame + .locator("body") + .evaluate((el) => getComputedStyle(el).backgroundColor); + const emptyHidden = await frame.locator(".state").isHidden(); + check( + "view-renders", + tooltip.includes("count()") && emptyHidden, + `light chart with hover tooltip "${tooltip.replace(/\s+/g, " ")}" -> ${light}`, + ); + + await mount("dark", ERRORS_CHART, errorsResult); + const darkBg = await frame + .locator("body") + .evaluate((el) => getComputedStyle(el).backgroundColor); + const dark = await shot("chart-dark.png"); + check( + "view-theme", + lightBg !== darkBg, + `host theme light=${lightBg} dark=${darkBg} -> ${dark}`, + ); + + await mount("light", ERRORS_CHART, errorsResult); + const before = await frame.locator(".subtitle").innerText(); + await frame.getByRole("button", { name: "7d", exact: true }).click(); + await frame.locator(".subtitle", { hasText: "Last 7 days" }).waitFor(); + await frame.locator('.chart[data-loading="false"]').waitFor(); + const range = await shot("chart-range-7d.png"); + const hostLog = await page.evaluate(() => window.hostLog); + const rangeCall = hostLog.find((entry) => entry.method === "tools/call"); + const rangeResult = calls.at(-1); + check( + "range-roundtrip", + rangeCall?.params?.name === TOOL && + rangeCall.params.arguments.period === "7d" && + rangeResult?.result?.structuredContent?.timeRange?.statsPeriod === "7d", + `"${before}" -> view called ${TOOL} period=7d through the host, got ${rangeResult?.result?.structuredContent?.series?.[0]?.buckets?.length} buckets -> ${range}`, + ); + + await frame.getByRole("button", { name: "Open in Sentry" }).click(); + await page.waitForFunction(() => + window.hostLog.some((e) => e.method === "ui/open-link"), + ); + const openLink = (await page.evaluate(() => window.hostLog)).find( + (e) => e.method === "ui/open-link", + ); + check( + "open-link", + openLink?.params?.url?.startsWith(`https://${ORG}.sentry.io/`), + `ui/open-link ${openLink?.params?.url}`, + ); + + await mount("dark", GROUPED_CHART, groupedResult); + const legend = await frame.locator(".legend").innerText(); + const grouped = await shot("chart-grouped-dark.png"); + check( + "grouped", + legend.split("\n").filter(Boolean).length === 3, + `top groups "${legend.replace(/\n/g, " | ")}" -> ${grouped}`, + ); + + // The rest of the lifecycle: a theme change, a cancelled call, teardown. + await page.evaluate(() => + window.bridge.sendHostContextChange({ theme: "light" }), + ); + await frame + .locator("html[data-theme='light']") + .waitFor({ state: "attached" }); + await page.evaluate(() => + window.bridge.sendToolCancelled({ reason: "verify-toolkit" }), + ); + const cancelled = await frame.locator(".state.error").innerText(); + const teardown = await page.evaluate(() => + window.bridge.teardownResource({ reason: "verify-toolkit" }), + ); + check( + "lifecycle", + cancelled.includes("cancelled") && JSON.stringify(teardown) === "{}", + `host-context-changed -> light, tool-cancelled -> "${cancelled}", ui/resource-teardown -> ${JSON.stringify(teardown)}`, + ); + + write("host-log.json", await page.evaluate(() => window.hostLog)); + write("calls.json", calls); + write("console-errors.json", consoleErrors); + check( + "default-csp", + consoleErrors.length === 0, + `${consoleErrors.length} console errors under the default CSP`, + ); +} catch (error) { + check( + "host-run", + false, + error instanceof Error ? (error.stack ?? error.message) : String(error), + ); +} finally { + await browser?.close(); + await client.close().catch(() => {}); + cleanup(); + writeFileSync(join(out, "server-stderr.txt"), stderr); +} +process.exit(failures > 0 ? 1 : 0); diff --git a/.github/workflows/token-cost.yml b/.github/workflows/token-cost.yml index 86a98b29af..711299dd34 100644 --- a/.github/workflows/token-cost.yml +++ b/.github/workflows/token-cost.yml @@ -14,6 +14,11 @@ on: - "packages/mcp-core/src/internal/tool-helpers/tool-call-formatting.ts" - "packages/mcp-core/scripts/measure-token-cost.ts" - "packages/mcp-core/scripts/generate-definitions.ts" + - "packages/mcp-core/chart-app/**" + - "packages/mcp-core/src/ui/**" + - "packages/mcp-core/src/ui-resources.ts" + - "packages/mcp-core/scripts/generate-chart-app.ts" + - "packages/mcp-core/scripts/measure-ui-views.ts" - "package.json" - "pnpm-lock.yaml" - "pnpm-workspace.yaml" @@ -29,6 +34,11 @@ on: - "packages/mcp-core/src/internal/tool-helpers/tool-call-formatting.ts" - "packages/mcp-core/scripts/measure-token-cost.ts" - "packages/mcp-core/scripts/generate-definitions.ts" + - "packages/mcp-core/chart-app/**" + - "packages/mcp-core/src/ui/**" + - "packages/mcp-core/src/ui-resources.ts" + - "packages/mcp-core/scripts/generate-chart-app.ts" + - "packages/mcp-core/scripts/measure-ui-views.ts" - "package.json" - "pnpm-lock.yaml" - "pnpm-workspace.yaml" @@ -126,6 +136,10 @@ jobs: # Save for summary cat token-report.md >> $GITHUB_STEP_SUMMARY + - name: Measure MCP Apps views + working-directory: packages/mcp-core + run: pnpm run measure-ui -- -o ui-stats.json --markdown token-report.md --markdown "$GITHUB_STEP_SUMMARY" + - name: Download main branch token stats if: github.event_name == 'pull_request' uses: dawidd6/action-download-artifact@v6 @@ -246,10 +260,11 @@ jobs: details_url: `https://github.com/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId}` }); - - name: Comment on PR if token count changed + - name: Comment on PR uses: actions/github-script@v7 - # Skip for fork PRs (no write permissions) - if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository && steps.compare.outputs.has_comparison == 'true' && steps.compare.outputs.delta != '0' + # Skip for fork PRs (no write permissions). Posts on every run, since + # a view can change while the tool token count stays the same. + if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository continue-on-error: true # Don't fail workflow if comment creation fails with: script: | @@ -290,5 +305,7 @@ jobs: if: always() with: name: token-stats-${{ github.sha }} - path: packages/mcp-core/token-stats.json + path: | + packages/mcp-core/token-stats.json + packages/mcp-core/ui-stats.json retention-days: 90 diff --git a/.oxfmtrc.json b/.oxfmtrc.json index 39e40ef1b8..b27ad9c221 100644 --- a/.oxfmtrc.json +++ b/.oxfmtrc.json @@ -12,6 +12,7 @@ "packages/cli/CHANGELOG.md", "packages/cli/AGENTS.md", "packages/mcp-server-mocks/src/fixtures/**", + "packages/mcp-core/src/ui/chart-app.generated.ts", "packages/codemod-cli3to4/tests/**", "**/worker-configuration.d.ts", "**/tsconfig*.json" diff --git a/.oxlintrc.json b/.oxlintrc.json index d39013caec..2962949c1a 100644 --- a/.oxlintrc.json +++ b/.oxlintrc.json @@ -13,6 +13,7 @@ "**/worker-configuration.d.ts", "**/tsconfig*.json", "packages/mcp-server-mocks/src/fixtures/**", + "packages/mcp-core/src/ui/chart-app.generated.ts", "packages/codemod-cli3to4/tests/**" ], "rules": { @@ -130,12 +131,20 @@ { "name": "sentry", "message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)." + }, + { + "name": "@modelcontextprotocol/ext-apps", + "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)." } ], "patterns": [ { "group": ["sentry/**", "**/cli/src/**", "**/packages/cli/**"], "message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)." + }, + { + "group": ["@modelcontextprotocol/ext-apps/**"], + "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)." } ] } @@ -398,6 +407,10 @@ "group": ["sentry/**", "**/cli/src/**", "**/packages/cli/**"], "message": "mcp-core and toolkit-core must not import the Sentry CLI. Inject CLI-only capabilities through interfaces defined in mcp-core or toolkit-core (see docs/architecture/overview.md#package-dependency-direction)." }, + { + "group": ["@modelcontextprotocol/ext-apps/**"], + "message": "mcp-core and its MCP Apps views speak MCP Apps directly (src/ui-resources.ts, chart-app/bridge.ts), so the server bundle and the views stay small. ext-apps is a dev dependency for the verify-toolkit host only (see design/mcp-apps.md)." + }, { "group": ["node:*"], "message": "Shared toolkit-core modules must run in browsers. Use web-standard APIs, or inject the host-specific piece." diff --git a/design/README.md b/design/README.md index bc361c45d8..92ba6c3a26 100644 --- a/design/README.md +++ b/design/README.md @@ -34,6 +34,7 @@ such as `automations#run-now`, and do not restate it. - [MCP tools](./mcp-tools.md): the Sentry tools an agent can list and call, and how it finds the right one. - [MCP tool responses](./mcp-tool-responses.md): what a tool result gives an agent to answer a Sentry question. +- [MCP Apps views](./mcp-apps.md): interactive views that MCP Apps hosts render inline for a tool result. - [MCP access](./mcp-access.md): who can use Sentry MCP, over which transport, and what a session can reach. - [Sentry CLI](./sentry-cli.md): the `sentry` command for people and agents in a terminal. - [Sentry Local](./sentry-local.md): the app telemetry `sentry local` captures on a developer's machine, with no account. diff --git a/design/mcp-apps.md b/design/mcp-apps.md new file mode 100644 index 0000000000..7fb1a01ce0 --- /dev/null +++ b/design/mcp-apps.md @@ -0,0 +1,73 @@ +# MCP Apps views + +A host that supports MCP Apps, such as Claude or VS Code, renders a Sentry +tool result as an interactive view inline in the conversation. Every other +client gets the same answer as text. + +## Intent + +- A view is an optional enhancement. A tool with a view gives every client + the complete answer, so a text-only client or a host without MCP Apps loses + nothing but the picture. +- The model never relays data to a view. A tool with a view takes a query, + and the server fetches the data from Sentry, so what the view shows comes + from Sentry, not from model output. +- A view costs a session nothing until a host renders it, and little when + one does. Views speak the MCP Apps protocol directly, with no SDK or schema + library, so adding one barely grows the server. +- A view is safe in any host's sandbox. It trusts nothing that it receives + and reaches nothing outside the host. + +## Entry points + +- The `render_sentry_chart` chart in an MCP Apps host, with its range picker + and Open in Sentry button, in experimental sessions. +- `ui://` resources in `resources/list` and `resources/read`, named by a + tool's `_meta.ui.resourceUri` (and `openai/outputTemplate` for ChatGPT). + +## Rules + +- MCP Apps ship in experimental sessions only, until real hosts are + verified. A tool with a view is marked `experimental`, so a stable + session lists neither the tool nor its view, and skill prompts do not + advertise it. +- A tool with a view is listed for every client that can call it, and its + result is the same for every client. A view shows nothing that the result + does not hold. +- A tool with a view takes a query, not values. Follow-up calls from the + view, such as a new time range, call the same tool through the host. +- A view is one self-contained HTML document with inline scripts and + styles. Its declared CSP lists no origins, and it loads nothing from the + network: no remote scripts, styles, fonts, or images, and no requests. +- Each view has a byte budget, and the build fails when the view exceeds + it. The chart's budget is 24 KiB. +- A view's `ui://` URI carries a version, and any change to the view's HTML + ships under a new version, because hosts cache views by URI. +- A view treats the tool result and every host message as untrusted. It + parses the result into its own shape at the boundary, shows an error state + instead of drawing data in the wrong shape, and writes text only as text. +- A session lists a view only when it lists a tool that names it. A session + with no such tool declares no resources capability. +- Views are not gated on the client advertising MCP Apps support + (`capabilities.extensions["io.modelcontextprotocol/ui"]`). The remote + server builds a new session for each HTTP request, so it cannot see what + the client sent in `initialize` when it answers `tools/list`. Gating there + would hide views from Claude, VS Code, and ChatGPT, which all advertise + support. Hosts that render without advertising, such as the ext-apps + reference host, would also lose them. Instead, the server loads a view's + HTML only when a host reads the view, so a text-only session never loads + it. +- A view follows the host's theme, locale, and time zone. + +## Gaps + +- Rendering is proven only against the ext-apps reference host + (`mcp-apps#real-hosts`). Claude, VS Code, ChatGPT, and Codex are not + verified, so "every MCP Apps host renders the view" is unproven. +- The spec says servers SHOULD check client capabilities before they list + UI tools. Sessions that cannot render, such as the Codex and Goose CLIs, + still get `_meta.ui` and a listed view. They never load its HTML. This + falls short of "costs a session nothing" by one tool `_meta` key and one + resource entry. Gating can follow once the remote server sees client + capabilities on each request, as the draft protocol's per-request + capabilities allow. diff --git a/design/mcp-tool-responses.md b/design/mcp-tool-responses.md index cd5a0e5da4..ac692fa36f 100644 --- a/design/mcp-tool-responses.md +++ b/design/mcp-tool-responses.md @@ -26,6 +26,8 @@ question, in Sentry's own terms, without reading upstream API payloads. - Response notes and side quests: short tips at the end of a result, such as a pagination cursor or source maps that failed to apply. - Feedback suggestions that point at `submit_feedback_to_sentry_team`. +- MCP Apps views, which render a tool's structured content inline in hosts + that support them. They follow [MCP Apps views](./mcp-apps.md). ## Rules diff --git a/design/mcp-tools.md b/design/mcp-tools.md index 79cf5834d3..37bddb56ef 100644 --- a/design/mcp-tools.md +++ b/design/mcp-tools.md @@ -32,6 +32,9 @@ harness the user already works in, such as Claude Code, Codex, or Cursor. that are not stable yet. - `search_sentry_tools` and `execute_sentry_tool`, only on the fallback gateway surface. +- MCP Apps views, which follow [MCP Apps views](./mcp-apps.md). + `render_sentry_chart` is the one tool with a view, and it is + experimental. ## Rules diff --git a/docs/contributing/adding-tools.md b/docs/contributing/adding-tools.md index 618cf14a85..d51bc578e6 100644 --- a/docs/contributing/adding-tools.md +++ b/docs/contributing/adding-tools.md @@ -264,6 +264,10 @@ particular: See [common-patterns.md](common-patterns.md#response-formatting) for shared formatting patterns and examples. +To render a result inline in MCP Apps hosts, see +[tool-responses.md](tool-responses.md#mcp-apps-views). A view is optional: +the tool still answers in full for every other client. + ## Step 3: Add Tests Follow comprehensive testing patterns from [../testing/overview.md](../testing/overview.md) for unit, integration, and evaluation tests. diff --git a/docs/contributing/tool-responses.md b/docs/contributing/tool-responses.md index 6c47e210ef..477168f47a 100644 --- a/docs/contributing/tool-responses.md +++ b/docs/contributing/tool-responses.md @@ -232,6 +232,34 @@ experimental sessions first stays pending until it graduates. The PR that makes an entry stale also deletes it. To add a `_meta` key, add it to `ALLOWED_TOOL_META` with a comment that says which client reads it. +## MCP Apps Views + +A tool can name an inline view for hosts that support +[MCP Apps](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx). +The rules a view follows are in +[design/mcp-apps.md](../../design/mcp-apps.md). `render_sentry_chart` is the +example: + +- The view is a `UiResource` in `packages/mcp-core/src/ui-resources.ts`: a + versioned `ui://` URI, the `htmlSha256` of its HTML, and a `loadHtml()` that + imports the generated module on the first `resources/read`. +- The tool sets `_meta: uiToolMeta(resource)`, which writes + `_meta.ui.resourceUri` for MCP Apps hosts and `openai/outputTemplate` for + ChatGPT. Add both keys to `ALLOWED_TOOL_META`. +- The view source lives in `packages/mcp-core/chart-app/`. `bridge.ts` is the + MCP Apps protocol over `postMessage`, and `parse.ts` parses + `structuredContent` into the chart type (`parse.test.ts` keeps it in step + with the tool's output schema). Do not import `@modelcontextprotocol/ext-apps` + or zod there; Oxlint rejects the first, and the budget rejects the second. +- Run `pnpm --filter @sentry/mcp-core generate-chart-app` after changing the + view. It and `ci:policy` fail when the view is over its budget or loads + anything from the network, and `ci:policy` fails when the generated file is + stale. `src/ui-resources.test.ts` then fails until you bump the URI version + and set the new `htmlSha256` it prints. +- Prove a view with `.agents/skills/verify-toolkit/map/mcp-apps.md`, which + mounts it through the ext-apps `AppBridge` in headless Chromium. That run is + also the conformance check for `bridge.ts`. + ## Suggested Actions Use `suggestedActions` when a tool result reveals a concrete follow-up tool call diff --git a/docs/evidence/mcp-apps-chart/chart-dark.png b/docs/evidence/mcp-apps-chart/chart-dark.png new file mode 100644 index 0000000000..746cd8d2e6 Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-dark.png differ diff --git a/docs/evidence/mcp-apps-chart/chart-grouped-dark.png b/docs/evidence/mcp-apps-chart/chart-grouped-dark.png new file mode 100644 index 0000000000..72831ff1ef Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-grouped-dark.png differ diff --git a/docs/evidence/mcp-apps-chart/chart-light.png b/docs/evidence/mcp-apps-chart/chart-light.png new file mode 100644 index 0000000000..6f1ebd6f14 Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-light.png differ diff --git a/docs/evidence/mcp-apps-chart/chart-range-7d.png b/docs/evidence/mcp-apps-chart/chart-range-7d.png new file mode 100644 index 0000000000..0ac5ab1e1d Binary files /dev/null and b/docs/evidence/mcp-apps-chart/chart-range-7d.png differ diff --git a/docs/evidence/mcp-apps-chart/checks.txt b/docs/evidence/mcp-apps-chart/checks.txt new file mode 100644 index 0000000000..5a6fcdf08e --- /dev/null +++ b/docs/evidence/mcp-apps-chart/checks.txt @@ -0,0 +1,9 @@ +PASS mcp-apps#tool-meta: render_sentry_chart _meta.ui.resourceUri=ui://sentry/chart/v1.html, openai/outputTemplate=ui://sentry/chart/v1.html +PASS mcp-apps#view-resource: resources/read ui://sentry/chart/v1.html: text/html;profile=mcp-app, 16 KiB HTML +PASS mcp-apps#view-renders: light chart with hover tooltip "Sep 10, 16:00 UTC count() 91" -> docs/evidence/mcp-apps-chart/chart-light.png +PASS mcp-apps#view-theme: host theme light=rgb(255, 255, 255) dark=rgb(30, 26, 37) -> docs/evidence/mcp-apps-chart/chart-dark.png +PASS mcp-apps#range-roundtrip: "errors · level:error · Last 24 hours" -> view called render_sentry_chart period=7d through the host, got 56 buckets -> docs/evidence/mcp-apps-chart/chart-range-7d.png +PASS mcp-apps#open-link: ui/open-link https://sentry-mcp-evals.sentry.io/explore/discover/homepage/?dataset=errors&queryDataset=error-events&query=level%3Aerror&project=-1&field=count%28%29&sort=-count%28%29&statsPeriod=7d&mode=aggregate&yAxis=count%28%29 +PASS mcp-apps#grouped: top groups "frontend@2.4.1 | frontend@2.4.0 | frontend@2.3.9" -> docs/evidence/mcp-apps-chart/chart-grouped-dark.png +PASS mcp-apps#lifecycle: host-context-changed -> light, tool-cancelled -> "The chart request was cancelled.", ui/resource-teardown -> {} +PASS mcp-apps#default-csp: 0 console errors under the default CSP diff --git a/docs/operations/token-cost-tracking.md b/docs/operations/token-cost-tracking.md index c3d2a22d06..182140682b 100644 --- a/docs/operations/token-cost-tracking.md +++ b/docs/operations/token-cost-tracking.md @@ -86,6 +86,26 @@ GitHub Actions workflow runs on every PR and push to main: **Workflow:** `.github/workflows/token-cost.yml` +## MCP Apps View Size + +The same workflow measures each MCP Apps view, the `ui://` HTML that a host +such as Claude, VS Code, or ChatGPT downloads to render a tool result. The +script builds the server with every skill, lists its resources, and reads each +`ui://` resource through `resources/read`, so a new view shows up without a +script change. + +```bash +pnpm --filter @sentry/mcp-core measure-ui # Display +pnpm --filter @sentry/mcp-core measure-ui -- -o ui-stats.json # Write JSON +``` + +Per view it reports raw, gzip (level 9), and brotli (quality 11) bytes, and raw +bytes as a percentage of the view's `budgetBytes` in `src/ui-resources.ts`. +The report adds an "MCP Apps views" section to the PR comment and job summary, +and `ui-stats.json` goes into the `token-stats-{sha}` artifact. The budget is +enforced by the view's generator, such as `generate-chart-app`, not by this +report; see [design/mcp-apps.md](../../design/mcp-apps.md). + ## Understanding the Results Run `pnpm run measure-tokens` for current numbers; the examples above are a diff --git a/packages/mcp-core/chart-app/bridge.ts b/packages/mcp-core/chart-app/bridge.ts new file mode 100644 index 0000000000..fed4286693 --- /dev/null +++ b/packages/mcp-core/chart-app/bridge.ts @@ -0,0 +1,249 @@ +/** + * The view side of MCP Apps: JSON-RPC 2.0 over `postMessage` with the host. + * Covers only what the chart view uses, so the view ships without zod or an + * MCP client SDK. + * + * Spec: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx + */ + +/** The stable spec version this view speaks. */ +const PROTOCOL_VERSION = "2026-01-26"; +const REQUEST_TIMEOUT_MS = 60_000; + +type JsonRpcId = string | number; + +interface JsonRpcError { + code: number; + message: string; + data?: unknown; +} + +/** One message on the wire, in either direction. */ +type JsonRpcMessage = + | { jsonrpc: "2.0"; id: JsonRpcId; method: string; params?: unknown } + | { jsonrpc: "2.0"; method: string; params?: unknown } + | { jsonrpc: "2.0"; id: JsonRpcId; result: unknown } + | { jsonrpc: "2.0"; id: JsonRpcId | null; error: JsonRpcError }; + +/** The fields of the spec's `HostContext` that the view reads. */ +export interface HostContext { + theme?: "light" | "dark"; + styles?: { variables?: Record }; + locale?: string; + timeZone?: string; +} + +interface ContentBlock { + type: string; + text?: string; +} + +/** An MCP `CallToolResult`. `structuredContent` is untrusted. */ +export interface CallToolResult { + content: ContentBlock[]; + structuredContent?: unknown; + isError?: boolean; +} + +interface ViewHandlers { + /** `ui/notifications/tool-input`: the complete tool arguments. */ + toolInput?(args: Record): void; + /** `ui/notifications/tool-result` */ + toolResult?(result: CallToolResult): void; + /** `ui/notifications/tool-cancelled` */ + toolCancelled?(reason: string | undefined): void; + /** The initial context and each `host-context-changed`, merged. */ + hostContext?(context: HostContext): void; + /** `ui/resource-teardown`, answered once this returns. */ + teardown?(): void; +} + +export interface Host { + /** `tools/call`, proxied by the host to the MCP server. */ + callTool( + name: string, + args: Record, + ): Promise; + /** `ui/open-link` */ + openLink(url: string): Promise; +} + +const isObject = (value: unknown): value is Record => + typeof value === "object" && value !== null && !Array.isArray(value); + +function toCallToolResult(params: unknown): CallToolResult { + const result = isObject(params) ? params : {}; + const content = Array.isArray(result["content"]) + ? result["content"].filter( + (block): block is ContentBlock => + isObject(block) && + typeof block["type"] === "string" && + (block["text"] === undefined || typeof block["text"] === "string"), + ) + : []; + return { + content, + structuredContent: result["structuredContent"], + isError: result["isError"] === true, + }; +} + +/** + * Runs the `ui/initialize` handshake, sends `ui/notifications/initialized`, + * then reports the view's size whenever it changes. Messages from any window + * other than `host` are ignored. + */ +export async function connect( + appInfo: { name: string; version: string }, + handlers: ViewHandlers, + host: Window = window.parent, +): Promise { + let nextId = 1; + let context: HostContext = {}; + const pending = new Map< + JsonRpcId, + { resolve(result: unknown): void; reject(error: Error): void } + >(); + const send = (message: JsonRpcMessage) => host.postMessage(message, "*"); + + function request(method: string, params: unknown): Promise { + const id = nextId++; + return new Promise((resolve, reject) => { + const timer = setTimeout(() => { + pending.delete(id); + reject(new Error(`${method} timed out`)); + }, REQUEST_TIMEOUT_MS); + pending.set(id, { + resolve: (result) => { + clearTimeout(timer); + resolve(result); + }, + reject: (error) => { + clearTimeout(timer); + reject(error); + }, + }); + send({ jsonrpc: "2.0", id, method, params }); + }); + } + + function updateContext(partial: unknown): void { + if (!isObject(partial)) return; + context = { ...context, ...partial }; + handlers.hostContext?.(context); + } + + function onNotification(method: string, params: unknown): void { + const values = isObject(params) ? params : {}; + switch (method) { + case "ui/notifications/tool-input": + handlers.toolInput?.( + isObject(values["arguments"]) ? values["arguments"] : {}, + ); + return; + case "ui/notifications/tool-result": + handlers.toolResult?.(toCallToolResult(params)); + return; + case "ui/notifications/tool-cancelled": + handlers.toolCancelled?.( + typeof values["reason"] === "string" ? values["reason"] : undefined, + ); + return; + case "ui/notifications/host-context-changed": + updateContext(params); + return; + } + // Other notifications, such as tool-input-partial, need nothing here. + } + + function onRequest(id: JsonRpcId, method: string): void { + if (method === "ui/resource-teardown") handlers.teardown?.(); + if (method === "ui/resource-teardown" || method === "ping") { + send({ jsonrpc: "2.0", id, result: {} }); + return; + } + send({ + jsonrpc: "2.0", + id, + error: { code: -32601, message: `Method not found: ${method}` }, + }); + } + + window.addEventListener("message", (event: MessageEvent) => { + const message = event.data; + if (event.source !== host || !isObject(message)) return; + if (message["jsonrpc"] !== "2.0") return; + const { id, method } = message; + const hasId = typeof id === "string" || typeof id === "number"; + if (typeof method === "string") { + if (hasId) onRequest(id, method); + else onNotification(method, message["params"]); + return; + } + const waiter = hasId ? pending.get(id) : undefined; + if (!hasId || !waiter) return; + pending.delete(id); + const error = message["error"]; + if (isObject(error)) { + waiter.reject( + new Error( + typeof error["message"] === "string" + ? error["message"] + : "The host could not complete the request.", + ), + ); + } else { + waiter.resolve(message["result"]); + } + }); + + const initialized = await request("ui/initialize", { + appInfo, + appCapabilities: {}, + protocolVersion: PROTOCOL_VERSION, + }); + updateContext(isObject(initialized) ? initialized["hostContext"] : undefined); + send({ jsonrpc: "2.0", method: "ui/notifications/initialized" }); + reportSize(send); + + return { + callTool: async (name, args) => + toCallToolResult(await request("tools/call", { name, arguments: args })), + openLink: async (url) => { + await request("ui/open-link", { url }); + }, + }; +} + +/** Sends `ui/notifications/size-changed` once per frame when the size changes. */ +function reportSize(send: (message: JsonRpcMessage) => void): void { + let scheduled = false; + let width = 0; + let height = 0; + const measure = () => { + if (scheduled) return; + scheduled = true; + requestAnimationFrame(() => { + scheduled = false; + const root = document.documentElement; + // Measure the content, not a height the host gave the iframe. + const previous = root.style.height; + root.style.height = "max-content"; + const nextHeight = Math.ceil(root.getBoundingClientRect().height); + root.style.height = previous; + const nextWidth = Math.ceil(window.innerWidth); + if (nextWidth === width && nextHeight === height) return; + width = nextWidth; + height = nextHeight; + send({ + jsonrpc: "2.0", + method: "ui/notifications/size-changed", + params: { width, height }, + }); + }); + }; + measure(); + const observer = new ResizeObserver(measure); + observer.observe(document.documentElement); + observer.observe(document.body); +} diff --git a/packages/mcp-core/chart-app/chart.test.ts b/packages/mcp-core/chart-app/chart.test.ts new file mode 100644 index 0000000000..0cac024ad4 --- /dev/null +++ b/packages/mcp-core/chart-app/chart.test.ts @@ -0,0 +1,48 @@ +import { describe, expect, it } from "vitest"; +import { scaleFraction, valueScale } from "./chart"; + +function plotted(values: number[]) { + const scale = valueScale(values); + return { + scale, + fractions: values.map((value) => scaleFraction(scale, value)), + baseline: scaleFraction(scale, 0), + }; +} + +describe("valueScale", () => { + it("keeps all-negative series inside the plot, with 0 at the top", () => { + const { scale, fractions, baseline } = plotted([-4, -2]); + + expect(scale).toEqual({ bottom: -4, top: 0, step: 1 }); + for (const fraction of fractions) { + expect(fraction).toBeGreaterThanOrEqual(0); + expect(fraction).toBeLessThanOrEqual(1); + } + expect(baseline).toBe(1); + }); + + it("spans mixed-sign series with the 0 baseline between them", () => { + const { scale, fractions, baseline } = plotted([-30, 5, 70]); + + expect(scale.bottom).toBeLessThanOrEqual(-30); + expect(scale.top).toBeGreaterThanOrEqual(70); + for (const fraction of fractions) { + expect(fraction).toBeGreaterThanOrEqual(0); + expect(fraction).toBeLessThanOrEqual(1); + } + expect(baseline).toBeGreaterThan(fractions[0] ?? 0); + expect(baseline).toBeLessThan(fractions[2] ?? 1); + }); + + it("puts 0 at the bottom of an all-positive series", () => { + const { scale, baseline } = plotted([56, 140]); + + expect(scale).toEqual({ bottom: 0, top: 150, step: 50 }); + expect(baseline).toBe(0); + }); + + it("gives an all-zero series a one-step domain", () => { + expect(valueScale([0, 0])).toEqual({ bottom: 0, top: 1, step: 1 }); + }); +}); diff --git a/packages/mcp-core/chart-app/chart.ts b/packages/mcp-core/chart-app/chart.ts new file mode 100644 index 0000000000..071e16b015 --- /dev/null +++ b/packages/mcp-core/chart-app/chart.ts @@ -0,0 +1,379 @@ +/** + * Draws a render_sentry_chart result as SVG: one area (or line, when there + * are several series) per series, a y grid, time labels, a hatched band over + * buckets that are still filling, and a hover tooltip. Values come from an + * untrusted tool result, so text only ever goes in through textContent. + */ +import type { ChartResult } from "../src/tools/support/chart/schema"; + +const SVG_NS = "http://www.w3.org/2000/svg"; +const HEIGHT = 220; +const MARGIN = { top: 8, right: 8, bottom: 22, left: 48 }; +export const SERIES_COLORS = [ + "#7553ff", + "#f2b712", + "#ff45a8", + "#3fb68b", + "#2ba1db", +]; + +const DURATION_MS: Record = { + nanosecond: 1e-6, + microsecond: 1e-3, + millisecond: 1, + second: 1000, + minute: 60_000, + hour: 3_600_000, +}; +const SIZE_UNITS = ["B", "KB", "MB", "GB", "TB"]; + +const compact = new Intl.NumberFormat(undefined, { + notation: "compact", + maximumFractionDigits: 1, +}); + +export function formatValue(value: number, chart: ChartResult): string { + if (chart.valueType === "duration") { + const ms = value * (DURATION_MS[chart.valueUnit ?? "millisecond"] ?? 1); + if (Math.abs(ms) < 1000) return `${Number(ms.toFixed(1))}ms`; + if (Math.abs(ms) < 60_000) return `${Number((ms / 1000).toFixed(2))}s`; + return `${Number((ms / 60_000).toFixed(1))}min`; + } + if (chart.valueType === "percentage") { + return `${Number((value * 100).toFixed(2))}%`; + } + if (chart.valueType === "size") { + let size = value; + let unit = 0; + while (Math.abs(size) >= 1024 && unit < SIZE_UNITS.length - 1) { + size /= 1024; + unit++; + } + return `${Number(size.toFixed(1))} ${SIZE_UNITS[unit]}`; + } + return compact.format(value); +} + +function svg( + tag: K, + attrs: Record, + parent?: Element, +): SVGElementTagNameMap[K] { + const el = document.createElementNS(SVG_NS, tag); + for (const [key, value] of Object.entries(attrs)) { + el.setAttribute(key, String(value)); + } + parent?.appendChild(el); + return el; +} + +/** Round step for about `count` gridlines across `range`. */ +function niceStep(range: number, count: number): number { + const raw = range / count; + const magnitude = 10 ** Math.floor(Math.log10(raw)); + const factor = [1, 2, 2.5, 5, 10].find((f) => f * magnitude >= raw) ?? 10; + return factor * magnitude; +} + +export interface TimeFormat { + locale: string | undefined; + timeZone: string | undefined; +} + +function timeFormatter(spanMs: number, format: TimeFormat) { + return new Intl.DateTimeFormat(format.locale, { + timeZone: format.timeZone, + ...(spanMs <= 2 * 86_400_000 + ? { hour: "2-digit", minute: "2-digit", hourCycle: "h23" } + : { month: "short", day: "numeric" }), + }); +} + +export function formatTooltipTime(time: number, format: TimeFormat): string { + return new Intl.DateTimeFormat(format.locale, { + timeZone: format.timeZone, + month: "short", + day: "numeric", + hour: "2-digit", + minute: "2-digit", + hourCycle: "h23", + timeZoneName: "short", + }).format(time); +} + +export interface ValueScale { + bottom: number; + top: number; + step: number; +} + +/** + * The y domain for `values`: round gridline steps from `bottom` to `top`, + * always including 0 so the baseline is on the chart, whether the values + * are positive, negative, or both. + */ +export function valueScale(values: readonly number[]): ValueScale { + const min = Math.min(0, ...values); + const max = Math.max(0, ...values); + const step = max > min ? niceStep(max - min, 4) : 1; + // `|| 0` turns -0 into 0, so the bottom label never reads "-0". + const bottom = Math.floor(min / step) * step || 0; + const top = Math.max(bottom + step, Math.ceil(max / step) * step); + return { bottom, top, step }; +} + +/** Where `value` sits in `scale`: 0 at the bottom of the plot, 1 at the top. */ +export function scaleFraction(scale: ValueScale, value: number): number { + return (value - scale.bottom) / (scale.top - scale.bottom); +} + +/** Renders the chart into `container`, replacing what was there. */ +export function drawChart( + container: HTMLElement, + chart: ChartResult, + format: TimeFormat, +): void { + container.replaceChildren(); + const width = Math.max(container.clientWidth, 280); + const plotWidth = width - MARGIN.left - MARGIN.right; + const plotHeight = HEIGHT - MARGIN.top - MARGIN.bottom; + const times = chart.series[0]?.buckets.map((b) => Date.parse(b.time)) ?? []; + const first = times[0] ?? 0; + const last = times.at(-1) ?? first; + const span = Math.max(last - first, 1); + const scale = valueScale( + chart.series.flatMap((s) => s.buckets.map((b) => b.value)), + ); + const { bottom, top, step } = scale; + const x = (time: number) => + MARGIN.left + + (times.length > 1 ? ((time - first) / span) * plotWidth : plotWidth / 2); + const y = (value: number) => + MARGIN.top + plotHeight - scaleFraction(scale, value) * plotHeight; + + const root = svg("svg", { + viewBox: `0 0 ${width} ${HEIGHT}`, + height: HEIGHT, + role: "img", + "aria-label": chart.title, + }); + const defs = svg("defs", {}, root); + const hatch = svg( + "pattern", + { + id: "incomplete-hatch", + width: 6, + height: 6, + patternUnits: "userSpaceOnUse", + patternTransform: "rotate(45)", + }, + defs, + ); + svg("line", { x1: 0, y1: 0, x2: 0, y2: 6, "stroke-width": 2 }, hatch); + + const grid = svg("g", { class: "grid axis" }, root); + const gridlines = Math.round((top - bottom) / step); + for (let i = 0; i <= gridlines; i++) { + const value = bottom + i * step; + svg( + "line", + { x1: MARGIN.left, x2: width - MARGIN.right, y1: y(value), y2: y(value) }, + grid, + ); + const label = svg( + "text", + { x: MARGIN.left - 6, y: y(value) + 4, "text-anchor": "end" }, + grid, + ); + label.textContent = formatValue(value, chart); + } + + const ticks = svg("g", { class: "axis" }, root); + const tickFormat = timeFormatter(span, format); + const tickCount = Math.min( + times.length, + Math.max(2, Math.floor(plotWidth / 90)), + ); + for (let i = 0; i < tickCount; i++) { + const time = first + (span * i) / Math.max(tickCount - 1, 1); + const label = svg( + "text", + { + x: x(time), + y: HEIGHT - 6, + "text-anchor": + i === 0 ? "start" : i === tickCount - 1 ? "end" : "middle", + }, + ticks, + ); + label.textContent = tickFormat.format(time); + } + + // Buckets still filling: a hatched band from the first one to the end. + const firstFilling = chart.series[0]?.buckets.findIndex((b) => b.incomplete); + if (firstFilling !== undefined && firstFilling >= 0) { + const fillingStart = x(times[Math.max(firstFilling - 1, 0)] ?? last); + svg( + "rect", + { + class: "incomplete-band", + x: fillingStart, + y: MARGIN.top, + width: Math.max(x(last) - fillingStart, 2), + height: plotHeight, + }, + root, + ); + } + svg( + "line", + { + class: "baseline", + x1: MARGIN.left, + x2: width - MARGIN.right, + y1: y(0), + y2: y(0), + }, + root, + ); + + const single = chart.series.length === 1; + chart.series.forEach((series, index) => { + const color = SERIES_COLORS[index % SERIES_COLORS.length] ?? "#7553ff"; + const points = series.buckets.map( + (b) => [x(Date.parse(b.time)), y(b.value)] as const, + ); + const split = series.buckets.findIndex((b) => b.incomplete); + const settled = split < 0 ? points : points.slice(0, Math.max(split, 1)); + const filling = split < 0 ? [] : points.slice(Math.max(split - 1, 0)); + const path = (pts: readonly (readonly [number, number])[]) => + pts.map(([px, py], i) => `${i ? "L" : "M"}${px},${py}`).join(""); + if (single && points.length > 1) { + svg( + "path", + { + d: `${path(points)}L${points.at(-1)?.[0]},${y(0)}L${points[0]?.[0]},${y(0)}Z`, + fill: color, + "fill-opacity": 0.16, + }, + root, + ); + } + svg( + "path", + { d: path(settled), fill: "none", stroke: color, "stroke-width": 2 }, + root, + ); + if (points.length === 1) { + const [px, py] = points[0] ?? [0, 0]; + svg("circle", { cx: px, cy: py, r: 4, fill: color }, root); + } + if (filling.length > 1) { + svg( + "path", + { + d: path(filling), + fill: "none", + stroke: color, + "stroke-width": 2, + "stroke-dasharray": "4 3", + }, + root, + ); + } + }); + + const crosshair = svg( + "line", + { + class: "crosshair", + y1: MARGIN.top, + y2: MARGIN.top + plotHeight, + visibility: "hidden", + }, + root, + ); + const markers = chart.series.map((_, index) => + svg( + "circle", + { + r: 3.5, + fill: SERIES_COLORS[index % SERIES_COLORS.length] ?? "#7553ff", + visibility: "hidden", + }, + root, + ), + ); + container.appendChild(root); + + const tooltip = document.createElement("div"); + tooltip.className = "tooltip"; + tooltip.hidden = true; + container.appendChild(tooltip); + + const hide = () => { + tooltip.hidden = true; + crosshair.setAttribute("visibility", "hidden"); + for (const marker of markers) marker.setAttribute("visibility", "hidden"); + }; + const showAt = (index: number) => { + const time = times[index]; + if (time === undefined) return hide(); + const px = x(time); + crosshair.setAttribute("x1", String(px)); + crosshair.setAttribute("x2", String(px)); + crosshair.setAttribute("visibility", "visible"); + const timeRow = document.createElement("div"); + timeRow.className = "time"; + const incomplete = chart.series[0]?.buckets[index]?.incomplete; + timeRow.textContent = `${formatTooltipTime(time, format)}${incomplete ? " (still filling)" : ""}`; + const rows = chart.series.map((series, s) => { + const bucket = series.buckets[index]; + const marker = markers[s]; + if (bucket && marker) { + marker.setAttribute("cx", String(px)); + marker.setAttribute("cy", String(y(bucket.value))); + marker.setAttribute("visibility", "visible"); + } + const row = document.createElement("div"); + row.className = "row"; + const swatch = document.createElement("span"); + swatch.className = "swatch"; + swatch.style.background = SERIES_COLORS[s % SERIES_COLORS.length] ?? ""; + const label = document.createElement("span"); + label.textContent = series.label; + const value = document.createElement("span"); + value.textContent = bucket ? formatValue(bucket.value, chart) : "–"; + row.append(swatch, label, value); + return row; + }); + tooltip.replaceChildren(timeRow, ...rows); + tooltip.hidden = false; + // The tooltip is HTML, so convert viewBox units to CSS pixels. They + // differ when the container is narrower than the minimum viewBox width. + const box = root.getBoundingClientRect(); + const toCss = box.width > 0 ? box.width / width : 1; + const cssX = px * toCss; + const tipWidth = tooltip.offsetWidth; + const left = Math.min(cssX + 12, box.width - tipWidth - 4); + tooltip.style.left = `${left < cssX && cssX - tipWidth - 12 > 0 ? cssX - tipWidth - 12 : Math.max(left, 0)}px`; + tooltip.style.top = `${MARGIN.top * toCss}px`; + }; + + root.addEventListener("pointermove", (event) => { + const box = root.getBoundingClientRect(); + const px = ((event.clientX - box.left) / box.width) * width; + if (px < MARGIN.left || px > width - MARGIN.right || times.length === 0) { + return hide(); + } + const time = first + ((px - MARGIN.left) / plotWidth) * span; + let nearest = 0; + times.forEach((t, i) => { + if (Math.abs(t - time) < Math.abs((times[nearest] ?? 0) - time)) { + nearest = i; + } + }); + showAt(nearest); + }); + root.addEventListener("pointerleave", hide); +} diff --git a/packages/mcp-core/chart-app/main.ts b/packages/mcp-core/chart-app/main.ts new file mode 100644 index 0000000000..3194dc91ae --- /dev/null +++ b/packages/mcp-core/chart-app/main.ts @@ -0,0 +1,312 @@ +/** + * The render_sentry_chart view. The host sends the tool's arguments and + * result; the range picker calls the tool again through the host and redraws + * in place. + */ +import type { ChartResult } from "../src/tools/support/chart/schema"; +import { + type CallToolResult, + connect, + type Host, + type HostContext, +} from "./bridge"; +import { + drawChart, + formatTooltipTime, + formatValue, + SERIES_COLORS, + type TimeFormat, +} from "./chart"; +import { parseChartResult } from "./parse"; + +const TOOL_NAME = "render_sentry_chart"; +const RANGES = ["1h", "24h", "7d", "14d"] as const; +const UNIT_NAMES: Record = { + m: "minute", + h: "hour", + d: "day", + w: "week", +}; + +type View = + | { kind: "waiting" } + | { kind: "ready"; chart: ChartResult } + | { kind: "error"; message: string; chart: ChartResult | null }; + +let view: View = { kind: "waiting" }; +let toolArgs: Record = {}; +let pendingRange: string | null = null; +let format: TimeFormat = { locale: undefined, timeZone: undefined }; + +function el( + tag: K, + className?: string, + text?: string, +): HTMLElementTagNameMap[K] { + const node = document.createElement(tag); + if (className) node.className = className; + if (text !== undefined) node.textContent = text; + return node; +} + +const title = el("h1", undefined, "Sentry chart"); +const subtitle = el("div", "subtitle"); +const ranges = el("div", "ranges"); +const openButton = el("button", "open", "Open in Sentry"); +const stats = el("div", "stats"); +const chartBox = el("div", "chart"); +const legend = el("div", "legend"); +const note = el("div", "note"); +const state = el("div", "state", "Loading chart…"); +const rangeButtons = RANGES.map((range) => { + const button = el("button", undefined, range); + button.type = "button"; + button.addEventListener("click", () => void changeRange(range)); + ranges.appendChild(button); + return button; +}); + +const header = el("header"); +const heading = el("div"); +heading.append(title, subtitle); +const controls = el("div", "controls"); +controls.append(ranges, openButton); +header.append(heading, controls); +const main = el("main"); +main.append(header, stats, chartBox, legend, note, state); +document.body.appendChild(main); + +function rangeLabel(chart: ChartResult): string { + const { statsPeriod, start, end } = chart.timeRange; + const match = statsPeriod ? /^(\d+)([mhdw])$/.exec(statsPeriod) : null; + if (match?.[1] && match[2]) { + const count = Number(match[1]); + const unit = UNIT_NAMES[match[2]] ?? match[2]; + return `Last ${count === 1 ? unit : `${count} ${unit}s`}`; + } + if (start && end) { + return `${formatTooltipTime(Date.parse(start), format)} – ${formatTooltipTime(Date.parse(end), format)}`; + } + return statsPeriod ?? ""; +} + +function stat(label: string, value: string): HTMLElement { + const item = el("span", undefined, `${label} `); + item.appendChild(el("strong", undefined, value)); + return item; +} + +// Self-hosted Sentry can serve plain http, including localhost. +function isWebUrl(url: string | undefined): url is string { + if (!url) return false; + try { + const { protocol } = new URL(url); + return protocol === "https:" || protocol === "http:"; + } catch { + return false; + } +} + +function render(): void { + const chart = view.kind === "waiting" ? null : view.chart; + const busy = pendingRange !== null; + chartBox.dataset["loading"] = String(busy); + for (const [index, button] of rangeButtons.entries()) { + const range = RANGES[index]; + button.disabled = busy || chart === null; + button.setAttribute( + "aria-pressed", + String((pendingRange ?? chart?.timeRange.statsPeriod) === range), + ); + } + openButton.disabled = !isWebUrl(chart?.url); + + if (view.kind === "error") { + state.hidden = false; + state.className = "state error"; + state.textContent = view.message; + } + if (!chart) { + if (view.kind === "waiting") state.hidden = false; + stats.replaceChildren(); + legend.replaceChildren(); + chartBox.replaceChildren(); + note.textContent = ""; + return; + } + + title.textContent = chart.title; + subtitle.replaceChildren( + `${chart.dataset} · `, + el("code", undefined, chart.query || "all events"), + ` · ${rangeLabel(chart)}`, + ); + + const hasData = chart.series.some((series) => series.buckets.length > 0); + if (view.kind === "ready") { + state.className = "state"; + state.hidden = hasData; + state.textContent = "No data for this query in this range."; + } + + const single = chart.series.length === 1 ? chart.series[0] : undefined; + const items: HTMLElement[] = []; + if (single?.total != null) { + items.push(stat("Total", formatValue(single.total, chart))); + } + if (chart.peak) { + items.push( + stat( + "Peak", + `${formatValue(chart.peak.value, chart)}${single ? "" : ` (${chart.peak.series})`} at ${formatTooltipTime(Date.parse(chart.peak.time), format)}`, + ), + ); + } + if (hasData) items.push(stat("Interval", chart.interval)); + stats.replaceChildren(...items); + + legend.replaceChildren( + ...(single + ? [] + : chart.series.map((series, index) => { + const item = el("span", "item"); + const swatch = el("span", "swatch"); + swatch.style.background = + SERIES_COLORS[index % SERIES_COLORS.length] ?? ""; + const total = + series.total === null + ? "" + : ` · ${formatValue(series.total, chart)}`; + item.append(swatch, `${series.label}${total}`); + return item; + })), + ); + + const filling = chart.series.some((series) => + series.buckets.some((bucket) => bucket.incomplete), + ); + const ingestion = + chart.ingestion && chart.ingestion.status !== "healthy" + ? ` Ingestion is ${chart.ingestion.status}.` + : ""; + note.textContent = hasData + ? `${filling ? "Hatched area: buckets still receiving data." : ""}${ingestion}`.trim() + : ""; + + if (hasData) { + drawChart(chartBox, chart, format); + } else { + chartBox.replaceChildren(); + } +} + +function errorText(result: CallToolResult): string { + const text = result.content.find((block) => block.type === "text")?.text; + return text ?? "The chart could not load."; +} + +function showResult(result: CallToolResult): void { + const previous = view.kind === "waiting" ? null : view.chart; + if (result.isError) { + view = { kind: "error", message: errorText(result), chart: previous }; + return; + } + const chart = parseChartResult(result.structuredContent); + view = chart + ? { kind: "ready", chart } + : { + kind: "error", + message: "The chart data was not in the expected shape.", + chart: previous, + }; +} + +let host: Host | null = null; + +async function changeRange(range: string): Promise { + const args: Record = { + ...toolArgs, + period: range, + start: null, + end: null, + }; + // A fixed bucket size may not fit the new range, so let Sentry pick. + delete args["interval"]; + if (!host) return; + pendingRange = range; + render(); + try { + const result = await host.callTool(TOOL_NAME, args); + if (!result.isError) toolArgs = args; + showResult(result); + } catch (error) { + view = { + kind: "error", + message: error instanceof Error ? error.message : String(error), + chart: view.kind === "waiting" ? null : view.chart, + }; + } finally { + pendingRange = null; + render(); + } +} + +function applyHostContext(context: HostContext): void { + const root = document.documentElement; + if (context.theme === "light" || context.theme === "dark") { + root.dataset["theme"] = context.theme; + root.style.colorScheme = context.theme; + } + for (const [name, value] of Object.entries(context.styles?.variables ?? {})) { + if (name.startsWith("--") && typeof value === "string") { + root.style.setProperty(name, value); + } + } + if (context.locale || context.timeZone) { + format = { + locale: context.locale ?? format.locale, + timeZone: context.timeZone ?? format.timeZone, + }; + } + render(); +} + +openButton.addEventListener("click", () => { + const chart = view.kind === "waiting" ? null : view.chart; + if (chart && isWebUrl(chart.url)) void host?.openLink(chart.url); +}); + +let lastWidth = 0; +new ResizeObserver(([entry]) => { + const width = Math.round(entry?.contentRect.width ?? 0); + if (width !== lastWidth && view.kind !== "waiting") { + lastWidth = width; + render(); + } +}).observe(main); + +render(); +void connect( + { name: "Sentry chart", version: "1.0.0" }, + { + toolInput: (args) => { + toolArgs = { ...args }; + }, + toolResult: (result) => { + showResult(result); + render(); + }, + toolCancelled: () => { + view = { + kind: "error", + message: "The chart request was cancelled.", + chart: view.kind === "waiting" ? null : view.chart, + }; + pendingRange = null; + render(); + }, + hostContext: applyHostContext, + }, +).then((connected) => { + host = connected; +}); diff --git a/packages/mcp-core/chart-app/parse.test.ts b/packages/mcp-core/chart-app/parse.test.ts new file mode 100644 index 0000000000..be2ec4b3c7 --- /dev/null +++ b/packages/mcp-core/chart-app/parse.test.ts @@ -0,0 +1,98 @@ +import { describe, expect, it } from "vitest"; +import { renderSentryChartOutputSchema } from "../src/tools/support/chart/schema"; +import { parseChartResult } from "./parse"; + +const chart = { + title: "count() of level:error", + dataset: "errors", + query: "level:error", + yAxis: "count()", + groupBy: "release", + valueType: "integer", + valueUnit: null, + interval: "1h", + timeRange: { statsPeriod: "24h", start: null, end: null }, + url: "https://sentry-mcp-evals.sentry.io/explore/discover/homepage/", + series: [ + { + label: "1.0.0", + total: 12, + buckets: [ + { + time: "2025-09-10T23:00:00.000Z", + value: 12, + incomplete: false, + outsideRetention: false, + }, + ], + }, + { label: "1.0.1", total: null, buckets: [] }, + ], + peak: { series: "1.0.0", time: "2025-09-10T23:00:00.000Z", value: 12 }, + ingestion: { + status: "healthy", + delaySeconds: null, + completeThrough: "2025-09-10T23:30:00.000Z", + }, +}; + +type Mutation = [string, (value: typeof chart) => unknown]; + +const invalid: Mutation[] = [ + ["null", () => null], + ["an array", () => [chart]], + ["no title", ({ title: _, ...rest }) => rest], + ["a numeric query", (c) => ({ ...c, query: 1 })], + ["an undefined groupBy", (c) => ({ ...c, groupBy: undefined })], + ["no timeRange", (c) => ({ ...c, timeRange: null })], + ["a series object", (c) => ({ ...c, series: {} })], + [ + "a string bucket value", + (c) => ({ + ...c, + series: [ + { + ...c.series[0], + buckets: [{ ...c.series[0]?.buckets[0], value: "12" }], + }, + ], + }), + ], + [ + "a bucket without incomplete", + (c) => ({ + ...c, + series: [{ ...c.series[0], buckets: [{ time: "t", value: 1 }] }], + }), + ], + ["a peak without time", (c) => ({ ...c, peak: { series: "a", value: 1 } })], + ["no ingestion", ({ ingestion: _, ...rest }) => rest], + [ + "a string delaySeconds", + (c) => ({ ...c, ingestion: { ...c.ingestion, delaySeconds: "5" } }), + ], +]; + +describe("parseChartResult", () => { + it("returns what renderSentryChartOutputSchema returns for a valid result", () => { + const input = { ...chart, extra: "dropped", peak: { ...chart.peak } }; + + expect(parseChartResult(input)).toEqual( + renderSentryChartOutputSchema.parse(input), + ); + expect(parseChartResult(input)).not.toHaveProperty("extra"); + }); + + it("accepts null peak and ingestion", () => { + expect(parseChartResult({ ...chart, peak: null, ingestion: null })).toEqual( + { ...chart, peak: null, ingestion: null }, + ); + }); + + it.each(invalid)("rejects %s, as the schema does", (_, mutate) => { + const input = mutate(structuredClone(chart)); + + expect(renderSentryChartOutputSchema.safeParse(input).success).toBe(false); + expect(parseChartResult(input)).toBeNull(); + }); +}); diff --git a/packages/mcp-core/chart-app/parse.ts b/packages/mcp-core/chart-app/parse.ts new file mode 100644 index 0000000000..6867e2bc16 --- /dev/null +++ b/packages/mcp-core/chart-app/parse.ts @@ -0,0 +1,110 @@ +/** + * Parses an untrusted render_sentry_chart `structuredContent` into a + * ChartResult, or returns null. Hand-written so the view ships without zod; + * parse.test.ts keeps it in step with renderSentryChartOutputSchema. Builds a + * new object, so unknown fields never reach the view. + */ +import type { ChartResult } from "../src/tools/support/chart/schema"; + +type Series = ChartResult["series"][number]; +type Bucket = Series["buckets"][number]; + +/** Thrown inside the parser; parseChartResult turns it into null. */ +class Invalid extends Error {} + +function record(value: unknown): Record { + if (typeof value !== "object" || value === null || Array.isArray(value)) { + throw new Invalid(); + } + return value as Record; +} + +function str(value: unknown): string { + if (typeof value !== "string") throw new Invalid(); + return value; +} + +function num(value: unknown): number { + if (typeof value !== "number" || !Number.isFinite(value)) throw new Invalid(); + return value; +} + +function bool(value: unknown): boolean { + if (typeof value !== "boolean") throw new Invalid(); + return value; +} + +function nullable(parse: (value: unknown) => T, value: unknown): T | null { + return value === null ? null : parse(value); +} + +function list(parse: (value: unknown) => T, value: unknown): T[] { + if (!Array.isArray(value)) throw new Invalid(); + return value.map(parse); +} + +function bucket(value: unknown): Bucket { + const b = record(value); + return { + time: str(b["time"]), + value: num(b["value"]), + incomplete: bool(b["incomplete"]), + outsideRetention: bool(b["outsideRetention"]), + }; +} + +function series(value: unknown): Series { + const s = record(value); + return { + label: str(s["label"]), + total: nullable(num, s["total"]), + buckets: list(bucket, s["buckets"]), + }; +} + +function peak(value: unknown): NonNullable { + const p = record(value); + return { + series: str(p["series"]), + time: str(p["time"]), + value: num(p["value"]), + }; +} + +function ingestion(value: unknown): NonNullable { + const i = record(value); + return { + status: str(i["status"]), + delaySeconds: nullable(num, i["delaySeconds"]), + completeThrough: nullable(str, i["completeThrough"]), + }; +} + +export function parseChartResult(value: unknown): ChartResult | null { + try { + const c = record(value); + const range = record(c["timeRange"]); + return { + title: str(c["title"]), + dataset: str(c["dataset"]), + query: str(c["query"]), + yAxis: str(c["yAxis"]), + groupBy: nullable(str, c["groupBy"]), + valueType: nullable(str, c["valueType"]), + valueUnit: nullable(str, c["valueUnit"]), + interval: str(c["interval"]), + timeRange: { + statsPeriod: nullable(str, range["statsPeriod"]), + start: nullable(str, range["start"]), + end: nullable(str, range["end"]), + }, + url: str(c["url"]), + series: list(series, c["series"]), + peak: nullable(peak, c["peak"]), + ingestion: nullable(ingestion, c["ingestion"]), + }; + } catch (error) { + if (error instanceof Invalid) return null; + throw error; + } +} diff --git a/packages/mcp-core/chart-app/styles.css b/packages/mcp-core/chart-app/styles.css new file mode 100644 index 0000000000..be9ca23e37 --- /dev/null +++ b/packages/mcp-core/chart-app/styles.css @@ -0,0 +1,241 @@ +:root { + color-scheme: light; + --bg: var(--color-background-primary, #ffffff); + --panel: var(--color-background-secondary, #faf9fb); + --fg: var(--color-text-primary, #2b2233); + --muted: var(--color-text-secondary, #71637e); + --border: var(--color-border-primary, #e0dce5); + --grid: var(--color-border-tertiary, #f0ecf3); + --danger: var(--color-text-danger, #cf2126); + --accent: #6c5fc7; + --radius: var(--border-radius-md, 6px); + font-family: var( + --font-sans, + -apple-system, + BlinkMacSystemFont, + "Segoe UI", + Roboto, + sans-serif + ); + font-size: var(--font-text-sm-size, 13px); +} + +[data-theme="dark"] { + color-scheme: dark; + --bg: var(--color-background-primary, #1e1a25); + --panel: var(--color-background-secondary, #262130); + --fg: var(--color-text-primary, #ebe6ef); + --muted: var(--color-text-secondary, #a397b0); + --border: var(--color-border-primary, #3e3446); + --grid: var(--color-border-tertiary, #2f2838); + --danger: var(--color-text-danger, #ff7f7f); + --accent: #a796f0; +} + +* { + box-sizing: border-box; +} + +html, +body { + margin: 0; + background: var(--bg); + color: var(--fg); +} + +main { + padding: 14px 16px 12px; +} + +header { + display: flex; + flex-wrap: wrap; + align-items: flex-start; + justify-content: space-between; + gap: 8px 16px; +} + +h1 { + margin: 0; + font-size: var(--font-heading-sm-size, 15px); + font-weight: var(--font-weight-semibold, 600); + overflow-wrap: anywhere; +} + +.subtitle { + margin-top: 2px; + color: var(--muted); + overflow-wrap: anywhere; +} + +.subtitle code { + font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, monospace); + font-size: 0.95em; +} + +.controls { + display: flex; + gap: 8px; + align-items: center; +} + +.ranges { + display: inline-flex; + border: 1px solid var(--border); + border-radius: var(--radius); + overflow: hidden; +} + +button { + font: inherit; + color: var(--fg); + background: var(--bg); + border: 0; + padding: 4px 10px; + cursor: pointer; +} + +.ranges button + button { + border-left: 1px solid var(--border); +} + +.ranges button[aria-pressed="true"] { + background: var(--accent); + color: #ffffff; +} + +button:disabled { + cursor: default; + opacity: 0.6; +} + +.open { + border: 1px solid var(--border); + border-radius: var(--radius); +} + +.stats { + display: flex; + flex-wrap: wrap; + gap: 4px 16px; + margin: 10px 0 4px; + color: var(--muted); +} + +.stats strong { + color: var(--fg); + font-weight: var(--font-weight-semibold, 600); +} + +.chart { + position: relative; + transition: opacity 120ms; +} + +.chart[data-loading="true"] { + opacity: 0.45; +} + +svg { + display: block; + width: 100%; + overflow: visible; +} + +.axis text { + fill: var(--muted); + font-size: 11px; +} + +.grid line { + stroke: var(--grid); +} + +.baseline { + stroke: var(--border); +} + +.incomplete-band { + fill: url(#incomplete-hatch); +} + +#incomplete-hatch line { + stroke: var(--border); +} + +.crosshair { + stroke: var(--muted); + stroke-dasharray: 2 3; +} + +.tooltip { + position: absolute; + pointer-events: none; + min-width: 140px; + padding: 6px 8px; + background: var(--panel); + border: 1px solid var(--border); + border-radius: var(--radius); + box-shadow: var(--shadow-md, 0 2px 8px rgba(0, 0, 0, 0.15)); + font-size: 12px; +} + +.tooltip .time { + color: var(--muted); + margin-bottom: 4px; +} + +.tooltip .row, +.legend .item { + display: flex; + gap: 6px; + align-items: center; +} + +.tooltip .row span:last-child { + margin-left: auto; + padding-left: 12px; + font-variant-numeric: tabular-nums; +} + +.swatch { + width: 8px; + height: 8px; + border-radius: 2px; + flex: none; +} + +.legend { + display: flex; + flex-wrap: wrap; + gap: 4px 14px; + margin-top: 6px; + color: var(--muted); +} + +.note { + margin-top: 6px; + color: var(--muted); + font-size: 12px; +} + +.state { + display: grid; + place-items: center; + min-height: 160px; + color: var(--muted); + text-align: center; + border: 1px dashed var(--border); + border-radius: var(--radius); + margin-top: 10px; + padding: 16px; +} + +.state.error { + color: var(--danger); +} + +/* Author display rules otherwise beat the hidden attribute. */ +[hidden] { + display: none !important; +} diff --git a/packages/mcp-core/chart-app/tsconfig.json b/packages/mcp-core/chart-app/tsconfig.json new file mode 100644 index 0000000000..ec11a7673a --- /dev/null +++ b/packages/mcp-core/chart-app/tsconfig.json @@ -0,0 +1,10 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + // Runs in an MCP Apps host's sandboxed iframe, not in Node. + "lib": ["ES2023", "DOM", "DOM.Iterable"], + "types": [], + "noEmit": true + }, + "include": ["*.ts"] +} diff --git a/packages/mcp-core/package.json b/packages/mcp-core/package.json index ea61352bd0..a157bd9a71 100644 --- a/packages/mcp-core/package.json +++ b/packages/mcp-core/package.json @@ -154,19 +154,27 @@ "test": "pnpm run validate-skills && vitest run", "test:ci": "pnpm run generate-definitions && pnpm run validate-skills && vitest run --reporter=default --reporter=junit --outputFile=tests.junit.xml", "test:watch": "pnpm run generate-definitions && vitest", - "typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json", + "typecheck": "tsc --noEmit && tsc --noEmit -p scripts/tsconfig.json && tsc --noEmit -p chart-app", "generate-definitions": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-definitions.ts && oxfmt --write src/toolDefinitions.json src/skillDefinitions.json", + "generate-chart-app": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-chart-app.ts", + "ci:policy": "pnpm run generate-chart-app --check", "generate-platform-setup": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-platform-setup.ts && oxfmt --write src/tools/support/project-setup/platforms.json", "generate-otel-namespaces": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/generate-otel-namespaces.ts", + "measure-ui": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/measure-ui-views.ts", "measure-tokens": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/measure-token-cost.ts", "validate-skills": "node --experimental-strip-types --import ../../scripts/strip-types-resolve.mjs scripts/validate-skills-mapping.ts" }, "devDependencies": { "@ai-sdk/provider": "^3.0.6", "@ai-sdk/provider-utils": "^4.0.11", + "@modelcontextprotocol/client": "catalog:", + "@modelcontextprotocol/core": "catalog:", + "@modelcontextprotocol/ext-apps": "catalog:", "@modelcontextprotocol/sdk": "catalog:", "@sentry/mcp-server-mocks": "workspace:*", + "esbuild": "^0.28.1", "msw": "catalog:", + "playwright-core": "catalog:", "tiktoken": "^1.0.18", "yaml": "^2.8.3" }, diff --git a/packages/mcp-core/scripts/generate-chart-app.ts b/packages/mcp-core/scripts/generate-chart-app.ts new file mode 100644 index 0000000000..5f26b7d9f5 --- /dev/null +++ b/packages/mcp-core/scripts/generate-chart-app.ts @@ -0,0 +1,75 @@ +/** + * Bundles the render_sentry_chart view (chart-app/) into one self-contained + * HTML document and writes it to src/ui/chart-app.generated.ts, so the stdio + * server and the Cloudflare Worker serve it without reading files. + * + * `--check` fails instead of writing when the committed file is stale. Both + * modes fail when the view breaks a rule in view-policy.ts. + */ +import { readFileSync, writeFileSync } from "node:fs"; +import { fileURLToPath } from "node:url"; +import { build, transform } from "esbuild"; +import { CHART_UI_RESOURCE } from "../src/ui-resources.ts"; +import { viewHtmlProblems } from "./view-policy.ts"; + +const BUDGET_BYTES = CHART_UI_RESOURCE.budgetBytes; + +const appDir = fileURLToPath(new URL("../chart-app/", import.meta.url)); +const outFile = fileURLToPath( + new URL("../src/ui/chart-app.generated.ts", import.meta.url), +); + +const bundle = await build({ + entryPoints: [`${appDir}main.ts`], + bundle: true, + minify: true, + format: "iife", + platform: "browser", + target: "es2022", + legalComments: "none", + charset: "utf8", + write: false, +}); +const script = bundle.outputFiles[0]?.text; +if (!script) { + throw new Error("esbuild produced no output for chart-app/main.ts"); +} +const style = await transform(readFileSync(`${appDir}styles.css`, "utf8"), { + loader: "css", + minify: true, +}); + +const html = [ + "", + '', + '', + "Sentry chart", + ``, + // An inline script ends at the first ``, +].join(""); + +const problems = viewHtmlProblems("The chart view", html, BUDGET_BYTES); +if (problems.length > 0) { + console.error(problems.join("\n")); + process.exit(1); +} + +const source = `// Generated by scripts/generate-chart-app.ts from chart-app/. Do not edit. +export const CHART_APP_HTML = ${JSON.stringify(html)}; +`; + +if (process.argv.includes("--check")) { + if (readFileSync(outFile, "utf8") !== source) { + console.error( + "src/ui/chart-app.generated.ts is stale. Run: pnpm --filter @sentry/mcp-core generate-chart-app", + ); + process.exit(1); + } + console.log("src/ui/chart-app.generated.ts is up to date."); +} else { + writeFileSync(outFile, source); + console.log( + `Wrote src/ui/chart-app.generated.ts (${Buffer.byteLength(html)} of ${BUDGET_BYTES} bytes).`, + ); +} diff --git a/packages/mcp-core/scripts/measure-ui-views.ts b/packages/mcp-core/scripts/measure-ui-views.ts new file mode 100644 index 0000000000..d074464fb9 --- /dev/null +++ b/packages/mcp-core/scripts/measure-ui-views.ts @@ -0,0 +1,191 @@ +/** + * Measure the MCP Apps views that hosts download. + * + * Builds the server with every skill, lists its resources, and reads each + * `ui://` resource through `resources/read`, as a host does before it renders + * a view. Reports raw, gzip, and brotli bytes against the view's budget. + * + * Usage: + * pnpm run measure-ui # Display table + * pnpm run measure-ui -- -o ui-stats.json # Write JSON to file + * pnpm run measure-ui -- --markdown report.md # Append a report section + */ +import * as fs from "node:fs"; +import * as path from "node:path"; +import { brotliCompressSync, constants, gzipSync } from "node:zlib"; +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { buildServer } from "../src/server.ts"; +import { ALL_SKILLS } from "../src/skills.ts"; +import { UI_RESOURCES } from "../src/ui-resources.ts"; + +interface ViewStats { + uri: string; + mime_type: string; + raw_bytes: number; + gzip_bytes: number; + brotli_bytes: number; + budget_bytes: number; + budget_percentage: number; +} + +function parseArgs() { + const args = process.argv.slice(2); + let outputFile: string | null = null; + const markdownFiles: string[] = []; + + for (let i = 0; i < args.length; i++) { + const arg = args[i]; + if (arg === "--output" || arg === "-o" || arg === "--markdown") { + const file = args[i + 1]; + if (!file) { + throw new Error(`${arg} requires a file path`); + } + if (arg === "--markdown") { + markdownFiles.push(file); + } else { + outputFile = file; + } + i++; + } else if (arg === "--help" || arg === "-h") { + console.log(` +Usage: pnpm run measure-ui -- [options] + +Options: + -o, --output Write JSON output to file + --markdown Append the markdown report section to file (repeatable) + -h, --help Show this help message +`); + process.exit(0); + } + } + + return { outputFile, markdownFiles }; +} + +/** Reads every `ui://` resource the server lists, as a host would. */ +async function readViews(): Promise { + const server = buildServer({ + context: { + accessToken: "measure-ui", + grantedSkills: new Set(ALL_SKILLS), + constraints: { organizationSlug: null, projectSlug: null }, + sentryHost: "sentry.io", + }, + // MCP Apps views ship to experimental sessions only for now. + experimentalMode: true, + }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + const client = new Client({ name: "measure-ui", version: "1.0.0" }); + await server.connect(serverTransport); + await client.connect(clientTransport); + + try { + const { resources } = await client.listResources(); + const views: ViewStats[] = []; + for (const { uri } of resources.filter((r) => r.uri.startsWith("ui://"))) { + const budget = UI_RESOURCES.find((r) => r.uri === uri)?.budgetBytes; + if (budget === undefined) { + throw new Error(`${uri} is not in UI_RESOURCES, so it has no budget`); + } + const { contents } = await client.readResource({ uri }); + for (const content of contents) { + const body = + "text" in content + ? Buffer.from(content.text, "utf8") + : Buffer.from(content.blob, "base64"); + views.push({ + uri: content.uri, + mime_type: content.mimeType ?? "", + raw_bytes: body.length, + gzip_bytes: gzipSync(body, { level: 9 }).length, + brotli_bytes: brotliCompressSync(body, { + params: { [constants.BROTLI_PARAM_QUALITY]: 11 }, + }).length, + budget_bytes: budget, + budget_percentage: Number(((body.length / budget) * 100).toFixed(1)), + }); + } + } + return views; + } finally { + await client.close(); + await server.close(); + } +} + +const bytes = (n: number) => `${n.toLocaleString("en-US")} B`; + +function formatMarkdown(views: ViewStats[]): string { + const lines = [ + "", + "### MCP Apps views", + "", + "Each `ui://` view as a host receives it from `resources/read`.", + "", + ]; + if (views.length === 0) { + lines.push("_The server lists no `ui://` resources._"); + } else { + lines.push( + "| View | MIME type | Raw | Gzip | Brotli | Budget | % of budget |", + "|------|-----------|-----|------|--------|--------|-------------|", + ); + for (const view of views) { + lines.push( + `| \`${view.uri}\` | \`${view.mime_type}\` | ${bytes(view.raw_bytes)} | ${bytes(view.gzip_bytes)} | ${bytes(view.brotli_bytes)} | ${bytes(view.budget_bytes)} | ${view.budget_percentage}% |`, + ); + } + lines.push( + "", + "The budget applies to raw bytes, and the view's generator fails over it.", + ); + } + return `${lines.join("\n")}\n`; +} + +function formatTable(views: ViewStats[]): string { + const lines = ["\n🧩 MCP Apps Views\n", "━".repeat(60)]; + for (const view of views) { + lines.push( + view.uri, + ` MIME type: ${view.mime_type}`, + ` Raw: ${bytes(view.raw_bytes)} (${view.budget_percentage}% of ${bytes(view.budget_bytes)})`, + ` Gzip: ${bytes(view.gzip_bytes)}`, + ` Brotli: ${bytes(view.brotli_bytes)}`, + ); + } + if (views.length === 0) { + lines.push("The server lists no ui:// resources."); + } + return lines.join("\n"); +} + +async function main() { + try { + const { outputFile, markdownFiles } = parseArgs(); + const views = await readViews(); + + for (const file of markdownFiles) { + fs.appendFileSync(file, formatMarkdown(views)); + } + if (outputFile) { + const absolutePath = path.resolve(outputFile); + fs.writeFileSync( + absolutePath, + JSON.stringify({ view_count: views.length, views }, null, 2), + ); + console.log(`✅ UI view stats written to: ${absolutePath}`); + } + console.log(formatTable(views)); + } catch (error) { + const err = error as Error; + console.error("[ERROR]", err.message, err.stack); + process.exit(1); + } +} + +if (import.meta.url === `file://${process.argv[1]}`) { + void main(); +} diff --git a/packages/mcp-core/scripts/view-policy.test.ts b/packages/mcp-core/scripts/view-policy.test.ts new file mode 100644 index 0000000000..9b829eb371 --- /dev/null +++ b/packages/mcp-core/scripts/view-policy.test.ts @@ -0,0 +1,45 @@ +import { describe, expect, it } from "vitest"; +import { CHART_APP_HTML } from "../src/ui/chart-app.generated.ts"; +import { CHART_UI_RESOURCE } from "../src/ui-resources.ts"; +import { viewHtmlProblems } from "./view-policy.ts"; + +const page = (body: string) => + `${body}`; + +describe("viewHtmlProblems", () => { + it("passes the generated chart view", () => { + expect( + viewHtmlProblems("chart", CHART_APP_HTML, CHART_UI_RESOURCE.budgetBytes), + ).toEqual([]); + }); + + it("fails a view over its budget", () => { + expect(viewHtmlProblems("big", page("x".repeat(2048)), 1024)).toEqual([ + expect.stringContaining("over its 1024-byte budget"), + ]); + }); + + it.each([ + ['', "src or href"], + ['', "src or href"], + ['', ""], + ["", "@import"], + ["", "url()"], + ["", "fetch()"], + ["", "XMLHttpRequest"], + ["", "WebSocket"], + ["", "EventSource"], + ["", "sendBeacon"], + ["", "dynamic import()"], + ])("fails a view that loads from the network: %s", (body, label) => { + expect(viewHtmlProblems("leaky", page(body), 1024)).toEqual([ + expect.stringContaining(label), + ]); + }); + + it("allows inline data and the SVG namespace", () => { + const body = + ''; + expect(viewHtmlProblems("inline", page(body), 1024)).toEqual([]); + }); +}); diff --git a/packages/mcp-core/scripts/view-policy.ts b/packages/mcp-core/scripts/view-policy.ts new file mode 100644 index 0000000000..be20b66fae --- /dev/null +++ b/packages/mcp-core/scripts/view-policy.ts @@ -0,0 +1,43 @@ +/** + * Checks a generated MCP Apps view before it is written or accepted as up to + * date: it fits its byte budget and loads nothing from the network, so it + * runs under the spec's default CSP with an empty `csp`. See + * design/mcp-apps.md. + */ + +/** Network loads that an empty `csp` would block, so a view must not use them. */ +const NETWORK_PATTERNS: ReadonlyArray<[string, RegExp]> = [ + ["an external src or href", /\b(?:src|href)\s*=\s*["']?(?:https?:)?\/\//i], + ["a element", / budgetBytes) { + problems.push( + `${name} is ${bytes} bytes, over its ${budgetBytes}-byte budget. Drop a dependency or raise the budget on purpose.`, + ); + } + for (const [label, pattern] of NETWORK_PATTERNS) { + if (pattern.test(html)) { + problems.push( + `${name} uses ${label}. A view loads nothing from the network.`, + ); + } + } + return problems; +} diff --git a/packages/mcp-core/src/api-client/client.ts b/packages/mcp-core/src/api-client/client.ts index 1b2d5f3dc3..7f848ce725 100644 --- a/packages/mcp-core/src/api-client/client.ts +++ b/packages/mcp-core/src/api-client/client.ts @@ -4747,6 +4747,7 @@ export class SentryApiService { statsPeriod, start, end, + topEvents, }: { organizationSlug: string; query: string; @@ -4757,6 +4758,11 @@ export class SentryApiService { statsPeriod?: string; start?: string; end?: string; + /** + * One series per value of `groupBy`, for the `limit` values with the + * highest `yAxis`, without an "Other" series. + */ + topEvents?: { groupBy: string; limit: number } | undefined; }, opts?: RequestOptions, ) { @@ -4764,6 +4770,12 @@ export class SentryApiService { queryParams.set("dataset", normalizeEventsDataset(dataset)); queryParams.set("query", query); queryParams.set("yAxis", yAxis); + if (topEvents) { + queryParams.set("topEvents", String(topEvents.limit)); + queryParams.set("groupBy", topEvents.groupBy); + queryParams.set("sort", `-${yAxis}`); + queryParams.set("excludeOther", "1"); + } // Omit interval to let Sentry pick a sensible bucket size for the range. if (interval) { queryParams.set("interval", interval); diff --git a/packages/mcp-core/src/api-client/schema.ts b/packages/mcp-core/src/api-client/schema.ts index 79b4a826f5..00321a0750 100644 --- a/packages/mcp-core/src/api-client/schema.ts +++ b/packages/mcp-core/src/api-client/schema.ts @@ -2668,7 +2668,8 @@ export const EventsTimeSeriesValueSchema = z /** * Response from the events-timeseries endpoint. The MCP always requests a - * single yAxis without topEvents, so `timeSeries` holds exactly one series. + * single yAxis, so `timeSeries` holds one series, or one per group with + * `topEvents`, each naming its group in `groupBy`. */ export const EventsTimeSeriesResponseSchema = z .object({ @@ -2677,6 +2678,14 @@ export const EventsTimeSeriesResponseSchema = z .object({ yAxis: z.string(), values: z.array(EventsTimeSeriesValueSchema), + groupBy: z + .array( + z.object({ + key: z.string(), + value: z.union([z.string(), z.number()]).nullable(), + }), + ) + .optional(), meta: z .object({ // Bucket width in milliseconds diff --git a/packages/mcp-core/src/server.metadata.test.ts b/packages/mcp-core/src/server.metadata.test.ts index b6ad31bb02..04fe4b834b 100644 --- a/packages/mcp-core/src/server.metadata.test.ts +++ b/packages/mcp-core/src/server.metadata.test.ts @@ -34,6 +34,9 @@ const ALLOWED_TOOL_META: Record = { // Claude Code keeps it loaded so a pasted Sentry URL works without a tool // search. See docs/mcp/harnesses.md. get_sentry_resource: ["anthropic/alwaysLoad"], + // MCP Apps hosts (Claude, VS Code) read `ui`; ChatGPT reads + // `openai/outputTemplate`. See src/ui-resources.ts. + render_sentry_chart: ["ui", "openai/outputTemplate"], }; /** Tools that return no `structuredContent` by design. */ diff --git a/packages/mcp-core/src/server.ts b/packages/mcp-core/src/server.ts index 4d56161486..49702c0b8f 100644 --- a/packages/mcp-core/src/server.ts +++ b/packages/mcp-core/src/server.ts @@ -59,6 +59,7 @@ import tools from "./tools/index"; import { isCatalogInfrastructureToolName } from "./tools/surfaces"; import type { StructuredToolOutput } from "./tools/types"; import type { ServerContext } from "./types"; +import { registerUiResources } from "./ui-resources"; import { getServerVersion } from "./version"; function getSkillGrantedAttributeName(skill: Skill): string { @@ -340,6 +341,10 @@ export function buildServer({ for (const { name, config, handler } of registrations) { server.registerTool(name, config, handler); } + registerUiResources( + server, + registrations.map(({ config }) => config), + ); // Registration enables this by default, but each server's tool catalog is fixed. if (registrations.length > 0) { server.server.registerCapabilities({ tools: { listChanged: false } }); @@ -409,6 +414,7 @@ function configureServer({ tool.outputSchema ?? (experimentalMode ? tool.experimentalOutputSchema : undefined), annotations: tool.annotations, + ...(tool._meta && { _meta: tool._meta }), }; const handleToolCall = async ( params: unknown, diff --git a/packages/mcp-core/src/server.ui-resources.test.ts b/packages/mcp-core/src/server.ui-resources.test.ts new file mode 100644 index 0000000000..6f118a8036 --- /dev/null +++ b/packages/mcp-core/src/server.ui-resources.test.ts @@ -0,0 +1,95 @@ +/** + * MCP Apps: what a host reads to render render_sentry_chart inline. The tool + * names its view in `_meta.ui.resourceUri`, and that `ui://` resource reads + * back as a self-contained HTML document with the MCP Apps mime type. MCP + * Apps ship to experimental sessions only for now. + */ +import { Client } from "@modelcontextprotocol/sdk/client/index.js"; +import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js"; +import { describe, expect, it, vi } from "vitest"; +import { buildServer } from "./server"; +import type { Skill } from "./skills"; +import type { ServerContext } from "./types"; + +vi.mock("@sentry/core/server", () => ({ + wrapMcpServerWithSentry: vi.fn((server) => server), +})); + +const CHART_URI = "ui://sentry/chart/v1.html"; +const MCP_APP_MIME_TYPE = "text/html;profile=mcp-app"; + +async function connect(skills: Skill[], experimentalMode = true) { + const context: ServerContext = { + accessToken: "test-token", + grantedSkills: new Set(skills), + constraints: { organizationSlug: null, projectSlug: null }, + sentryHost: "sentry.io", + }; + const server = buildServer({ context, experimentalMode }); + const [clientTransport, serverTransport] = + InMemoryTransport.createLinkedPair(); + const client = new Client({ name: "mcp-apps-host", version: "1.0.0" }); + await server.connect(serverTransport); + await client.connect(clientTransport); + return { + client, + async [Symbol.asyncDispose]() { + await client.close(); + await server.close(); + }, + }; +} + +describe("MCP Apps chart view", () => { + it("links render_sentry_chart to its view in tools/list", async () => { + await using session = await connect(["inspect"]); + const { tools } = await session.client.listTools(); + const chartTool = tools.find((tool) => tool.name === "render_sentry_chart"); + + expect(chartTool?._meta).toEqual({ + ui: { resourceUri: CHART_URI }, + "openai/outputTemplate": CHART_URI, + }); + }); + + it("lists and reads the view as a self-contained HTML document", async () => { + await using session = await connect(["inspect"]); + + expect(session.client.getServerCapabilities()?.resources).toEqual({ + listChanged: false, + }); + const { resources } = await session.client.listResources(); + expect(resources).toEqual([ + expect.objectContaining({ uri: CHART_URI, mimeType: MCP_APP_MIME_TYPE }), + ]); + + const { contents } = await session.client.readResource({ uri: CHART_URI }); + expect(contents).toHaveLength(1); + const [view] = contents; + expect(view).toMatchObject({ + uri: CHART_URI, + mimeType: MCP_APP_MIME_TYPE, + _meta: { ui: { csp: {}, prefersBorder: true } }, + }); + const html = view && "text" in view ? view.text : ""; + expect(html.startsWith("")).toBe(true); + expect(html.endsWith("")).toBe(true); + }); + + it("lists no view when the session cannot call the chart tool", async () => { + await using session = await connect(["project-management"]); + const { tools } = await session.client.listTools(); + + expect(tools.map((tool) => tool.name)).not.toContain("render_sentry_chart"); + expect(session.client.getServerCapabilities()?.resources).toBeUndefined(); + }); + + it("keeps the chart tool and its view out of stable sessions", async () => { + await using session = await connect(["inspect"], false); + const { tools } = await session.client.listTools(); + + expect(tools.map((tool) => tool.name)).not.toContain("render_sentry_chart"); + expect(tools.some((tool) => tool._meta?.["ui"] !== undefined)).toBe(false); + expect(session.client.getServerCapabilities()?.resources).toBeUndefined(); + }); +}); diff --git a/packages/mcp-core/src/test-utils/ui-resource-policy.ts b/packages/mcp-core/src/test-utils/ui-resource-policy.ts new file mode 100644 index 0000000000..69ac575f68 --- /dev/null +++ b/packages/mcp-core/src/test-utils/ui-resource-policy.ts @@ -0,0 +1,70 @@ +/** + * The MCP Apps rules from design/mcp-apps.md that hold between tools and + * views: every `_meta.ui.resourceUri` names a known view, every view has a + * tool, a view's `ui://` URI is versioned and changes with its HTML, and its + * `csp` allows no origins. + */ +import { createHash } from "node:crypto"; +import type { UiResource } from "../ui-resources"; + +interface ToolWithMeta { + name: string; + _meta?: Record | undefined; +} + +function resourceUri(tool: ToolWithMeta): unknown { + const ui = tool._meta?.["ui"]; + return typeof ui === "object" && ui !== null && "resourceUri" in ui + ? ui.resourceUri + : undefined; +} + +/** Returns one message per broken rule; empty when every rule holds. */ +export async function uiResourceProblems( + tools: readonly ToolWithMeta[], + resources: readonly UiResource[], +): Promise { + const problems: string[] = []; + const uris = new Set(resources.map((resource) => resource.uri)); + const referenced = new Set(); + for (const tool of tools) { + const uri = resourceUri(tool); + if (uri === undefined) continue; + referenced.add(uri); + if (typeof uri !== "string" || !uris.has(uri)) { + problems.push( + `${tool.name} names view ${JSON.stringify(uri)}, which is not a UI resource.`, + ); + } + } + if (uris.size !== resources.length) { + problems.push("Two UI resources share a URI."); + } + for (const resource of resources) { + if (!referenced.has(resource.uri)) { + problems.push(`No tool names ${resource.uri}, so it is never listed.`); + } + if (!/^ui:\/\/[^/]+\/.*v\d+/.test(resource.uri)) { + problems.push( + `${resource.uri} has no version. Hosts cache views by URI, so it needs one, such as v1.`, + ); + } + const domains = Object.entries(resource.meta.csp).filter( + ([, list]) => list.length > 0, + ); + if (domains.length > 0) { + problems.push( + `${resource.uri} allows ${domains.map(([key]) => key).join(", ")} in its csp. A view loads nothing from the network.`, + ); + } + const sha256 = createHash("sha256") + .update(await resource.loadHtml()) + .digest("hex"); + if (sha256 !== resource.htmlSha256) { + problems.push( + `The HTML of ${resource.uri} changed. Hosts cache views by URI, so bump its version and set htmlSha256 to "${sha256}".`, + ); + } + } + return problems; +} diff --git a/packages/mcp-core/src/tools/catalog/index.ts b/packages/mcp-core/src/tools/catalog/index.ts index d2a897479b..155fab4b4e 100644 --- a/packages/mcp-core/src/tools/catalog/index.ts +++ b/packages/mcp-core/src/tools/catalog/index.ts @@ -42,6 +42,7 @@ import linkIssue from "./link-issue"; import unlinkIssue from "./unlink-issue"; import searchEvents from "./search-events"; import searchErrors from "./search-errors"; +import renderSentryChart from "./render-sentry-chart"; import searchLogs from "./search-logs"; import searchTraces from "./search-traces"; import searchMetrics from "./search-metrics"; @@ -176,6 +177,7 @@ const catalogTools = withFreshReadInputs({ search_profiles: searchProfiles, search_replays: searchReplays, search_events: searchEvents, + render_sentry_chart: renderSentryChart, create_team: createTeam, create_project: createProject, update_project: updateProject, diff --git a/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts b/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts new file mode 100644 index 0000000000..de05aab3d1 --- /dev/null +++ b/packages/mcp-core/src/tools/catalog/render-sentry-chart.test.ts @@ -0,0 +1,255 @@ +import { mswServer } from "@sentry/mcp-server-mocks"; +import { HttpResponse, http } from "msw"; +import { describe, expect, it } from "vitest"; +import { UserInputError } from "../../errors"; +import { + assertStructuredOnlyResult, + getStructuredContent, +} from "../../test-utils/structured-content.js"; +import type { ChartResult } from "../support/chart/schema"; +import renderSentryChart from "./render-sentry-chart.js"; + +const context = { + constraints: { organizationSlug: null }, + accessToken: "access-token", + userId: "1", +}; + +const TIMESERIES_URL = + "https://sentry.io/api/0/organizations/sentry-mcp-evals/events-timeseries/"; + +const baseParams = { + organizationSlug: "sentry-mcp-evals", + regionUrl: null, + dataset: "errors" as const, + query: "level:error", + yAxis: "count()", + groupBy: null, + projectSlug: null, + period: "1h", + start: null, + end: null, + interval: "15m", + title: null, +}; + +describe("render_sentry_chart", () => { + it("returns every bucket of the series", async () => { + const result = await renderSentryChart.handler(baseParams, context); + + assertStructuredOnlyResult(result); + expect(getStructuredContent(result)).toMatchInlineSnapshot(` + { + "dataset": "errors", + "groupBy": null, + "ingestion": null, + "interval": "15m", + "peak": { + "series": "count()", + "time": "2025-09-10T23:30:00.000Z", + "value": 140, + }, + "query": "level:error", + "series": [ + { + "buckets": [ + { + "incomplete": false, + "outsideRetention": false, + "time": "2025-09-10T23:00:00.000Z", + "value": 56, + }, + { + "incomplete": false, + "outsideRetention": false, + "time": "2025-09-10T23:15:00.000Z", + "value": 56, + }, + { + "incomplete": false, + "outsideRetention": false, + "time": "2025-09-10T23:30:00.000Z", + "value": 140, + }, + { + "incomplete": true, + "outsideRetention": false, + "time": "2025-09-10T23:45:00.000Z", + "value": 56, + }, + ], + "label": "count()", + "total": 308, + }, + ], + "timeRange": { + "end": null, + "start": null, + "statsPeriod": "1h", + }, + "title": "count()", + "url": "https://sentry-mcp-evals.sentry.io/explore/discover/homepage/?dataset=errors&queryDataset=error-events&query=level%3Aerror&project=-1&field=count%28%29&sort=-count%28%29&statsPeriod=1h&mode=aggregate&yAxis=count%28%29", + "valueType": "integer", + "valueUnit": null, + "yAxis": "count()", + } + `); + }); + + it("asks Sentry for the top 5 groups and labels each series by its value", async () => { + let captured: URLSearchParams | undefined; + mswServer.use( + http.get(TIMESERIES_URL, ({ request }) => { + captured = new URL(request.url).searchParams; + return HttpResponse.json({ + timeSeries: ["2.4.1", null].map((release, index) => ({ + yAxis: "p95(span.duration)", + groupBy: [{ key: "release", value: release }], + values: [ + { + timestamp: 1757545200000, + value: 120 - index, + incomplete: false, + }, + ], + meta: { + interval: 3600000, + valueType: "duration", + valueUnit: "millisecond", + order: index, + isOther: false, + }, + })), + }); + }), + ); + + const result = await renderSentryChart.handler( + { + ...baseParams, + dataset: "spans", + yAxis: "p95(span.duration)", + groupBy: "release", + period: null, + interval: null, + }, + context, + ); + + expect(Object.fromEntries(captured ?? [])).toMatchObject({ + dataset: "spans", + yAxis: "p95(span.duration)", + topEvents: "5", + groupBy: "release", + sort: "-p95(span.duration)", + excludeOther: "1", + statsPeriod: "24h", + }); + const chart = getStructuredContent(result); + expect(chart.title).toBe("p95(span.duration) by release"); + expect(chart.valueUnit).toBe("millisecond"); + expect(chart.series.map(({ label, total }) => ({ label, total }))).toEqual([ + { label: "2.4.1", total: null }, + { label: "(none)", total: null }, + ]); + expect(chart.peak).toEqual({ + series: "2.4.1", + time: "2025-09-10T23:00:00.000Z", + value: 120, + }); + }); + + it.each([ + ["every accessible project when projectSlug is omitted", null, ["-1"]], + [ + "only the named project", + "cloudflare-mcp", + [expect.stringMatching(/^\d+$/)], + ], + ])("charts %s", async (_, projectSlug, expected) => { + let projects: string[] | undefined; + mswServer.use( + http.get(TIMESERIES_URL, ({ request }) => { + projects = new URL(request.url).searchParams.getAll("project"); + return HttpResponse.json({ timeSeries: [] }); + }), + ); + + await renderSentryChart.handler({ ...baseParams, projectSlug }, context); + + expect(projects).toEqual(expected); + expect(projects).not.toEqual(projectSlug ? ["-1"] : []); + }); + + it("links grouped errors charts to Discover with the group-by column", async () => { + mswServer.use( + http.get(TIMESERIES_URL, () => HttpResponse.json({ timeSeries: [] })), + ); + + const chart = getStructuredContent( + await renderSentryChart.handler( + { ...baseParams, groupBy: "release" }, + context, + ), + ); + + expect(new URL(chart.url).searchParams.getAll("field")).toEqual([ + "release", + "count()", + ]); + }); + + it("returns an empty chart when a grouped query matches nothing", async () => { + mswServer.use( + http.get(TIMESERIES_URL, () => HttpResponse.json({ timeSeries: [] })), + ); + + const chart = getStructuredContent( + await renderSentryChart.handler( + { ...baseParams, groupBy: "release" }, + context, + ), + ); + + expect(chart.series).toEqual([]); + expect(chart.peak).toBeNull(); + }); + + it.each([ + ["start without end", { start: "2025-09-10T00:00:00Z", period: null }], + [ + "period with start and end", + { start: "2025-09-10T00:00:00Z", end: "2025-09-11T00:00:00Z" }, + ], + ["grouped profiles", { dataset: "profiles" as const, groupBy: "release" }], + ])("rejects %s", async (_, overrides) => { + await expect( + renderSentryChart.handler({ ...baseParams, ...overrides }, context), + ).rejects.toBeInstanceOf(UserInputError); + }); + + it("rejects an aggregate that returns text", async () => { + mswServer.use( + http.get(TIMESERIES_URL, () => + HttpResponse.json({ + timeSeries: [ + { + yAxis: "latest_event()", + values: [ + { timestamp: 1757545200000, value: "abc", incomplete: false }, + ], + meta: { interval: 3600000, valueType: "string" }, + }, + ], + }), + ), + ); + + await expect( + renderSentryChart.handler( + { ...baseParams, yAxis: "latest_event()" }, + context, + ), + ).rejects.toBeInstanceOf(UserInputError); + }); +}); diff --git a/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts b/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts new file mode 100644 index 0000000000..9c2dbe6345 --- /dev/null +++ b/packages/mcp-core/src/tools/catalog/render-sentry-chart.ts @@ -0,0 +1,256 @@ +import { z } from "zod"; +import type { EventsTimeSeriesResponse } from "../../api-client/schema"; +import { UserInputError } from "../../errors"; +import { apiServiceFromContext } from "../../internal/tool-helpers/api"; +import { defineTool } from "../../internal/tool-helpers/define"; +import { structuredResult } from "../../internal/tool-helpers/results"; +import { + ParamOrganizationSlug, + ParamPeriod, + ParamProjectSlug, + ParamRegionUrl, +} from "../../schema"; +import { setTargetTagsAndAttributes } from "../../telem/scope"; +import type { ServerContext } from "../../types"; +import { CHART_UI_RESOURCE, uiToolMeta } from "../../ui-resources"; +import { PUBLIC_EVENTS_DATASETS } from "../../utils/events-datasets"; +import { + type ChartResult, + renderSentryChartOutputSchema, +} from "../support/chart/schema"; +import { toStructuredIngestion } from "../support/ingestion"; +import { summarizeSeries } from "../support/search-events/formatters"; + +/** Top groups plotted when the chart is split by an attribute. */ +const MAX_CHART_SERIES = 5; +const DEFAULT_PERIOD = "24h"; + +const INTERVAL_UNITS: [unit: string, ms: number][] = [ + ["d", 86_400_000], + ["h", 3_600_000], + ["m", 60_000], +]; + +function formatInterval(ms: number): string { + for (const [unit, unitMs] of INTERVAL_UNITS) { + if (ms % unitMs === 0) return `${ms / unitMs}${unit}`; + } + return `${ms / 1000}s`; +} + +function seriesLabel( + series: EventsTimeSeriesResponse["timeSeries"][number], +): string { + if (!series.groupBy?.length) return series.yAxis; + return series.groupBy + .map(({ value }) => (value === null || value === "" ? "(none)" : value)) + .join(", "); +} + +function toChartSeries( + response: EventsTimeSeriesResponse, + yAxis: string, +): { series: ChartResult["series"]; peak: ChartResult["peak"] } { + let peak: ChartResult["peak"] = null; + const series = response.timeSeries.map((entry) => { + const label = seriesLabel(entry); + const summary = summarizeSeries(entry, yAxis); + if (summary.peak && (!peak || summary.peak.value > peak.value)) { + peak = { + series: label, + time: new Date(summary.peak.timestamp).toISOString(), + value: summary.peak.value, + }; + } + return { + label, + total: summary.total, + buckets: summary.points.map((point) => ({ + time: new Date(point.timestamp).toISOString(), + value: point.value, + incomplete: point.filling, + outsideRetention: point.outsideRetention, + })), + }; + }); + return { series, peak }; +} + +export default defineTool({ + // MCP Apps views ship to experimental sessions first. + experimental: true, + includeInSkillDefinitions: false, + name: "render_sentry_chart", + title: "Render Sentry Chart", + skills: ["inspect", "triage", "seer"], + requiredScopes: ["event:read"], + description: + "Chart a count, rate, duration, or other aggregate of Sentry errors, logs, spans, metrics, or profiles over time, optionally split into the top 5 values of one attribute. Returns every bucket of each series, and MCP Apps hosts show it as an interactive chart. To find individual events, use the dataset search tools.", + inputSchema: { + organizationSlug: ParamOrganizationSlug, + regionUrl: ParamRegionUrl.nullable().default(null), + dataset: z.enum(PUBLIC_EVENTS_DATASETS).describe("Data to chart."), + query: z + .string() + .trim() + .default("") + .describe( + "Sentry search syntax filter, such as `level:error environment:production`. Empty matches everything.", + ), + yAxis: z + .string() + .trim() + .min(1) + .describe( + "Aggregate to plot, such as `count()`, `p95(span.duration)`, or `count_unique(user)`.", + ), + groupBy: z + .string() + .trim() + .min(1) + .nullable() + .default(null) + .describe( + "Attribute to split by, such as `release` or `transaction`; plots its top 5 values. Not supported for profiles.", + ), + projectSlug: ParamProjectSlug.nullable().default(null), + period: ParamPeriod.nullable() + .default(null) + .describe( + "Relative time window, e.g. `1h`, `24h`, `7d`; defaults to 24h. Do not combine with start and end.", + ), + start: z + .string() + .trim() + .nullable() + .default(null) + .describe("Absolute start, ISO 8601; requires end."), + end: z + .string() + .trim() + .nullable() + .default(null) + .describe("Absolute end, ISO 8601; requires start."), + interval: z + .string() + .trim() + .regex(/^\d+[mhd]$/, "Use a bucket size like `5m`, `1h`, or `1d`.") + .nullable() + .default(null) + .describe("Bucket size such as 5m or 1h. Omit to let Sentry pick."), + title: z + .string() + .trim() + .min(1) + .nullable() + .default(null) + .describe("Chart heading; defaults to the aggregate."), + }, + annotations: { + readOnlyHint: true, + destructiveHint: false, + openWorldHint: true, + }, + outputSchema: renderSentryChartOutputSchema, + _meta: uiToolMeta(CHART_UI_RESOURCE), + async handler(params, context: ServerContext) { + if ((params.start === null) !== (params.end === null)) { + throw new UserInputError("Pass both `start` and `end`, or neither."); + } + if (params.start !== null && params.period !== null) { + throw new UserInputError( + "Pass either `period` or `start` and `end`, not both.", + ); + } + if (params.groupBy !== null && params.dataset === "profiles") { + throw new UserInputError( + "Sentry cannot split profile charts by an attribute. Remove `groupBy`.", + ); + } + + const apiService = apiServiceFromContext(context, { + regionUrl: params.regionUrl ?? undefined, + }); + const organizationSlug = params.organizationSlug; + setTargetTagsAndAttributes({ + organizationSlug, + projectSlug: params.projectSlug ?? undefined, + }); + + // Without a project, Sentry only charts projects whose teams the user + // belongs to. `-1` covers every project the user can access, as the UI's + // "All Projects" does. + let projectId = "-1"; + if (params.projectSlug) { + const project = await apiService.getProject({ + organizationSlug, + projectSlugOrId: params.projectSlug, + }); + projectId = String(project.id); + } + + const timeParams: { statsPeriod?: string; start?: string; end?: string } = + params.start !== null && params.end !== null + ? { start: params.start, end: params.end } + : { statsPeriod: params.period ?? DEFAULT_PERIOD }; + const response = await apiService.getEventsTimeSeries({ + organizationSlug, + query: params.query, + yAxis: params.yAxis, + interval: params.interval ?? undefined, + projectId, + dataset: params.dataset, + ...timeParams, + topEvents: params.groupBy + ? { groupBy: params.groupBy, limit: MAX_CHART_SERIES } + : undefined, + }); + + const meta = response.timeSeries[0]?.meta; + if (meta?.valueType === "string") { + throw new UserInputError( + `\`${params.yAxis}\` returns text, which cannot be charted. Use a numeric aggregate such as \`count()\`.`, + ); + } + const { series, peak } = toChartSeries(response, params.yAxis); + + return structuredResult({ + title: + params.title ?? + (params.groupBy + ? `${params.yAxis} by ${params.groupBy}` + : params.yAxis), + dataset: params.dataset, + query: params.query, + yAxis: params.yAxis, + groupBy: params.groupBy, + valueType: meta?.valueType ?? null, + valueUnit: meta?.valueUnit ?? null, + interval: meta + ? formatInterval(meta.interval) + : (params.interval ?? "auto"), + timeRange: { + statsPeriod: timeParams.statsPeriod ?? null, + start: timeParams.start ?? null, + end: timeParams.end ?? null, + }, + url: apiService.getEventsExplorerUrl( + organizationSlug, + params.query, + projectId, + params.dataset, + // Discover reads group-by columns from `field`, so list it first. + params.groupBy ? [params.groupBy, params.yAxis] : [params.yAxis], + `-${params.yAxis}`, + [params.yAxis], + params.groupBy ? [params.groupBy] : [], + timeParams.statsPeriod, + timeParams.start, + timeParams.end, + ), + series, + peak, + ingestion: toStructuredIngestion(response.meta?.ingestion), + }); + }, +}); diff --git a/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts b/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts index 266b25a1f0..39e26250f0 100644 --- a/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts +++ b/packages/mcp-core/src/tools/catalog/search-errors.structured.test.ts @@ -346,7 +346,20 @@ describe("search_errors structured output", () => { "query": "errors per hour", "resultType": "timeSeries", "results": [], - "suggestedActions": [], + "suggestedActions": [ + { + "arguments": { + "dataset": "errors", + "organizationSlug": "test-org", + "period": "24h", + "query": "level:error", + "yAxis": "count()", + }, + "reason": "Chart every bucket of this series.", + "toolName": "render_sentry_chart", + "type": "tool_call", + }, + ], "timeSeries": { "bucketCount": 4, "buckets": [ diff --git a/packages/mcp-core/src/tools/support/chart/schema.ts b/packages/mcp-core/src/tools/support/chart/schema.ts new file mode 100644 index 0000000000..00034948eb --- /dev/null +++ b/packages/mcp-core/src/tools/support/chart/schema.ts @@ -0,0 +1,62 @@ +/** + * The render_sentry_chart result. Imports only zod, so the chart view parses + * the same contract the tool declares. + */ +import { z } from "zod"; +import { ingestionSchema } from "../ingestion"; + +const chartBucketSchema = z.object({ + time: z.string(), + value: z.number(), + incomplete: z + .boolean() + .describe("Data is still arriving, so the value may rise."), + outsideRetention: z + .boolean() + .describe( + "Starts before the retention window, so older data is missing and the value will not change.", + ), +}); + +export const renderSentryChartOutputSchema = z.object({ + title: z.string(), + dataset: z.string(), + query: z.string(), + yAxis: z.string(), + groupBy: z.string().nullable(), + valueType: z + .string() + .nullable() + .describe("Such as integer, number, duration, percentage, or size."), + valueUnit: z.string().nullable().describe("Such as millisecond or byte."), + interval: z.string().describe("Bucket size, such as 5m or 1h."), + timeRange: z.object({ + statsPeriod: z.string().nullable(), + start: z.string().nullable(), + end: z.string().nullable(), + }), + url: z.string(), + series: z + .array( + z.object({ + label: z + .string() + .describe("The group's value, or the aggregate when ungrouped."), + total: z + .number() + .nullable() + .describe("Sum of all buckets; null for non-additive aggregates."), + buckets: z + .array(chartBucketSchema) + .describe("Every bucket, oldest first."), + }), + ) + .describe("One series, or one per top group, largest first."), + peak: z + .object({ series: z.string(), time: z.string(), value: z.number() }) + .nullable() + .describe("Highest bucket across series that is no longer receiving data."), + ingestion: ingestionSchema, +}); + +export type ChartResult = z.output; diff --git a/packages/mcp-core/src/tools/support/ingestion.ts b/packages/mcp-core/src/tools/support/ingestion.ts new file mode 100644 index 0000000000..a388a46440 --- /dev/null +++ b/packages/mcp-core/src/tools/support/ingestion.ts @@ -0,0 +1,29 @@ +/** + * Ingestion delay in structured time series results. Imports only zod, so the + * chart view can share it. + */ +import { z } from "zod"; +import type { IngestionMeta } from "../../api-client/schema"; + +export const ingestionSchema = z + .object({ + status: z.string(), + delaySeconds: z.number().nullable(), + completeThrough: z.string().nullable(), + }) + .nullable(); + +export function toStructuredIngestion( + ingestion: IngestionMeta | undefined, +): z.output { + return ingestion + ? { + status: ingestion.status, + delaySeconds: ingestion.delaySeconds ?? null, + completeThrough: + ingestion.completeThrough === undefined + ? null + : new Date(ingestion.completeThrough).toISOString(), + } + : null; +} diff --git a/packages/mcp-core/src/tools/support/search-events/formatters.ts b/packages/mcp-core/src/tools/support/search-events/formatters.ts index a36d05fe29..e380db3130 100644 --- a/packages/mcp-core/src/tools/support/search-events/formatters.ts +++ b/packages/mcp-core/src/tools/support/search-events/formatters.ts @@ -989,7 +989,7 @@ function formatIngestionStatus(ingestion: IngestionMeta): string { return `- **Ingestion**: ${ingestion.status}${detail}`; } -interface TimeSeriesPoint { +export interface TimeSeriesPoint { timestamp: number; time: string; /** Sort key: the number, or parsed time for date-typed strings. */ @@ -1001,62 +1001,61 @@ interface TimeSeriesPoint { outsideRetention: boolean; } -interface TimeSeriesSummary { +/** One series of an events-timeseries result, with every bucket. */ +export interface SeriesSummary { /** Every bucket, oldest first. */ - bucketCount: number; - /** The most recent `MAX_TIME_SERIES_ROWS` buckets. */ - shown: TimeSeriesPoint[]; + points: TimeSeriesPoint[]; total: number | null; hasFilling: boolean; peak: TimeSeriesPoint | undefined; +} + +interface TimeSeriesSummary extends Omit { + bucketCount: number; + /** The most recent `MAX_TIME_SERIES_ROWS` buckets. */ + shown: TimeSeriesPoint[]; ingestion: IngestionMeta | undefined; } const MAX_TIME_SERIES_ROWS = 48; /** - * Summarize an events-timeseries result: a metric bucketed over time. + * Summarize one series: a metric bucketed over time. * Buckets flagged `incomplete` by Sentry are still receiving data and are * excluded from the peak; those that start before the retention window are * permanently partial and will not change. */ -export function summarizeTimeSeries( - series: EventsTimeSeriesResponse, +export function summarizeSeries( + series: EventsTimeSeriesResponse["timeSeries"][number] | undefined, yAxis: string, -): TimeSeriesSummary { +): SeriesSummary { // String aggregates can return identifiers, even when their values look numeric. - const isStringSeries = series.timeSeries[0]?.meta.valueType === "string"; - const points = (series.timeSeries[0]?.values ?? []).map( - (bucket): TimeSeriesPoint => { - // OUTSIDE_RETENTION buckets start before the retention window: their data - // is permanently partial. Every other reason means data is still arriving. - const outsideRetention = - bucket.incomplete && bucket.incompleteReason === "OUTSIDE_RETENTION"; - const raw = bucket.value ?? 0; - // Date-typed aggregates such as max(timestamp) return ISO datetime - // strings. Number() rejects those whole (parseFloat would keep the year), - // so order them by parsed time and display the raw string. - const numeric = typeof raw === "number" ? raw : Number(raw); - const isNumeric = !Number.isNaN(numeric); - const keepsNumber = !isStringSeries && isNumeric; - return { - timestamp: bucket.timestamp, - time: formatBucketTime(bucket.timestamp), - value: isNumeric ? numeric : Date.parse(String(raw)) || 0, - rawValue: keepsNumber ? numeric : String(raw), - display: keepsNumber ? numeric.toLocaleString() : String(raw), - filling: bucket.incomplete && !outsideRetention, - outsideRetention, - }; - }, - ); + const isStringSeries = series?.meta.valueType === "string"; + const points = (series?.values ?? []).map((bucket): TimeSeriesPoint => { + // OUTSIDE_RETENTION buckets start before the retention window: their data + // is permanently partial. Every other reason means data is still arriving. + const outsideRetention = + bucket.incomplete && bucket.incompleteReason === "OUTSIDE_RETENTION"; + const raw = bucket.value ?? 0; + // Date-typed aggregates such as max(timestamp) return ISO datetime + // strings. Number() rejects those whole (parseFloat would keep the year), + // so order them by parsed time and display the raw string. + const numeric = typeof raw === "number" ? raw : Number(raw); + const isNumeric = !Number.isNaN(numeric); + const keepsNumber = !isStringSeries && isNumeric; + return { + timestamp: bucket.timestamp, + time: formatBucketTime(bucket.timestamp), + value: isNumeric ? numeric : Date.parse(String(raw)) || 0, + rawValue: keepsNumber ? numeric : String(raw), + display: keepsNumber ? numeric.toLocaleString() : String(raw), + filling: bucket.incomplete && !outsideRetention, + outsideRetention, + }; + }); return { - bucketCount: points.length, - shown: - points.length > MAX_TIME_SERIES_ROWS - ? points.slice(-MAX_TIME_SERIES_ROWS) - : points, + points, // Total is only meaningful for additive aggregates; summing count_unique / // avg / percentile buckets would be wrong, so omit it for those. total: @@ -1072,6 +1071,22 @@ export function summarizeTimeSeries( (max, p) => (max === undefined || p.value > max.value ? p : max), undefined, ), + }; +} + +/** Summarize an ungrouped events-timeseries result, keeping recent buckets. */ +export function summarizeTimeSeries( + series: EventsTimeSeriesResponse, + yAxis: string, +): TimeSeriesSummary { + const { points, ...summary } = summarizeSeries(series.timeSeries[0], yAxis); + return { + ...summary, + bucketCount: points.length, + shown: + points.length > MAX_TIME_SERIES_ROWS + ? points.slice(-MAX_TIME_SERIES_ROWS) + : points, ingestion: series.meta?.ingestion, }; } diff --git a/packages/mcp-core/src/tools/support/search-events/search.ts b/packages/mcp-core/src/tools/support/search-events/search.ts index 2d6a076636..6eeda9581d 100644 --- a/packages/mcp-core/src/tools/support/search-events/search.ts +++ b/packages/mcp-core/src/tools/support/search-events/search.ts @@ -1224,6 +1224,15 @@ async function executeSearchEvents( notes: droppedEventsNote ? [...notesFor(pointsWithData), droppedEventsNote] : notesFor(pointsWithData), + session: { + apiService, + organizationSlug, + experimentalMode: context.experimentalMode ?? false, + availableToolNames: context.availableToolNames, + directToolNames: context.directToolNames, + }, + projectSlug: params.projectSlug, + regionUrl: params.regionUrl, }); } const timeSeriesOutput = formatTimeSeriesResults({ diff --git a/packages/mcp-core/src/tools/support/search-events/structured.ts b/packages/mcp-core/src/tools/support/search-events/structured.ts index f9d62dddce..1d2f0a56d7 100644 --- a/packages/mcp-core/src/tools/support/search-events/structured.ts +++ b/packages/mcp-core/src/tools/support/search-events/structured.ts @@ -30,6 +30,7 @@ import { type SearchResultHints, summarizeTimeSeries, } from "./formatters"; +import { ingestionSchema, toStructuredIngestion } from "../ingestion"; import { type FlexibleEventData, isAggregateQuery } from "./utils"; export const timeRangeSchema = z.object({ @@ -64,13 +65,7 @@ const timeSeriesSchema = z.object({ }) .nullable() .describe("Highest bucket that is no longer receiving data."), - ingestion: z - .object({ - status: z.string(), - delaySeconds: z.number().nullable(), - completeThrough: z.string().nullable(), - }) - .nullable(), + ingestion: ingestionSchema, bucketCount: z.number(), buckets: z .array( @@ -455,9 +450,33 @@ export function buildStructuredTimeSeriesResult(params: { timeRange: { statsPeriod?: string; start?: string; end?: string }; url: string; notes: string[]; + session: StructuredSearchSession; + projectSlug: string | null; + regionUrl: string | null; }): StructuredToolOutput { const { bucketCount, shown, total, hasFilling, peak, ingestion } = summarizeTimeSeries(params.series, params.yAxis); + const { session, timeRange } = params; + const chartAction = buildSuggestedToolAction({ + toolName: "render_sentry_chart", + arguments: { + organizationSlug: session.organizationSlug, + dataset: params.dataset, + query: params.query, + yAxis: params.yAxis, + ...(timeRange.start && timeRange.end + ? { start: timeRange.start, end: timeRange.end } + : timeRange.statsPeriod + ? { period: timeRange.statsPeriod } + : {}), + ...(params.projectSlug && { projectSlug: params.projectSlug }), + ...(params.regionUrl && { regionUrl: params.regionUrl }), + }, + reason: "Chart every bucket of this series.", + experimentalMode: session.experimentalMode, + availableToolNames: session.availableToolNames, + directToolNames: session.directToolNames, + }); return structuredResult({ query: params.inputQuery, @@ -484,16 +503,7 @@ export function buildStructuredTimeSeriesResult(params: { peak: peak ? { time: new Date(peak.timestamp).toISOString(), value: peak.rawValue } : null, - ingestion: ingestion - ? { - status: ingestion.status, - delaySeconds: ingestion.delaySeconds ?? null, - completeThrough: - ingestion.completeThrough === undefined - ? null - : new Date(ingestion.completeThrough).toISOString(), - } - : null, + ingestion: toStructuredIngestion(ingestion), bucketCount, buckets: shown.map((point) => ({ time: new Date(point.timestamp).toISOString(), @@ -502,6 +512,6 @@ export function buildStructuredTimeSeriesResult(params: { outsideRetention: point.outsideRetention, })), }, - suggestedActions: [], + suggestedActions: chartAction ? [chartAction] : [], }); } diff --git a/packages/mcp-core/src/tools/types.ts b/packages/mcp-core/src/tools/types.ts index e453e93325..083c457261 100644 --- a/packages/mcp-core/src/tools/types.ts +++ b/packages/mcp-core/src/tools/types.ts @@ -170,6 +170,12 @@ export interface ToolConfig< idempotentHint?: boolean; openWorldHint: boolean; }; + /** + * MCP `_meta` sent with the tool in tools/list, for keys that hosts read, + * such as `ui.resourceUri` (MCP Apps). Every key must be listed in + * `ALLOWED_TOOL_META` in server.metadata.test.ts. + */ + _meta?: Record; handler: ToolHandler>; /** * Optional hook invoked when the handler throws, for tool-specific failure diff --git a/packages/mcp-core/src/ui-resources.test.ts b/packages/mcp-core/src/ui-resources.test.ts new file mode 100644 index 0000000000..cddf348fbb --- /dev/null +++ b/packages/mcp-core/src/ui-resources.test.ts @@ -0,0 +1,94 @@ +import { createHash } from "node:crypto"; +import { describe, expect, it } from "vitest"; +import { uiResourceProblems } from "./test-utils/ui-resource-policy"; +import tools from "./tools"; +import { + CHART_UI_RESOURCE, + UI_RESOURCES, + type UiResource, +} from "./ui-resources"; + +const catalog = Object.entries(tools).map(([name, tool]) => ({ + name, + _meta: tool._meta, +})); + +const html = ""; +const view: UiResource = { + uri: "ui://sentry/test/v1.html", + name: "test", + title: "Test", + description: "Test view", + htmlSha256: createHash("sha256").update(html).digest("hex"), + budgetBytes: 1024, + loadHtml: async () => html, + meta: { csp: {} }, +}; +const tool = { name: "test_tool", _meta: { ui: { resourceUri: view.uri } } }; + +describe("UI resources", () => { + it("follow every MCP Apps rule in the tool catalog", async () => { + expect(await uiResourceProblems(catalog, UI_RESOURCES)).toEqual([]); + }); + + it("has a view for render_sentry_chart", () => { + expect(tools.render_sentry_chart._meta).toEqual({ + ui: { resourceUri: CHART_UI_RESOURCE.uri }, + "openai/outputTemplate": CHART_UI_RESOURCE.uri, + }); + }); +}); + +describe("uiResourceProblems", () => { + it("passes a valid view", async () => { + expect(await uiResourceProblems([tool], [view])).toEqual([]); + }); + + it("fails when a tool names a view that does not exist", async () => { + const stray = { + name: "stray", + _meta: { ui: { resourceUri: "ui://x/v1" } }, + }; + + expect(await uiResourceProblems([tool, stray], [view])).toEqual([ + `stray names view "ui://x/v1", which is not a UI resource.`, + ]); + }); + + it("fails when no tool names a view", async () => { + expect(await uiResourceProblems([], [view])).toEqual([ + `No tool names ${view.uri}, so it is never listed.`, + ]); + }); + + it("fails an unversioned URI", async () => { + const unversioned = { ...view, uri: "ui://sentry/test.html" as const }; + const named = { + name: "t", + _meta: { ui: { resourceUri: unversioned.uri } }, + }; + + expect(await uiResourceProblems([named], [unversioned])).toEqual([ + expect.stringContaining("has no version"), + ]); + }); + + it("fails a csp that allows an origin", async () => { + const leaky = { + ...view, + meta: { csp: { connectDomains: ["https://sentry.io"] } }, + }; + + expect(await uiResourceProblems([tool], [leaky])).toEqual([ + expect.stringContaining("allows connectDomains in its csp"), + ]); + }); + + it("fails when the HTML changes but the recorded hash does not", async () => { + const edited = { ...view, loadHtml: async () => `${html}\n` }; + + expect(await uiResourceProblems([tool], [edited])).toEqual([ + expect.stringContaining(`The HTML of ${view.uri} changed`), + ]); + }); +}); diff --git a/packages/mcp-core/src/ui-resources.ts b/packages/mcp-core/src/ui-resources.ts new file mode 100644 index 0000000000..b2000609c4 --- /dev/null +++ b/packages/mcp-core/src/ui-resources.ts @@ -0,0 +1,135 @@ +/** + * MCP Apps views: `ui://` HTML resources that a host renders inline for a + * tool result. A tool opts in with `_meta: uiToolMeta(resource)`, and the + * server lists each resource that a registered tool references. + * Views are generated HTML strings, so they need no file system at runtime. + * + * Spec: https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx + */ +import type { McpServer } from "@modelcontextprotocol/server"; + +/** The MIME type of an MCP Apps view. */ +export const UI_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app"; + +/** `_meta.ui` on a tool: the view that renders its results. */ +export interface UiToolMeta { + resourceUri: string; +} + +/** + * `_meta.ui` on a view resource. Each `csp` list names origins that the host + * may allow; an empty `csp` means the view loads nothing from the network. + */ +export interface UiResourceMeta { + csp: { + connectDomains?: string[]; + resourceDomains?: string[]; + frameDomains?: string[]; + baseUriDomains?: string[]; + }; + prefersBorder?: boolean; +} + +export interface UiResource { + /** Hosts cache a view by its URI, so bump the version when the HTML changes. */ + uri: `ui://${string}`; + name: string; + title: string; + description: string; + /** + * SHA-256 of the HTML that `uri` serves. A test fails when the HTML changes + * and this does not, so a change also bumps the version in `uri`. + */ + htmlSha256: string; + /** Most bytes the HTML may take. The view's generator fails over it. */ + budgetBytes: number; + /** + * Loads the self-contained HTML5 document (inline scripts and styles only) + * on the first `resources/read`, so sessions that never render a view do + * not load it. + */ + loadHtml(): Promise; + meta: UiResourceMeta; +} + +/** The render_sentry_chart view. Built from chart-app/ by generate-chart-app. */ +export const CHART_UI_RESOURCE: UiResource = { + uri: "ui://sentry/chart/v1.html", + name: "sentry_chart", + title: "Sentry Chart", + description: + "Interactive time series chart for render_sentry_chart results, with a range picker and a link to Sentry.", + htmlSha256: + "c42d34d3aa082a33b4ab293b509dbe4b2dbde7edc4965033cffa8b920fc6e39f", + // About 1.5x the current view, so a new dependency cannot slip in. + budgetBytes: 24 * 1024, + loadHtml: async () => + (await import("./ui/chart-app.generated")).CHART_APP_HTML, + // Self-contained, so it loads nothing from the network. + meta: { csp: {}, prefersBorder: true }, +}; + +export const UI_RESOURCES: readonly UiResource[] = [CHART_UI_RESOURCE]; + +/** + * `_meta` for a tool whose result renders in `resource`. ChatGPT reads + * `openai/outputTemplate`; MCP Apps hosts read `ui.resourceUri`. + */ +export function uiToolMeta(resource: UiResource): { + ui: UiToolMeta; + "openai/outputTemplate": string; +} { + return { + ui: { resourceUri: resource.uri }, + "openai/outputTemplate": resource.uri, + }; +} + +function referencedResourceUri( + meta: Record | undefined, +): string | undefined { + const ui = meta?.["ui"]; + if (typeof ui !== "object" || ui === null || !("resourceUri" in ui)) { + return undefined; + } + return typeof ui.resourceUri === "string" ? ui.resourceUri : undefined; +} + +/** Lists the views that the registered tools reference. */ +export function registerUiResources( + server: McpServer, + tools: readonly { _meta?: Record | undefined }[], +): void { + const referenced = new Set( + tools.map((tool) => referencedResourceUri(tool._meta)), + ); + const resources = UI_RESOURCES.filter((resource) => + referenced.has(resource.uri), + ); + for (const resource of resources) { + server.registerResource( + resource.name, + resource.uri, + { + title: resource.title, + description: resource.description, + mimeType: UI_RESOURCE_MIME_TYPE, + _meta: { ui: resource.meta }, + }, + async () => ({ + contents: [ + { + uri: resource.uri, + mimeType: UI_RESOURCE_MIME_TYPE, + text: await resource.loadHtml(), + _meta: { ui: resource.meta }, + }, + ], + }), + ); + } + // Registration enables this by default, but the set of views is fixed. + if (resources.length > 0) { + server.server.registerCapabilities({ resources: { listChanged: false } }); + } +} diff --git a/packages/mcp-core/src/ui/chart-app.generated.ts b/packages/mcp-core/src/ui/chart-app.generated.ts new file mode 100644 index 0000000000..ff36828222 --- /dev/null +++ b/packages/mcp-core/src/ui/chart-app.generated.ts @@ -0,0 +1,2 @@ +// Generated by scripts/generate-chart-app.ts from chart-app/. Do not edit. +export const CHART_APP_HTML = "Sentry chart"; diff --git a/packages/mcp-server-mocks/src/events-timeseries.ts b/packages/mcp-server-mocks/src/events-timeseries.ts new file mode 100644 index 0000000000..608d748c47 --- /dev/null +++ b/packages/mcp-server-mocks/src/events-timeseries.ts @@ -0,0 +1,102 @@ +/** + * Deterministic `events-timeseries` responses. The series ends at a fixed + * time and its bucket size follows the requested range, so a chart drawn + * from it looks the same on every run and changes shape when the range does. + */ +import { HttpResponse } from "msw"; + +const SERIES_END = Date.UTC(2025, 8, 11, 0, 0, 0); +const MINUTE = 60_000; +const HOUR = 60 * MINUTE; +const DAY = 24 * HOUR; + +/** Bucket size per range when the request names no interval. */ +const DEFAULT_INTERVALS: [rangeMs: number, intervalMs: number][] = [ + [HOUR, MINUTE], + [DAY, 30 * MINUTE], + [7 * DAY, 3 * HOUR], + [Number.POSITIVE_INFINITY, 6 * HOUR], +]; + +const UNIT_MS: Record = { + s: 1000, + m: MINUTE, + h: HOUR, + d: DAY, + w: 7 * DAY, +}; + +function parseDuration(value: string | null): number | undefined { + const match = value ? /^(\d+)([smhdw])$/.exec(value) : null; + const unit = match?.[2]; + return match && unit ? Number(match[1]) * (UNIT_MS[unit] ?? 0) : undefined; +} + +const GROUP_VALUES = ["frontend@2.4.1", "frontend@2.4.0", "frontend@2.3.9"]; + +export function eventsTimeSeriesResponse(request: Request): Response { + const params = new URL(request.url).searchParams; + const yAxis = params.get("yAxis"); + if (!params.get("dataset") || !yAxis) { + return HttpResponse.json( + { detail: "dataset and yAxis are required" }, + { status: 400 }, + ); + } + const topEvents = params.get("topEvents"); + const groupBy = params.get("groupBy"); + if (topEvents && (!groupBy || !params.get("sort"))) { + return HttpResponse.json( + { detail: "groupBy is a required parameter when doing topEvents" }, + { status: 400 }, + ); + } + + const start = params.get("start"); + const end = params.get("end"); + const [rangeStart, rangeEnd] = + start && end + ? [Date.parse(start), Date.parse(end)] + : [ + SERIES_END - (parseDuration(params.get("statsPeriod")) ?? 14 * DAY), + SERIES_END, + ]; + const range = rangeEnd - rangeStart; + const interval = + parseDuration(params.get("interval")) ?? + DEFAULT_INTERVALS.find(([limit]) => range <= limit)?.[1] ?? + 6 * HOUR; + const bucketCount = Math.max(1, Math.round(range / interval)); + + const groups = groupBy + ? GROUP_VALUES.slice(0, Number(topEvents) || GROUP_VALUES.length) + : [null]; + const isDuration = /duration/.test(yAxis); + const timeSeries = groups.map((group, groupIndex) => ({ + yAxis, + ...(group !== null && { groupBy: [{ key: groupBy, value: group }] }), + values: Array.from({ length: bucketCount }, (_, index) => { + const wave = Math.sin((index / bucketCount) * Math.PI * 4 + groupIndex); + const spike = index === Math.floor(bucketCount * 0.7) ? 2.5 : 1; + const base = (isDuration ? 180 : 40) / (groupIndex + 1); + const isLast = index === bucketCount - 1; + return { + timestamp: rangeEnd - (bucketCount - index) * interval, + value: Math.round(base * (1.4 + wave) * spike), + incomplete: isLast, + ...(isLast && { incompleteReason: "INGESTION_PENDING" }), + }; + }), + meta: { + interval, + valueType: isDuration ? "duration" : "integer", + valueUnit: isDuration ? "millisecond" : null, + ...(group !== null && { order: groupIndex, isOther: false }), + }, + })); + + return HttpResponse.json({ + timeSeries, + meta: { start: rangeStart, end: rangeEnd }, + }); +} diff --git a/packages/mcp-server-mocks/src/index.ts b/packages/mcp-server-mocks/src/index.ts index 268be4de11..b085631932 100644 --- a/packages/mcp-server-mocks/src/index.ts +++ b/packages/mcp-server-mocks/src/index.ts @@ -85,6 +85,7 @@ import uptimeChecksFixture from "./fixtures/uptime-checks.json" with { type: "js import uptimeMonitorFixture from "./fixtures/uptime-monitor.json" with { type: "json" }; import userFixture from "./fixtures/user.json" with { type: "json" }; import { issueFixture2 } from "./payloads"; +import { eventsTimeSeriesResponse } from "./events-timeseries"; /** * Builds MSW handlers for both SaaS and self-hosted Sentry instances. @@ -563,6 +564,11 @@ export const restHandlers: HttpHandler[] = buildHandlers([ }); }, }, + { + method: "get", + path: "/api/0/organizations/sentry-mcp-evals/events-timeseries/", + fetch: ({ request }) => eventsTimeSeriesResponse(request), + }, { method: "get", path: "/api/0/organizations/sentry-mcp-evals/events/", diff --git a/packages/mcp-server/script/bundle.ts b/packages/mcp-server/script/bundle.ts index 47fe9b8b52..b54df7db82 100644 --- a/packages/mcp-server/script/bundle.ts +++ b/packages/mcp-server/script/bundle.ts @@ -23,9 +23,9 @@ const CLI_ROOT = resolve(PACKAGE_ROOT, "../cli"); const OUTFILE = resolve(PACKAGE_ROOT, "dist/sentry-mcp.cjs"); /** - * Output is 3,624,475 bytes (3.46 MiB) once help's image banner is left out. - * The budget leaves about 300 KB for new tools and commands, not enough for a - * heavy CLI dependency to slip in unnoticed. + * Output is 3,902,133 bytes (3.72 MiB) once help's image banner is left out, + * 17 KB of it the inlined render_sentry_chart MCP Apps view. The budget + * leaves about 30 KB, so a heavy dependency or view cannot slip in unnoticed. */ const MAX_BUNDLE_BYTES = 3.75 * 1024 * 1024; diff --git a/plugins/sentry-mcp-experimental/agents/sentry-mcp.md b/plugins/sentry-mcp-experimental/agents/sentry-mcp.md index 17eb42990a..65124e5830 100644 --- a/plugins/sentry-mcp-experimental/agents/sentry-mcp.md +++ b/plugins/sentry-mcp-experimental/agents/sentry-mcp.md @@ -63,6 +63,7 @@ allowedTools: - link_issue - onboarding_status_update - remove_team_from_project + - render_sentry_chart - search_agent_conversations - search_attributes - search_docs diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a3ee071ae2..d31e4395bb 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -195,6 +195,15 @@ catalogs: '@cloudflare/workers-types': specifier: ^4.20260405.1 version: 4.20260405.1 + '@modelcontextprotocol/client': + specifier: 2.4.0 + version: 2.4.0 + '@modelcontextprotocol/core': + specifier: 2.4.0 + version: 2.4.0 + '@modelcontextprotocol/ext-apps': + specifier: 2.0.4 + version: 2.0.4 '@modelcontextprotocol/server': specifier: 2.4.0 version: 2.4.0 @@ -312,6 +321,9 @@ catalogs: oxlint: specifier: 1.93.0 version: 1.93.0 + playwright-core: + specifier: 1.65.1 + version: 1.65.1 react: specifier: ^19.2.8 version: 19.2.8 @@ -1058,15 +1070,30 @@ importers: '@ai-sdk/provider-utils': specifier: ^4.0.33 version: 4.0.40(zod@4.6.7) + '@modelcontextprotocol/client': + specifier: 'catalog:' + version: 2.4.0 + '@modelcontextprotocol/core': + specifier: 'catalog:' + version: 2.4.0 + '@modelcontextprotocol/ext-apps': + specifier: 'catalog:' + version: 2.0.4(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/core@2.4.0)(@modelcontextprotocol/server@2.4.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.7) '@modelcontextprotocol/sdk': specifier: 1.32.2 version: 1.32.2(@cfworker/json-schema@4.1.1)(supports-color@10.1.0)(zod@4.6.7) '@sentry/mcp-server-mocks': specifier: workspace:* version: link:../mcp-server-mocks + esbuild: + specifier: ^0.28.1 + version: 0.28.2 msw: specifier: 'catalog:' version: 2.15.0(@types/node@22.20.3)(typescript@7.0.2) + playwright-core: + specifier: 'catalog:' + version: 1.65.1 tiktoken: specifier: ^1.0.18 version: 1.0.22 @@ -2991,6 +3018,24 @@ packages: resolution: {integrity: sha512-z8QBKqdfXLPzkLQuG4xp8hrVEMm1PZ1IgxMN2sMbJiFiAKOWXnAzogXn2W4aqIBlP1ea6U5yiqVquvUNM1Cj6Q==} engines: {node: '>=20'} + '@modelcontextprotocol/ext-apps@2.0.4': + resolution: {integrity: sha512-B+PcbuGiaf0e5I3uy4iO5tS3Abo+5w8JvZFzHMzQdq9yVwP836zJkw2+KCGOQ0r4TM1fuQi4JdnbuWjkS4aBvg==} + engines: {node: '>=20'} + peerDependencies: + '@modelcontextprotocol/client': ^2.0.0 + '@modelcontextprotocol/core': ^2.0.0 + '@modelcontextprotocol/server': ^2.0.0 + react: ^17.0.0 || ^18.0.0 || ^19.0.0 + react-dom: ^17.0.0 || ^18.0.0 || ^19.0.0 + zod: ^4.6.6 + peerDependenciesMeta: + '@modelcontextprotocol/server': + optional: true + react: + optional: true + react-dom: + optional: true + '@modelcontextprotocol/sdk@1.32.2': resolution: {integrity: sha512-SWsVtH/0vULSQStoZ6xxH2K09Li8fXYTMC64ZeogCdpZ3XSi1eCPOByV1OpuJxuI3OcmHhosDWYyii07tpPsLw==} engines: {node: '>=18'} @@ -7354,6 +7399,11 @@ packages: resolution: {integrity: sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==} engines: {node: '>=16.20.0'} + playwright-core@1.65.1: + resolution: {integrity: sha512-hqPpz7blSMPxWVdoeE1yiBSzXsKiVOd2k+kjCvmUywD2GPO2Dd9HfcWnq9NN0GHbNZDFgZ9JfBFr+X5/BLo0qw==} + engines: {node: '>=20'} + hasBin: true + pngjs@7.0.0: resolution: {integrity: sha512-LKWqWJRhstyYo9pGvgor/ivk2w94eSjE3RGVuzLGlr3NmD8bf7RcYGze1mNdEHRP6TRP6rMuDHk5t44hnTRyow==} engines: {node: '>=14.19.0'} @@ -10422,6 +10472,17 @@ snapshots: dependencies: zod: 4.6.7 + '@modelcontextprotocol/ext-apps@2.0.4(@modelcontextprotocol/client@2.4.0)(@modelcontextprotocol/core@2.4.0)(@modelcontextprotocol/server@2.4.0)(react-dom@19.2.8(react@19.2.8))(react@19.2.8)(zod@4.6.7)': + dependencies: + '@modelcontextprotocol/client': 2.4.0 + '@modelcontextprotocol/core': 2.4.0 + '@standard-schema/spec': 1.1.0 + zod: 4.6.7 + optionalDependencies: + '@modelcontextprotocol/server': 2.4.0 + react: 19.2.8 + react-dom: 19.2.8(react@19.2.8) + '@modelcontextprotocol/sdk@1.32.2(@cfworker/json-schema@4.1.1)(supports-color@10.1.0)(zod@4.6.7)': dependencies: '@hono/node-server': 2.1.7(hono@4.13.18) @@ -14764,6 +14825,8 @@ snapshots: pkce-challenge@5.0.1: {} + playwright-core@1.65.1: {} + pngjs@7.0.0: {} portable-executable-signature@2.0.6: {} diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 186ff9edb7..51d7f42ef8 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -56,6 +56,9 @@ catalog: "@cloudflare/vitest-plugin": 1.4.12 "@cloudflare/workers-oauth-provider": ^0.10.3 "@cloudflare/workers-types": ^4.20260405.1 + "@modelcontextprotocol/client": 2.4.0 + "@modelcontextprotocol/core": 2.4.0 + "@modelcontextprotocol/ext-apps": 2.0.4 "@modelcontextprotocol/sdk": 1.32.2 "@modelcontextprotocol/server": 2.4.0 "@radix-ui/react-accordion": ^1.2.20 @@ -94,6 +97,7 @@ catalog: miniflare: 5.20261101.0-beta msw: ^2.15.0 open: ^10.1.2 + playwright-core: 1.65.1 oxfmt: 0.78.0 oxlint: 1.93.0 react: ^19.2.8 diff --git a/scripts/oxc-config.test.mjs b/scripts/oxc-config.test.mjs index 5fdf2c270b..a8d36d873e 100644 --- a/scripts/oxc-config.test.mjs +++ b/scripts/oxc-config.test.mjs @@ -1,6 +1,9 @@ import assert from "node:assert/strict"; -import { readFileSync } from "node:fs"; +import { spawnSync } from "node:child_process"; +import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs"; +import { join } from "node:path"; import { test } from "node:test"; +import { fileURLToPath } from "node:url"; function readRootJson(path) { return JSON.parse( @@ -119,3 +122,25 @@ test("mcp-core and toolkit-core cannot import the CLI", () => { } assert.match(scripts.lint, /pnpm run lint:deps/); }); + +test("mcp-core cannot import the ext-apps SDK at runtime", () => { + const root = fileURLToPath(new URL("..", import.meta.url)); + const dir = mkdtempSync(join(root, "packages/mcp-core/.lint-fixture-")); + try { + for (const specifier of [ + "@modelcontextprotocol/ext-apps", + "@modelcontextprotocol/ext-apps/server", + ]) { + const file = join(dir, "view.ts"); + writeFileSync(file, `export * from "${specifier}";\n`); + const lint = spawnSync("pnpm", ["exec", "oxlint", file], { + cwd: root, + encoding: "utf8", + }); + assert.notEqual(lint.status, 0, specifier); + assert.match(lint.stdout, /no-restricted-imports/, specifier); + } + } finally { + rmSync(dir, { recursive: true, force: true }); + } +});