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

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 5 additions & 3 deletions docs/contributing/tool-responses.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,9 +100,11 @@ notes.

Side quests are things that might help but may not matter for the current
task, such as configuration issues or follow-ups. Source maps that failed to
apply are one. List each once, at the end under `## Concerns Identified`. When
one changes how to read the current data, add a one-line caveat where that data
appears. Raise one only when Sentry's own data shows it unambiguously.
apply are one. List each once, at the end under `## Concerns Identified`, as a
short tip that names the problem and its fix. When one changes how to read the
current data, say so in the tip: "Source maps weren't applied, so frames may be
minified." Raise one only when Sentry's own data shows it unambiguously. Build
them with `buildSideQuests` in `packages/mcp-core/src/internal/side-quests.ts`.

## Formatting Upstream Data

Expand Down
30 changes: 13 additions & 17 deletions packages/mcp-core/src/internal/formatting.ts
Original file line number Diff line number Diff line change
Expand Up @@ -33,13 +33,9 @@ import type {
TraceSpan,
} from "../api-client/types";
import { logIssue } from "../telem/logging";
import {
buildConcerns,
formatConcernCaveats,
formatConcernsSection,
hasReadableStack,
} from "./concerns";
import { buildIssueSideQuests, hasReadableStack } from "./issue-side-quests";
import { selectEventPackages } from "./event-packages";
import { formatSideQuests } from "./side-quests";
import { formatUnknown } from "./unknown-formatting";
import {
type CodeLocation,
Expand Down Expand Up @@ -2377,13 +2373,16 @@ export function formatIssueOutput({
output += `**URL**: ${apiService.getIssueUrl(organizationSlug, issue.shortId)}\n`;
output += "\n";

const concerns = buildConcerns(event, { sourceMapDebug });
// caveats go before the first data they affect: Code Location, or else the
// top of Event Details, above the stacktrace
const caveats = formatConcernCaveats(concerns);
const sideQuests = buildIssueSideQuests(
{ event, sourceMapDebug },
{
experimentalMode: experimentalMode ?? false,
availableToolNames,
directToolNames,
},
);

if (codeLocation) {
output += caveats;
output += formatCodeLocation(codeLocation);
}

Expand Down Expand Up @@ -2426,8 +2425,8 @@ export function formatIssueOutput({
output += ` and Sentry Event ID **${sentryEventId}**`;
}
output += " to help us add support for this event type.\n";
if (concerns.length > 0) {
output += `\n${formatConcernsSection(concerns)}`;
if (sideQuests) {
output += `\n${formatSideQuests(sideQuests)}`;
}

if (aiConversations && aiConversations.length > 0) {
Expand All @@ -2451,9 +2450,6 @@ export function formatIssueOutput({
return output;
}

if (!codeLocation) {
output += caveats;
}
output += `**Event ID**: ${event.id}\n`;
output += `**Type**: ${formatUnknown(event.type)}\n`;
// default: error without exception data, generic: performance/metric issue, csp: CSP violation
Expand Down Expand Up @@ -2509,7 +2505,7 @@ export function formatIssueOutput({
output += "\n";
}

output += formatConcernsSection(concerns);
output += formatSideQuests(sideQuests);

output += "## Response Notes\n\n";
for (const note of buildIssueResponseNotes({
Expand Down
84 changes: 84 additions & 0 deletions packages/mcp-core/src/internal/issue-side-quests.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,84 @@
import { eventFixture, sourceMapDebugFixture } from "@sentry/mcp-server-mocks";
import { describe, expect, it } from "vitest";
import { EventSchema, SourceMapDebugSchema } from "../api-client/schema";
import { buildIssueSideQuests } from "./issue-side-quests";

const session = { experimentalMode: false };
const files = ["/a.js", "/b.js", "/c.js"];

/**
* The fixture's three raw frames, each from its own bundle, with a source map
* error for each and one more for `/d.js`, which has no frame.
*/
function eventWithFourFiles() {
const fixture = structuredClone(eventFixture);
for (const entry of fixture.entries) {
if (entry.type !== "exception") {
continue;
}
for (const value of entry.data.values) {
value.rawStacktrace?.frames.forEach(
(frame: { absPath: string | null }, index: number) => {
frame.absPath = files[index] ?? frame.absPath;
},
);
}
}
return EventSchema.parse({
...fixture,
user: { ...fixture.user, id: "8f3c2a" },
errors: [...files, "/d.js"].map((url) => ({
type: "js_no_source",
message: "Source code was not found",
data: { url },
})),
});
}

describe("buildIssueSideQuests", () => {
it("lists each file's cause when the causes differ", () => {
const event = eventWithFourFiles();
const debug = SourceMapDebugSchema.parse(sourceMapDebugFixture);
// `/b.js` has a debug ID, but nothing was uploaded for it
debug.exceptions[0].frames[1].debug_id_process.debug_id =
"41f4b626-efd6-5847-915c-69f5d33361fb";

expect(buildIssueSideQuests({ event, sourceMapDebug: debug }, session))
.toMatchInlineSnapshot(`
[
{
"details": [
"\`/a.js\` and \`/c.js\` have no debug ID, and the project has no debug ID uploads. Inject debug IDs with the bundler plugin or \`sentry-cli sourcemaps inject\`, deploy, then upload those same files.",
"\`/b.js\` has debug ID \`41f4b626-efd6-5847-915c-69f5d33361fb\`, but no source file or source map with it was uploaded. Upload the deployed build output after injecting debug IDs, with the bundler plugin or \`sentry-cli sourcemaps upload\`.",
"1 more file: the source file or its source map was not found. Upload source maps for this release from the same build that was deployed.",
],
"docs": "https://docs.sentry.io/platforms/javascript/sourcemaps/troubleshooting_js/",
"id": "js_source_maps",
"tip": "Source maps weren't applied to 4 files, so frames may be minified; the cause differs by file.",
},
]
`);
});

it("keeps the remainder when three files have three causes", () => {
const event = eventWithFourFiles();
const debug = SourceMapDebugSchema.parse(sourceMapDebugFixture);
// `/b.js` and `/c.js` each have their own debug ID, with nothing uploaded
debug.exceptions[0].frames[1].debug_id_process.debug_id =
"41f4b626-efd6-5847-915c-69f5d33361fb";
debug.exceptions[0].frames[2].debug_id_process.debug_id =
"6f88580e-719d-56bb-81e1-afad5d3d78ac";

const [quest] =
buildIssueSideQuests({ event, sourceMapDebug: debug }, session) ?? [];

// the third cause joins the remainder, so `/d.js` is still explained
expect(quest.details).toMatchInlineSnapshot(`
[
"\`/a.js\` has no debug ID, and the project has no debug ID uploads. Inject debug IDs with the bundler plugin or \`sentry-cli sourcemaps inject\`, deploy, then upload those same files.",
"\`/b.js\` has debug ID \`41f4b626-efd6-5847-915c-69f5d33361fb\`, but no source file or source map with it was uploaded. Upload the deployed build output after injecting debug IDs, with the bundler plugin or \`sentry-cli sourcemaps upload\`.",
"\`/c.js\` and 1 more: the source file or its source map was not found. Upload source maps for this release from the same build that was deployed.",
]
`);
});
});
Loading
Loading