@gaffer-sh/mcp

MCP (Model Context Protocol) server for Gaffer - 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 and coverage data. It runs in code mode: three MCP tools over a namespace of 17 functions — 16 read-only analytics functions plus upload_test_results. 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.)

Related MCP server: Koalr

Prerequisites

1. A Gaffer account with test results uploaded

2. An API Key from Account Settings > API Keys

Setup

Claude Code (CLI)

The easiest way to add the Gaffer MCP server is via the Claude Code CLI:

claude mcp add gaffer -e GAFFER_API_KEY=gaf_your_api_key_here -- npx -y @gaffer-sh/mcp

Claude Code (Manual)

Alternatively, add to your Claude Code settings (~/.claude.json or project .claude/settings.json):

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gaffer": {
      "command": "npx",
      "args": ["-y", "@gaffer-sh/mcp"],
      "env": {
        "GAFFER_API_KEY": "gaf_your_api_key_here"
      }
    }
  }
}

How this server works

This server uses code mode. Instead of exposing one MCP tool per API call, it exposes three tools plus a codemode namespace you call from JavaScript. Fewer tool definitions occupy the context window, and a single execution can chain several calls.

const health = await codemode.get_project_health({ projectId: "proj_abc" });
if (health.flakyTestCount > 0) {
  const flaky = await codemode.get_flaky_tests({ projectId: "proj_abc" });
  return { health, flaky };
}
return { health };

Functions available via execute_code

Every function except upload_test_results is read-only.

Function Reference

list_projects

List all projects you have access to.

• 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_project_health

Get the health metrics for a project.

• 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

Get the pass/fail history for a specific test.

• 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), 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), 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

Get parsed test results for a specific test run.

• 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 URLs for report files uploaded with a test run.

• Input: testRunId (required)

• Returns: List of files with filename, size, content type, download URL

• Example: "Get the Playwright report for the latest test run"

get_report_browser_url

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.

• 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?"

get_failure_clusters

Group failed tests by root cause using error message similarity.

• Input: projectId (required), testRunId (required)

• Returns: Clusters of failed tests grouped by similar error messages, with representative error and test count

• Example: "Are these 15 failures from the same bug?"

search_failures

Search past failures by error message, stack trace, or test name — or list every failure in the window.

• Input: query (optional — omit to return all failures), projectId (required for gaf_ keys), searchIn (optional: errors/names/all, default all), days (optional, default: 30), branch (optional), limit (optional, default: 20)

• Returns: Matching failures with test name, error message, run and commit context, plus truncated when scan caps cut the list short

• Example: "Have we seen this connection-refused error before?" / "What failed in the last 7 days?"

get_upload_status

Check if CI results have been uploaded and processed.

• Input: projectId (required), sessionId (optional), commitSha (optional), branch (optional)

• Returns: Upload session(s) with processing status, linked test runs and coverage reports

• Example: "Are my test results ready for commit abc123?"

upload_test_results

Upload structured test results. This is the only function that writes.

Use it when you have results in hand — parsed from CI output or a runner's JSON report — and no Gaffer CLI is available to upload them.

• Input: projectId (required for gaf_ keys), framework (required), tests (required), branch, commitSha, ciProvider, startedAt, finishedAt, coverage

• Returns: uploadSessionId, the generated runId, and the derived pass/fail/skip summary

• Example: "Upload these 42 parsed pytest results so we can track them"

runId, the run timestamps and the summary are derived from tests — pass startedAt/finishedAt only if you know the real wall-clock window.

Two constraints worth knowing:

• Not idempotent. Each call creates a new run, so a retry after an uncertain failure produces a duplicate. Check get_upload_status instead of retrying.

• Rate-limited per project, and every call is written to the project's audit log with the id of the credential that made it.

Processing is asynchronous: results take a few seconds to become visible to the read functions.

Agentic CI Workflows

These workflows show how an AI agent diagnoses CI failures, waits for results, and finds coverage gaps. Each step is a codemode function, so a whole chain runs inside one execute_code call rather than one round-trip per step.

Workflow: Diagnose CI Failures

list_test_runs(projectId, status="failed")
  → get_test_run_details(projectId, testRunId, status="failed")
  → get_failure_clusters(projectId, testRunId)
  → get_test_history(projectId, testName="...")
  → compare_test_metrics(projectId, testName, beforeCommit, afterCommit)

1. Find the failed test run

2. Get individual failure details with stack traces

3. Group failures by root cause — often 15 failures are 2-3 bugs

4. Check if each failure is new (regression) or recurring

5. Verify fixes by comparing before/after

Workflow: Wait for Results

get_upload_status(projectId, commitSha="abc123")
  → poll until processingStatus="completed"
  → get_test_run_details(projectId, testRunId)

1. Check if results for a commit have been uploaded

2. Wait for processing to complete

3. Use linked test run IDs to get results

Workflow: Find Coverage Gaps

find_uncovered_failure_areas(projectId)
  → get_untested_files(projectId)
  → get_coverage_for_file(projectId, filePath="src/critical/")

1. Find files with both low coverage and test failures (highest risk)

2. Find files with no coverage at all

3. Drill into specific directories for targeted analysis

Function Quick Reference

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 Tokens

Project Tokens (gfr_ prefix) are designed for uploading test results and only provide access to a single project. When you use one, omit projectId — it resolves automatically. User API Keys are preferred for the MCP server because they enable list_projects and read across projects.

Environment Variables

Local Development

pnpm install
pnpm build

Test locally with Claude Code (use absolute path to built file):

{
  "mcpServers": {
    "gaffer": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GAFFER_API_KEY": "gaf_..."
      }
    }
  }
}

License

MIT