@cyanheads/mcp-ts-core 0.1.29 → 0.2.1

package/dist/utils/network/retry.d.ts

@@ -0,0 +1,83 @@
+import type { RequestContext } from '../../utils/internal/requestContext.js';
+/** Configuration for {@link withRetry}. */
+export interface RetryOptions {
+    /**
+     * Base delay in milliseconds before the first retry.
+     * Subsequent delays are `baseDelayMs * 2^attempt`. Default: `1000`.
+     *
+     * Calibrate to the upstream's recovery time:
+     * - 200–500ms for ephemeral failures (connection pool)
+     * - 1–2s for rate-limited APIs
+     * - 2–5s for service degradation / outages
+     */
+    baseDelayMs?: number;
+    /**
+     * Request context for correlated logging. When provided, log entries
+     * include `requestId`, `traceId`, etc.
+     */
+    context?: RequestContext;
+    /**
+     * Custom predicate to determine if an error is transient and should be
+     * retried. When provided, this replaces the default `McpError` code check.
+     * Return `true` to retry, `false` to fail immediately.
+     */
+    isTransient?: (error: unknown) => boolean;
+    /**
+     * Jitter factor applied to each delay. `0` = no jitter, `1` = full jitter
+     * (delay randomized between 0 and calculated delay). Default: `0.25`.
+     */
+    jitter?: number;
+    /**
+     * Maximum delay cap in milliseconds. Prevents unbounded growth on high
+     * retry counts. Default: `30000` (30s).
+     */
+    maxDelayMs?: number;
+    /**
+     * Maximum number of retry attempts after the initial call.
+     * Total attempts = `maxRetries + 1`. Default: `3`.
+     */
+    maxRetries?: number;
+    /**
+     * Operation name for structured log messages. Used in log context and
+     * enriched error messages on exhaustion.
+     */
+    operation?: string;
+    /**
+     * Optional AbortSignal. When aborted, the retry loop exits immediately
+     * without further attempts.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Executes `fn` with retry logic and exponential backoff.
+ *
+ * The retry boundary should wrap the **full pipeline** — HTTP fetch, response
+ * parsing, and validation — not just the network call. This ensures that
+ * transient upstream errors (e.g., HTTP 200 with an error body) are retried.
+ *
+ * When retries exhaust, the final error is enriched with attempt count in both
+ * the message and structured data, so callers know retries were already attempted.
+ *
+ * @typeParam T - Return type of the operation.
+ * @param fn - The async operation to execute with retries.
+ * @param options - Retry configuration. All fields optional with sensible defaults.
+ * @returns The result of `fn` on success.
+ * @throws The enriched final error when all attempts are exhausted, or the original
+ *   error immediately if it is not classified as transient.
+ *
+ * @example
+ * ```ts
+ * // Service method — retry covers fetch + parse
+ * async function fetchStudy(id: string, ctx: Context): Promise<Study> {
+ *   return withRetry(
+ *     async () => {
+ *       const text = await apiClient.get(`/studies/${id}`);
+ *       return responseHandler.parse<Study>(text);
+ *     },
+ *     { operation: 'fetchStudy', context: ctx, baseDelayMs: 1000 },
+ *   );
+ * }
+ * ```
+ */
+export declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/utils/network/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAYzE,2CAA2C;AAC3C,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAC;IAEzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC;IAE1C;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;OAGG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AA6DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAiD/F"}

package/dist/utils/network/retry.js

@@ -0,0 +1,152 @@
+/**
+ * @fileoverview Retry utility with exponential backoff for wrapping operations that
+ * may fail transiently. Designed so the retry boundary covers the full pipeline
+ * (HTTP fetch + response parsing/validation), not just the network call.
+ * @module src/utils/network/retry
+ * @see docs/service-resilience.md
+ */
+import { JsonRpcErrorCode, McpError } from '../../types-global/errors.js';
+import { logger } from '../../utils/internal/logger.js';
+/**
+ * Error codes considered transient — eligible for retry.
+ * Matches the framework's error classification in `mappings.ts`.
+ */
+const TRANSIENT_CODES = new Set([
+    JsonRpcErrorCode.ServiceUnavailable,
+    JsonRpcErrorCode.Timeout,
+    JsonRpcErrorCode.RateLimited,
+]);
+/**
+ * Computes the backoff delay for a given attempt with optional jitter.
+ *
+ * @param attempt - Zero-based attempt index (0 = first retry).
+ * @param baseDelayMs - Base delay in milliseconds.
+ * @param maxDelayMs - Maximum delay cap.
+ * @param jitter - Jitter factor (0–1).
+ * @returns Delay in milliseconds.
+ */
+function computeDelay(attempt, baseDelayMs, maxDelayMs, jitter) {
+    const exponential = Math.min(baseDelayMs * 2 ** attempt, maxDelayMs);
+    if (jitter <= 0)
+        return exponential;
+    const jitterRange = exponential * jitter;
+    return exponential - jitterRange + Math.random() * jitterRange * 2;
+}
+/**
+ * Default transient check: `McpError` with a transient code, or any non-McpError
+ * (network failures, unexpected throws) which are assumed transient.
+ */
+function defaultIsTransient(error) {
+    if (error instanceof McpError) {
+        return TRANSIENT_CODES.has(error.code);
+    }
+    // Non-McpError (raw network errors, unexpected throws) — assume transient
+    return true;
+}
+/**
+ * Enriches an error with retry exhaustion context.
+ * Appends attempt count to the message and to `data` for programmatic access.
+ */
+function enrichExhaustedError(error, totalAttempts, operation) {
+    if (error instanceof McpError) {
+        const suffix = `(failed after ${totalAttempts} attempt${totalAttempts > 1 ? 's' : ''})`;
+        const enrichedMessage = error.message ? `${error.message} ${suffix}` : suffix;
+        const enrichedData = {
+            ...error.data,
+            retryAttempts: totalAttempts,
+            ...(operation ? { operation } : {}),
+        };
+        return new McpError(error.code, enrichedMessage, enrichedData, { cause: error });
+    }
+    if (error instanceof Error) {
+        const suffix = `(failed after ${totalAttempts} attempt${totalAttempts > 1 ? 's' : ''})`;
+        const wrapped = new Error(`${error.message} ${suffix}`, { cause: error });
+        wrapped.name = error.name;
+        return wrapped;
+    }
+    return error;
+}
+/**
+ * Executes `fn` with retry logic and exponential backoff.
+ *
+ * The retry boundary should wrap the **full pipeline** — HTTP fetch, response
+ * parsing, and validation — not just the network call. This ensures that
+ * transient upstream errors (e.g., HTTP 200 with an error body) are retried.
+ *
+ * When retries exhaust, the final error is enriched with attempt count in both
+ * the message and structured data, so callers know retries were already attempted.
+ *
+ * @typeParam T - Return type of the operation.
+ * @param fn - The async operation to execute with retries.
+ * @param options - Retry configuration. All fields optional with sensible defaults.
+ * @returns The result of `fn` on success.
+ * @throws The enriched final error when all attempts are exhausted, or the original
+ *   error immediately if it is not classified as transient.
+ *
+ * @example
+ * ```ts
+ * // Service method — retry covers fetch + parse
+ * async function fetchStudy(id: string, ctx: Context): Promise<Study> {
+ *   return withRetry(
+ *     async () => {
+ *       const text = await apiClient.get(`/studies/${id}`);
+ *       return responseHandler.parse<Study>(text);
+ *     },
+ *     { operation: 'fetchStudy', context: ctx, baseDelayMs: 1000 },
+ *   );
+ * }
+ * ```
+ */
+export async function withRetry(fn, options = {}) {
+    const { maxRetries = 3, baseDelayMs = 1000, maxDelayMs = 30_000, jitter = 0.25, operation, context, signal, isTransient = defaultIsTransient, } = options;
+    const totalAttempts = maxRetries + 1;
+    for (let attempt = 0; attempt < totalAttempts; attempt++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            // Abort signal — exit immediately, no more retries
+            if (signal?.aborted) {
+                throw error;
+            }
+            const isLastAttempt = attempt >= maxRetries;
+            // Non-transient errors fail immediately
+            if (!isTransient(error)) {
+                throw error;
+            }
+            if (isLastAttempt) {
+                throw enrichExhaustedError(error, totalAttempts, operation);
+            }
+            // Log and backoff
+            const delay = computeDelay(attempt, baseDelayMs, maxDelayMs, jitter);
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            logger.debug(`Retry ${attempt + 1}/${maxRetries} for ${operation ?? 'operation'}: ${errorMessage} — waiting ${Math.round(delay)}ms`, context);
+            await sleep(delay, signal);
+        }
+    }
+    // Unreachable — the loop always returns or throws
+    throw new McpError(JsonRpcErrorCode.InternalError, 'withRetry: unexpected loop exit');
+}
+/** Sleeps for the given duration, aborting early if the signal fires. */
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted) {
+            reject(signal.reason);
+            return;
+        }
+        let onAbort;
+        const timer = setTimeout(() => {
+            if (onAbort)
+                signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        if (signal) {
+            onAbort = () => {
+                clearTimeout(timer);
+                reject(signal.reason);
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+        }
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/utils/network/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/utils/network/retry.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACtE,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AAGpD;;;GAGG;AACH,MAAM,eAAe,GAAG,IAAI,GAAG,CAAmB;IAChD,gBAAgB,CAAC,kBAAkB;IACnC,gBAAgB,CAAC,OAAO;IACxB,gBAAgB,CAAC,WAAW;CAC7B,CAAC,CAAC;AA0DH;;;;;;;;GAQG;AACH,SAAS,YAAY,CACnB,OAAe,EACf,WAAmB,EACnB,UAAkB,EAClB,MAAc;IAEd,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,WAAW,GAAG,CAAC,IAAI,OAAO,EAAE,UAAU,CAAC,CAAC;IACrE,IAAI,MAAM,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC;IACpC,MAAM,WAAW,GAAG,WAAW,GAAG,MAAM,CAAC;IACzC,OAAO,WAAW,GAAG,WAAW,GAAG,IAAI,CAAC,MAAM,EAAE,GAAG,WAAW,GAAG,CAAC,CAAC;AACrE,CAAC;AAED;;;GAGG;AACH,SAAS,kBAAkB,CAAC,KAAc;IACxC,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,OAAO,eAAe,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC;IACD,0EAA0E;IAC1E,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,KAAc,EAAE,aAAqB,EAAE,SAAkB;IACrF,IAAI,KAAK,YAAY,QAAQ,EAAE,CAAC;QAC9B,MAAM,MAAM,GAAG,iBAAiB,aAAa,WAAW,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACxF,MAAM,eAAe,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC;QAC9E,MAAM,YAAY,GAA4B;YAC5C,GAAG,KAAK,CAAC,IAAI;YACb,aAAa,EAAE,aAAa;YAC5B,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACpC,CAAC;QACF,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,eAAe,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;IACnF,CAAC;IAED,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,MAAM,MAAM,GAAG,iBAAiB,aAAa,WAAW,aAAa,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC;QACxF,MAAM,OAAO,GAAG,IAAI,KAAK,CAAC,GAAG,KAAK,CAAC,OAAO,IAAI,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;QAC1E,OAAO,CAAC,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC;QAC1B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAI,EAAoB,EAAE,UAAwB,EAAE;IACjF,MAAM,EACJ,UAAU,GAAG,CAAC,EACd,WAAW,GAAG,IAAI,EAClB,UAAU,GAAG,MAAM,EACnB,MAAM,GAAG,IAAI,EACb,SAAS,EACT,OAAO,EACP,MAAM,EACN,WAAW,GAAG,kBAAkB,GACjC,GAAG,OAAO,CAAC;IAEZ,MAAM,aAAa,GAAG,UAAU,GAAG,CAAC,CAAC;IAErC,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,GAAG,aAAa,EAAE,OAAO,EAAE,EAAE,CAAC;QACzD,IAAI,CAAC;YACH,OAAO,MAAM,EAAE,EAAE,CAAC;QACpB,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,mDAAmD;YACnD,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC;YACd,CAAC;YAED,MAAM,aAAa,GAAG,OAAO,IAAI,UAAU,CAAC;YAE5C,wCAAwC;YACxC,IAAI,CAAC,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC;gBACxB,MAAM,KAAK,CAAC;YACd,CAAC;YAED,IAAI,aAAa,EAAE,CAAC;gBAClB,MAAM,oBAAoB,CAAC,KAAK,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC;YAC9D,CAAC;YAED,kBAAkB;YAClB,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;YACrE,MAAM,YAAY,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;YAE5E,MAAM,CAAC,KAAK,CACV,SAAS,OAAO,GAAG,CAAC,IAAI,UAAU,QAAQ,SAAS,IAAI,WAAW,KAAK,YAAY,cAAc,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,EACtH,OAAO,CACR,CAAC;YAEF,MAAM,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;IACH,CAAC;IAED,kDAAkD;IAClD,MAAM,IAAI,QAAQ,CAAC,gBAAgB,CAAC,aAAa,EAAE,iCAAiC,CAAC,CAAC;AACxF,CAAC;AAED,yEAAyE;AACzE,SAAS,KAAK,CAAC,EAAU,EAAE,MAAoB;IAC7C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACtB,OAAO;QACT,CAAC;QAED,IAAI,OAAiC,CAAC;QAEtC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,IAAI,OAAO;gBAAE,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YAC3D,OAAO,EAAE,CAAC;QACZ,CAAC,EAAE,EAAE,CAAC,CAAC;QAEP,IAAI,MAAM,EAAE,CAAC;YACX,OAAO,GAAG,GAAG,EAAE;gBACb,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;YACxB,CAAC,CAAC;YACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QAC5D,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/parsing/xmlParser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"xmlParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/xmlParser.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAchG;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CA6DlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}
+{"version":3,"file":"xmlParser.d.ts","sourceRoot":"","sources":["../../../src/utils/parsing/xmlParser.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,KAAK,cAAc,EAAyB,MAAM,oCAAoC,CAAC;AAoBhG;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACG,KAAK,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,CAAC,CAAC;CA6DlF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,SAAS,WAAkB,CAAC"}

package/dist/utils/parsing/xmlParser.js

@@ -15,7 +15,9 @@ import { thinkBlockRegex } from './thinkBlock.js';
 let _fxp;
 let _xmlParserInstance;
 async function getFxp() {
-    _fxp ??= await import('fast-xml-parser').catch(() => {
+    if (_fxp)
+        return _fxp;
+    _fxp = await import('fast-xml-parser').catch(() => {
         throw configurationError('Install "fast-xml-parser" to use XML parsing: bun add fast-xml-parser');
     });
     return _fxp;

package/dist/utils/parsing/xmlParser.js.map

@@ -1 +1 @@
-{"version":3,"file":"xmlParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/xmlParser.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"xmlParser.js","sourceRoot":"","sources":["../../../src/utils/parsing/xmlParser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC/E,OAAO,EAAE,MAAM,EAAE,MAAM,4BAA4B,CAAC;AACpD,OAAO,EAAuB,qBAAqB,EAAE,MAAM,oCAAoC,CAAC;AAChG,OAAO,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAMlD,IAAI,IAA2B,CAAC;AAChC,IAAI,kBAAgE,CAAC;AAErE,KAAK,UAAU,MAAM;IACnB,IAAI,IAAI;QAAE,OAAO,IAAI,CAAC;IACtB,IAAI,GAAG,MAAO,MAAM,CAAC,iBAAiB,CAAwB,CAAC,KAAK,CAAC,GAAG,EAAE;QACxE,MAAM,kBAAkB,CACtB,uEAAuE,CACxE,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,OAAO,SAAS;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,KAAK,CAAC,KAAK,CAAc,SAAiB,EAAE,OAAwB;QAClE,IAAI,aAAa,GAAG,SAAS,CAAC;QAC9B,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC;QAE/C,IAAI,KAAK,EAAE,CAAC;YACV,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAEpC,MAAM,UAAU,GACd,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,sBAAsB;iBAClC,CAAC,CAAC;YACL,IAAI,YAAY,EAAE,CAAC;gBACjB,MAAM,CAAC,KAAK,CAAC,wCAAwC,EAAE;oBACrD,GAAG,UAAU;oBACb,YAAY;iBACb,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,KAAK,CAAC,mCAAmC,EAAE,UAAU,CAAC,CAAC;YAChE,CAAC;YACD,aAAa,GAAG,YAAY,CAAC;QAC/B,CAAC;QAED,aAAa,GAAG,aAAa,CAAC,IAAI,EAAE,CAAC;QAErC,IAAI,CAAC,aAAa,EAAE,CAAC;YACnB,MAAM,eAAe,CACnB,gEAAgE,EAChE,OAAO,CACR,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,MAAM,EAAE,CAAC;YAC3B,kBAAkB,KAAK,IAAI,GAAG,CAAC,SAAS,CAAC;gBACvC,eAAe,EAAE,KAAK;gBACtB,YAAY,EAAE,KAAK;aACpB,CAAC,CAAC;YACH,OAAO,kBAAkB,CAAC,KAAK,CAAC,aAAa,CAAM,CAAC;QACtD,CAAC;QAAC,OAAO,CAAU,EAAE,CAAC;YACpB,MAAM,KAAK,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YAC5D,MAAM,eAAe,GACnB,OAAO;gBACP,qBAAqB,CAAC,oBAAoB,CAAC;oBACzC,SAAS,EAAE,sBAAsB;iBAClC,CAAC,CAAC;YACL,MAAM,CAAC,KAAK,CAAC,8BAA8B,EAAE;gBAC3C,GAAG,eAAe;gBAClB,YAAY,EAAE,KAAK,CAAC,OAAO;gBAC3B,gBAAgB,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC;aAClD,CAAC,CAAC;YAEH,MAAM,eAAe,CAAC,wBAAwB,KAAK,CAAC,OAAO,EAAE,EAAE;gBAC7D,GAAG,OAAO;gBACV,qBAAqB,EACnB,aAAa,CAAC,SAAS,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,aAAa,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7E,QAAQ,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;aAC/D,CAAC,CAAC;QACL,CAAC;IACH,CAAC;CACF;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,SAAS,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cyanheads/mcp-ts-core",
-  "version": "0.1.29",
+  "version": "0.2.1",
   "mcpName": "io.github.cyanheads/mcp-ts-core",
   "description": "Agent-native TypeScript framework for building MCP servers. Build tools, not infrastructure. Declarative definitions with auth, multi-backend storage, OpenTelemetry, and first-class support for Node.js and Cloudflare Workers.",
   "main": "dist/core/index.js",
@@ -83,6 +83,10 @@
       "types": "./dist/testing/index.d.ts",
       "import": "./dist/testing/index.js"
     },
+    "./testing/fuzz": {
+      "types": "./dist/testing/fuzz.d.ts",
+      "import": "./dist/testing/fuzz.js"
+    },
     "./tsconfig.base.json": "./tsconfig.base.json",
     "./vitest.config": "./vitest.config.base.ts",
     "./biome": "./biome.json",

package/skills/add-service/SKILL.md

@@ -98,6 +98,58 @@ handler: async (input, ctx) => {
 },
 ```
 
+## Resilience (External API Services)
+
+When a service wraps an external API, apply these patterns. See `docs/service-resilience.md` for full rationale.
+
+### Retry wraps the full pipeline
+
+Place retry at the service method level — covering both HTTP fetch and response parsing/validation. The HTTP client should be single-attempt; the service owns retry. Use `withRetry` from `@cyanheads/mcp-ts-core/utils`:
+
+```typescript
+import { withRetry, fetchWithTimeout } from '@cyanheads/mcp-ts-core/utils';
+import type { Context } from '@cyanheads/mcp-ts-core';
+
+async fetchItem(id: string, ctx: Context): Promise<Item> {
+  return withRetry(
+    async () => {
+      const response = await fetchWithTimeout(
+        `${this.baseUrl}/items/${id}`,
+        10_000,
+        ctx,
+      );
+      const text = await response.text();
+      return this.parseResponse<Item>(text);
+    },
+    {
+      operation: 'fetchItem',
+      context: ctx,
+      baseDelayMs: 1000,    // calibrate to upstream recovery time
+      signal: ctx.signal,
+    },
+  );
+}
+```
+
+### Key principles
+
+1. **Calibrate backoff to the upstream.** 200–500ms for ephemeral failures, 1–2s for rate-limited APIs, 2–5s for service degradation. The default `baseDelayMs: 1000` suits most APIs.
+2. **Check HTTP status before parsing.** `fetchWithTimeout` already throws `ServiceUnavailable` on non-OK responses — this prevents feeding HTML error pages into XML/JSON parsers.
+3. **Classify parse failures by content.** If the upstream returns HTTP 200 with an HTML error page, detect it and throw `ServiceUnavailable` (transient) instead of `SerializationError` (non-transient).
+4. **Exhausted retries say so.** `withRetry` automatically enriches the final error with attempt count — callers know retries were already attempted.
+
+### Response handler pattern
+
+```typescript
+parseResponse<T>(text: string): T {
+  // Detect HTML error pages masquerading as successful responses
+  if (/^\s*<(!DOCTYPE\s+html|html[\s>])/i.test(text)) {
+    throw serviceUnavailable('API returned HTML instead of expected format — likely rate-limited.');
+  }
+  // Parse and validate...
+}
+```
+
 ## Checklist
 
 - [ ] Directory created at `src/services/{{domain}}/`
@@ -106,4 +158,5 @@ handler: async (input, ctx) => {
 - [ ] Service methods accept `Context` for logging and storage
 - [ ] `init` function registered in `setup()` callback in `src/index.ts`
 - [ ] Accessor throws `Error` if not initialized
+- [ ] If wrapping external API: retry covers full pipeline (fetch + parse), backoff calibrated
 - [ ] `bun run devcheck` passes

package/skills/api-utils/SKILL.md

@@ -30,6 +30,7 @@ Utility exports from `@cyanheads/mcp-ts-core/utils`. Utilities with complex APIs
 | Export | API | Notes |
 |:-------|:----|:------|
 | `fetchWithTimeout` | `(url, timeoutMs, context: RequestContext, options?: FetchWithTimeoutOptions) -> Promise<Response>` | Wraps `fetch` with `AbortController` timeout. `FetchWithTimeoutOptions` extends `RequestInit` (minus `signal`) and adds `rejectPrivateIPs?: boolean` and `signal?: AbortSignal` (external cancellation). SSRF protection: blocks RFC 1918, loopback, link-local, CGNAT, cloud metadata. DNS validation on Node; hostname-only on Workers. Manual redirect following (max 5) with per-hop SSRF check. |
+| `withRetry` | `<T>(fn: () => Promise<T>, options?: RetryOptions) -> Promise<T>` | Executes `fn` with exponential backoff. Retries on transient errors (`ServiceUnavailable`, `Timeout`, `RateLimited`); non-transient errors fail immediately. On exhaustion, enriches the final error with attempt count in message and `data.retryAttempts`. **Place the retry boundary around the full pipeline** (fetch + parse), not just the network call. See `docs/service-resilience.md`. `RetryOptions`: `maxRetries` (default `3`), `baseDelayMs` (default `1000`), `maxDelayMs` (default `30000`), `jitter` (default `0.25`), `operation` (log label), `context` (RequestContext), `signal` (AbortSignal), `isTransient` (custom predicate). |
 
 ---
 

package/skills/design-mcp-server/SKILL.md

@@ -269,6 +269,16 @@ Skip for purely data/action-oriented servers.
 
 **Services** — one per external dependency. Init/accessor pattern. Skip if all tools are thin wrappers with no shared state.
 
+For services wrapping external APIs, plan the resilience layer. See `docs/service-resilience.md` for full rationale.
+
+| Concern | Decision |
+|:--------|:---------|
+| **Retry boundary** | Service method wraps full pipeline (fetch + parse), not just the network call. Use `withRetry` from `/utils`. |
+| **Backoff calibration** | Match base delay to upstream recovery time: 200–500ms (ephemeral), 1–2s (rate-limited), 2–5s (degraded). |
+| **HTTP status check** | `fetchWithTimeout` already handles this — non-OK → `ServiceUnavailable`. |
+| **Parse failure classification** | Response handler detects HTML error pages and throws transient errors, not `SerializationError`. |
+| **Exhausted retry messaging** | `withRetry` enriches the final error with attempt count automatically. |
+
 **Config** — list env vars (API keys, base URLs). Goes in `src/config/server-config.ts` as a separate Zod schema.
 
 ### 8. Write the Design Doc
@@ -358,6 +368,7 @@ Execute the plan using the scaffolding skills:
 - [ ] Annotations set correctly (`readOnlyHint`, `destructiveHint`, etc.)
 - [ ] Resource URIs use `{param}` templates, pagination planned for large lists
 - [ ] Service layer planned (or explicitly skipped with reasoning)
+- [ ] Resilience planned for external API services (retry boundary, backoff, parse classification)
 - [ ] Server config env vars identified
 - [ ] Design doc written to `docs/design.md`
 - [ ] Design confirmed with user (or user pre-authorized implementation)

package/skills/report-issue-framework/SKILL.md

@@ -0,0 +1,223 @@
+---
+name: report-issue-framework
+description: >
+  File a bug or feature request against @cyanheads/mcp-ts-core when you hit a framework issue. Use when a builder, utility, context method, or config behaves contrary to the documented API — not for server-specific application bugs.
+metadata:
+  author: cyanheads
+  version: "1.1"
+  audience: external
+  type: workflow
+---
+
+## When to Use
+
+You've isolated a problem to `@cyanheads/mcp-ts-core` itself — not your server code, not a misconfiguration, not a missing peer dependency. Typical triggers:
+
+- Framework builder (`tool()`, `resource()`, `prompt()`) rejects valid input or produces incorrect output
+- `createApp()` or `createWorkerHandler()` fails on a valid config
+- `Context` properties (`ctx.log`, `ctx.state`, `ctx.elicit`, etc.) behave contrary to docs
+- A utility from `/utils`, `/errors`, `/auth`, `/storage`, `/services` returns wrong results or throws unexpectedly
+- Type exports are incorrect or missing (compile error on documented usage)
+- The definition linter (`bun run lint:mcp`) produces false positives or misses real violations
+
+## Before Filing
+
+1. **Confirm framework version** — `bun pm ls @cyanheads/mcp-ts-core` or check `node_modules/@cyanheads/mcp-ts-core/package.json`
+2. **Check you're on latest** — `bun outdated @cyanheads/mcp-ts-core`. If behind, update and retest before filing.
+3. **Isolate the issue** — reproduce with a minimal handler or standalone script. Strip server-specific services, config, and dependencies. If the bug disappears when isolated, it's likely in your server code.
+4. **Search existing issues** — don't file duplicates:
+
+```bash
+gh issue list -R cyanheads/mcp-ts-core --search "your error message or keyword"
+```
+
+## Redact Before Posting
+
+GitHub issues are **public**. Do not include secrets, credentials, API keys, or tokens. Redact sensitive values from env vars, headers, and logs before submitting. Replace with obvious placeholders: `REDACTED`, `sk-...REDACTED`. Do not rely on partial masking — partial keys can still be exploited.
+
+## Filing a Bug
+
+The repo has YAML form issue templates. Use `--web` to open the form in the browser (preferred when available), or pass `--title` + `--body` for non-interactive use.
+
+### Browser (interactive)
+
+```bash
+gh issue create -R cyanheads/mcp-ts-core --template "Bug Report" --web
+```
+
+### CLI (non-interactive)
+
+Structure the `--body` to match the template's form fields:
+
+````bash
+gh issue create -R cyanheads/mcp-ts-core \
+  --title "bug(scope): concise description" \
+  --label "bug" \
+  --body "$(cat <<'ISSUE'
+### mcp-ts-core version
+
+0.1.29
+
+### Runtime
+
+Bun
+
+### Runtime version
+
+Bun 1.2.x
+
+### Transport
+
+stdio
+
+### OS
+
+macOS 15.x
+
+### Description
+
+Brief explanation of the bug — what you expected vs what happened.
+
+### Reproduction
+
+```ts
+import { tool, z } from '@cyanheads/mcp-ts-core';
+
+export const broken = tool('broken_example', {
+  description: 'Minimal repro.',
+  input: z.object({ id: z.string().describe('ID') }),
+  output: z.object({
+    name: z.string().describe('Name'),
+    extra: z.string().optional().describe('Optional field'),
+  }),
+  async handler(input, ctx) {
+    return { name: 'test' }; // omitting optional field causes validation error
+  },
+});
+```
+
+### Actual behavior
+
+```
+Error: Output validation failed: ...
+```
+
+### Expected behavior
+
+Omitting an optional output field should pass validation.
+
+### Additional context
+
+Any workarounds, related issues, or observations.
+ISSUE
+)"
+````
+
+### Title conventions
+
+Format: `bug(<scope>): concise description`
+
+| Scope | When |
+|:------|:-----|
+| `tool` | Tool builder, handler, format, annotations |
+| `resource` | Resource builder, handler, list, params |
+| `prompt` | Prompt builder, generate, args |
+| `context` | Context, logger, state, progress, elicit, sample |
+| `config` | AppConfig, parseConfig, env parsing |
+| `errors` | McpError, error factories, auto-classification |
+| `auth` | Auth modes, scope checking, JWT/OAuth |
+| `storage` | StorageService, providers |
+| `transport` | stdio/http transport, SSE, session handling |
+| `worker` | createWorkerHandler, Worker runtime |
+| `utils` | Utilities (formatting, parsing, pagination, etc.) |
+| `linter` | Definition linter false positives/negatives |
+| `types` | Type exports, type inference |
+| `services` | LLM, Speech, Graph services |
+| `deps` | Dependency issues, peer dep conflicts |
+
+### Labels
+
+| Label | When |
+|:------|:-----|
+| `bug` | Something broken |
+| `regression` | Worked before, broken after update |
+| `types` | TypeScript type issue |
+| `docs` | Documentation is wrong or misleading |
+| `enhancement` | Feature request or improvement (not a bug) |
+
+Combine labels: `--label "bug" --label "types"`.
+
+### Attaching logs or stack traces
+
+For long output, write to a file and attach:
+
+```bash
+bun run dev:stdio 2>&1 | head -100 > /tmp/mcp-error.log
+
+# As part of a new issue
+gh issue create -R cyanheads/mcp-ts-core \
+  --title "bug(transport): stdio crashes on large payload" \
+  --label "bug" \
+  --body-file /tmp/mcp-error.log
+
+# Or as a comment on an existing issue
+gh issue comment <number> -R cyanheads/mcp-ts-core --body-file /tmp/mcp-error.log
+```
+
+## Filing a Feature Request
+
+### Browser (interactive)
+
+```bash
+gh issue create -R cyanheads/mcp-ts-core --template "Feature Request" --web
+```
+
+### CLI (non-interactive)
+
+````bash
+gh issue create -R cyanheads/mcp-ts-core \
+  --title "feat(scope): concise description" \
+  --label "enhancement" \
+  --body "$(cat <<'ISSUE'
+### Use case
+
+Describe the problem you're solving and why the framework should handle it.
+
+### Proposed API
+
+```ts
+import { withRetry } from '@cyanheads/mcp-ts-core/utils';
+
+const result = await withRetry(() => fetchExternal(url), {
+  maxAttempts: 3,
+  backoff: 'exponential',
+});
+```
+
+### Alternatives considered
+
+What you tried or considered instead.
+ISSUE
+)"
+````
+
+## Following Up
+
+```bash
+# Check issue status
+gh issue view <number> -R cyanheads/mcp-ts-core
+
+# Add context or respond to maintainer questions
+gh issue comment <number> -R cyanheads/mcp-ts-core --body "Additional context..."
+
+# List your open issues
+gh issue list -R cyanheads/mcp-ts-core --author @me
+```
+
+## Checklist
+
+- [ ] Confirmed bug is in `@cyanheads/mcp-ts-core`, not server code
+- [ ] Running latest (or documented) framework version
+- [ ] Searched existing issues — no duplicate found
+- [ ] All secrets, credentials, and tokens redacted
+- [ ] Issue filed with: version, runtime, repro code, actual vs expected behavior