Harmonize MCP Error Handling Across Tools and HTTP Parsing

[esgn]

Closes #35

Overview

This PR introduces a unified error contract for all MCP tools and improves upstream error parsing to make failures more consistent, actionable, and localized (French) across the project.

What Changed

• Added a shared BaseTool class and moved tool error response creation to a single normalization path.
• Introduced src/helpers/errors/ with:
  • toolError.ts for centralized error classification/normalization (invalid_tool_params, upstream, execution).
  • zodErrorMapFr.ts for French Zod messages, installed at module load to avoid first-call English messages.
• Refactored src/helpers/http.ts:
  • Reorganized file in runtime call order with improved top-level documentation.
  • Standardized ServiceResponseError shape to nested metadata (http + service).
  • Improved XML/JSON/HTML upstream error extraction and diagnostics.
  • Tightened JSON error field extraction to known, non-parasitic field lists.
• Updated tools to extend the new BaseTool so all tool failures share the same MCP structuredContent error contract.
• Updated WFS engine error checks to rely on instanceof ServiceResponseError.
• Updated MCP docs generation:
  • Excluded BaseTool from generated tool docs.
  • Added an auto-generated “MCP error contract” section in docs/mcp-tools.md.
  • Made docs:mcp run a build first to ensure docs are generated from current compiled tools.
• Expanded and aligned tests:
  • Added dedicated tests for toolError and BaseTool normalization.
  • Extended HTTP parser coverage (JSON/XML/HTML/non-2xx cases).
  • Aligned WFS tests to use the real ServiceResponseError constructor/signature.

Why

• Ensure clients receive a stable, machine-readable MCP error payload regardless of where a failure happens.
• Prevent misleading or inconsistent error details across tools.
• Improve observability and user-facing clarity for upstream service failures.
• Keep generated docs aligned with runtime behavior.

Validation

• npm run typecheck passes.
• npm test passes (124 tests).

Notes

• mcp-framework build output may still report Validated 11 tools successfully because its internal validator scans compiled files differently; runtime loading and docs generation explicitly exclude BaseTool.