@gaffer-sh/mcp 0.1.0 → 0.2.0

package/README.md

@@ -9,11 +9,27 @@ This MCP server connects AI coding assistants like Claude Code and Cursor to you
 - 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
+- Browse all your projects (with user API Keys)
+- Access test report files (HTML reports, coverage, etc.)
 
 ## Prerequisites
 
 1. A [Gaffer](https://gaffer.sh) account with test results uploaded
-2. An API key from your project settings
+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
 
@@ -28,7 +44,7 @@ Add to your Claude Code settings (`~/.claude.json` or project `.claude/settings.
       "command": "npx",
       "args": ["-y", "@gaffer-sh/mcp"],
       "env": {
-        "GAFFER_API_KEY": "gfr_your_api_key_here"
+        "GAFFER_API_KEY": "gaf_your_api_key_here"
       }
     }
   }
@@ -46,7 +62,7 @@ Add to `.cursor/mcp.json` in your project:
       "command": "npx",
       "args": ["-y", "@gaffer-sh/mcp"],
       "env": {
-        "GAFFER_API_KEY": "gfr_your_api_key_here"
+        "GAFFER_API_KEY": "gaf_your_api_key_here"
       }
     }
   }
@@ -55,11 +71,25 @@ Add to `.cursor/mcp.json` in your project:
 
 ## Available Tools
 
+### `list_projects`
+
+List all projects you have access to. **Requires a user API Key (`gaf_`).**
+
+**Input:**
+- `organizationId` (optional): Filter by organization
+- `limit` (optional): Max results (default: 50)
+
+**Returns:**
+- List of projects with IDs, names, and organization info
+
+**Example prompt:** "What projects do I have in Gaffer?"
+
 ### `get_project_health`
 
-Get the health metrics for your project.
+Get the health metrics for a project.
 
 **Input:**
+- `projectId` (required with user API Keys): Project ID from `list_projects`
 - `days` (optional): Number of days to analyze (default: 30)
 
 **Returns:**
@@ -75,9 +105,10 @@ Get the health metrics for your project.
 
 Get the pass/fail history for a specific test.
 
-**Input (one required):**
-- `testName`: Exact test name to search for
-- `filePath`: File path containing the test
+**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)
 
 **Returns:**
@@ -93,9 +124,10 @@ Get the pass/fail history for a specific test.
 
 ### `get_flaky_tests`
 
-Get the list of flaky tests in your project.
+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)
@@ -114,11 +146,12 @@ Get the list of flaky tests in your project.
 
 List recent test runs with optional filtering.
 
-**Input (all optional):**
-- `commitSha`: Filter by commit SHA (supports prefix matching)
-- `branch`: Filter by branch name
-- `status`: Filter by "passed" (no failures) or "failed" (has failures)
-- `limit`: Max results (default: 20)
+**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)
 
 **Returns:**
 - List of test runs with pass/fail/skip counts
@@ -130,11 +163,58 @@ List recent test runs with optional filtering.
 - "Show me test runs on the main branch"
 - "Did any tests fail on my feature branch?"
 
+### `get_report`
+
+Get the report files for a specific test run. **Requires a user API Key (`gaf_`).**
+
+**Input:**
+- `testRunId` (required): Test run ID from `list_test_runs`
+
+**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
+
+**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_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"
+
 ## Environment Variables
 
 | Variable | Required | Description |
 |----------|----------|-------------|
-| `GAFFER_API_KEY` | Yes | Your Gaffer API key (starts with `gfr_`) |
+| `GAFFER_API_KEY` | Yes | Your Gaffer API Key (starts with `gaf_`) |
 | `GAFFER_API_URL` | No | API base URL (default: `https://app.gaffer.sh`) |
 
 ## Local Development
@@ -151,7 +231,7 @@ pnpm --filter @gaffer-sh/mcp build
       "command": "node",
       "args": ["/path/to/gaffer-v2/packages/mcp-server/dist/index.js"],
       "env": {
-        "GAFFER_API_KEY": "gfr_..."
+        "GAFFER_API_KEY": "gaf_..."
       }
     }
   }

package/dist/index.js

@@ -6,15 +6,26 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 
 // src/api-client.ts
 var REQUEST_TIMEOUT_MS = 3e4;
