@gaffer-sh/mcp 0.3.0 → 0.4.1

package/README.md

@@ -4,11 +4,12 @@ MCP (Model Context Protocol) server for [Gaffer](https://gaffer.sh) - give your
 
 ## What is this?
 
-This MCP server connects AI coding assistants like Claude Code and Cursor to your Gaffer test history. It allows AI to:
+This MCP server connects AI coding assistants like Claude Code and Cursor to your Gaffer test history and coverage data. It allows AI to:
 
 - Check your project's test health (pass rate, flaky tests, trends)
 - Look up the history of specific tests to understand stability
 - Get context about test failures when debugging
+- Analyze code coverage and identify untested areas
 - Browse all your projects (with user API Keys)
 - Access test report files (HTML reports, coverage, etc.)
 
@@ -17,20 +18,6 @@ This MCP server connects AI coding assistants like Claude Code and Cursor to you
 1. A [Gaffer](https://gaffer.sh) account with test results uploaded
 2. An API Key from Account Settings > API Keys
 
-## Authentication
-
-The MCP server supports two types of authentication:
-
-### User API Keys (Recommended)
-
-User API Keys (`gaf_` prefix) provide read-only access to all projects across your organizations. This is the recommended approach as it allows your AI assistant to work across multiple projects.
-
-Get your API Key from: **Account Settings > API Keys**
-
-### Project Upload Tokens (Legacy)
-
-Project Upload Tokens (`gfr_` prefix) are designed for uploading test results and only provide access to a single project. While still supported for backward compatibility, user API Keys are preferred for the MCP server.
-
 ## Setup
 
 ### Claude Code
@@ -71,144 +58,197 @@ Add to `.cursor/mcp.json` in your project:
 
 ## Available Tools
 
-### `list_projects`
+### Project & Test Run Tools
 
-List all projects you have access to. **Requires a user API Key (`gaf_`).**
+| Tool | Description |
+|------|-------------|
+| `list_projects` | List all projects you have access to |
+| `get_project_health` | Get health metrics (pass rate, flaky count, trends) |
+| `list_test_runs` | List recent test runs with optional filtering |
+| `get_test_run_details` | Get parsed test results for a specific test run |
+| `get_report` | Get report file URLs for a test run |
+| `get_report_browser_url` | Get a browser-navigable URL for viewing reports |
 
-**Input:**
-- `organizationId` (optional): Filter by organization
-- `limit` (optional): Max results (default: 50)
+### Test Analysis Tools
 
-**Returns:**
-- List of projects with IDs, names, and organization info
+| Tool | Description |
+|------|-------------|
+| `get_test_history` | Get pass/fail history for a specific test |
+| `get_flaky_tests` | Get tests with high flip rates (pass↔fail) |
+| `get_slowest_tests` | Get slowest tests by P95 duration |
+| `compare_test_metrics` | Compare test performance between commits |
 
-**Example prompt:** "What projects do I have in Gaffer?"
+### Coverage Tools
 
-### `get_project_health`
+| Tool | Description |
+|------|-------------|
+| `get_coverage_summary` | Get overall coverage metrics and trends |
+| `get_coverage_for_file` | Get coverage for specific files or paths |
+| `get_untested_files` | Get files below a coverage threshold |
+| `find_uncovered_failure_areas` | Find files with low coverage AND test failures |
 
-Get the health metrics for a project.
+## Tool Details
 
-**Input:**
-- `projectId` (required with user API Keys): Project ID from `list_projects`
-- `days` (optional): Number of days to analyze (default: 30)
+### `list_projects`
 
-**Returns:**
-- Health score (0-100)
-- Pass rate percentage
-- Number of test runs
-- Flaky test count
-- Trend (up/down/stable)
+List all projects you have access to.
 
-**Example prompt:** "What's the health of my test suite?"
+- **Input:** `organizationId` (optional), `limit` (optional, default: 50)
+- **Returns:** List of projects with IDs, names, and organization info
+- **Example:** "What projects do I have in Gaffer?"
 
-### `get_test_history`
+### `get_project_health`
 
-Get the pass/fail history for a specific test.
+Get the health metrics for a project.
 
-**Input:**
-- `projectId` (required with user API Keys): Project ID from `list_projects`
-- `testName`: Exact test name to search for (one of testName or filePath required)
-- `filePath`: File path containing the test (one of testName or filePath required)
-- `limit` (optional): Max results (default: 20)
+- **Input:** `projectId` (required), `days` (optional, default: 30)
+- **Returns:** Health score (0-100), pass rate, test run count, flaky test count, trend
+- **Example:** "What's the health of my test suite?"
+
+### `get_test_history`
 
-**Returns:**
-- History of test runs with pass/fail status
-- Duration of each run
-- Branch and commit info
-- Error messages for failures
-- Summary statistics
+Get the pass/fail history for a specific test.
 
-**Example prompts:**
-- "Is the login test flaky? Check its history"
-- "Show me the history for tests in auth.test.ts"
+- **Input:** `projectId` (required), `testName` or `filePath` (one required), `limit` (optional)
+- **Returns:** History of runs with status, duration, branch, commit, errors
+- **Example:** "Is the login test flaky? Check its history"
 
 ### `get_flaky_tests`
 
 Get the list of flaky tests in a project.
 
-**Input:**
-- `projectId` (required with user API Keys): Project ID from `list_projects`
-- `threshold` (optional): Minimum flip rate to be considered flaky (0-1, default: 0.1)
-- `limit` (optional): Max results (default: 50)
-- `days` (optional): Analysis period in days (default: 30)
-
-**Returns:**
-- List of flaky tests with flip rates
-- Number of status transitions
-- Total runs analyzed
-- When each test last ran
-
-**Example prompts:**
-- "Which tests are flaky in my project?"
-- "Show me the most unstable tests"
+- **Input:** `projectId` (required), `threshold` (optional, default: 0.1), `days` (optional), `limit` (optional)
+- **Returns:** List of flaky tests with flip rates, transition counts, run counts
+- **Example:** "Which tests are flaky in my project?"
 
 ### `list_test_runs`
 
 List recent test runs with optional filtering.
 
-**Input:**
-- `projectId` (required with user API Keys): Project ID from `list_projects`
-- `commitSha` (optional): Filter by commit SHA (supports prefix matching)
-- `branch` (optional): Filter by branch name
-- `status` (optional): Filter by "passed" (no failures) or "failed" (has failures)
-- `limit` (optional): Max results (default: 20)
+- **Input:** `projectId` (required), `commitSha` (optional), `branch` (optional), `status` (optional), `limit` (optional)
+- **Returns:** List of test runs with pass/fail/skip counts, commit and branch info
+- **Example:** "What tests failed in the last commit?"
+
+### `get_test_run_details`
 
-**Returns:**
-- List of test runs with pass/fail/skip counts
-- Commit SHA and branch info
-- Pagination info
+Get parsed test results for a specific test run.
 
-**Example prompts:**
-- "What tests failed in the last commit?"
-- "Show me test runs on the main branch"
-- "Did any tests fail on my feature branch?"
+- **Input:** `testRunId` (required), `projectId` (required), `status` (optional filter), `limit` (optional)
+- **Returns:** Individual test results with name, status, duration, file path, errors
+- **Example:** "Show me all failed tests from this test run"
 
 ### `get_report`
 
-Get the report files for a specific test run. **Requires a user API Key (`gaf_`).**
+Get URLs for report files uploaded with a test run.
 
-**Input:**
-- `testRunId` (required): Test run ID from `list_test_runs`
+- **Input:** `testRunId` (required)
+- **Returns:** List of files with filename, size, content type, download URL
+- **Example:** "Get the Playwright report for the latest test run"
 
-**Returns:**
-- Test run ID and project info
-- Framework used (e.g., playwright, vitest)
-- List of files with:
-  - Filename (e.g., "report.html", "coverage/index.html")
-  - File size in bytes
-  - Content type (e.g., "text/html")
-  - Download URL
+### `get_report_browser_url`
 
-**Example prompts:**
-- "Get the Playwright report for the latest test run"
-- "What files were uploaded with this test run?"
-- "Show me the coverage report"
+Get a browser-navigable URL for viewing a test report.
+
+- **Input:** `projectId` (required), `testRunId` (required), `filename` (optional)
+- **Returns:** Signed URL valid for 30 minutes
+- **Example:** "Give me a link to view the test report"
 
 ### `get_slowest_tests`
 
-Get the slowest tests in a project, sorted by P95 duration. **Requires a user API Key (`gaf_`).**
-
-**Input:**
-- `projectId` (required): Project ID from `list_projects`
-- `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")
-
-**Returns:**
-- List of slowest tests with:
-  - name: Short test name
-  - fullName: Full test name including describe blocks
-  - filePath: Test file path (if available)
-  - framework: Test framework used
-  - avgDurationMs: Average duration in milliseconds
-  - p95DurationMs: 95th percentile duration
-  - runCount: Number of runs in the period
-- Summary with project info
-
-**Example prompts:**
-- "Which tests are slowing down my CI pipeline?"
-- "Find the slowest Playwright tests"
-- "Show me e2e tests that need optimization"
+Get the slowest tests in a project, sorted by P95 duration.
+
+- **Input:** `projectId` (required), `days` (optional), `limit` (optional), `framework` (optional), `branch` (optional)
+- **Returns:** List of tests with average and P95 duration, run count
+- **Example:** "Which tests are slowing down my CI pipeline?"
+
+### `compare_test_metrics`
+
+Compare test metrics between two commits or test runs.
+
+- **Input:** `projectId` (required), `testName` (required), `beforeCommit`/`afterCommit` OR `beforeRunId`/`afterRunId`
+- **Returns:** Before/after metrics with duration change and percentage
+- **Example:** "Did my fix make this test faster?"
+
+### `get_coverage_summary`
+
+Get the coverage metrics summary for a project.
+
+- **Input:** `projectId` (required), `days` (optional, default: 30)
+- **Returns:** Line/branch/function coverage percentages, trend, report count, lowest coverage files
+- **Example:** "What's our test coverage?"
+
+### `get_coverage_for_file`
+
+Get coverage metrics for specific files or paths.
+
+- **Input:** `projectId` (required), `filePath` (required - exact or partial match)
+- **Returns:** List of matching files with line/branch/function coverage
+- **Example:** "What's the coverage for our API routes?"
+
+### `get_untested_files`
+
+Get files with little or no test coverage.
+
+- **Input:** `projectId` (required), `maxCoverage` (optional, default: 10%), `limit` (optional)
+- **Returns:** List of files below threshold sorted by coverage (lowest first)
+- **Example:** "Which files have no tests?"
+
+### `find_uncovered_failure_areas`
+
+Find code areas with both low coverage AND test failures (high risk).
+
+- **Input:** `projectId` (required), `days` (optional), `coverageThreshold` (optional, default: 80%)
+- **Returns:** Risk areas ranked by score, with file path, coverage %, failure count
+- **Example:** "Where should we focus our testing efforts?"
+
+## Prioritizing Coverage Improvements
+
+When using coverage tools to improve your test suite, combine coverage data with codebase exploration for best results:
+
+### 1. Understand Code Utilization
+
+Before targeting files purely by coverage percentage, explore which code is actually critical:
+
+- **Find entry points:** Look for route definitions, event handlers, exported functions - these reveal what code actually executes in production
+- **Find heavily-imported files:** Files imported by many others are high-value targets
+- **Identify critical business logic:** Look for files handling auth, payments, data mutations, or core domain logic
+
+### 2. Prioritize by Impact
+
+Low coverage alone doesn't indicate priority. Consider:
+
+- **High utilization + low coverage = highest priority** - Code that runs frequently but lacks tests
+- **Large files with 0% coverage** - More uncovered lines means bigger impact on overall coverage
+- **Files with both failures and low coverage** - Use `find_uncovered_failure_areas` for this
+
+### 3. Use Path-Based Queries
+
+The `get_untested_files` tool may return many frontend components. For backend or specific areas:
+
+```
+# Query specific paths with get_coverage_for_file
+get_coverage_for_file(filePath="server/services")
+get_coverage_for_file(filePath="src/api")
+get_coverage_for_file(filePath="lib/core")
+```
+
+### 4. Iterative Improvement
+
+1. Get baseline with `get_coverage_summary`
+2. Identify targets with `get_coverage_for_file` on critical paths
+3. Write tests for highest-impact files
+4. Re-check coverage after CI uploads new results
+5. Repeat
+
+## Authentication
+
+### User API Keys (Recommended)
+
+User API Keys (`gaf_` prefix) provide read-only access to all projects across your organizations. Get your API Key from: **Account Settings > API Keys**
+
+### Project Upload Tokens (Legacy)
+
+Project Upload Tokens (`gfr_` prefix) are designed for uploading test results and only provide access to a single project. User API Keys are preferred for the MCP server.
 
 ## Environment Variables
 

package/dist/index.js

@@ -341,6 +341,112 @@ var GafferApiClient = class _GafferApiClient {
       }
     );
   }
+  /**
+   * Get coverage summary for a project
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.days - Analysis period in days (default: 30)
+   * @returns Coverage summary with trends and lowest coverage files
+   */
+  async getCoverageSummary(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getCoverageSummary requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    return this.request(
+      `/user/projects/${options.projectId}/coverage-summary`,
+      {
+        ...options.days && { days: options.days }
+      }
+    );
+  }
+  /**
+   * Get coverage files for a project with filtering
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.filePath - Filter to specific file path
+   * @param options.minCoverage - Minimum coverage percentage
+   * @param options.maxCoverage - Maximum coverage percentage
+   * @param options.limit - Maximum number of results
+   * @param options.offset - Pagination offset
+   * @param options.sortBy - Sort by 'path' or 'coverage'
+   * @param options.sortOrder - Sort order 'asc' or 'desc'
+   * @returns List of files with coverage data
+   */
+  async getCoverageFiles(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getCoverageFiles requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    return this.request(
+      `/user/projects/${options.projectId}/coverage/files`,
+      {
+        ...options.filePath && { filePath: options.filePath },
+        ...options.minCoverage !== void 0 && { minCoverage: options.minCoverage },
+        ...options.maxCoverage !== void 0 && { maxCoverage: options.maxCoverage },
+        ...options.limit && { limit: options.limit },
+        ...options.offset && { offset: options.offset },
+        ...options.sortBy && { sortBy: options.sortBy },
+        ...options.sortOrder && { sortOrder: options.sortOrder }
+      }
+    );
+  }
+  /**
+   * Get risk areas (files with low coverage AND test failures)
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.days - Analysis period in days (default: 30)
+   * @param options.coverageThreshold - Include files below this coverage (default: 80)
+   * @returns List of risk areas sorted by risk score
+   */
+  async getCoverageRiskAreas(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getCoverageRiskAreas requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    return this.request(
+      `/user/projects/${options.projectId}/coverage/risk-areas`,
+      {
+        ...options.days && { days: options.days },
+        ...options.coverageThreshold !== void 0 && { coverageThreshold: options.coverageThreshold }
+      }
+    );
+  }
+  /**
+   * Get a browser-navigable URL for viewing a test report
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @param options.testRunId - The test run ID (required)
+   * @param options.filename - Specific file to open (default: index.html)
+   * @returns URL with signed token for browser access
+   */
+  async getReportBrowserUrl(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getReportBrowserUrl 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}/reports/${options.testRunId}/browser-url`,
+      {
+        ...options.filename && { filename: options.filename }
+      }
+    );
+  }
 };
 
 // src/tools/compare-test-metrics.ts
