Parity: currents-mcp ↔ Currents API

[miguelangaranocurrents]

Objective

Bring currents-mcp to complete parity with the Currents REST API.

Parity Matrix

Endpoint	Method	OpenAPI Ref	MCP Tool Name	Status	Notes
/actions	GET	listActions	currents-list-actions	OK	Supports projectId, status[], search filters
/actions	POST	createAction	currents-create-action	OK	Requires projectId, name, action[], matcher
/actions/{actionId}	GET	getAction	currents-get-action	OK	actionId is globally unique
/actions/{actionId}	PUT	updateAction	currents-update-action	OK	All fields optional, at least one required
/actions/{actionId}	DELETE	deleteAction	currents-delete-action	OK	Soft delete (archive)
/actions/{actionId}/enable	PUT	enableAction	currents-enable-action	OK	Changes status to active
/actions/{actionId}/disable	PUT	disableAction	currents-disable-action	OK	Changes status to disabled
/projects	GET	listProjects	currents-get-projects	OK	Supports cursor pagination + fetchAll helper
/projects/{projectId}	GET	getProject	currents-get-project	OK	Returns project details
/projects/{projectId}/runs	GET	listProjectRuns	currents-get-runs	OK	Full filtering: branches[], tags[], tag_operator, status[], completion_state[], authors[], search, date_start, date_end, pagination
/projects/{projectId}/insights	GET	getProjectInsights	currents-get-project-insights	OK	Requires date_start, date_end; supports resolution, tags[], branches[], groups[], authors[]
/runs/{runId}	GET	getRun	currents-get-run-details	OK	Returns full run details
/runs/{runId}	DELETE	deleteRun	currents-delete-run	OK	Permanent deletion
/runs/find	GET	findRun	currents-find-run	OK	Search by ciBuildId or branch+tags; supports pwLastRun flag
/runs/{runId}/cancel	PUT	cancelRun	currents-cancel-run	OK	Cancel in-progress run
/runs/{runId}/reset	PUT	resetRun	currents-reset-run	OK	Reset failed specs; requires machineId[], supports isBatchedOr8n
/runs/cancel-ci/github	PUT	cancelRunGithubCI	currents-cancel-run-github-ci	OK	Cancel by GitHub workflow; requires githubRunId, githubRunAttempt; optional projectId, ciBuildId
/instances/{instanceId}	GET	getInstance	currents-get-spec-instance	OK	Returns spec file execution details
/spec-files/{projectId}	GET	getSpecFiles	currents-get-spec-files-performance	OK	Page-based pagination; supports specNameFilter, order, dir, tags[], branches[], groups[], authors[], includeFailedInDuration
/test-results/{signature}	GET	getTestResults	currents-get-test-results	OK	Cursor pagination; supports date_start, date_end, branches[], tags[], authors[], status[], groups[], flaky filter
/tests/{projectId}	GET	getTests	currents-get-tests-performance	OK	Page-based pagination; supports spec, title filters, order, dir, tags[], branches[], groups[], authors[], min_executions, test_state[], metric_settings
/errors/{projectId}	GET	getErrorsExplorer	currents-get-errors-explorer	FIXED	Added in this PR. Aggregated error metrics with filtering by error_target, error_message, error_category, error_action, tags[], branches[], authors[], groups[]; supports group_by[], order_by, dir, metric, top_n; page-based pagination
/signature/test	POST	generateSignature	currents-get-tests-signatures	OK	Generates test signature from projectId, specFilePath, testTitle
/webhooks	GET	listWebhooks	currents-list-webhooks	OK	Lists all webhooks for a project
/webhooks	POST	createWebhook	currents-create-webhook	OK	Requires projectId, url; optional headers, hookEvents[], label
/webhooks/{hookId}	GET	getWebhook	currents-get-webhook	OK	Returns full webhook details
/webhooks/{hookId}	PUT	updateWebhook	currents-update-webhook	OK	All fields optional
/webhooks/{hookId}	DELETE	deleteWebhook	currents-delete-webhook	OK	Permanent deletion

Summary of Fixes

Added Endpoints (1)

• Errors Explorer (`GET /errors/{projectId}`)
  • New tool: `currents-get-errors-explorer`
  • Provides aggregated error metrics with comprehensive filtering
  • Supports error-specific filters: `error_target`, `error_message`, `error_category`, `error_action`
  • Supports grouping by target, action, category, or message
  • Includes timeline data with configurable metric (occurrence/test/branch) and top_n
  • Page-based pagination (page, limit)
  • Standard filters: tags[], branches[], groups[], authors[]
  • Special `tags_logical_operator` parameter (OR/AND)

Parameter Verification

All existing tools verified to match OpenAPI specification:

• Array parameters use bracket notation (`tags[]`, `branches[]`, `authors[]`, `groups[]`)
• Deprecated parameters NOT implemented (correctly using only current parameter names)
• Pagination: Cursor-based for most endpoints, page-based for explorers
• Required vs optional parameters match spec exactly
• Default values align with OpenAPI defaults
• Enum values match specification

No Breaking Changes

All existing tools maintain backward compatibility.

Verification

Build Status

```bash
npm run build

✓ TypeScript compilation successful

```

Test Results

```bash
npm test

✓ 3 test files passed (35 tests total)

✓ All request, project, and webhook tests passed

```

Code Quality

• TypeScript types properly defined
• Zod schemas match OpenAPI parameter specifications
• Error handling consistent across all tools
• Logging for all API operations

References

OpenAPI Specification

• Source: https://api.currents.dev/v1/docs/openapi.json
• Version: 1.0.0
• All 28 endpoint+method combinations verified

Result

28 REST API operations → 28 MCP tools (100% coverage)

---

Summary by cubic

Adds the Errors Explorer tool to currents-mcp, completing full parity with the Currents REST API. All 28 API operations now have matching MCP tools, with no breaking changes.

• New Features
  • currents-get-errors-explorer (GET /errors/{projectId}) with aggregated error metrics.
  • Filters: error_target, error_message, error_category, error_action.
  • Grouping: group_by[] for target, action, category, message; order_by and dir.
  • Timeline metrics: occurrence | test | branch; top_n cap.
  • Standard filters: tags[], branches[], authors[], groups[]; tags_logical_operator (OR/AND).
  • Page-based pagination: page, limit.

^{Written for commit 726fb65. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 5 files