+function detectTokenType(token) {
+  if (token.startsWith("gaf_")) {
+    return "user";
+  }
+  return "project";
+}
 var GafferApiClient = class _GafferApiClient {
   apiKey;
   baseUrl;
+  tokenType;
   constructor(config) {
     this.apiKey = config.apiKey;
     this.baseUrl = config.baseUrl.replace(/\/$/, "");
+    this.tokenType = detectTokenType(config.apiKey);
   }
   /**
    * Create client from environment variables
+   *
+   * Supports:
+   * - GAFFER_API_KEY (for user API Keys gaf_)
    */
   static fromEnv() {
     const apiKey = process.env.GAFFER_API_KEY;
@@ -24,6 +35,12 @@ var GafferApiClient = class _GafferApiClient {
     const baseUrl = process.env.GAFFER_API_URL || "https://app.gaffer.sh";
     return new _GafferApiClient({ apiKey, baseUrl });
   }
+  /**
+   * Check if using a user API Key (enables cross-project features)
+   */
+  isUserToken() {
+    return this.tokenType === "user";
+  }
   /**
    * Make authenticated request to Gaffer API
    */
@@ -44,7 +61,7 @@ var GafferApiClient = class _GafferApiClient {
         headers: {
           "X-API-Key": this.apiKey,
           "Accept": "application/json",
-          "User-Agent": "gaffer-mcp/0.1.0"
+          "User-Agent": "gaffer-mcp/0.2.0"
         },
         signal: controller.signal
       });
@@ -63,16 +80,53 @@ var GafferApiClient = class _GafferApiClient {
       clearTimeout(timeoutId);
     }
   }
