feat: integrate Seer AI analysis into issue details

Enhanced get_issue_details to include Seer AI analysis when available, providing users with both raw issue data and AI-powered insights in a single tool call.

Changes:
- Add Seer analysis context to issue details output
- Update tool descriptions to clarify use cases
- Add formatSeerContext utility for clean analysis display
- Include tests for Seer integration
- Fix markdown formatting in documentation
- Export autofixStateFixture for testing

Fixes #360, #361

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: dcramer

docs/architecture.mdc

@@ -29,6 +29,7 @@ packages/
 The core MCP implementation and npm-publishable package.
 
 **Structure:**
+
 ```
 src/
 ├── api-client/         # Sentry API client
@@ -43,14 +44,15 @@ src/
 ```
 
 **Key responsibilities:**
+
 - Implements MCP protocol using the official SDK
 - Provides tools for Sentry operations (issues, projects, etc.)
 - Handles authentication and API communication
 - Formats responses for LLM consumption
 
 ### packages/mcp-cloudflare
 
-A separate web chat application that uses the MCP server. 
+A separate web chat application that uses the MCP server.
 
 **Note**: This is NOT part of the MCP server itself - it's a demonstration of how to build a chat interface that consumes MCP.
 
@@ -61,6 +63,7 @@ See [Cloudflare Web App Documentation](./cloudflare/overview.md) for details.
 Evaluation tests that verify real Sentry operations.
 
 **Uses:**
+
 - Vercel AI SDK for LLM integration
 - Real Sentry API calls with mocked responses
 - Factuality scoring for output validation
@@ -70,6 +73,7 @@ Evaluation tests that verify real Sentry operations.
 Centralized mock data and MSW handlers.
 
 **Provides:**
+
 - Fixture data for all Sentry entities
 - MSW request handlers
 - Shared test utilities
@@ -79,6 +83,7 @@ Centralized mock data and MSW handlers.
 Interactive CLI for testing the MCP server with an AI agent.
 
 **Key features:**
+
 - Vercel AI SDK integration with Anthropic
 - Interactive and single-prompt modes
 - OAuth authentication for remote servers
@@ -107,12 +112,14 @@ server.setRequestHandler(ListToolsRequestSchema, () => ({
 The MCP server supports multiple transport mechanisms:
 
 **Stdio Transport** (Primary):
+
 - Direct process communication
 - Used by IDEs (Cursor, VS Code) and local tools
 - Configured via command-line args
 - This is the standard MCP transport
 
 **HTTP/SSE Transport** (For web apps):
+
 - Allows web applications to connect to MCP
 - Used by the example Cloudflare chat app
 - Not part of core MCP spec
@@ -168,6 +175,7 @@ Each tool follows a consistent structure:
    - Evaluation tests
 
 **Tool Count Constraints:**
+
 - AI agents have a 45 tool limit (Cursor, etc.)
 - Sentry MCP must stay under 25 tools (target: ~20)
 - Consolidate functionality where possible
@@ -183,6 +191,7 @@ Two-tier error system:
 ### 7. Build System
 
 Turbo for monorepo orchestration:
+
 - Dependency-aware builds
 - Parallel task execution
 - Shared TypeScript configs
@@ -207,20 +216,26 @@ Turbo for monorepo orchestration:
 ## MCP Concept Mappings
 
 ### Tools
+
 Execute actions and retrieve data:
+
 - `find_issues` - Search for issues
 - `get_project_details` - Fetch project info
 - `create_issue_comment` - Add comments
 - `search_docs` - Search Sentry documentation
 - `get_doc` - Fetch full documentation pages
 
 ### Prompts
+
 Multi-step workflows:
+
 - `find_errors_in_file` - Analyze file errors
 - `fix_issue_with_seer` - AI-suggested fixes
 
 ### Resources
+
 External documentation and data:
+
 - Platform docs (React, Python, etc.)
 - API references
 - Configuration examples

docs/cloudflare/prompts-integration.md

@@ -138,6 +138,7 @@ Users can type `/prompts` in the chat to see all available MCP prompts:
 ```
 
 This displays a formatted list with:
+
 - Prompt names and descriptions
 - Required and optional parameters
 - Parameter types and descriptions
@@ -197,4 +198,4 @@ The AI agent is automatically aware of available prompts through its enhanced sy
 - Zod schemas are converted to simple JSON schemas for client consumption
 - Graceful fallback to stream data if metadata endpoint fails
 - Loading and error states provide better user experience
-- The implementation is designed to be easily removable once AI SDK supports prompts natively
+- The implementation is designed to be easily removable once AI SDK supports prompts natively

packages/mcp-server-mocks/src/index.ts

@@ -722,6 +722,7 @@ export const restHandlers = buildHandlers([
     path: "/api/0/organizations/sentry-mcp-evals/issues/6507376926/",
     fetch: () => HttpResponse.json(issueFixture2),
   },
+
   {
     method: "get",
     path: "/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/events/7ca573c0f4814912aaa9bdc77d1a7d51/",
@@ -754,6 +755,7 @@ export const restHandlers = buildHandlers([
     path: "/api/0/organizations/sentry-mcp-evals/issues/6507376926/events/latest/",
     fetch: () => HttpResponse.json(eventsFixture),
   },
+
   {
     method: "get",
     path: "/api/0/organizations/sentry-mcp-evals/releases/",
@@ -769,36 +771,22 @@ export const restHandlers = buildHandlers([
     path: "/api/0/organizations/sentry-mcp-evals/tags/",
     fetch: () => HttpResponse.json(tagsFixture),
   },
-  {
-    method: "get",
-    path: "/api/0/organizations/sentry-mcp-evals/issues/6507376925/autofix/",
-    fetch: () => HttpResponse.json(autofixStateFixture),
-  },
   {
     method: "get",
     path: "/api/0/organizations/sentry-mcp-evals/issues/PEATED-A8/autofix/",
     fetch: () => HttpResponse.json(autofixStateFixture),
   },
   {
     method: "post",
-    path: "/api/0/organizations/sentry-mcp-evals/issues/6507376925/autofix/",
+    path: "/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-42/autofix/",
     fetch: () => HttpResponse.json({ run_id: 123 }),
   },
   {
     method: "post",
     path: "/api/0/organizations/sentry-mcp-evals/issues/PEATED-A8/autofix/",
     fetch: () => HttpResponse.json({ run_id: 123 }),
   },
-  {
-    method: "get",
-    path: "/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/autofix/",
-    fetch: () => HttpResponse.json({ autofix: null }),
-  },
-  {
-    method: "post",
-    path: "/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/autofix/",
-    fetch: () => HttpResponse.json({ run_id: 12 }),
-  },
+
   {
     method: "get",
     path: "/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-45/autofix/",
@@ -1203,3 +1191,6 @@ export const mswServer = setupServer(
   ...searchHandlers,
   ...docsHandlers,
 );
+
+// Export fixtures for use in tests
+export { autofixStateFixture };

packages/mcp-server/src/internal/formatting.ts

@@ -6,7 +6,7 @@
  * and contextual information with consistent formatting patterns.
  */
 import type { z } from "zod";
-import type { Event, Issue } from "../api-client/types";
+import type { Event, Issue, AutofixRunState } from "../api-client/types";
 import type {
   ErrorEntrySchema,
   ErrorEventSchema,
@@ -17,6 +17,11 @@ import type {
   ThreadsEntrySchema,
   SentryApiService,
 } from "../api-client";
+import {
+  getOutputForAutofixStep,
+  getStatusDisplayName,
+  isTerminalStatus,
+} from "../tools/utils/seer-utils";
 
 // Language detection mappings
 const LANGUAGE_EXTENSIONS: Record<string, string> = {
@@ -604,6 +609,63 @@ function formatContexts(contexts: z.infer<typeof EventSchema>["contexts"]) {
     .join("\n\n")}\n\n`;
 }
 
+/**
+ * Formats Seer AI analysis context for inclusion in issue details.
+ * Provides a minimal summary showing just the key solution when available.
+ *
+ * @param autofixState - The autofix state containing Seer analysis data
+ * @returns Formatted markdown string with Seer context, or empty string if no analysis exists
+ */
+function formatSeerContext(autofixState: AutofixRunState): string {
+  if (!autofixState.autofix) {
+    return "";
+  }
+
+  const { autofix } = autofixState;
+  const parts: string[] = [];
+
+  parts.push("## Seer AI Analysis");
+  parts.push("");
+
+  // For completed analyses, show just the key solution
+  if (isTerminalStatus(autofix.status) && autofix.steps.length > 0) {
+    const completedSteps = autofix.steps.filter(
+      (step) => step.status === "COMPLETED",
+    );
+
+    // Find the solution step and show its description directly
+    const solutionStep = completedSteps.find(
+      (step) => step.type === "solution",
+    );
+
+    if (solutionStep) {
+      // For solution steps, use the description directly
+      const solutionDescription = solutionStep.description;
+      if (
+        solutionDescription &&
+        typeof solutionDescription === "string" &&
+        solutionDescription.trim()
+      ) {
+        parts.push(solutionDescription.trim());
+      } else {
+        // Fallback to extracting from output if no description
+        const solutionOutput = getOutputForAutofixStep(solutionStep);
+        const lines = solutionOutput.split("\n");
+        const firstParagraph = lines.find(
+          (line) =>
+            line.trim().length > 50 &&
+            !line.startsWith("#") &&
+            !line.startsWith("*"),
+        );
+        if (firstParagraph) {
+          parts.push(firstParagraph.trim());
+        }
+      }
+    }
+  }
+  return `${parts.join("\n")}\n\n`;
+}
+
 /**
  * Formats a Sentry issue with its latest event into comprehensive markdown output.
  * Includes issue metadata, event details, and usage instructions.
@@ -616,11 +678,13 @@ export function formatIssueOutput({
   issue,
   event,
   apiService,
+  autofixState,
 }: {
   organizationSlug: string;
   issue: Issue;
   event: Event;
   apiService: SentryApiService;
+  autofixState?: AutofixRunState;
 }) {
   let output = `# Issue ${issue.shortId} in **${organizationSlug}**\n\n`;
   output += `**Description**: ${issue.title}\n`;
@@ -644,6 +708,12 @@ export function formatIssueOutput({
   }
   output += "\n";
   output += formatEventOutput(event);
+
+  // Add Seer context if available
+  if (autofixState) {
+    output += formatSeerContext(autofixState);
+  }
+
   output += "# Using this information\n\n";
   output += `- You can reference the IssueID in commit messages (e.g. \`Fixes ${issue.shortId}\`) to automatically close the issue when the commit is merged.\n`;
   output +=

packages/mcp-server/src/tools/analyze-issue-with-seer.ts

@@ -23,14 +23,13 @@ import {
 export default defineTool({
   name: "analyze_issue_with_seer",
   description: [
-    "**ALWAYS use this tool when a user asks how to fix a Sentry issue.** Seer AI analyzes production errors to identify root causes and provide specific code fixes.",
+    "Use Seer AI to analyze production errors and get detailed root cause analysis with specific code fixes.",
     "",
-    "Use this tool IMMEDIATELY when:",
-    '- User asks "how do I fix this error?" or "what\'s causing this issue?"',
-    "- User shares a Sentry issue URL and wants help resolving it",
-    "- User needs to understand why an error is happening in production",
-    "- User wants specific code changes to fix their issue",
-    "- User asks about the root cause of any Sentry error",
+    "Use this tool when you need:",
+    "- Detailed AI-powered root cause analysis",
+    "- Specific code fixes and implementation guidance",
+    "- Step-by-step troubleshooting for complex issues",
+    "- Understanding why an error is happening in production",
     "",
     "What this tool provides:",
     "- Root cause analysis with code-level explanations",
@@ -44,12 +43,6 @@ export default defineTool({
     "3. Returns complete fix recommendations",
     "",
     "<examples>",
-    '### User: "How do I fix ISSUE-123?"',
-    "",
-    "```",
-    "analyze_issue_with_seer(organizationSlug='my-organization', issueId='ISSUE-123')",
-    "```",
-    "",
     '### User: "What\'s causing this error? https://my-org.sentry.io/issues/PROJECT-1Z43"',
     "",
     "```",
@@ -64,7 +57,7 @@ export default defineTool({
     "</examples>",
     "",
     "<hints>",
-    "- ALWAYS prefer this over get_issue_details when users want fixes, not just error details",
+    "- Use this tool when you need deeper analysis beyond basic issue details",
     "- If the user provides an issueUrl, extract it and use that parameter alone",
     "- The analysis includes actual code snippets and fixes, not just error descriptions",
     "- Results are cached - subsequent calls return instantly",

packages/mcp-server/src/tools/get-issue-details.test.ts

@@ -1,4 +1,6 @@
 import { describe, it, expect } from "vitest";
+import { http, HttpResponse } from "msw";
+import { mswServer, autofixStateFixture } from "@sentry/mcp-server-mocks";
 import getIssueDetails from "./get-issue-details.js";
 
 describe("get_issue_details", () => {
@@ -263,4 +265,33 @@ describe("get_issue_details", () => {
       "Invalid regionUrl provided: https. Must be a valid URL.",
     );
   });
+
+  it("includes Seer analysis when available", async () => {
+    // Add ADDITIONAL endpoint binding for autofix state using mswServer.use()
+    // The default fixtures will handle the regular issue and events endpoints
+    mswServer.use(
+      http.get(
+        "https://sentry.io/api/0/organizations/sentry-mcp-evals/issues/CLOUDFLARE-MCP-41/autofix/",
+        () => HttpResponse.json(autofixStateFixture),
+      ),
+    );
+
+    const result = await getIssueDetails.handler(
+      {
+        organizationSlug: "sentry-mcp-evals",
+        issueId: "CLOUDFLARE-MCP-41",
+        eventId: undefined,
+        issueUrl: undefined,
+        regionUrl: undefined,
+      },
+      {
+        accessToken: "access-token",
+        userId: "1",
+        organizationSlug: null,
+      },
+    );
+
+    expect(result).toContain("## Seer AI Analysis");
+    expect(result).toContain("Consolidate bottle and price data fetching");
+  });
 });