@gaffer-sh/mcp 0.2.1 → 0.3.0

package/dist/index.js

@@ -6,6 +6,12 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/api-client.ts
 var REQUEST_TIMEOUT_MS = 3e4;
+var MAX_RETRIES = 3;
+var INITIAL_RETRY_DELAY_MS = 1e3;
+var RETRYABLE_STATUS_CODES = [401, 429, 500, 502, 503, 504];
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function detectTokenType(token) {
   if (token.startsWith("gaf_")) {
     return "user";
@@ -42,7 +48,7 @@ var GafferApiClient = class _GafferApiClient {
     return this.tokenType === "user";
   }
   /**
-   * Make authenticated request to Gaffer API
+   * Make authenticated request to Gaffer API with retry logic
    */
   async request(endpoint, params) {
     const url = new URL(`/api/v1${endpoint}`, this.baseUrl);
@@ -53,32 +59,59 @@ var GafferApiClient = class _GafferApiClient {
         }
       }
     }
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
-    try {
-      const response = await fetch(url.toString(), {
-        method: "GET",
-        headers: {
-          "X-API-Key": this.apiKey,
-          "Accept": "application/json",
-          "User-Agent": "gaffer-mcp/0.2.0"
-        },
-        signal: controller.signal
-      });
-      if (!response.ok) {
-        const errorData = await response.json().catch(() => ({}));
-        const errorMessage = errorData.error?.message || `API request failed: ${response.status}`;
-        throw new Error(errorMessage);
-      }
-      return response.json();
-    } catch (error) {
-      if (error instanceof Error && error.name === "AbortError") {
-        throw new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`);
+    let lastError = null;
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+      try {
+        const response = await fetch(url.toString(), {
+          method: "GET",
+          headers: {
+            "X-API-Key": this.apiKey,
+            "Accept": "application/json",
+            "User-Agent": "gaffer-mcp/0.2.1"
+          },
+          signal: controller.signal
+        });
+        if (!response.ok) {
+          const errorData = await response.json().catch(() => ({}));
+          if (RETRYABLE_STATUS_CODES.includes(response.status) && attempt < MAX_RETRIES) {
+            let delayMs = INITIAL_RETRY_DELAY_MS * 2 ** attempt;
+            if (response.status === 429) {
+              const retryAfter = response.headers.get("Retry-After");
+              if (retryAfter) {
+                delayMs = Math.max(delayMs, Number.parseInt(retryAfter, 10) * 1e3);
+              }
+            }
+            lastError = new Error(errorData.error?.message || `API request failed: ${response.status}`);
+            await sleep(delayMs);
+            continue;
+          }
+          const errorMessage = errorData.error?.message || `API request failed: ${response.status}`;
+          throw new Error(errorMessage);
+        }
+        return response.json();
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error && error.name === "AbortError") {
+          lastError = new Error(`Request timed out after ${REQUEST_TIMEOUT_MS}ms`);
+          if (attempt < MAX_RETRIES) {
+            await sleep(INITIAL_RETRY_DELAY_MS * 2 ** attempt);
+            continue;
+          }
+          throw lastError;
+        }
+        if (error instanceof TypeError && attempt < MAX_RETRIES) {
+          lastError = error;
+          await sleep(INITIAL_RETRY_DELAY_MS * 2 ** attempt);
+          continue;
+        }
+        throw error;
+      } finally {
+        clearTimeout(timeoutId);
       }
-      throw error;
-    } finally {
-      clearTimeout(timeoutId);
     }
+    throw lastError || new Error("Request failed after retries");
   }
   /**
    * List all projects the user has access to
@@ -228,6 +261,7 @@ var GafferApiClient = class _GafferApiClient {
    * @param options.days - Analysis period in days (default: 30)
    * @param options.limit - Maximum number of results (default: 20)
    * @param options.framework - Filter by test framework
+   * @param options.branch - Filter by git branch name
    * @returns Slowest tests sorted by P95 duration
    */
   async getSlowestTests(options) {
@@ -240,31 +274,195 @@ var GafferApiClient = class _GafferApiClient {
     return this.request(`/user/projects/${options.projectId}/slowest-tests`, {
       ...options.days && { days: options.days },
       ...options.limit && { limit: options.limit },
-      ...options.framework && { framework: options.framework }
+      ...options.framework && { framework: options.framework },
+      ...options.branch && { branch: options.branch }
     });
   }
+  /**
+   * Get parsed test results for a specific test run
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.testRunId - The test run ID (required)
+   * @param options.status - Filter by test status ('passed', 'failed', 'skipped')
+   * @param options.limit - Maximum number of results (default: 100)
+   * @param options.offset - Pagination offset (default: 0)
+   * @returns Parsed test cases with pagination
+   */
+  async getTestRunDetails(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getTestRunDetails requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    if (!options.testRunId) {
+      throw new Error("testRunId is required");
+    }
+    return this.request(
+      `/user/projects/${options.projectId}/test-runs/${options.testRunId}/details`,
+      {
+        ...options.status && { status: options.status },
+        ...options.limit && { limit: options.limit },
+        ...options.offset && { offset: options.offset }
+      }
+    );
+  }
+  /**
+   * Compare test metrics between two commits or test runs
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.testName - The test name to compare (required)
+   * @param options.beforeCommit - Commit SHA for before (use with afterCommit)
+   * @param options.afterCommit - Commit SHA for after (use with beforeCommit)
+   * @param options.beforeRunId - Test run ID for before (use with afterRunId)
+   * @param options.afterRunId - Test run ID for after (use with beforeRunId)
+   * @returns Comparison of test metrics
+   */
+  async compareTestMetrics(options) {
+    if (!this.isUserToken()) {
+      throw new Error("compareTestMetrics requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    if (!options.testName) {
+      throw new Error("testName is required");
+    }
+    return this.request(
+      `/user/projects/${options.projectId}/compare-test`,
+      {
+        testName: options.testName,
+        ...options.beforeCommit && { beforeCommit: options.beforeCommit },
+        ...options.afterCommit && { afterCommit: options.afterCommit },
+        ...options.beforeRunId && { beforeRunId: options.beforeRunId },
+        ...options.afterRunId && { afterRunId: options.afterRunId }
+      }
+    );
+  }
 };
 
-// src/tools/get-flaky-tests.ts
+// src/tools/compare-test-metrics.ts
 import { z } from "zod";
+var compareTestMetricsInputSchema = {
+  projectId: z.string().describe("Project ID. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  testName: z.string().describe("The test name to compare. Can be the short name or full name including describe blocks."),
+  beforeCommit: z.string().optional().describe('Commit SHA for the "before" measurement. Use with afterCommit.'),
+  afterCommit: z.string().optional().describe('Commit SHA for the "after" measurement. Use with beforeCommit.'),
+  beforeRunId: z.string().optional().describe('Test run ID for the "before" measurement. Use with afterRunId.'),
+  afterRunId: z.string().optional().describe('Test run ID for the "after" measurement. Use with beforeRunId.')
+};
+var compareTestMetricsOutputSchema = {
+  testName: z.string(),
+  before: z.object({
+    testRunId: z.string(),
+    commit: z.string().nullable(),
+    branch: z.string().nullable(),
+    status: z.enum(["passed", "failed", "skipped"]),
+    durationMs: z.number().nullable(),
+    createdAt: z.string()
+  }),
+  after: z.object({
+    testRunId: z.string(),
+    commit: z.string().nullable(),
+    branch: z.string().nullable(),
+    status: z.enum(["passed", "failed", "skipped"]),
+    durationMs: z.number().nullable(),
+    createdAt: z.string()
+  }),
+  change: z.object({
+    durationMs: z.number().nullable(),
+    percentChange: z.number().nullable(),
+    statusChanged: z.boolean()
+  })
+};
+async function executeCompareTestMetrics(client, input) {
+  const hasCommits = input.beforeCommit && input.afterCommit;
+  const hasRunIds = input.beforeRunId && input.afterRunId;
+  if (!hasCommits && !hasRunIds) {
+    throw new Error("Must provide either (beforeCommit + afterCommit) or (beforeRunId + afterRunId)");
+  }
+  if (hasCommits) {
+    if (input.beforeCommit.trim().length === 0 || input.afterCommit.trim().length === 0) {
+      throw new Error("beforeCommit and afterCommit must not be empty strings");
+    }
+  }
+  if (hasRunIds) {
+    if (input.beforeRunId.trim().length === 0 || input.afterRunId.trim().length === 0) {
+      throw new Error("beforeRunId and afterRunId must not be empty strings");
+    }
+  }
+  const response = await client.compareTestMetrics({
+    projectId: input.projectId,
+    testName: input.testName,
+    beforeCommit: input.beforeCommit,
+    afterCommit: input.afterCommit,
+    beforeRunId: input.beforeRunId,
+    afterRunId: input.afterRunId
+  });
+  return response;
+}
+var compareTestMetricsMetadata = {
+  name: "compare_test_metrics",
+  title: "Compare Test Metrics",
+  description: `Compare test metrics between two commits or test runs.
+
+Useful for measuring the impact of code changes on test performance or reliability.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects to find available project IDs.
+
+Parameters:
+- projectId (required): Project ID
+- testName (required): The test name to compare (short name or full name)
+- Option 1 - Compare by commit:
+  - beforeCommit: Commit SHA for "before" measurement
+  - afterCommit: Commit SHA for "after" measurement
+- Option 2 - Compare by test run:
+  - beforeRunId: Test run ID for "before" measurement
+  - afterRunId: Test run ID for "after" measurement
+
+Returns:
+- testName: The test that was compared
+- before: Metrics from the before commit/run
+  - testRunId, commit, branch, status, durationMs, createdAt
+- after: Metrics from the after commit/run
+  - testRunId, commit, branch, status, durationMs, createdAt
+- change: Calculated changes
+  - durationMs: Duration difference (negative = faster)
+  - percentChange: Percentage change (negative = improvement)
+  - statusChanged: Whether pass/fail status changed
+
+Use cases:
+- "Did my fix make this test faster?"
+- "Compare test performance between these two commits"
+- "Did this test start failing after my changes?"
+- "Show me the before/after for the slow test I optimized"
+
+Tip: Use get_test_history first to find the commit SHAs or test run IDs you want to compare.`
+};
+
+// src/tools/get-flaky-tests.ts
+import { z as z2 } from "zod";
 var getFlakyTestsInputSchema = {
-  projectId: z.string().optional().describe("Project ID to get flaky tests for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
-  threshold: z.number().min(0).max(1).optional().describe("Minimum flip rate to be considered flaky (0-1, default: 0.1 = 10%)"),
-  limit: z.number().int().min(1).max(100).optional().describe("Maximum number of flaky tests to return (default: 50)"),
-  days: z.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)")
+  projectId: z2.string().optional().describe("Project ID to get flaky tests for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  threshold: z2.number().min(0).max(1).optional().describe("Minimum flip rate to be considered flaky (0-1, default: 0.1 = 10%)"),
+  limit: z2.number().int().min(1).max(100).optional().describe("Maximum number of flaky tests to return (default: 50)"),
+  days: z2.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)")
 };
 var getFlakyTestsOutputSchema = {
-  flakyTests: z.array(z.object({
-    name: z.string(),
-    flipRate: z.number(),
-    flipCount: z.number(),
-    totalRuns: z.number(),
-    lastSeen: z.string()
+  flakyTests: z2.array(z2.object({
+    name: z2.string(),
+    flipRate: z2.number(),
+    flipCount: z2.number(),
+    totalRuns: z2.number(),
+    lastSeen: z2.string()
   })),
-  summary: z.object({
-    threshold: z.number(),
-    totalFlaky: z.number(),
-    period: z.number()
+  summary: z2.object({
+    threshold: z2.number(),
+    totalFlaky: z2.number(),
+    period: z2.number()
   })
 };
 async function executeGetFlakyTests(client, input) {
@@ -304,22 +502,22 @@ specific tests are flaky and need investigation.`
 };
 
 // src/tools/get-project-health.ts
-import { z as z2 } from "zod";
+import { z as z3 } from "zod";
 var getProjectHealthInputSchema = {
-  projectId: z2.string().optional().describe("Project ID to get health for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
-  days: z2.number().int().min(1).max(365).optional().describe("Number of days to analyze (default: 30)")
+  projectId: z3.string().optional().describe("Project ID to get health for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  days: z3.number().int().min(1).max(365).optional().describe("Number of days to analyze (default: 30)")
 };
 var getProjectHealthOutputSchema = {
-  projectName: z2.string(),
-  healthScore: z2.number(),
-  passRate: z2.number().nullable(),
-  testRunCount: z2.number(),
-  flakyTestCount: z2.number(),
-  trend: z2.enum(["up", "down", "stable"]),
-  period: z2.object({
-    days: z2.number(),
-    start: z2.string(),
-    end: z2.string()
+  projectName: z3.string(),
+  healthScore: z3.number(),
+  passRate: z3.number().nullable(),
+  testRunCount: z3.number(),
+  flakyTestCount: z3.number(),
+  trend: z3.enum(["up", "down", "stable"]),
+  period: z3.object({
+    days: z3.number(),
+    start: z3.string(),
+    end: z3.string()
   })
 };
 async function executeGetProjectHealth(client, input) {
@@ -356,22 +554,22 @@ Use this to understand the current state of your test suite.`
 };
 
 // src/tools/get-report.ts
-import { z as z3 } from "zod";
+import { z as z4 } from "zod";
 var getReportInputSchema = {
-  testRunId: z3.string().describe("The test run ID to get report files for. Use list_test_runs to find test run IDs.")
+  testRunId: z4.string().describe("The test run ID to get report files for. Use list_test_runs to find test run IDs.")
 };
 var getReportOutputSchema = {
-  testRunId: z3.string(),
-  projectId: z3.string(),
-  projectName: z3.string(),
-  resultSchema: z3.string().optional(),
-  files: z3.array(z3.object({
-    filename: z3.string(),
-    size: z3.number(),
-    contentType: z3.string(),
-    downloadUrl: z3.string()
+  testRunId: z4.string(),
+  projectId: z4.string(),
+  projectName: z4.string(),
+  resultSchema: z4.string().optional(),
+  files: z4.array(z4.object({
+    filename: z4.string(),
+    size: z4.number(),
+    contentType: z4.string(),
+    downloadUrl: z4.string()
   })),
-  urlExpiresInSeconds: z3.number().optional()
+  urlExpiresInSeconds: z4.number().optional()
 };
 async function executeGetReport(client, input) {
   const response = await client.getReport(input.testRunId);
@@ -392,52 +590,66 @@ async function executeGetReport(client, input) {
 var getReportMetadata = {
   name: "get_report",
   title: "Get Report Files",
-  description: `Get the report files for a specific test run.
+  description: `Get URLs for report files uploaded with a test run.
+
+IMPORTANT: This tool returns download URLs, not file content. You must fetch the URLs separately.
 
-Returns a list of files uploaded with the test run, including:
-- filename: The file name (e.g., "report.html", "coverage/index.html")
+Returns for each file:
+- filename: The file name (e.g., "report.html", "results.json", "junit.xml")
 - size: File size in bytes
-- contentType: MIME type (e.g., "text/html", "application/json")
-- downloadUrl: Presigned URL to download the file directly (no authentication required)
-- urlExpiresInSeconds: How long the download URLs are valid (typically 5 minutes)
+- contentType: MIME type (e.g., "text/html", "application/json", "application/xml")
+- downloadUrl: Presigned URL to download the file (valid for ~5 minutes)
 
-Common report types:
-- HTML reports (Playwright, pytest-html, Vitest UI)
-- JSON results (Jest, Vitest)
-- JUnit XML files
-- Coverage reports
+How to use the returned URLs:
 
-Use cases:
-- "Get the Playwright report for this test run"
-- "Download the coverage report"
-- "What files were uploaded with this test run?"
+1. **JSON files** (results.json, coverage.json):
+   Use WebFetch with the downloadUrl to retrieve and parse the JSON content.
+   Example: WebFetch(url=downloadUrl, prompt="Extract test results from this JSON")
+
+2. **XML files** (junit.xml, xunit.xml):
+   Use WebFetch with the downloadUrl to retrieve and parse the XML content.
+   Example: WebFetch(url=downloadUrl, prompt="Parse the test results from this JUnit XML")
 
-Note: Download URLs are presigned and expire after a few minutes. Request fresh URLs if needed.`
+3. **HTML reports** (Playwright, pytest-html, Vitest):
+   These are typically bundled React/JavaScript applications that require a browser.
+   They cannot be meaningfully parsed by WebFetch.
+   For programmatic analysis, use get_test_run_details instead.
+
+Recommendations:
+- For analyzing test results programmatically: Use get_test_run_details (returns parsed test data)
+- For JSON/XML files: Use this tool + WebFetch on the downloadUrl
+- For HTML reports: Direct users to view in browser, or use get_test_run_details
+
+Use cases:
+- "What files are in this test run?" (list available reports)
+- "Get the coverage data from this run" (then WebFetch the JSON URL)
+- "Parse the JUnit XML results" (then WebFetch the XML URL)`
 };
 
 // src/tools/get-slowest-tests.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 var getSlowestTestsInputSchema = {
-  projectId: z4.string().describe("Project ID to get slowest tests for. Required. Use list_projects to find project IDs."),
-  days: z4.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)"),
-  limit: z4.number().int().min(1).max(100).optional().describe("Maximum number of tests to return (default: 20)"),
-  framework: z4.string().optional().describe('Filter by test framework (e.g., "playwright", "vitest", "jest")')
+  projectId: z5.string().describe("Project ID to get slowest tests for. Required. Use list_projects to find project IDs."),
+  days: z5.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)"),
+  limit: z5.number().int().min(1).max(100).optional().describe("Maximum number of tests to return (default: 20)"),
+  framework: z5.string().optional().describe('Filter by test framework (e.g., "playwright", "vitest", "jest")'),
+  branch: z5.string().optional().describe('Filter by git branch name (e.g., "main", "develop")')
 };
 var getSlowestTestsOutputSchema = {
-  slowestTests: z4.array(z4.object({
-    name: z4.string(),
-    fullName: z4.string(),
-    filePath: z4.string().optional(),
-    framework: z4.string().optional(),
-    avgDurationMs: z4.number(),
-    p95DurationMs: z4.number(),
-    runCount: z4.number()
+  slowestTests: z5.array(z5.object({
+    name: z5.string(),
+    fullName: z5.string(),
+    filePath: z5.string().optional(),
+    framework: z5.string().optional(),
+    avgDurationMs: z5.number(),
+    p95DurationMs: z5.number(),
+    runCount: z5.number()
   })),
-  summary: z4.object({
-    projectId: z4.string(),
-    projectName: z4.string(),
-    period: z4.number(),
-    totalReturned: z4.number()
+  summary: z5.object({
+    projectId: z5.string(),
+    projectName: z5.string(),
+    period: z5.number(),
+    totalReturned: z5.number()
   })
 };
 async function executeGetSlowestTests(client, input) {
@@ -445,7 +657,8 @@ async function executeGetSlowestTests(client, input) {
     projectId: input.projectId,
     days: input.days,
     limit: input.limit,
-    framework: input.framework
+    framework: input.framework,
+    branch: input.branch
   });
   return {
     slowestTests: response.slowestTests.map((test) => ({
@@ -473,6 +686,7 @@ Parameters:
 - days (optional): Analysis period in days (default: 30, max: 365)
 - limit (optional): Max tests to return (default: 20, max: 100)
 - framework (optional): Filter by framework (e.g., "playwright", "vitest")
+- branch (optional): Filter by git branch (e.g., "main", "develop")
 
 Returns:
 - List of slowest tests with:
@@ -488,32 +702,33 @@ Returns:
 Use cases:
 - "Which tests are slowing down my CI pipeline?"
 - "Find the slowest Playwright tests to optimize"
-- "Show me e2e tests taking over 30 seconds"`
+- "Show me e2e tests taking over 30 seconds"
+- "What are the slowest tests on the main branch?"`
 };
 
 // src/tools/get-test-history.ts
-import { z as z5 } from "zod";
+import { z as z6 } from "zod";
 var getTestHistoryInputSchema = {
-  projectId: z5.string().optional().describe("Project ID to get test history for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
-  testName: z5.string().optional().describe("Exact test name to search for"),
-  filePath: z5.string().optional().describe("File path containing the test"),
-  limit: z5.number().int().min(1).max(100).optional().describe("Maximum number of results (default: 20)")
+  projectId: z6.string().optional().describe("Project ID to get test history for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  testName: z6.string().optional().describe("Exact test name to search for"),
+  filePath: z6.string().optional().describe("File path containing the test"),
+  limit: z6.number().int().min(1).max(100).optional().describe("Maximum number of results (default: 20)")
 };
 var getTestHistoryOutputSchema = {
-  history: z5.array(z5.object({
-    testRunId: z5.string(),
-    createdAt: z5.string(),
-    branch: z5.string().optional(),
-    commitSha: z5.string().optional(),
-    status: z5.enum(["passed", "failed", "skipped", "pending"]),
-    durationMs: z5.number(),
-    message: z5.string().optional()
+  history: z6.array(z6.object({
+    testRunId: z6.string(),
+    createdAt: z6.string(),
+    branch: z6.string().optional(),
+    commitSha: z6.string().optional(),
+    status: z6.enum(["passed", "failed", "skipped", "pending"]),
+    durationMs: z6.number(),
+    message: z6.string().optional()
   })),
-  summary: z5.object({
-    totalRuns: z5.number(),
-    passedRuns: z5.number(),
-    failedRuns: z5.number(),
-    passRate: z5.number().nullable()
+  summary: z6.object({
+    totalRuns: z6.number(),
+    passedRuns: z6.number(),
+    failedRuns: z6.number(),
+    passRate: z6.number().nullable()
   })
 };
 async function executeGetTestHistory(client, input) {
@@ -567,24 +782,108 @@ Returns:
 Use this to investigate flaky tests or understand test stability.`
 };
 
+// src/tools/get-test-run-details.ts
+import { z as z7 } from "zod";
+var getTestRunDetailsInputSchema = {
+  testRunId: z7.string().describe("The test run ID to get details for. Use list_test_runs to find test run IDs."),
+  projectId: z7.string().describe("Project ID the test run belongs to. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  status: z7.enum(["passed", "failed", "skipped"]).optional().describe("Filter tests by status. Returns only tests matching this status."),
+  limit: z7.number().int().min(1).max(500).optional().describe("Maximum number of tests to return (default: 100, max: 500)"),
+  offset: z7.number().int().min(0).optional().describe("Number of tests to skip for pagination (default: 0)")
+};
+var getTestRunDetailsOutputSchema = {
+  testRunId: z7.string(),
+  summary: z7.object({
+    passed: z7.number(),
+    failed: z7.number(),
+    skipped: z7.number(),
+    total: z7.number()
+  }),
+  tests: z7.array(z7.object({
+    name: z7.string(),
+    fullName: z7.string(),
+    status: z7.enum(["passed", "failed", "skipped"]),
+    durationMs: z7.number().nullable(),
+    filePath: z7.string().nullable(),
+    error: z7.string().nullable()
+  })),
+  pagination: z7.object({
+    total: z7.number(),
+    limit: z7.number(),
+    offset: z7.number(),
+    hasMore: z7.boolean()
+  })
+};
+async function executeGetTestRunDetails(client, input) {
+  const response = await client.getTestRunDetails({
+    projectId: input.projectId,
+    testRunId: input.testRunId,
+    status: input.status,
+    limit: input.limit,
+    offset: input.offset
+  });
+  return {
+    testRunId: response.testRunId,
+    summary: response.summary,
+    tests: response.tests,
+    pagination: response.pagination
+  };
+}
+var getTestRunDetailsMetadata = {
+  name: "get_test_run_details",
+  title: "Get Test Run Details",
+  description: `Get parsed test results for a specific test run.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects to find available project IDs, and list_test_runs to find test run IDs.
+
+Parameters:
+- testRunId (required): The test run ID to get details for
+- projectId (required): Project ID the test run belongs to
+- status (optional): Filter by test status: "passed", "failed", or "skipped"
+- limit (optional): Max tests to return (default: 100, max: 500)
+- offset (optional): Pagination offset (default: 0)
+
+Returns:
+- testRunId: The test run ID
+- summary: Overall counts (passed, failed, skipped, total)
+- tests: Array of individual test results with:
+  - name: Short test name
+  - fullName: Full test name including describe blocks
+  - status: Test status (passed, failed, skipped)
+  - durationMs: Test duration in milliseconds (null if not recorded)
+  - filePath: Test file path (null if not recorded)
+  - error: Error message for failed tests (null otherwise)
+- pagination: Pagination info (total, limit, offset, hasMore)
+
+Use cases:
+- "Show me all failed tests from this test run"
+- "Get the test results from commit abc123"
+- "List tests that took the longest in this run"
+- "Find tests with errors in the auth module"
+
+Note: For aggregate analytics like flaky test detection or duration trends,
+use get_test_history, get_flaky_tests, or get_slowest_tests instead.`
+};
+
 // src/tools/list-projects.ts
-import { z as z6 } from "zod";
+import { z as z8 } from "zod";
 var listProjectsInputSchema = {
-  organizationId: z6.string().optional().describe("Filter by organization ID (optional)"),
-  limit: z6.number().int().min(1).max(100).optional().describe("Maximum number of projects to return (default: 50)")
+  organizationId: z8.string().optional().describe("Filter by organization ID (optional)"),
+  limit: z8.number().int().min(1).max(100).optional().describe("Maximum number of projects to return (default: 50)")
 };
 var listProjectsOutputSchema = {
-  projects: z6.array(z6.object({
-    id: z6.string(),
-    name: z6.string(),
-    description: z6.string().nullable().optional(),
-    organization: z6.object({
-      id: z6.string(),
-      name: z6.string(),
-      slug: z6.string()
+  projects: z8.array(z8.object({
+    id: z8.string(),
+    name: z8.string(),
+    description: z8.string().nullable().optional(),
+    organization: z8.object({
+      id: z8.string(),
+      name: z8.string(),
+      slug: z8.string()
     })
   })),
-  total: z6.number()
+  total: z8.number()
 };
 async function executeListProjects(client, input) {
   const response = await client.listProjects({
@@ -613,28 +912,28 @@ Requires a user API Key (gaf_). Get one from Account Settings in the Gaffer dash
 };
 
 // src/tools/list-test-runs.ts
-import { z as z7 } from "zod";
+import { z as z9 } from "zod";
 var listTestRunsInputSchema = {
-  projectId: z7.string().optional().describe("Project ID to list test runs for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
-  commitSha: z7.string().optional().describe("Filter by commit SHA (exact or prefix match)"),
-  branch: z7.string().optional().describe("Filter by branch name"),
-  status: z7.enum(["passed", "failed"]).optional().describe('Filter by status: "passed" (no failures) or "failed" (has failures)'),
-  limit: z7.number().int().min(1).max(100).optional().describe("Maximum number of test runs to return (default: 20)")
+  projectId: z9.string().optional().describe("Project ID to list test runs for. Required when using a user API Key (gaf_). Use list_projects to find project IDs."),
+  commitSha: z9.string().optional().describe("Filter by commit SHA (exact or prefix match)"),
+  branch: z9.string().optional().describe("Filter by branch name"),
+  status: z9.enum(["passed", "failed"]).optional().describe('Filter by status: "passed" (no failures) or "failed" (has failures)'),
+  limit: z9.number().int().min(1).max(100).optional().describe("Maximum number of test runs to return (default: 20)")
 };
 var listTestRunsOutputSchema = {
-  testRuns: z7.array(z7.object({
-    id: z7.string(),
-    commitSha: z7.string().optional(),
-    branch: z7.string().optional(),
-    passedCount: z7.number(),
-    failedCount: z7.number(),
-    skippedCount: z7.number(),
-    totalCount: z7.number(),
-    createdAt: z7.string()
+  testRuns: z9.array(z9.object({
+    id: z9.string(),
+    commitSha: z9.string().optional(),
+    branch: z9.string().optional(),
+    passedCount: z9.number(),
+    failedCount: z9.number(),
+    skippedCount: z9.number(),
+    totalCount: z9.number(),
+    createdAt: z9.string()
   })),
-  pagination: z7.object({
-    total: z7.number(),
-    hasMore: z7.boolean()
+  pagination: z9.object({
+    total: z9.number(),
+    hasMore: z9.boolean()
   })
 };
 async function executeListTestRuns(client, input) {
@@ -691,6 +990,23 @@ Use cases:
 };
 
 // src/index.ts
+function logError(toolName, error) {
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const message = error instanceof Error ? error.message : "Unknown error";
+  const stack = error instanceof Error ? error.stack : void 0;
+  console.error(`[${timestamp}] [gaffer-mcp] ${toolName} failed: ${message}`);
+  if (stack) {
+    console.error(stack);
+  }
+}
+function handleToolError(toolName, error) {
+  logError(toolName, error);
+  const message = error instanceof Error ? error.message : "Unknown error";
+  return {
+    content: [{ type: "text", text: `Error: ${message}` }],
+    isError: true
+  };
+}
 async function main() {
   const apiKey = process.env.GAFFER_API_KEY;
   if (!apiKey) {
@@ -733,11 +1049,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(getProjectHealthMetadata.name, error);
       }
     }
   );
@@ -757,11 +1069,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(getTestHistoryMetadata.name, error);
       }
     }
   );
@@ -781,11 +1089,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(getFlakyTestsMetadata.name, error);
       }
     }
   );
@@ -805,11 +1109,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(listTestRunsMetadata.name, error);
       }
     }
   );
@@ -829,11 +1129,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(listProjectsMetadata.name, error);
       }
     }
   );
@@ -853,11 +1149,7 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
-        return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
-        };
+        return handleToolError(getReportMetadata.name, error);
       }
     }
   );
@@ -877,11 +1169,47 @@ async function main() {
           structuredContent: output
         };
       } catch (error) {
-        const message = error instanceof Error ? error.message : "Unknown error";
+        return handleToolError(getSlowestTestsMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    getTestRunDetailsMetadata.name,
+    {
+      title: getTestRunDetailsMetadata.title,
+      description: getTestRunDetailsMetadata.description,
+      inputSchema: getTestRunDetailsInputSchema,
+      outputSchema: getTestRunDetailsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetTestRunDetails(client, input);
         return {
-          content: [{ type: "text", text: `Error: ${message}` }],
-          isError: true
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
         };
+      } catch (error) {
+        return handleToolError(getTestRunDetailsMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    compareTestMetricsMetadata.name,
+    {
+      title: compareTestMetricsMetadata.title,
+      description: compareTestMetricsMetadata.description,
+      inputSchema: compareTestMetricsInputSchema,
+      outputSchema: compareTestMetricsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeCompareTestMetrics(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(compareTestMetricsMetadata.name, error);
       }
     }
   );

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gaffer-sh/mcp",
   "type": "module",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "MCP server for Gaffer test history - give your AI assistant memory of your tests",
   "license": "MIT",
   "author": "Gaffer <hello@gaffer.sh>",