+  /**
+   * List all projects the user has access to
+   * Requires user API Key (gaf_)
+   *
+   * @param options - Query options
+   * @param options.organizationId - Filter by organization ID
+   * @param options.limit - Maximum number of results
+   * @param options.offset - Offset for pagination
+   */
+  async listProjects(options = {}) {
+    if (!this.isUserToken()) {
+      throw new Error("listProjects requires a user API Key (gaf_). Upload Tokens (gfr_) can only access a single project.");
+    }
+    return this.request("/user/projects", {
+      ...options.organizationId && { organizationId: options.organizationId },
+      ...options.limit && { limit: options.limit },
+      ...options.offset && { offset: options.offset }
+    });
+  }
   /**
    * Get project health analytics
+   *
+   * @param options - Query options
+   * @param options.projectId - Required for user tokens, ignored for project tokens
+   * @param options.days - Analysis period in days (default: 30)
    */
   async getProjectHealth(options = {}) {
+    if (this.isUserToken()) {
+      if (!options.projectId) {
+        throw new Error("projectId is required when using a user API Key");
+      }
+      return this.request(`/user/projects/${options.projectId}/health`, {
+        days: options.days || 30
+      });
+    }
     return this.request("/project/analytics", {
       days: options.days || 30
     });
   }
   /**
    * Get test history for a specific test
+   *
+   * @param options - Query options
+   * @param options.projectId - Required for user tokens, ignored for project tokens
+   * @param options.testName - Test name to search for
+   * @param options.filePath - File path to search for
+   * @param options.limit - Maximum number of results
    */
   async getTestHistory(options) {
     const testName = options.testName?.trim();
@@ -80,6 +134,16 @@ var GafferApiClient = class _GafferApiClient {
     if (!testName && !filePath) {
       throw new Error("Either testName or filePath is required (and must not be empty)");
     }
+    if (this.isUserToken()) {
+      if (!options.projectId) {
+        throw new Error("projectId is required when using a user API Key");
+      }
+      return this.request(`/user/projects/${options.projectId}/test-history`, {
+        ...testName && { testName },
+        ...filePath && { filePath },
+        ...options.limit && { limit: options.limit }
+      });
+    }
     return this.request("/project/test-history", {
       ...testName && { testName },
       ...filePath && { filePath },
@@ -88,8 +152,24 @@ var GafferApiClient = class _GafferApiClient {
   }
   /**
    * Get flaky tests for the project
+   *
+   * @param options - Query options
+   * @param options.projectId - Required for user tokens, ignored for project tokens
+   * @param options.threshold - Minimum flip rate to be considered flaky (0-1)
+   * @param options.limit - Maximum number of results
+   * @param options.days - Analysis period in days
    */
   async getFlakyTests(options = {}) {
+    if (this.isUserToken()) {
+      if (!options.projectId) {
+        throw new Error("projectId is required when using a user API Key");
+      }
+      return this.request(`/user/projects/${options.projectId}/flaky-tests`, {
+        ...options.threshold && { threshold: options.threshold },
+        ...options.limit && { limit: options.limit },
+        ...options.days && { days: options.days }
+      });
+    }
     return this.request("/project/flaky-tests", {
       ...options.threshold && { threshold: options.threshold },
       ...options.limit && { limit: options.limit },
@@ -98,8 +178,26 @@ var GafferApiClient = class _GafferApiClient {
   }
   /**
    * List test runs for the project
+   *
+   * @param options - Query options
+   * @param options.projectId - Required for user tokens, ignored for project tokens
+   * @param options.commitSha - Filter by commit SHA
+   * @param options.branch - Filter by branch name
+   * @param options.status - Filter by status ('passed' or 'failed')
+   * @param options.limit - Maximum number of results
    */
   async getTestRuns(options = {}) {
+    if (this.isUserToken()) {
+      if (!options.projectId) {
+        throw new Error("projectId is required when using a user API Key");
+      }
+      return this.request(`/user/projects/${options.projectId}/test-runs`, {
+        ...options.commitSha && { commitSha: options.commitSha },
+        ...options.branch && { branch: options.branch },
+        ...options.status && { status: options.status },
+        ...options.limit && { limit: options.limit }
+      });
+    }
     return this.request("/project/test-runs", {
       ...options.commitSha && { commitSha: options.commitSha },
       ...options.branch && { branch: options.branch },
@@ -107,11 +205,50 @@ var GafferApiClient = class _GafferApiClient {
       ...options.limit && { limit: options.limit }
     });
   }
+  /**
+   * Get report files for a test run
+   *
+   * @param testRunId - The test run ID
+   * @returns Report metadata with download URLs for each file
+   */
+  async getReport(testRunId) {
+    if (!this.isUserToken()) {
+      throw new Error("getReport requires a user API Key (gaf_). Upload Tokens (gfr_) cannot access reports via API.");
+    }
+    if (!testRunId) {
+      throw new Error("testRunId is required");
+    }
+    return this.request(`/user/test-runs/${testRunId}/report`);
+  }
+  /**
+   * Get slowest tests for a project
+   *
+   * @param options - Query options
+   * @param options.projectId - The project ID (required)
+   * @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
+   * @returns Slowest tests sorted by P95 duration
+   */
+  async getSlowestTests(options) {
+    if (!this.isUserToken()) {
+      throw new Error("getSlowestTests requires a user API Key (gaf_).");
+    }
+    if (!options.projectId) {
+      throw new Error("projectId is required");
+    }
+    return this.request(`/user/projects/${options.projectId}/slowest-tests`, {
+      ...options.days && { days: options.days },
+      ...options.limit && { limit: options.limit },
+      ...options.framework && { framework: options.framework }
+    });
+  }
 };
 
 // src/tools/get-flaky-tests.ts
 import { z } 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)")
@@ -132,6 +269,7 @@ var getFlakyTestsOutputSchema = {
 };
 async function executeGetFlakyTests(client, input) {
   const response = await client.getFlakyTests({
+    projectId: input.projectId,
     threshold: input.threshold,
     limit: input.limit,
     days: input.days
@@ -144,7 +282,10 @@ async function executeGetFlakyTests(client, input) {
 var getFlakyTestsMetadata = {
   name: "get_flaky_tests",
   title: "Get Flaky Tests",
-  description: `Get the list of flaky tests in the project.
+  description: `Get the list of flaky tests in a project.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
 
 A test is considered flaky if it frequently switches between pass and fail states
 (high "flip rate"). This helps identify unreliable tests that need attention.
@@ -165,6 +306,7 @@ specific tests are flaky and need investigation.`
 // src/tools/get-project-health.ts
 import { z as z2 } 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)")
 };
 var getProjectHealthOutputSchema = {
@@ -181,7 +323,10 @@ var getProjectHealthOutputSchema = {
   })
 };
 async function executeGetProjectHealth(client, input) {
-  const response = await client.getProjectHealth({ days: input.days });
+  const response = await client.getProjectHealth({
+    projectId: input.projectId,
+    days: input.days
+  });
   return {
     projectName: response.analytics.projectName,
     healthScore: response.analytics.healthScore,
@@ -195,7 +340,10 @@ async function executeGetProjectHealth(client, input) {
 var getProjectHealthMetadata = {
   name: "get_project_health",
   title: "Get Project Health",
-  description: `Get the health metrics for the project associated with your API key.
+  description: `Get the health metrics 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:
 - Health score (0-100): Overall project health based on pass rate and trend
@@ -207,28 +355,162 @@ Returns:
 Use this to understand the current state of your test suite.`
 };
 
-// src/tools/get-test-history.ts
+// src/tools/get-report.ts
 import { z as z3 } 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.")
+};
+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()
+  }))
+};
+async function executeGetReport(client, input) {
+  const response = await client.getReport(input.testRunId);
+  return {
+    testRunId: response.testRunId,
+    projectId: response.projectId,
+    projectName: response.projectName,
+    resultSchema: response.resultSchema,
+    files: response.files.map((file) => ({
+      filename: file.filename,
+      size: file.size,
+      contentType: file.contentType,
+      downloadUrl: file.downloadUrl
+    }))
+  };
+}
+var getReportMetadata = {
+  name: "get_report",
+  title: "Get Report Files",
+  description: `Get the report files for a specific test run.
+
+Returns a list of files uploaded with the test run, including:
+- filename: The file name (e.g., "report.html", "coverage/index.html")
+- size: File size in bytes
+- contentType: MIME type (e.g., "text/html", "application/json")
+- downloadUrl: URL to download the file (requires authentication)
+
+Common report types:
+- HTML reports (Playwright, pytest-html, Vitest UI)
+- JSON results (Jest, Vitest)
+- JUnit XML files
+- Coverage reports
+
+Use cases:
+- "Get the Playwright report for this test run"
+- "Download the coverage report"
+- "What files were uploaded with this test run?"
+
+Note: Download URLs require the same API key authentication used for this request.`
+};
+
+// src/tools/get-slowest-tests.ts
+import { z as z4 } 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")')
+};
+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()
+  })),
+  summary: z4.object({
+    projectId: z4.string(),
+    projectName: z4.string(),
+    period: z4.number(),
+    totalReturned: z4.number()
+  })
+};
+async function executeGetSlowestTests(client, input) {
+  const response = await client.getSlowestTests({
+    projectId: input.projectId,
+    days: input.days,
+    limit: input.limit,
+    framework: input.framework
+  });
+  return {
+    slowestTests: response.slowestTests.map((test) => ({
+      name: test.name,
+      fullName: test.fullName,
+      filePath: test.filePath,
+      framework: test.framework,
+      avgDurationMs: test.avgDurationMs,
+      p95DurationMs: test.p95DurationMs,
+      runCount: test.runCount
+    })),
+    summary: response.summary
+  };
+}
+var getSlowestTestsMetadata = {
+  name: "get_slowest_tests",
+  title: "Get Slowest Tests",
+  description: `Get the slowest tests in a project, sorted by P95 duration.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
+Parameters:
+- projectId (required): Project ID to analyze
+- 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 test duration in milliseconds
+  - p95DurationMs: 95th percentile duration (used for sorting)
+  - runCount: Number of times the test ran in the period
+- Summary with project info and period
+
+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"`
+};
+
+// src/tools/get-test-history.ts
+import { z as z5 } from "zod";
 var getTestHistoryInputSchema = {
-  testName: z3.string().optional().describe("Exact test name to search for"),
-  filePath: z3.string().optional().describe("File path containing the test"),
-  limit: z3.number().int().min(1).max(100).optional().describe("Maximum number of results (default: 20)")
+  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)")
 };
 var getTestHistoryOutputSchema = {
-  history: z3.array(z3.object({
-    testRunId: z3.string(),
-    createdAt: z3.string(),
-    branch: z3.string().optional(),
-    commitSha: z3.string().optional(),
-    status: z3.enum(["passed", "failed", "skipped", "pending"]),
-    durationMs: z3.number(),
-    message: z3.string().optional()
+  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()
   })),
-  summary: z3.object({
-    totalRuns: z3.number(),
-    passedRuns: z3.number(),
-    failedRuns: z3.number(),
-    passRate: z3.number().nullable()
+  summary: z5.object({
+    totalRuns: z5.number(),
+    passedRuns: z5.number(),
+    failedRuns: z5.number(),
+    passRate: z5.number().nullable()
   })
 };
 async function executeGetTestHistory(client, input) {
@@ -236,6 +518,7 @@ async function executeGetTestHistory(client, input) {
     throw new Error("Either testName or filePath is required");
   }
   const response = await client.getTestHistory({
+    projectId: input.projectId,
     testName: input.testName,
     filePath: input.filePath,
     limit: input.limit || 20
@@ -264,6 +547,9 @@ var getTestHistoryMetadata = {
   title: "Get Test History",
   description: `Get the pass/fail history for a specific test.
 
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
+
 Search by either:
 - testName: The exact name of the test (e.g., "should handle user login")
 - filePath: The file path containing the test (e.g., "tests/auth.test.ts")
@@ -278,32 +564,79 @@ Returns:
 Use this to investigate flaky tests or understand test stability.`
 };
 
+// src/tools/list-projects.ts
+import { z as z6 } 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)")
+};
+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()
+    })
+  })),
+  total: z6.number()
+};
+async function executeListProjects(client, input) {
+  const response = await client.listProjects({
+    organizationId: input.organizationId,
+    limit: input.limit
+  });
+  return {
+    projects: response.projects.map((p) => ({
+      id: p.id,
+      name: p.name,
+      description: p.description,
+      organization: p.organization
+    })),
+    total: response.pagination.total
+  };
+}
+var listProjectsMetadata = {
+  name: "list_projects",
+  title: "List Projects",
+  description: `List all projects you have access to.
+
+Returns a list of projects with their IDs, names, and organization info.
+Use this to find project IDs for other tools like get_project_health.
+
+Requires a user API Key (gaf_). Get one from Account Settings in the Gaffer dashboard.`
+};
+
 // src/tools/list-test-runs.ts
