Skip to content

refactor: Adopt respond* response constructors across tools #937

@jirispilka

Description

@jirispilka

Part of #935. One mechanical PR — independent of #936.

Goal

Introduce the respond* family and route every tool response through it. Mechanical substitution; wire output stays byte-identical so apify-mcp-server-internal sees no change.

Scope

  • Add to src/utils/mcp.ts:
    • respondOk(text, opts?) — success with text ({ structuredContent?, meta? })
    • respondJson(value, opts?) — success carrying JSON; owns the ```json fence
    • respondEmpty(text) — success, intentionally no data (thin alias of respondOk for now)
    • respondUserError(text, opts?)SOFT_FAIL; category defaults to INVALID_INPUT (Exclude<…, 'INTERNAL_ERROR'>), httpStatus?, detail?, structuredContent?
    • respondServerError(text, opts?)FAILED; pass the caught error, category/httpStatus derived via existing classifyFailureCategory / getHttpStatusCode
  • Migrate all src/tools handlers + the inline error paths in src/mcp/server.ts.
  • Delete the 6 domain builders: buildActorNotFoundResponse, buildSearchActorsEmptyResponse, buildPermissionApprovalResponse, buildPermissionApprovalErrorResponse, buildGetActorRunError, buildCallActorErrorResponse, plus the inline storage not-found literals.
  • Un-export buildMCPResponse (make it private to utils/mcp.ts); shrink extractToolTelemetry accordingly.
  • Collapse the ~8 hand-rolled ```json fences into respondJson.

Fixes within this PR

  • P2respondServerError fills failureCategory by default → no more "category unknown".
  • P3 — the 10 duplicated SOFT_FAIL + INVALID_INPUT literals collapse into respondUserError.

Out of scope

  • The brand + narrowing ToolEntry.call (the compile-time lock) — separate sub-issue. call stays Promise<object> here.
  • A real NO_DATA telemetry status (P5).

Acceptance

  • No remaining call sites build raw response shapes or inline JSON fences.
  • pnpm run type-check, pnpm run lint, pnpm run test:unit clean; assertions migrated to the respond* shapes.

Metadata

Metadata

Assignees

No one assigned

    Labels

    t-aiIssues owned by the AI team.

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions