Improving error handling in crashlytics tools and using more guide content

Author: maxl0rd

src/crashlytics/filters.ts

@@ -4,11 +4,7 @@ import { FirebaseError } from "../error";
 export const ApplicationIdSchema = z
   .string()
   .describe(
-    "Firebase app id. For an Android application, read the " +
-      "mobilesdk_app_id value specified in the google-services.json file for " +
-      "the current package name. For an iOS Application, read the GOOGLE_APP_ID " +
-      "from GoogleService-Info.plist. If neither is available, ask the user to " +
-      "provide the app id.",
+    "Firebase App Id. Leave blank if unknown to receive instructions for finding it.",
   );
 
 export const IssueIdSchema = z.string().describe("Crashlytics issue id, as hexidecimal uuid");
@@ -109,12 +105,15 @@ export function filterToUrlSearchParams(filter: EventFilter): URLSearchParams {
 const displayNamePattern = /^[^()]+\s+\([^()]+\)$/; // Regular expression like "xxxx (yyy)"
 
 /**
- * Perform some simplistic validation on filters.
+ * Perform some simplistic validation on filters and fill .
  * @param filter filters to validate
  * @throws FirebaseError if any of the filters are invalid.
  */
-export function validateEventFilters(filter: EventFilter): void {
-  if (!filter) return;
+export function validateEventFilters(filter: EventFilter = {}): EventFilter {
+  if (!!filter.intervalStartTime && !filter.intervalEndTime) {
+    // interval.end_time is required if interval.start_time is set but the agent likes to forget it
+    filter.intervalEndTime = new Date().toISOString();
+  }   
   const ninetyDaysAgo = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
   if (filter.intervalStartTime && new Date(filter.intervalStartTime) < ninetyDaysAgo) {
     throw new FirebaseError("intervalStartTime must be less than 90 days in the past");
@@ -140,4 +139,5 @@ export function validateEventFilters(filter: EventFilter): void {
       }
     });
   }
+  return filter;
 }

src/crashlytics/reports.spec.ts

@@ -140,7 +140,7 @@ describe("getReport", () => {
       .reply(200, mockResponse);
 
     const result = await getReport(
-      CrashlyticsReport.TopIssues,
+      CrashlyticsReport.TOP_ISSUES,
       appId,
       { issueErrorTypes: [issueType] },
       pageSize,
@@ -153,7 +153,7 @@ describe("getReport", () => {
   it("should throw a FirebaseError if the appId is invalid", async () => {
     const invalidAppId = "invalid-app-id";
 
-    await expect(getReport(CrashlyticsReport.TopIssues, invalidAppId, {})).to.be.rejectedWith(
+    await expect(getReport(CrashlyticsReport.TOP_ISSUES, invalidAppId, {})).to.be.rejectedWith(
       FirebaseError,
       "Unable to get the projectId from the AppId.",
     );

src/crashlytics/reports.ts

@@ -9,26 +9,39 @@ import {
   EventFilterSchema,
   filterToUrlSearchParams,
 } from "./filters";
+import { FirebaseError } from "../error";
 
 const DEFAULT_PAGE_SIZE = 10;
 
+export enum CrashlyticsReport {
+  TOP_ISSUES = "topIssues",
+  TOP_VARIANTS = "topVariants",
+  TOP_VERSIONS = "topVersions",
+  TOP_OPERATING_SYSTEMS = "topOperatingSystems",
+  TOP_APPLE_DEVICES = "topAppleDevices",
+  TOP_ANDROID_DEVICES = "topAndroidDevices",
+}
+
+export const CrashlyticsReportSchema = z.nativeEnum(CrashlyticsReport);
+
+export function toReportEnum(reportName: string): CrashlyticsReport | undefined {
+  const enumValues = Object.values(CrashlyticsReport);
+  if (enumValues.includes(reportName as CrashlyticsReport)) {
+    return reportName as CrashlyticsReport;
+  } else {
+    return undefined;
+  }
+}
+
 export const ReportInputSchema = z.object({
   appId: ApplicationIdSchema,
+  report: CrashlyticsReportSchema,
   filter: EventFilterSchema,
   pageSize: z.number().optional().describe("Number of rows to return").default(DEFAULT_PAGE_SIZE),
 });
 
 export type ReportInput = z.infer<typeof ReportInputSchema>;
 
-export enum CrashlyticsReport {
-  TopIssues = "topIssues",
-  TopVariants = "topVariants",
-  TopVersions = "topVersions",
-  TopOperatingSystems = "topOperatingSystems",
-  TopAppleDevices = "topAppleDevices",
-  TopAndroidDevices = "topAndroidDevices",
-}
-
 /**
  * Returns a report for Crashlytics events.
  * @param report One of the supported reports in the CrashlyticsReport enum
@@ -62,23 +75,27 @@ export function simplifyReport(report: Report): Report {
 }
 
 export async function getReport(
-  report: CrashlyticsReport,
+  reportName: CrashlyticsReport,
   appId: string,
   filter: EventFilter,
   pageSize = DEFAULT_PAGE_SIZE,
 ): Promise<Report> {
+  
+  if (!reportName) {
+    throw new FirebaseError("Invalid Crashlytics report " + reportName);
+  }
   const requestProjectNumber = parseProjectNumber(appId);
   const queryParams = filterToUrlSearchParams(filter);
   queryParams.set("page_size", `${pageSize}`);
   logger.debug(
-    `[crashlytics] report ${report} called with appId: ${appId} filter: ${queryParams.toString()}, page_size: ${pageSize}`,
+    `[crashlytics] report ${reportName} called with appId: ${appId} filter: ${queryParams.toString()}, page_size: ${pageSize}`,
   );
   const response = await CRASHLYTICS_API_CLIENT.request<void, Report>({
     method: "GET",
     headers: {
       "Content-Type": "application/json",
     },
-    path: `/projects/${requestProjectNumber}/apps/${appId}/reports/${report}`,
+    path: `/projects/${requestProjectNumber}/apps/${appId}/reports/${reportName}`,
     queryParams: queryParams,
     timeout: TIMEOUT,
   });

src/mcp/prompts/crashlytics/connect.ts

@@ -1,4 +1,5 @@
 import { prompt } from "../../prompt";
+import { RESOURCE_CONTENT as connectResourceContent } from "../../resources/guides/crashlytics_connect";
 
 export const connect = prompt(
   "crashlytics",
@@ -34,25 +35,8 @@ You will assist developers in investigating and resolving mobile application iss
 
 **Obtain the Firebase App ID.** 
     If an App ID is not readily available, consult this guide for selection: [Firebase App Id Guide](firebase://guides/app_id).
-### Next Steps
 
-After confirming the user is logged into Firebase and the correct App ID is identified, inquire about the desired actions. Your capabilities include:
-- Reading Crashlytics reports.
-- Investigating bug reports using Crashlytics event data.
-- Proposing code changes to resolve identified bugs.
-
-Only ask the user one question at a time. Do not proceed without user instructions.
-Upon receiving user instructions, refer to the relevant resources for guidance.
-Use the Firebase \`read_resources\` tool to access the following guides.
-
-  1. [Firebase Crashlytics Reports Guide](firebase://guides/crashlytics/reports)
-     This guide details how to request and use aggregated numerical data from Crashlytics. The agent should read this guide before requesting any report.
-    
-  2. [Firebase Crashlytics Issues Guide](firebase://guides/crashlytics/issues)
-     This guide details how to work with issues within Crashlytics. The agent should read this guide before prioritizing issues or presenting issue data to the user.
-
-  3. [Investigating Crashlytics Issues](firebase://guides/crashlytics/investigations)
-     This guide provides instructions on investigating the root causes of crashes and exceptions reported in Crashlytics issues.
+${ connectResourceContent }
 `.trim(),
         },
       },

src/mcp/resources/guides/app_id.ts

@@ -1,20 +1,6 @@
 import { resource } from "../../resource";
 
-export const app_id = resource(
-  {
-    uri: "firebase://guides/app_id",
-    name: "app_id_guide",
-    title: "Firebase App Id Guide",
-    description:
-      "guides the coding agent through choosing a Firebase App ID in the current project",
-  },
-  async (uri) => {
-    return {
-      contents: [
-        {
-          uri,
-          type: "text",
-          text: `
+export const RESOURCE_CONTENT = `
 ### Firebase App ID
   The Firebase App ID is used to identify a mobile or web client application to Firebase back end services such as Crashlytics or Remote Config. Use the information below to find the developer's App ID.
 
@@ -38,9 +24,19 @@ export const app_id = resource(
           number (typically "1"), a project number, a platform type ("android", "ios", or "web"), 
           and a sequence of hexadecimal characters. 
        ii. Store the valid app id value, the android package name or ios bundle identifier, and the project directory.
-`.trim(),
-        },
-      ],
+`.trim();
+
+export const app_id = resource(
+  {
+    uri: "firebase://guides/app_id",
+    name: "app_id_guide",
+    title: "Firebase App Id Guide",
+    description:
+      "guides the coding agent through choosing a Firebase App ID in the current project",
+  },
+  async (uri) => {
+    return {
+      contents: [{ uri, type: "text", text: RESOURCE_CONTENT }],
     };
   },
 );

src/mcp/resources/guides/crashlytics_connect.ts

@@ -0,0 +1,49 @@
+import { resource } from "../../resource";
+
+export const RESOURCE_CONTENT = `
+### Instructions for Working with Firebase Crashlytics Tools
+
+Only ask the user one question at a time. Do not proceed without user instructions. Upon receiving user instructions, refer to the relevant resources for guidance.
+
+Use the \`firebase_read_resources\` tool to access the following guides.
+
+  1. [Firebase App Id Guide](firebase://guides/app_id)
+     This guide provides crucial instructions for obtaining the application's App Id which is required for all API calls.
+
+  1. [Firebase Crashlytics Reports Guide](firebase://guides/crashlytics/reports)
+     This guide details how to request and use aggregated numerical data from Crashlytics. The agent should read this guide before requesting any report.
+    
+  2. [Firebase Crashlytics Issues Guide](firebase://guides/crashlytics/issues)
+     This guide details how to work with issues within Crashlytics. The agent should read this guide before prioritizing issues or presenting issue data to the user.
+
+  3. [Investigating Crashlytics Issues](firebase://guides/crashlytics/investigations)
+     This guide provides instructions on investigating the root causes of crashes and exceptions reported in Crashlytics issues.
+
+### Check That You Are Connected
+
+Verify that you can read the app's Crashlytics data by getting the topVersions report. This report will tell you which app versions have the most events.
+  a. Call the \`firebase_get_environment\` tool if you need to find the app_id.
+  b. Call the \`crashlytics_get_report\` tool to read the \`topVersions\` report.
+  c. If you haven't read the reports guide, then the tool will include it in the response. This is OK. Simply call the tool again.
+  d. Help the user resolve any issues that arise when trying to connect.
+
+After confirming you can access Crashlytics, inquire about the desired actions. Your capabilities include:
+
+  - Reading Crashlytics reports.
+  - Investigating bug reports using Crashlytics event data.
+  - Proposing code changes to resolve identified bugs.
+`.trim();
+
+export const crashlytics_connect = resource(
+  {
+    uri: "firebase://guides/crashlytics/connect",
+    name: "crashlytics_connect_guide",
+    title: "Firebase Crashlytics Connect Guide",
+    description: "Guides the coding agent to connect to Firebase Crashlytics.",
+  },
+  async (uri) => {
+    return {
+      contents: [{ uri, type: "text", text: RESOURCE_CONTENT }],
+    };
+  },
+);

src/mcp/resources/guides/crashlytics_investigations.ts

@@ -1,20 +1,6 @@
 import { resource } from "../../resource";
 
-export const crashlytics_investigations = resource(
-  {
-    uri: "firebase://guides/crashlytics/investigations",
-    name: "crashlytics_investigations_guide",
-    title: "Firebase Crashlytics Investigations Guide",
-    description:
-      "Guides the coding agent when investigating bugs reported in Crashlytics issues, including procedures for diagnosing and fixing crashes.",
-  },
-  async (uri) => {
-    return {
-      contents: [
-        {
-          uri,
-          type: "text",
-          text: `
+const RESOURCE_CONTENT = `
 ### How to Diagnose and Fix Crashlytics Issues
 
   Follow these steps to diagnose bugs and and propose fixes for issues.
@@ -61,9 +47,19 @@ export const crashlytics_investigations = resource(
   10. Only if they approve the plan, create a fix for the issue.
     10a. Be mindful of API contracts and do not add fields to resources without a clear way to populate those fields
     10b. If there is not enough information in the crash report to find a root cause, describe why you cannot fix the issue instead of making a guess.
-`.trim(),
-        },
-      ],
+`.trim();
+
+export const crashlytics_investigations = resource(
+  {
+    uri: "firebase://guides/crashlytics/investigations",
+    name: "crashlytics_investigations_guide",
+    title: "Firebase Crashlytics Investigations Guide",
+    description:
+      "Guides the coding agent when investigating bugs reported in Crashlytics issues, including procedures for diagnosing and fixing crashes.",
+  },
+  async (uri) => {
+    return {
+      contents: [{ uri, type: "text", text: RESOURCE_CONTENT }],
     };
   },
 );

src/mcp/resources/guides/crashlytics_issues.ts

@@ -1,20 +1,6 @@
 import { resource } from "../../resource";
 
-export const crashlytics_issues = resource(
-  {
-    uri: "firebase://guides/crashlytics/issues",
-    name: "crashlytics_issues_guide",
-    title: "Firebase Crashlytics Issues Guide",
-    description:
-      "Guides the coding agent when working with Crashlytics issues, including prioritization rules and procedures for diagnosing and fixing crashes. ",
-  },
-  async (uri) => {
-    return {
-      contents: [
-        {
-          uri,
-          type: "text",
-          text: `
+const RESOURCE_CONTENT = `
 ### How to Display Issues
 
 When displaying a list of issues, favor the following format:
@@ -28,11 +14,11 @@ When displaying a list of issues, favor the following format:
 
 Follow these steps to fetch issues and prioritize them.
 
-  1. Use the 'crashlytics_get_top_issues' tool to fetch up to 20 issues.
+  1. Use the 'crashlytics_get_report' tool to fetch the 'topIssues' report.
     1a. Analyze the user's query and apply the appropriate filters. Use the information in the [Firebase Crashlytics Reports Guide](firebase://guides/crashlytics/reports) to further construct appropriate report requests.
     1b. If the user asks for crashes, then set the *issueErrorType* filter to *FATAL*.
     1c. If the user asks about a particular time range, then set both the *intervalStartTime* and *intervalEndTime*.
-  2. Use the 'crashlytics_get_top_versions' tool to fetch the top versions for this app.
+  2. Use the 'crashlytics_get_report' tool to fetch the 'topVersions' for this app.
   3. If the user instructions include statements about prioritization, use those instructions.
   4. If the user instructions do not include statements about prioritization, then prioritize the returned issues using the following criteria:
     4a. The app versions for the issue include the most recent version of the app.
@@ -41,9 +27,19 @@ Follow these steps to fetch issues and prioritize them.
   5. Return the top 5 issues, with a brief description each in a numerical list with the recommended format.
     5a. Describe the rationale for the prioritization order.
   6. Ask the user if they would like to diagnose and fix any of the issues presented before taking any action.
-`.trim(),
-        },
-      ],
+`.trim();
+
+export const crashlytics_issues = resource(
+  {
+    uri: "firebase://guides/crashlytics/issues",
+    name: "crashlytics_issues_guide",
+    title: "Firebase Crashlytics Issues Guide",
+    description:
+      "Guides the coding agent when working with Crashlytics issues, including prioritization rules and procedures for diagnosing and fixing crashes. ",
+  },
+  async (uri) => {
+    return {
+      contents: [{ uri, type: "text", text: RESOURCE_CONTENT }],
     };
   },
 );