@gaffer-sh/mcp 0.4.2 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gaffer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -85,6 +85,13 @@ Add to `.cursor/mcp.json` in your project:
 | `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 |
+| `get_failure_clusters` | Group failed tests by root cause (error similarity) |
+
+### Upload & Status Tools
+
+| Tool | Description |
+|------|-------------|
+| `get_upload_status` | Check if CI results are uploaded and processed |
 
 ### Coverage Tools
 
@@ -209,6 +216,79 @@ Find code areas with both low coverage AND test failures (high risk).
 - **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?"
+
+### `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?"
+
+## Agentic CI Workflows
+
+These workflows show how an AI agent can use Gaffer tools to diagnose CI failures, wait for results, and find coverage gaps.
+
+### 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
+
+### Tool Quick Reference
+
+| Agent Question | Tool |
+|---|---|
+| "What failed?" | `get_test_run_details` |
+| "Same root cause?" | `get_failure_clusters` |
+| "Is it flaky?" | `get_flaky_tests` |
+| "Is this new?" | `get_test_history` |
+| "Did my fix work?" | `compare_test_metrics` |
+| "Are results ready?" | `get_upload_status` |
+| "What's untested?" | `find_uncovered_failure_areas` |
+| "What's slow?" | `get_slowest_tests` |
+
 ## Prioritizing Coverage Improvements
 
 When using coverage tools to improve your test suite, combine coverage data with codebase exploration for best results:
@@ -268,16 +348,18 @@ Project Upload Tokens (`gfr_` prefix) are designed for uploading test results an
 ## Local Development
 
 ```bash
-# From monorepo root
 pnpm install
-pnpm --filter @gaffer-sh/mcp build
+pnpm build
+```
 
-# Test locally with Claude Code (use absolute path)
+Test locally with Claude Code (use absolute path to built file):
+
+```json
 {
   "mcpServers": {
     "gaffer": {
       "command": "node",
-      "args": ["/path/to/gaffer-v2/packages/mcp-server/dist/index.js"],
+      "args": ["/absolute/path/to/dist/index.js"],
       "env": {
         "GAFFER_API_KEY": "gaf_..."
       }

package/dist/index.d.ts

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