1feature:
 2  name: api-client
 3  product: cooked-mcp
 4  description: Call Cooked's customer API predictably while hiding HTTP details from MCP tools.
 5components:
 6  REQUESTS:
 7    requirements:
 8      1: JSON Cooked requests send Content-Type application/json when they have a body.
 9      2: JSON Cooked requests send Accept application/json.
10      3: Cooked request paths are built without allowing malformed path joins.
11      4: Cooked query parameters are URL-encoded.
12      5: User-scoped Cooked API paths use the authenticated username from the login response.
13  ERRORS:
14    requirements:
15      1: Cooked API error responses are converted into concise user-facing MCP tool errors.
16      2: Cooked API errors include the HTTP status when available.
17      3: Cooked API errors include Cooked's error code when available.
18      4: Cooked API errors include Cooked's error message when available.
19      5: Cooked API error handling preserves enough detail for the agent to choose a follow-up action.
20      6: Cooked API error handling does not expose session cookies or credentials.
21  RESPONSES:
22    requirements:
23      1: Cooked API responses are decoded and validated for fields used by MCP tools before formatting.
24      2: Unknown fields in Cooked API responses do not break otherwise valid tool calls.
25      3: Unexpected Cooked response shapes are reported as recoverable tool errors when possible.
26constraints:
27  LIMITS:
28    requirements:
29      1: Cooked response bodies read for error reporting are bounded.
30      2: List-like MCP tool text responses are summarized instead of returning unbounded result sets.
31      3: When a response is truncated or paginated, the tool response says how to fetch more results.
32  VERIFICATION:
33    requirements:
34      1: API client behaviour is verified with fake Cooked HTTP servers.
35      2: API client tests do not contact the real Cooked service.