@@ -443,26 +549,219 @@ Use cases:
 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
+// src/tools/find-uncovered-failure-areas.ts
 import { z as z2 } from "zod";
+var findUncoveredFailureAreasInputSchema = {
+  projectId: z2.string().describe("Project ID to analyze. Required. Use list_projects to find project IDs."),
+  days: z2.number().int().min(1).max(365).optional().describe("Number of days to analyze for test failures (default: 30)"),
+  coverageThreshold: z2.number().min(0).max(100).optional().describe("Include files with coverage below this percentage (default: 80)")
+};
+var findUncoveredFailureAreasOutputSchema = {
+  hasCoverage: z2.boolean(),
+  hasTestResults: z2.boolean(),
+  riskAreas: z2.array(z2.object({
+    filePath: z2.string(),
+    coverage: z2.number(),
+    failureCount: z2.number(),
+    riskScore: z2.number(),
+    testNames: z2.array(z2.string())
+  })),
+  message: z2.string().optional()
+};
+async function executeFindUncoveredFailureAreas(client, input) {
+  const response = await client.getCoverageRiskAreas({
+    projectId: input.projectId,
+    days: input.days,
+    coverageThreshold: input.coverageThreshold
+  });
+  return {
+    hasCoverage: response.hasCoverage,
+    hasTestResults: response.hasTestResults,
+    riskAreas: response.riskAreas,
+    message: response.message
+  };
+}
+var findUncoveredFailureAreasMetadata = {
+  name: "find_uncovered_failure_areas",
+  title: "Find Uncovered Failure Areas",
+  description: `Find areas of code that have both low coverage AND test failures.
+
+This cross-references test failures with coverage data to identify high-risk
+areas in your codebase that need attention. Files are ranked by a "risk score"
+calculated as: (100 - coverage%) \xD7 failureCount.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
+Parameters:
+- projectId: The project to analyze (required)
+- days: Analysis period for test failures (default: 30)
+- coverageThreshold: Include files below this coverage % (default: 80)
+
+Returns:
+- List of risk areas sorted by risk score (highest risk first)
+- Each area includes: file path, coverage %, failure count, risk score, test names
+
+Use this to prioritize which parts of your codebase need better test coverage.`
+};
+
+// src/tools/get-coverage-for-file.ts
+import { z as z3 } from "zod";
+var getCoverageForFileInputSchema = {
+  projectId: z3.string().describe("Project ID to get coverage for. Required. Use list_projects to find project IDs."),
+  filePath: z3.string().describe("File path to get coverage for. Can be exact path or partial match.")
+};
+var getCoverageForFileOutputSchema = {
+  hasCoverage: z3.boolean(),
+  files: z3.array(z3.object({
+    path: z3.string(),
+    lines: z3.object({
+      covered: z3.number(),
+      total: z3.number(),
+      percentage: z3.number()
+    }),
+    branches: z3.object({
+      covered: z3.number(),
+      total: z3.number(),
+      percentage: z3.number()
+    }),
+    functions: z3.object({
+      covered: z3.number(),
+      total: z3.number(),
+      percentage: z3.number()
+    })
+  })),
+  message: z3.string().optional()
+};
+async function executeGetCoverageForFile(client, input) {
+  const response = await client.getCoverageFiles({
+    projectId: input.projectId,
+    filePath: input.filePath,
+    limit: 10
+    // Return up to 10 matching files
+  });
+  return {
+    hasCoverage: response.hasCoverage,
+    files: response.files.map((f) => ({
+      path: f.path,
+      lines: f.lines,
+      branches: f.branches,
+      functions: f.functions
+    })),
+    message: response.message
+  };
+}
+var getCoverageForFileMetadata = {
+  name: "get_coverage_for_file",
+  title: "Get Coverage for File",
+  description: `Get coverage metrics for a specific file or files matching a path pattern.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
+Parameters:
+- projectId: The project to query (required)
+- filePath: File path to search for (exact or partial match)
+
+Returns:
+- Line coverage (covered/total/percentage)
+- Branch coverage (covered/total/percentage)
+- Function coverage (covered/total/percentage)
+
+This is the preferred tool for targeted coverage analysis. Use path prefixes to focus on
+specific areas of the codebase:
+- "server/services" - Backend service layer
+- "server/utils" - Backend utilities
+- "src/api" - API routes
+- "lib/core" - Core business logic
+
+Before querying, explore the codebase to identify critical paths - entry points,
+heavily-imported files, and code handling auth/payments/data mutations.
+Prioritize: high utilization + low coverage = highest impact.`
+};
+
+// src/tools/get-coverage-summary.ts
+import { z as z4 } from "zod";
+var getCoverageSummaryInputSchema = {
+  projectId: z4.string().describe("Project ID to get coverage for. Required. Use list_projects to find project IDs."),
+  days: z4.number().int().min(1).max(365).optional().describe("Number of days to analyze for trends (default: 30)")
+};
+var getCoverageSummaryOutputSchema = {
+  hasCoverage: z4.boolean(),
+  current: z4.object({
+    lines: z4.number(),
+    branches: z4.number(),
+    functions: z4.number()
+  }).optional(),
+  trend: z4.object({
+    direction: z4.enum(["up", "down", "stable"]),
+    change: z4.number()
+  }).optional(),
+  totalReports: z4.number(),
+  latestReportDate: z4.string().nullable().optional(),
+  lowestCoverageFiles: z4.array(z4.object({
+    path: z4.string(),
+    coverage: z4.number()
+  })).optional(),
+  message: z4.string().optional()
+};
+async function executeGetCoverageSummary(client, input) {
+  const response = await client.getCoverageSummary({
+    projectId: input.projectId,
+    days: input.days
+  });
+  return {
+    hasCoverage: response.hasCoverage,
+    current: response.current,
+    trend: response.trend,
+    totalReports: response.totalReports,
+    latestReportDate: response.latestReportDate,
+    lowestCoverageFiles: response.lowestCoverageFiles,
+    message: response.message
+  };
+}
+var getCoverageSummaryMetadata = {
+  name: "get_coverage_summary",
+  title: "Get Coverage Summary",
+  description: `Get the coverage metrics summary for a project.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
+Returns:
+- Current coverage percentages (lines, branches, functions)
+- Trend direction (up, down, stable) and change amount
+- Total number of coverage reports
+- Latest report date
+- Top 5 files with lowest coverage
+
+Use this to understand your project's overall test coverage health.
+
+After getting the summary, use get_coverage_for_file with path prefixes to drill into
+specific areas (e.g., "server/services", "src/api", "lib/core"). This helps identify
+high-value targets in critical code paths rather than just the files with lowest coverage.`
+};
+
+// src/tools/get-flaky-tests.ts
+import { z as z5 } from "zod";
 var getFlakyTestsInputSchema = {
-  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)")
+  projectId: z5.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: z5.number().min(0).max(1).optional().describe("Minimum flip rate to be considered flaky (0-1, default: 0.1 = 10%)"),
+  limit: z5.number().int().min(1).max(100).optional().describe("Maximum number of flaky tests to return (default: 50)"),
+  days: z5.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)")
 };
 var getFlakyTestsOutputSchema = {
-  flakyTests: z2.array(z2.object({
-    name: z2.string(),
-    flipRate: z2.number(),
-    flipCount: z2.number(),
-    totalRuns: z2.number(),
-    lastSeen: z2.string()
+  flakyTests: z5.array(z5.object({
+    name: z5.string(),
+    flipRate: z5.number(),
+    flipCount: z5.number(),
+    totalRuns: z5.number(),
+    lastSeen: z5.string()
   })),
-  summary: z2.object({
-    threshold: z2.number(),
-    totalFlaky: z2.number(),
-    period: z2.number()
+  summary: z5.object({
+    threshold: z5.number(),
+    totalFlaky: z5.number(),
+    period: z5.number()
   })
 };
 async function executeGetFlakyTests(client, input) {
@@ -502,22 +801,22 @@ specific tests are flaky and need investigation.`
 };
 
 // src/tools/get-project-health.ts
-import { z as z3 } from "zod";
+import { z as z6 } from "zod";
 var getProjectHealthInputSchema = {
-  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)")
+  projectId: z6.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: z6.number().int().min(1).max(365).optional().describe("Number of days to analyze (default: 30)")
 };
 var getProjectHealthOutputSchema = {
-  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()
+  projectName: z6.string(),
+  healthScore: z6.number(),
+  passRate: z6.number().nullable(),
+  testRunCount: z6.number(),
+  flakyTestCount: z6.number(),
+  trend: z6.enum(["up", "down", "stable"]),
+  period: z6.object({
+    days: z6.number(),
+    start: z6.string(),
+    end: z6.string()
   })
 };
 async function executeGetProjectHealth(client, input) {
@@ -553,23 +852,77 @@ Returns:
 Use this to understand the current state of your test suite.`
 };
 
+// src/tools/get-report-browser-url.ts
+import { z as z7 } from "zod";
+var getReportBrowserUrlInputSchema = {
+  projectId: z7.string().describe("Project ID the test run belongs to. Required. Use list_projects to find project IDs."),
+  testRunId: z7.string().describe("The test run ID to get the report URL for. Use list_test_runs to find test run IDs."),
+  filename: z7.string().optional().describe("Specific file to open (default: index.html or first HTML file)")
+};
+var getReportBrowserUrlOutputSchema = {
+  url: z7.string(),
+  filename: z7.string(),
+  testRunId: z7.string(),
+  expiresAt: z7.string(),
+  expiresInSeconds: z7.number()
+};
+async function executeGetReportBrowserUrl(client, input) {
+  const response = await client.getReportBrowserUrl({
+    projectId: input.projectId,
+    testRunId: input.testRunId,
+    filename: input.filename
+  });
+  return {
+    url: response.url,
+    filename: response.filename,
+    testRunId: response.testRunId,
+    expiresAt: response.expiresAt,
+    expiresInSeconds: response.expiresInSeconds
+  };
+}
+var getReportBrowserUrlMetadata = {
+  name: "get_report_browser_url",
+  title: "Get Report Browser URL",
+  description: `Get a browser-navigable URL for viewing a test report (Playwright, Vitest, etc.).
+
+Returns a signed URL that can be opened directly in a browser without requiring
+the user to log in. The URL expires after 30 minutes for security.
+
+When using a user API Key (gaf_), you must provide both projectId and testRunId.
+Use list_projects and list_test_runs to find available IDs.
+
+Parameters:
+- projectId: The project the test run belongs to (required)
+- testRunId: The test run to view (required)
+- filename: Specific file to open (optional, defaults to index.html)
+
+Returns:
+- url: Browser-navigable URL with signed token
+- filename: The file being accessed
+- expiresAt: ISO timestamp when the URL expires
+- expiresInSeconds: Time until expiration
+
+The returned URL can be shared with users who need to view the report.
+Note: URLs expire after 30 minutes for security.`
+};
+
 // src/tools/get-report.ts
-import { z as z4 } from "zod";
+import { z as z8 } from "zod";
 var getReportInputSchema = {
-  testRunId: z4.string().describe("The test run ID to get report files for. Use list_test_runs to find test run IDs.")
+  testRunId: z8.string().describe("The test run ID to get report files for. Use list_test_runs to find test run IDs.")
 };
 var getReportOutputSchema = {
-  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()
+  testRunId: z8.string(),
+  projectId: z8.string(),
+  projectName: z8.string(),
+  resultSchema: z8.string().optional(),
+  files: z8.array(z8.object({
+    filename: z8.string(),
+    size: z8.number(),
+    contentType: z8.string(),
+    downloadUrl: z8.string()
   })),
-  urlExpiresInSeconds: z4.number().optional()
+  urlExpiresInSeconds: z8.number().optional()
 };
 async function executeGetReport(client, input) {
   const response = await client.getReport(input.testRunId);
@@ -627,29 +980,29 @@ Use cases:
 };
 
 // src/tools/get-slowest-tests.ts
-import { z as z5 } from "zod";
+import { z as z9 } from "zod";
 var getSlowestTestsInputSchema = {
-  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")')
+  projectId: z9.string().describe("Project ID to get slowest tests for. Required. Use list_projects to find project IDs."),
+  days: z9.number().int().min(1).max(365).optional().describe("Analysis period in days (default: 30)"),
+  limit: z9.number().int().min(1).max(100).optional().describe("Maximum number of tests to return (default: 20)"),
+  framework: z9.string().optional().describe('Filter by test framework (e.g., "playwright", "vitest", "jest")'),
+  branch: z9.string().optional().describe('Filter by git branch name (e.g., "main", "develop")')
 };
 var getSlowestTestsOutputSchema = {
-  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()
+  slowestTests: z9.array(z9.object({
+    name: z9.string(),
+    fullName: z9.string(),
+    filePath: z9.string().optional(),
+    framework: z9.string().optional(),
+    avgDurationMs: z9.number(),
+    p95DurationMs: z9.number(),
+    runCount: z9.number()
   })),
-  summary: z5.object({
-    projectId: z5.string(),
-    projectName: z5.string(),
-    period: z5.number(),
-    totalReturned: z5.number()
+  summary: z9.object({
+    projectId: z9.string(),
+    projectName: z9.string(),
+    period: z9.number(),
+    totalReturned: z9.number()
   })
 };
 async function executeGetSlowestTests(client, input) {
@@ -707,28 +1060,28 @@ Use cases:
 };
 
 // src/tools/get-test-history.ts
-import { z as z6 } from "zod";
+import { z as z10 } from "zod";
 var getTestHistoryInputSchema = {
-  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)")
+  projectId: z10.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: z10.string().optional().describe("Exact test name to search for"),
+  filePath: z10.string().optional().describe("File path containing the test"),
+  limit: z10.number().int().min(1).max(100).optional().describe("Maximum number of results (default: 20)")
 };
 var getTestHistoryOutputSchema = {
-  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()
+  history: z10.array(z10.object({
+    testRunId: z10.string(),
+    createdAt: z10.string(),
+    branch: z10.string().optional(),
+    commitSha: z10.string().optional(),
+    status: z10.enum(["passed", "failed", "skipped", "pending"]),
+    durationMs: z10.number(),
+    message: z10.string().optional()
   })),
-  summary: z6.object({
-    totalRuns: z6.number(),
-    passedRuns: z6.number(),
-    failedRuns: z6.number(),
-    passRate: z6.number().nullable()
+  summary: z10.object({
+    totalRuns: z10.number(),
+    passedRuns: z10.number(),
+    failedRuns: z10.number(),
+    passRate: z10.number().nullable()
   })
 };
 async function executeGetTestHistory(client, input) {
@@ -783,35 +1136,35 @@ Use this to investigate flaky tests or understand test stability.`
 };
 
 // src/tools/get-test-run-details.ts
-import { z as z7 } from "zod";
+import { z as z11 } 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)")
+  testRunId: z11.string().describe("The test run ID to get details for. Use list_test_runs to find test run IDs."),
+  projectId: z11.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: z11.enum(["passed", "failed", "skipped"]).optional().describe("Filter tests by status. Returns only tests matching this status."),
+  limit: z11.number().int().min(1).max(500).optional().describe("Maximum number of tests to return (default: 100, max: 500)"),
+  offset: z11.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()
+  testRunId: z11.string(),
+  summary: z11.object({
+    passed: z11.number(),
+    failed: z11.number(),
+    skipped: z11.number(),
+    total: z11.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()
+  tests: z11.array(z11.object({
+    name: z11.string(),
+    fullName: z11.string(),
+    status: z11.enum(["passed", "failed", "skipped"]),
+    durationMs: z11.number().nullable(),
+    filePath: z11.string().nullable(),
+    error: z11.string().nullable()
   })),
-  pagination: z7.object({
-    total: z7.number(),
-    limit: z7.number(),
-    offset: z7.number(),
-    hasMore: z7.boolean()
+  pagination: z11.object({
+    total: z11.number(),
+    limit: z11.number(),
+    offset: z11.number(),
+    hasMore: z11.boolean()
   })
 };
 async function executeGetTestRunDetails(client, input) {
@@ -866,24 +1219,107 @@ 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/get-untested-files.ts
+import { z as z12 } from "zod";
+var getUntestedFilesInputSchema = {
+  projectId: z12.string().describe("Project ID to analyze. Required. Use list_projects to find project IDs."),
+  maxCoverage: z12.number().min(0).max(100).optional().describe('Maximum coverage percentage to include (default: 10 for "untested")'),
+  limit: z12.number().int().min(1).max(100).optional().describe("Maximum number of files to return (default: 20)")
+};
+var getUntestedFilesOutputSchema = {
+  hasCoverage: z12.boolean(),
+  files: z12.array(z12.object({
+    path: z12.string(),
+    lines: z12.object({
+      covered: z12.number(),
+      total: z12.number(),
+      percentage: z12.number()
+    }),
+    branches: z12.object({
+      covered: z12.number(),
+      total: z12.number(),
+      percentage: z12.number()
+    }),
+    functions: z12.object({
+      covered: z12.number(),
+      total: z12.number(),
+      percentage: z12.number()
+    })
+  })),
+  totalCount: z12.number(),
+  message: z12.string().optional()
+};
+async function executeGetUntestedFiles(client, input) {
+  const maxCoverage = input.maxCoverage ?? 10;
+  const limit = input.limit ?? 20;
+  const response = await client.getCoverageFiles({
+    projectId: input.projectId,
+    maxCoverage,
+    limit,
+    sortBy: "coverage",
+    sortOrder: "asc"
+    // Lowest coverage first
+  });
+  return {
+    hasCoverage: response.hasCoverage,
+    files: response.files.map((f) => ({
+      path: f.path,
+      lines: f.lines,
+      branches: f.branches,
+      functions: f.functions
+    })),
+    totalCount: response.pagination.total,
+    message: response.message
+  };
+}
+var getUntestedFilesMetadata = {
+  name: "get_untested_files",
+  title: "Get Untested Files",
+  description: `Get files with little or no test coverage.
+
+Returns files sorted by coverage percentage (lowest first), filtered
+to only include files below a coverage threshold.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
+Parameters:
+- projectId: The project to analyze (required)
+- maxCoverage: Include files with coverage at or below this % (default: 10)
+- limit: Maximum number of files to return (default: 20, max: 100)
+
+Returns:
+- List of files sorted by coverage (lowest first)
+- Each file includes line/branch/function coverage metrics
+- Total count of files matching the criteria
+
+IMPORTANT: Results may be dominated by certain file types (e.g., UI components) that are
+numerous but not necessarily the highest priority. For targeted analysis of specific code
+areas (backend, services, utilities), use get_coverage_for_file with path prefixes instead.
+
+To prioritize effectively, explore the codebase to understand which code is heavily utilized
+(entry points, frequently-imported files, critical business logic) and then query coverage
+for those specific paths.`
+};
+
 // src/tools/list-projects.ts
-import { z as z8 } from "zod";
+import { z as z13 } from "zod";
 var listProjectsInputSchema = {
-  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)")
+  organizationId: z13.string().optional().describe("Filter by organization ID (optional)"),
+  limit: z13.number().int().min(1).max(100).optional().describe("Maximum number of projects to return (default: 50)")
 };
 var listProjectsOutputSchema = {
-  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()
+  projects: z13.array(z13.object({
+    id: z13.string(),
+    name: z13.string(),
+    description: z13.string().nullable().optional(),
+    organization: z13.object({
+      id: z13.string(),
+      name: z13.string(),
+      slug: z13.string()
     })
   })),
-  total: z8.number()
+  total: z13.number()
 };
 async function executeListProjects(client, input) {
   const response = await client.listProjects({
@@ -912,28 +1348,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 z9 } from "zod";
+import { z as z14 } from "zod";
 var listTestRunsInputSchema = {
-  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)")
+  projectId: z14.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: z14.string().optional().describe("Filter by commit SHA (exact or prefix match)"),
+  branch: z14.string().optional().describe("Filter by branch name"),
+  status: z14.enum(["passed", "failed"]).optional().describe('Filter by status: "passed" (no failures) or "failed" (has failures)'),
+  limit: z14.number().int().min(1).max(100).optional().describe("Maximum number of test runs to return (default: 20)")
 };
 var listTestRunsOutputSchema = {
-  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()
+  testRuns: z14.array(z14.object({
+    id: z14.string(),
+    commitSha: z14.string().optional(),
+    branch: z14.string().optional(),
+    passedCount: z14.number(),
+    failedCount: z14.number(),
+    skippedCount: z14.number(),
+    totalCount: z14.number(),
+    createdAt: z14.string()
   })),
-  pagination: z9.object({
-    total: z9.number(),
-    hasMore: z9.boolean()
+  pagination: z14.object({
+    total: z14.number(),
+    hasMore: z14.boolean()
   })
 };
 async function executeListTestRuns(client, input) {
@@ -1029,10 +1465,33 @@ async function main() {
     process.exit(1);
   }
   const client = GafferApiClient.fromEnv();
-  const server = new McpServer({
-    name: "gaffer",
-    version: "0.1.0"
-  });
+  const server = new McpServer(
+    {
+      name: "gaffer",
+      version: "0.1.0"
+    },
+    {
+      instructions: `Gaffer provides test analytics and coverage data for your projects.
+
+## Coverage Analysis Best Practices
+
+When helping users improve test coverage, combine coverage data with codebase exploration:
+
+1. **Understand code utilization first**: Before targeting files by coverage percentage, explore which code is critical:
+   - Find entry points (route definitions, event handlers, exported functions)
+   - Find heavily-imported files (files imported by many others are high-value targets)
+   - Identify critical business logic (auth, payments, data mutations)
+
+2. **Prioritize by impact**: Low coverage alone doesn't indicate priority. Consider:
+   - High utilization + low coverage = highest priority
+   - Large files with 0% coverage have bigger impact than small files
+   - Use find_uncovered_failure_areas for files with both low coverage AND test failures
+
+3. **Use path-based queries**: The get_untested_files tool may return many files of a certain type (e.g., UI components). For targeted analysis, use get_coverage_for_file with path prefixes to focus on specific areas of the codebase.
+
+4. **Iterate**: Get baseline \u2192 identify targets \u2192 write tests \u2192 re-check coverage after CI uploads new results.`
+    }
+  );
   server.registerTool(
     getProjectHealthMetadata.name,
     {
@@ -1213,6 +1672,106 @@ async function main() {
       }
     }
   );
+  server.registerTool(
+    getCoverageSummaryMetadata.name,
+    {
+      title: getCoverageSummaryMetadata.title,
+      description: getCoverageSummaryMetadata.description,
+      inputSchema: getCoverageSummaryInputSchema,
+      outputSchema: getCoverageSummaryOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetCoverageSummary(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(getCoverageSummaryMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    getCoverageForFileMetadata.name,
+    {
+      title: getCoverageForFileMetadata.title,
+      description: getCoverageForFileMetadata.description,
+      inputSchema: getCoverageForFileInputSchema,
+      outputSchema: getCoverageForFileOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetCoverageForFile(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(getCoverageForFileMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    findUncoveredFailureAreasMetadata.name,
+    {
+      title: findUncoveredFailureAreasMetadata.title,
+      description: findUncoveredFailureAreasMetadata.description,
+      inputSchema: findUncoveredFailureAreasInputSchema,
+      outputSchema: findUncoveredFailureAreasOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeFindUncoveredFailureAreas(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(findUncoveredFailureAreasMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    getUntestedFilesMetadata.name,
+    {
+      title: getUntestedFilesMetadata.title,
+      description: getUntestedFilesMetadata.description,
+      inputSchema: getUntestedFilesInputSchema,
+      outputSchema: getUntestedFilesOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetUntestedFiles(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(getUntestedFilesMetadata.name, error);
+      }
+    }
+  );
+  server.registerTool(
+    getReportBrowserUrlMetadata.name,
+    {
+      title: getReportBrowserUrlMetadata.title,
+      description: getReportBrowserUrlMetadata.description,
+      inputSchema: getReportBrowserUrlInputSchema,
+      outputSchema: getReportBrowserUrlOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetReportBrowserUrl(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        return handleToolError(getReportBrowserUrlMetadata.name, error);
+      }
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

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