feat(mcp-server): hardened upstream GraphQL client (MCP Prompt 12)

[gilgardosh]

Summary

Implements Prompt 12 – GraphQL upstream client with timeout/retry guardrails
(see docs/mcp/spec.md §5.3, §10.3, §10.4). Adds
the single shared client that tool handlers use to reach the Accounter GraphQL
server.

Stacked PR: targets claude/mcp-prompt-11-policy-evaluator (Prompt 11, #4012).
Review/merge Prompts 05→11 first; this diff shows only the Prompt 12 changes.

Changes

• src/upstream/graphql-client.ts — UpstreamGraphQLClient:
  • Timeout + cancellation via AbortController (a per-call budget); an aborted request maps to a retryable TIMEOUT_ERROR.
  • Bounded retries for idempotent reads only — network errors, timeouts, and 5xx are retried up to maxRetries (default 2); 4xx (auth/validation) and GraphQL-level errors are never retried.
  • Header propagation — X-Correlation-Id and the caller's Authorization bearer token are forwarded; the raw token is never logged.
  • Sanitized errors — UpstreamError (UPSTREAM_ERROR / TIMEOUT_ERROR, retryable flag) with business-safe messages only (GraphQL error messages collapsed, capped; no stack traces / SQL).
  • Read-only guard — mutations/subscriptions are refused (phase-1 non-goal). createReadOperation is the only surface tools use — there is no generic execute-anything API.
• src/upstream/default-client.ts — env-backed, memoized client factory (endpoint + timeout from config).
• Tests — success + header propagation (correlation id & Authorization, omitted when absent), read-only guard, timeout mapping, retry eligibility (503 retried then success, 400/401 not retried, exhaustion on persistent 5xx), GraphQL-error sanitization, and a createReadOperation round-trip. 140 tests total.

Validation

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

Notes / open decisions

• Authorization forwarding. The prompt asks to forward the caller's bearer token upstream. The client accepts it via UpstreamRequestContext.authorization; populating it from the authenticated request (the token captured at verification time) is wired when the first real tool executes (Prompt 13). Forwarding the user's own token means upstream re-applies the exact same identity/tenant checks — defense in depth over the connector's own policy evaluator.
• Retry backoff. Retries are immediate (no delay) to stay within the tight tool-latency budget; if we want jittered backoff, that's a small follow-up. Retries are capped and only for idempotent reads, so this is safe.
• fetch-based (Node global) with an injectable fetchImpl for hermetic tests — no graphql-request dependency, keeping full control over timeout/retry/headers.

🤖 Generated with Claude Code

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request introduces a hardened, read-only upstream GraphQL client (UpstreamGraphQLClient) with built-in timeouts, bounded retries, header propagation, and error sanitization, along with comprehensive unit tests and a memoized default client instance. The review feedback highlights critical security and robustness improvements: addressing a potential bypass in the read-only query validation regex, adding defensive checks in sanitizeGraphQLErrors to prevent TypeErrors on malformed error arrays, and wrapping response.json() in a try-catch block to handle non-JSON responses gracefully.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

If any element in the errors array is null or not an object, accessing error.message will throw a raw TypeError, bypassing the error sanitization layer. Adding a safety check ensures robustness against malformed upstream error payloads.

Suggested change

	function sanitizeGraphQLErrors(errors: Array<{ message?: unknown }>): string {
	const messages = errors
	.map(error => (typeof error.message === 'string' ? error.message : ''))
	.map(message => message.trim())
	.filter(Boolean)
	.slice(0, 3);
	return messages.length > 0 ? messages.join('; ') : 'Upstream GraphQL error';
	}
	function sanitizeGraphQLErrors(errors: Array<{ message?: unknown }>): string {
	const messages = errors
	.map(error => (error && typeof error === 'object' && typeof error.message === 'string' ? error.message : ''))
	.map(message => message.trim())
	.filter(Boolean)
	.slice(0, 3);
	return messages.length > 0 ? messages.join('; ') : 'Upstream GraphQL error';
	}