feat(mcp-server): unified error taxonomy & mapper (MCP Prompt 17)

[gilgardosh]

Summary

Implements Prompt 17 – Unified error taxonomy and mapper (see
docs/mcp/spec.md §10.2/§10.3). Centralizes all
failure handling in one taxonomy so every error source produces a consistent,
business-safe payload.

Stacked PR: targets claude/mcp-prompt-16-output-truncation (Prompt 16, #4017).
Review/merge Prompts 09→16 first; this diff shows only the Prompt 17 changes.

Changes

• src/errors/taxonomy.ts
  • Seven machine codes: VALIDATION_ERROR, AUTHENTICATION_ERROR, AUTHORIZATION_ERROR, UPSTREAM_ERROR, TIMEOUT_ERROR, RATE_LIMIT_ERROR, INTERNAL_ERROR.
  • McpError base (+ ToolInputError, RateLimitError) and DEFAULT_RETRYABLE per code.
  • toErrorPayload(error, correlationId) maps every source — McpError, UpstreamError, TokenVerificationError, and anything unexpected — into { code, message, correlationId, retryable, issues?, retryAfterMs? }. Unknown errors become a sanitized INTERNAL_ERROR (no stack traces / SQL / internal detail).
  • errorPayload(...) builder and toToolErrorResult(payload) renderer (isError: true).
• src/tools/execute.ts — refactored to build/render all failures through the taxonomy; the canonical ToolInputError now lives in the taxonomy and is re-exported here for tool handlers.
• Tests — every mapping branch (incl. sanitization + non-Error throwables), retryability defaults, isInternalError, and tool-result rendering. 191 tests total.

Validation

• yarn workspace @accounter/mcp-server test → 191 passed
• yarn workspace @accounter/mcp-server lint / typecheck / build → pass

Notes

• Behavior preserved: the tool-result shape is unchanged except retryable is now always present (spec wants a retryability hint on every error) and the generic internal message is sanitized.
• AUTHENTICATION_ERROR is available for tool-layer mapping (e.g. a TokenVerificationError bubbling up); the transport-level 401 challenge for unauthenticated POST /mcp (Prompt 07) is unchanged.
• RateLimitError / RATE_LIMIT_ERROR are defined here and consumed by the rate limiter in Prompt 18.

🤖 Generated with Claude Code

---

Generated by Claude Code

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.

[Copilot]

Pull request overview

Implements Prompt 17’s unified error taxonomy for the MCP server by centralizing error codes, retryability defaults, and mapping of diverse failure sources into a consistent, business-safe tool error payload.

Changes:

• Added src/errors/taxonomy.ts defining the canonical error codes/classes and the toErrorPayload/toToolErrorResult mapping pipeline.
• Refactored tool execution to route validation, authorization, and runtime failures through the taxonomy (including sanitized internal errors).
• Added unit tests for the mapper and updated MCP-server README to document the new error taxonomy and payload shape.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 2 comments.

File	Description
packages/mcp-server/src/tools/execute.ts	Refactors tool execution to render all failures via the centralized taxonomy helpers and logs only unmapped/internal failures.
packages/mcp-server/src/errors/taxonomy.ts	Introduces unified error taxonomy, error base classes, and mapping/rendering helpers for MCP tool error results.
packages/mcp-server/src/errors/tests/taxonomy.test.ts	Adds unit coverage for payload building, mapping branches, internal-error detection, and tool-result rendering.
packages/mcp-server/README.md	Updates documentation to describe the unified taxonomy and the extended structured error payload fields.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.