feat(search-events): Translate natural language queries with Seer

packages/mcp-core/src/api-client/client.ts

@@ -90,6 +90,8 @@ import {
   ReplayListResponseSchema,
   ReplayRecordingSegmentsSchema,
   RepositoryListSchema,
+  SearchAgentStartSchema,
+  SearchAgentStateSchema,
   SpansSearchResponseSchema,
   StacktraceLinkSchema,
   TagListSchema,
@@ -117,6 +119,8 @@ import type {
   AlertRuleUpdate,
   AutofixRun,
   AutofixRunState,
+  SearchAgentStart,
+  SearchAgentState,
   ClientKey,
   ClientKeyList,
   CommitList,
@@ -175,6 +179,16 @@ import type {
 
 const SENTRY_MCP_SEARCH_EVENTS_REFERRER = "api.mcp.search-events";
 
+/**
+ * Filters on other events in the same trace, e.g. spans whose trace also has a
+ * matching log. Only the spans and logs datasets support them.
+ */
+export type CrossEventQueries = {
+  spanQuery?: string;
+  logQuery?: string;
+  metricQuery?: string;
+};
+
 type ExplorerAggregateParams = {
   fields?: string[];
   aggregateFunctions?: string[];
@@ -1648,12 +1662,28 @@ export class SentryApiService {
    * Gets a single organization by slug.
    *
    * @param organizationSlug Organization identifier
+   * @param params Query parameters
+   * @param params.includeFeatureFlags Include `features` in the response (omitted by Sentry otherwise)
+   * @param params.detailed Include projects and teams (Sentry defaults to true)
    * @param opts Request options including host override
    * @returns Organization data
    */
-  async getOrganization(organizationSlug: string, opts?: RequestOptions) {
+  async getOrganization(
+    organizationSlug: string,
+    params?: { includeFeatureFlags?: boolean; detailed?: boolean },
+    opts?: RequestOptions,
+  ) {
+    const queryParams = new URLSearchParams();
+    if (params?.includeFeatureFlags) {
+      queryParams.set("include_feature_flags", "1");
+    }
+    if (params?.detailed === false) {
+      queryParams.set("detailed", "0");
+    }
+    const queryString = queryParams.toString();
+    const organizationPath = apiPath`/organizations/${organizationSlug}/`;
     const body = await this.requestJSON(
-      apiPath`/organizations/${organizationSlug}/`,
+      `${organizationPath}${queryString ? `?${queryString}` : ""}`,
       undefined,
       opts,
     );
@@ -4732,6 +4762,7 @@ export class SentryApiService {
     start?: string;
     end?: string;
     sort: string;
+    crossEventQueries?: CrossEventQueries;
   }): URLSearchParams {
     const queryParams = new URLSearchParams();
 
@@ -4756,6 +4787,11 @@ export class SentryApiService {
       queryParams.set("sampling", "NORMAL");
     }
 
+    const { spanQuery, logQuery, metricQuery } = params.crossEventQueries ?? {};
+    if (spanQuery) queryParams.set("spanQuery", spanQuery);
+    if (logQuery) queryParams.set("logQuery", logQuery);
+    if (metricQuery) queryParams.set("metricQuery", metricQuery);
+
     queryParams.set("sort", params.sort);
 
     // Add fields
@@ -4788,6 +4824,7 @@ export class SentryApiService {
       start,
       end,
       sort = "-timestamp",
+      crossEventQueries,
     }: {
       organizationSlug: string;
       query: string;
@@ -4799,6 +4836,7 @@ export class SentryApiService {
       start?: string;
       end?: string;
       sort?: string;
+      crossEventQueries?: CrossEventQueries;
     },
     opts?: RequestOptions,
   ) {
@@ -4834,6 +4872,7 @@ export class SentryApiService {
         start,
         end,
         sort,
+        crossEventQueries,
       });
     }
 
@@ -4946,6 +4985,55 @@ export class SentryApiService {
     return AutofixRunStateSchema.parse(body);
   }
 
+  // POST https://us.sentry.io/api/0/organizations/my-org/search-agent/start/
+  async startSearchAgent(
+    {
+      organizationSlug,
+      projectIds,
+      naturalLanguageQuery,
+      strategy,
+    }: {
+      organizationSlug: string;
+      projectIds: number[];
+      naturalLanguageQuery: string;
+      strategy: "Traces" | "Issues" | "Logs" | "Errors" | "Metrics";
+    },
+    opts?: RequestOptions,
+  ): Promise<SearchAgentStart> {
+    const body = await this.requestJSON(
+      apiPath`/organizations/${organizationSlug}/search-agent/start/`,
+      {
+        method: "POST",
+        body: JSON.stringify({
+          project_ids: projectIds,
+          natural_language_query: naturalLanguageQuery,
+          strategy,
+        }),
+      },
+      opts,
+    );
+    return SearchAgentStartSchema.parse(body);
+  }
+
+  // GET https://us.sentry.io/api/0/organizations/my-org/search-agent/state/{runId}/
+  async getSearchAgentState(
+    {
+      organizationSlug,
+      runId,
+    }: {
+      organizationSlug: string;
+      runId: string;
+    },
+    opts?: RequestOptions,
+  ): Promise<SearchAgentState> {
+    const body = await this.requestJSON(
+      apiPath`/organizations/${organizationSlug}/search-agent/state/${runId}/`,
+      undefined,
+      opts,
+    );
+    return SearchAgentStateSchema.parse(body);
+  }
+
   /**
    * Retrieves high-level metadata about a trace.
    *

packages/mcp-core/src/api-client/schema.ts

@@ -84,6 +84,9 @@ export const OrganizationSchema = z
         organizationUrl: z.string().url(),
       })
       .optional(),
+    // Only returned by the organization details endpoint, not the list endpoint.
+    features: z.array(z.string()).optional(),
+    hideAiFeatures: z.boolean().optional(),
   })
   .passthrough();
 
@@ -1402,6 +1405,75 @@ export const AutofixRunStateSchema = z.object({
   formatted: z.object({ format: z.string(), content: z.string() }).optional(),
 });
 
+/**
+ * Schemas for Seer's search agent, which translates natural language into
+ * Sentry search queries.
+ *
+ * Upstream source of truth in getsentry/sentry:
+ * - `src/sentry/seer/endpoints/search_agent_start.py`
+ * - `src/sentry/seer/endpoints/search_agent_state.py`
+ * - `src/sentry/seer/endpoints/search_agent_types.py`
+ */
+export const SearchAgentStartSchema = z
+  .object({
+    // Null until Seer has picked up the run; poll with sentry_run_id instead.
+    run_id: z.number().nullable(),
+    sentry_run_id: z.string(),
+  })
+  .passthrough();
+
+export const SearchAgentQuerySchema = z
+  .object({
+    query: z.string(),
+    group_by: z.array(z.string()).default([]),
+    visualization: z
+      .array(
+        z
+          .object({
+            y_axes: z.array(z.string()).default([]),
+            // Only set when the user asks for a time bucket, e.g. "per hour".
+            interval: z.string().nullable().optional(),
+          })
+          .passthrough(),
+      )
+      .default([]),
+    sort: z.string().default(""),
+    // Empty when an absolute start/end range is used instead.
+    stats_period: z.string().default(""),
+    start: z.string().nullable().optional(),
+    end: z.string().nullable().optional(),
+    mode: z.string(),
+    // Cross-event filters, only set for the Traces strategy.
+    span_query: z.string().nullable().optional(),
+    log_query: z.string().nullable().optional(),
+    metric_query: z.string().nullable().optional(),
+  })
+  .passthrough();
+
+export const SearchAgentTranslateSchema = z
+  .object({
+    responses: z.array(SearchAgentQuerySchema),
+    unsupported_reason: z.string().nullable().optional(),
+    // Projects Seer scoped the query to, a superset of the requested projects
+    // when it broadens scope. Absent when there's no expansion.
+    project_ids: z.array(z.number()).nullable().optional(),
+  })
+  .passthrough();
+
+export const SearchAgentStateSchema = z
+  .object({
+    session: z
+      .object({
+        // Only `status` is set while the run is still being created in Seer.
+        status: z.string(),
+        final_response: SearchAgentTranslateSchema.nullable().optional(),
+        unsupported_reason: z.string().nullable().optional(),
+      })
+      .passthrough()
+      .nullable(),
+  })
+  .passthrough();
+
 export const EventAttachmentSchema = z.object({
   id: z.string(),
   name: z.string(),

packages/mcp-core/src/api-client/types.ts

@@ -54,6 +54,8 @@ import type {
   AssignedToSchema,
   AutofixRunSchema,
   AutofixRunStateSchema,
+  SearchAgentStartSchema,
+  SearchAgentStateSchema,
   ClientKeyListSchema,
   ClientKeySchema,
   CommitListSchema,
@@ -232,6 +234,8 @@ export type EventAttachment = z.infer<typeof EventAttachmentSchema>;
 export type Tag = z.infer<typeof TagSchema>;
 export type AutofixRun = z.infer<typeof AutofixRunSchema>;
 export type AutofixRunState = z.infer<typeof AutofixRunStateSchema>;
+export type SearchAgentStart = z.infer<typeof SearchAgentStartSchema>;
+export type SearchAgentState = z.infer<typeof SearchAgentStateSchema>;
 export type AssignedTo = z.infer<typeof AssignedToSchema>;
 export type ReplayDetails = z.infer<typeof ReplayDetailsSchema>;
 export type ReplayList = z.infer<typeof ReplayListResponseSchema>["data"];