@gaffer-sh/mcp 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# @gaffer-sh/mcp
+
+MCP (Model Context Protocol) server for [Gaffer](https://gaffer.sh) - give your AI assistant memory of your tests.
+
+## What is this?
+
+This MCP server connects AI coding assistants like Claude Code and Cursor to your Gaffer test history. 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
+
+## Prerequisites
+
+1. A [Gaffer](https://gaffer.sh) account with test results uploaded
+2. An API key from your project settings
+
+## Setup
+
+### Claude Code
+
+Add to your Claude Code settings (`~/.claude.json` or project `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "gaffer": {
+      "command": "npx",
+      "args": ["-y", "@gaffer-sh/mcp"],
+      "env": {
+        "GAFFER_API_KEY": "gfr_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "gaffer": {
+      "command": "npx",
+      "args": ["-y", "@gaffer-sh/mcp"],
+      "env": {
+        "GAFFER_API_KEY": "gfr_your_api_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `get_project_health`
+
+Get the health metrics for your project.
+
+**Input:**
+- `days` (optional): Number of days to analyze (default: 30)
+
+**Returns:**
+- Health score (0-100)
+- Pass rate percentage
+- Number of test runs
+- Flaky test count
+- Trend (up/down/stable)
+
+**Example prompt:** "What's the health of my test suite?"
+
+### `get_test_history`
+
+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
+- `limit` (optional): Max results (default: 20)
+
+**Returns:**
+- History of test runs with pass/fail status
+- Duration of each run
+- Branch and commit info
+- Error messages for failures
+- Summary statistics
+
+**Example prompts:**
+- "Is the login test flaky? Check its history"
+- "Show me the history for tests in auth.test.ts"
+
+### `get_flaky_tests`
+
+Get the list of flaky tests in your project.
+
+**Input:**
+- `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"
+
+### `list_test_runs`
+
+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)
+
+**Returns:**
+- List of test runs with pass/fail/skip counts
+- Commit SHA and branch info
+- Pagination info
+
+**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?"
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `GAFFER_API_KEY` | Yes | Your Gaffer API key (starts with `gfr_`) |
+| `GAFFER_API_URL` | No | API base URL (default: `https://app.gaffer.sh`) |
+
+## Local Development
+
+```bash
+# From monorepo root
+pnpm install
+pnpm --filter @gaffer-sh/mcp build
+
+# Test locally with Claude Code (use absolute path)
+{
+  "mcpServers": {
+    "gaffer": {
+      "command": "node",
+      "args": ["/path/to/gaffer-v2/packages/mcp-server/dist/index.js"],
+      "env": {
+        "GAFFER_API_KEY": "gfr_..."
+      }
+    }
+  }
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/index.js

@@ -0,0 +1,482 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/api-client.ts
+var REQUEST_TIMEOUT_MS = 3e4;
+var GafferApiClient = class _GafferApiClient {
+  apiKey;
+  baseUrl;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = config.baseUrl.replace(/\/$/, "");
+  }
+  /**
+   * Create client from environment variables
+   */
+  static fromEnv() {
+    const apiKey = process.env.GAFFER_API_KEY;
+    if (!apiKey) {
+      throw new Error("GAFFER_API_KEY environment variable is required");
+    }
+    const baseUrl = process.env.GAFFER_API_URL || "https://app.gaffer.sh";
+    return new _GafferApiClient({ apiKey, baseUrl });
+  }
+  /**
+   * Make authenticated request to Gaffer API
+   */
+  async request(endpoint, params) {
+    const url = new URL(`/api/v1${endpoint}`, this.baseUrl);
+    if (params) {
+      for (const [key, value] of Object.entries(params)) {
+        if (value !== void 0 && value !== null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    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.1.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`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+  /**
+   * Get project health analytics
+   */
+  async getProjectHealth(options = {}) {
+    return this.request("/project/analytics", {
+      days: options.days || 30
+    });
+  }
+  /**
+   * Get test history for a specific test
+   */
+  async getTestHistory(options) {
+    const testName = options.testName?.trim();
+    const filePath = options.filePath?.trim();
+    if (!testName && !filePath) {
+      throw new Error("Either testName or filePath is required (and must not be empty)");
+    }
+    return this.request("/project/test-history", {
+      ...testName && { testName },
+      ...filePath && { filePath },
+      ...options.limit && { limit: options.limit }
+    });
+  }
+  /**
+   * Get flaky tests for the project
+   */
+  async getFlakyTests(options = {}) {
+    return this.request("/project/flaky-tests", {
+      ...options.threshold && { threshold: options.threshold },
+      ...options.limit && { limit: options.limit },
+      ...options.days && { days: options.days }
+    });
+  }
+  /**
+   * List test runs for the project
+   */
+  async getTestRuns(options = {}) {
+    return this.request("/project/test-runs", {
+      ...options.commitSha && { commitSha: options.commitSha },
+      ...options.branch && { branch: options.branch },
+      ...options.status && { status: options.status },
+      ...options.limit && { limit: options.limit }
+    });
+  }
+};
+
+// src/tools/get-flaky-tests.ts
+import { z } from "zod";
+var getFlakyTestsInputSchema = {
+  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)")
+};
+var getFlakyTestsOutputSchema = {
+  flakyTests: z.array(z.object({
+    name: z.string(),
+    flipRate: z.number(),
+    flipCount: z.number(),
+    totalRuns: z.number(),
+    lastSeen: z.string()
+  })),
+  summary: z.object({
+    threshold: z.number(),
+    totalFlaky: z.number(),
+    period: z.number()
+  })
+};
+async function executeGetFlakyTests(client, input) {
+  const response = await client.getFlakyTests({
+    threshold: input.threshold,
+    limit: input.limit,
+    days: input.days
+  });
+  return {
+    flakyTests: response.flakyTests,
+    summary: response.summary
+  };
+}
+var getFlakyTestsMetadata = {
+  name: "get_flaky_tests",
+  title: "Get Flaky Tests",
+  description: `Get the list of flaky tests in the project.
+
+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.
+
+Returns:
+- List of flaky tests with:
+  - name: Test name
+  - flipRate: How often the test flips between pass/fail (0-1)
+  - flipCount: Number of status transitions
+  - totalRuns: Total test executions analyzed
+  - lastSeen: When the test last ran
+- Summary with threshold used and total count
+
+Use this after get_project_health shows flaky tests exist, to identify which
+specific tests are flaky and need investigation.`
+};
+
+// src/tools/get-project-health.ts
+import { z as z2 } from "zod";
+var getProjectHealthInputSchema = {
+  days: z2.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()
+  })
+};
+async function executeGetProjectHealth(client, input) {
+  const response = await client.getProjectHealth({ days: input.days });
+  return {
+    projectName: response.analytics.projectName,
+    healthScore: response.analytics.healthScore,
+    passRate: response.analytics.passRate,
+    testRunCount: response.analytics.testRunCount,
+    flakyTestCount: response.analytics.flakyTestCount,
+    trend: response.analytics.trend,
+    period: response.analytics.period
+  };
+}
+var getProjectHealthMetadata = {
+  name: "get_project_health",
+  title: "Get Project Health",
+  description: `Get the health metrics for the project associated with your API key.
+
+Returns:
+- Health score (0-100): Overall project health based on pass rate and trend
+- Pass rate: Percentage of tests passing
+- Test run count: Number of test runs in the period
+- Flaky test count: Number of tests with inconsistent results
+- Trend: Whether test health is improving (up), declining (down), or stable
+
+Use this to understand the current state of your test suite.`
+};
+
+// src/tools/get-test-history.ts
+import { z as z3 } 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)")
+};
+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()
+  })),
+  summary: z3.object({
+    totalRuns: z3.number(),
+    passedRuns: z3.number(),
+    failedRuns: z3.number(),
+    passRate: z3.number().nullable()
+  })
+};
+async function executeGetTestHistory(client, input) {
+  if (!input.testName && !input.filePath) {
+    throw new Error("Either testName or filePath is required");
+  }
+  const response = await client.getTestHistory({
+    testName: input.testName,
+    filePath: input.filePath,
+    limit: input.limit || 20
+  });
+  return {
+    history: response.history.map((entry) => ({
+      testRunId: entry.testRunId,
+      createdAt: entry.createdAt,
+      branch: entry.branch,
+      commitSha: entry.commitSha,
+      status: entry.test.status,
+      durationMs: entry.test.durationMs,
+      message: entry.test.message || void 0
+      // Convert null to undefined for schema compliance
+    })),
+    summary: {
+      totalRuns: response.summary.totalRuns,
+      passedRuns: response.summary.passedRuns,
+      failedRuns: response.summary.failedRuns,
+      passRate: response.summary.passRate
+    }
+  };
+}
+var getTestHistoryMetadata = {
+  name: "get_test_history",
+  title: "Get Test History",
+  description: `Get the pass/fail history for a specific test.
+
+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")
+
+Returns:
+- History of test runs showing pass/fail status over time
+- Duration of each run
+- Branch and commit information
+- Error messages for failed runs
+- Summary statistics (pass rate, total runs)
+
+Use this to investigate flaky tests or understand test stability.`
+};
+
+// src/tools/list-test-runs.ts
+import { z as z4 } 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)")
+};
+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()
+  })),
+  pagination: z4.object({
+    total: z4.number(),
+    hasMore: z4.boolean()
+  })
+};
+async function executeListTestRuns(client, input) {
+  const response = await client.getTestRuns({
+    commitSha: input.commitSha,
+    branch: input.branch,
+    status: input.status,
+    limit: input.limit || 20
+  });
+  return {
+    testRuns: response.testRuns.map((run) => ({
+      id: run.id,
+      commitSha: run.commitSha || void 0,
+      branch: run.branch || void 0,
+      passedCount: run.summary.passed,
+      failedCount: run.summary.failed,
+      skippedCount: run.summary.skipped,
+      totalCount: run.summary.total,
+      createdAt: run.createdAt
+    })),
+    pagination: {
+      total: response.pagination.total,
+      hasMore: response.pagination.hasMore
+    }
+  };
+}
+var listTestRunsMetadata = {
+  name: "list_test_runs",
+  title: "List Test Runs",
+  description: `List recent test runs for the project with optional filtering.
+
+Filter by:
+- commitSha: Filter by commit SHA (supports prefix matching)
+- branch: Filter by branch name
+- status: Filter by "passed" (no failures) or "failed" (has failures)
+
+Returns:
+- List of test runs with:
+  - id: Test run ID (can be used with get_test_run for details)
+  - commitSha: Git commit SHA
+  - branch: Git branch name
+  - passedCount/failedCount/skippedCount: Test counts
+  - createdAt: When the test run was created
+- Pagination info (total count, hasMore flag)
+
+Use cases:
+- "What tests failed in commit abc123?"
+- "Show me recent test runs on main branch"
+- "What's the status of tests on my feature branch?"`
+};
+
+// src/index.ts
+async function main() {
+  if (!process.env.GAFFER_API_KEY) {
+    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("");
+    console.error("Then configure Claude Code or Cursor with:");
+    console.error(JSON.stringify({
+      mcpServers: {
+        gaffer: {
+          command: "npx",
+          args: ["-y", "@gaffer-sh/mcp"],
+          env: {
+            GAFFER_API_KEY: "your-api-key-here"
+          }
+        }
+      }
+    }, null, 2));
+    process.exit(1);
+  }
+  const client = GafferApiClient.fromEnv();
+  const server = new McpServer({
+    name: "gaffer",
+    version: "0.1.0"
+  });
+  server.registerTool(
+    getProjectHealthMetadata.name,
+    {
+      title: getProjectHealthMetadata.title,
+      description: getProjectHealthMetadata.description,
+      inputSchema: getProjectHealthInputSchema,
+      outputSchema: getProjectHealthOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetProjectHealth(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(
+    getTestHistoryMetadata.name,
+    {
+      title: getTestHistoryMetadata.title,
+      description: getTestHistoryMetadata.description,
+      inputSchema: getTestHistoryInputSchema,
+      outputSchema: getTestHistoryOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetTestHistory(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(
+    getFlakyTestsMetadata.name,
+    {
+      title: getFlakyTestsMetadata.title,
+      description: getFlakyTestsMetadata.description,
+      inputSchema: getFlakyTestsInputSchema,
+      outputSchema: getFlakyTestsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeGetFlakyTests(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(
+    listTestRunsMetadata.name,
+    {
+      title: listTestRunsMetadata.title,
+      description: listTestRunsMetadata.description,
+      inputSchema: listTestRunsInputSchema,
+      outputSchema: listTestRunsOutputSchema
+    },
+    async (input) => {
+      try {
+        const output = await executeListTestRuns(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);
+}
+main().catch((error) => {
+  console.error("Fatal error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gaffer-sh/mcp",
+  "type": "module",
+  "version": "0.1.0",
+  "description": "MCP server for Gaffer test history - give your AI assistant memory of your tests",
+  "license": "MIT",
+  "author": "Gaffer <hello@gaffer.sh>",
+  "homepage": "https://gaffer.sh",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gaffer-sh/gaffer-v2.git",
+    "directory": "packages/mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/gaffer-sh/gaffer-v2/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gaffer",
+    "test-results",
+    "claude",
+    "cursor",
+    "ai-assistant"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "gaffer-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "bumpp": "^10.1.0",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  },
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "chmod +x dist/index.js",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "release": "bumpp --tag 'mcp-v%s' --commit 'chore(mcp): release v%s' && git push --follow-tags"
+  }
+}