-import { z as z4 } from "zod";
+import { z as z7 } from "zod";
 var listTestRunsInputSchema = {
-  commitSha: z4.string().optional().describe("Filter by commit SHA (exact or prefix match)"),
-  branch: z4.string().optional().describe("Filter by branch name"),
-  status: z4.enum(["passed", "failed"]).optional().describe('Filter by status: "passed" (no failures) or "failed" (has failures)'),
-  limit: z4.number().int().min(1).max(100).optional().describe("Maximum number of test runs to return (default: 20)")
+  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)")
 };
 var listTestRunsOutputSchema = {
-  testRuns: z4.array(z4.object({
-    id: z4.string(),
-    commitSha: z4.string().optional(),
-    branch: z4.string().optional(),
-    passedCount: z4.number(),
-    failedCount: z4.number(),
-    skippedCount: z4.number(),
-    totalCount: z4.number(),
-    createdAt: z4.string()
+  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()
   })),
-  pagination: z4.object({
-    total: z4.number(),
-    hasMore: z4.boolean()
+  pagination: z7.object({
+    total: z7.number(),
+    hasMore: z7.boolean()
   })
 };
 async function executeListTestRuns(client, input) {
   const response = await client.getTestRuns({
+    projectId: input.projectId,
     commitSha: input.commitSha,
     branch: input.branch,
     status: input.status,
@@ -329,7 +662,10 @@ async function executeListTestRuns(client, input) {
 var listTestRunsMetadata = {
   name: "list_test_runs",
   title: "List Test Runs",
-  description: `List recent test runs for the project with optional filtering.
+  description: `List recent test runs for a project with optional filtering.
+
+When using a user API Key (gaf_), you must provide a projectId.
+Use list_projects first to find available project IDs.
 
 Filter by:
 - commitSha: Filter by commit SHA (supports prefix matching)
@@ -353,10 +689,11 @@ Use cases:
 
 // src/index.ts
 async function main() {
-  if (!process.env.GAFFER_API_KEY) {
+  const apiKey = process.env.GAFFER_API_KEY;
+  if (!apiKey) {
     console.error("Error: GAFFER_API_KEY environment variable is required");
     console.error("");
-    console.error("Get your API key from: https://app.gaffer.sh/settings/api-keys");
+    console.error("Get your API Key from: https://app.gaffer.sh/account/api-keys");
     console.error("");
     console.error("Then configure Claude Code or Cursor with:");
     console.error(JSON.stringify({
@@ -365,7 +702,7 @@ async function main() {
           command: "npx",
           args: ["-y", "@gaffer-sh/mcp"],
           env: {
-            GAFFER_API_KEY: "your-api-key-here"
+            GAFFER_API_KEY: "gaf_your-api-key-here"
           }
         }
       }
@@ -473,6 +810,78 @@ async function main() {
       }
     }
   );
+  server.registerTool(
+    listProjectsMetadata.name,
+    {
+      title: listProjectsMetadata.title,
+      description: listProjectsMetadata.description,
+      inputSchema: listProjectsInputSchema,
+      outputSchema: listProjectsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeListProjects(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    getReportMetadata.name,
+    {
+      title: getReportMetadata.title,
+      description: getReportMetadata.description,
+      inputSchema: getReportInputSchema,
+      outputSchema: getReportOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetReport(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
+  server.registerTool(
+    getSlowestTestsMetadata.name,
+    {
+      title: getSlowestTestsMetadata.title,
+      description: getSlowestTestsMetadata.description,
+      inputSchema: getSlowestTestsInputSchema,
+      outputSchema: getSlowestTestsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetSlowestTests(client, input);
+        return {
+          content: [{ type: "text", text: JSON.stringify(output, null, 2) }],
+          structuredContent: output
+        };
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+          content: [{ type: "text", text: `Error: ${message}` }],
+          isError: true
+        };
+      }
+    }
+  );
   const transport = new StdioServerTransport();
   await server.connect(transport);
 }

package/package.json

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