@deotio/mcp-sigv4-proxy 0.3.0 → 0.4.1

package/README.md

@@ -32,7 +32,8 @@ stdin (JSON-RPC) -> validate -> SigV4 sign -> HTTPS POST -> response relay -> st
 2. Validates each message is well-formed JSON-RPC 2.0
 3. Signs the request with AWS SigV4 using the configured credentials
 4. Forwards to the target MCP endpoint via HTTPS (with configurable timeout and retries)
-5. Relays the response (JSON or SSE stream) back to stdout
+5. Retries on HTTP 5xx and 424 (AgentCore cold-start timeout) with exponential backoff
+6. Relays the response (JSON or SSE stream) back to stdout
 
 ## Environment variables
 
@@ -43,8 +44,9 @@ stdin (JSON-RPC) -> validate -> SigV4 sign -> HTTPS POST -> response relay -> st
 | `AWS_REGION` | no | inferred from URL, then `us-east-1` | AWS region for SigV4 signing |
 | `AWS_SERVICE` | no | inferred from URL, then `bedrock-agentcore` | SigV4 service name |
 | `MCP_TIMEOUT` | no | `180` | Request timeout in seconds |
-| `MCP_RETRIES` | no | `0` | Retry count for 5xx errors and network failures (0-10) |
+| `MCP_RETRIES` | no | `2` | Retry count for 5xx/424 errors and network failures (0-10) |
 | `MCP_LOG_LEVEL` | no | `ERROR` | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `SILENT` |
+| `MCP_WARM` | no | `0` | Set to `1` to enable [warm mode](doc/configuration.md#warm-mode) for slow-starting backends |
 
 ## Prerequisites
 
@@ -59,7 +61,7 @@ bedrock-agentcore:InvokeAgentRuntime
 - **HTTPS-only** — `MCP_SERVER_URL` must use `https://`. The only exception is `http://localhost` / `http://127.0.0.1` for local development.
 - **TLS enforcement** — the proxy refuses to start if `NODE_TLS_REJECT_UNAUTHORIZED=0` is set, since it sends signed AWS credentials.
 - **Input validation** — only well-formed JSON-RPC 2.0 messages are signed and forwarded.
-- **Sanitized errors** — HTTP error bodies from the upstream are logged to stderr, not forwarded to the MCP client. Only the status code is relayed.
+- **Informative errors** — HTTP error responses include the upstream error message (e.g. `HTTP 403: User is not authorized`) in the JSON-RPC error for easier debugging. Full response bodies are logged to stderr.
 - **Buffer limits** — SSE streams are capped at 1 MB to prevent unbounded memory growth.
 
 ## Documentation

package/dist/proxy.js

@@ -8,6 +8,10 @@ const DEFAULT_TIMEOUT_MS = 180_000; // 180s, matches AWS proxy
 const DEFAULT_RETRIES = 2;
 const RETRY_BASE_MS = 1000;
 const COLD_START_RETRY_MS = 5000;
+// Warm mode defaults
+const DEFAULT_WARM_RETRIES = 5;
+const DEFAULT_WARM_RETRY_DELAY_MS = 10_000;
+const DEFAULT_WARM_TIMEOUT_MS = 300_000; // 5 min
 const LOG_LEVEL_ORDER = {
     DEBUG: 0,
     INFO: 1,
@@ -74,12 +78,26 @@ export function validateEnv() {
     const retries = process.env.MCP_RETRIES
         ? Math.min(Math.max(0, Math.floor(Number(process.env.MCP_RETRIES))), 10)
         : DEFAULT_RETRIES;
+    // Parse warm mode
+    const warm = process.env.MCP_WARM === '1';
+    const warmRetries = process.env.MCP_WARM_RETRIES
+        ? Math.min(Math.max(0, Math.floor(Number(process.env.MCP_WARM_RETRIES))), 20)
+        : DEFAULT_WARM_RETRIES;
+    const warmRetryDelayMs = process.env.MCP_WARM_RETRY_DELAY
+        ? Math.max(1000, Number(process.env.MCP_WARM_RETRY_DELAY))
+        : DEFAULT_WARM_RETRY_DELAY_MS;
+    const warmTimeoutMs = process.env.MCP_WARM_TIMEOUT
+        ? Number(process.env.MCP_WARM_TIMEOUT)
+        : DEFAULT_WARM_TIMEOUT_MS;
     log('INFO', `target: ${url.hostname}, service: ${service}, region: ${region}`);
     if (inferred) {
         log('DEBUG', `inferred service=${inferred.service}, region=${inferred.region} from URL`);
     }
     log('DEBUG', `timeout: ${timeoutMs}ms, retries: ${retries}`);
-    return { url, region, service, timeoutMs, retries };
+    if (warm) {
+        log('INFO', `warm mode enabled (retries: ${warmRetries}, delay: ${warmRetryDelayMs}ms, timeout: ${warmTimeoutMs}ms)`);
+    }
+    return { url, region, service, timeoutMs, retries, warm, warmRetries, warmRetryDelayMs, warmTimeoutMs };
 }
 export function createSigner(config) {
     return new SignatureV4({
@@ -273,14 +291,206 @@ export async function processLine(line, config, signer) {
         }) + '\n');
     }
 }
+const WARM_CACHEABLE = new Set([
+    'initialize', 'tools/list', 'resources/list', 'prompts/list',
+]);
+// Exported for testing
+export { syntheticInitializeResult };
+/**
+ * Synthetic MCP initialize response returned when the backend hasn't responded yet.
+ * Advertises tools/resources/prompts capabilities so Claude Code proceeds to list calls.
+ */
+function syntheticInitializeResult() {
+    return {
+        protocolVersion: '2025-03-26',
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        serverInfo: { name: 'mcp-sigv4-proxy-warm', version: '0.4.1' },
+    };
+}
+export async function warmBackend(config, signer) {
+    const state = { ready: Promise.resolve(false), cache: {}, active: false };
+    state.ready = (async () => {
+        const deadline = Date.now() + config.warmTimeoutMs;
+        // Step 1: Initialize the backend (retry through cold-start 424s)
+        const initBody = JSON.stringify({
+            jsonrpc: '2.0',
+            id: '__warmup_init__',
+            method: 'initialize',
+            params: {
+                protocolVersion: '2025-03-26',
+                capabilities: {},
+                clientInfo: { name: 'mcp-sigv4-proxy', version: '0.4.0' },
+            },
+        });
+        let initResponse = null;
+        for (let attempt = 0; attempt <= config.warmRetries; attempt++) {
+            if (Date.now() >= deadline)
+                break;
+            try {
+                const request = buildHttpRequest(config.url, initBody);
+                const signed = await signer.sign(request);
+                initResponse = await fetchWithTimeout(config.url.toString(), { method: 'POST', headers: signed.headers, body: initBody }, Math.min(config.timeoutMs, deadline - Date.now()));
+                if (initResponse.ok)
+                    break;
+                if (initResponse.status === 424 && attempt < config.warmRetries) {
+                    const delay = config.warmRetryDelayMs * Math.pow(2, attempt);
+                    log('INFO', `warm: cold-start (HTTP 424), retrying in ${delay}ms (${attempt + 1}/${config.warmRetries})`);
+                    await sleep(Math.min(delay, deadline - Date.now()));
+                    initResponse = null;
+                    continue;
+                }
+                log('WARNING', `warm: initialize failed with HTTP ${initResponse.status}`);
+                return false;
+            }
+            catch (err) {
+                if (attempt < config.warmRetries) {
+                    const delay = config.warmRetryDelayMs * Math.pow(2, attempt);
+                    log('WARNING', `warm: initialize error (${err}), retrying in ${delay}ms`);
+                    await sleep(Math.min(delay, deadline - Date.now()));
+                    continue;
+                }
+                log('ERROR', `warm: initialize failed after ${config.warmRetries} retries: ${err}`);
+                return false;
+            }
+        }
+        if (!initResponse?.ok) {
+            log('ERROR', 'warm: backend did not respond to initialize within timeout');
+            return false;
+        }
+        // Check for session ID — warm mode is incompatible with stateful servers
+        const sessionId = initResponse.headers.get('mcp-session-id');
+        if (sessionId) {
+            log('WARNING', 'warm: backend returned mcp-session-id header — stateful servers are not '
+                + 'compatible with warm mode. Falling back to pass-through mode.');
+            return false;
+        }
+        // Cache the initialize result (extract from JSON-RPC response wrapper)
+        try {
+            const body = await initResponse.text();
+            const parsed = JSON.parse(body);
+            if (parsed.result) {
+                state.cache.initialize = parsed.result;
+            }
+            else {
+                state.cache.initialize = syntheticInitializeResult();
+            }
+        }
+        catch {
+            state.cache.initialize = syntheticInitializeResult();
+        }
+        log('INFO', 'warm: backend initialized, prefetching capability lists');
+        // Step 2: Prefetch tools/list, resources/list, prompts/list
+        const listMethods = ['tools/list', 'resources/list', 'prompts/list'];
+        await Promise.all(listMethods.map(async (method) => {
+            try {
+                const listBody = JSON.stringify({
+                    jsonrpc: '2.0', id: `__warmup_${method}__`, method, params: {},
+                });
+                const request = buildHttpRequest(config.url, listBody);
+                const signed = await signer.sign(request);
+                const response = await fetchWithTimeout(config.url.toString(), { method: 'POST', headers: signed.headers, body: listBody }, Math.min(config.timeoutMs, Math.max(1000, deadline - Date.now())));
+                if (response.ok) {
+                    const body = await response.text();
+                    const parsed = JSON.parse(body);
+                    if (parsed.result) {
+                        state.cache[method] = parsed.result;
+                        log('DEBUG', `warm: cached ${method} (${JSON.stringify(parsed.result).length} bytes)`);
+                    }
+                }
+            }
+            catch (err) {
+                log('WARNING', `warm: failed to prefetch ${method}: ${err}`);
+            }
+        }));
+        state.active = true;
+        const cached = Object.keys(state.cache).length;
+        log('INFO', `warm: ready (${cached} responses cached)`);
+        return true;
+    })();
+    return state;
+}
+/**
+ * Process a line in warm mode. Returns true if the message was handled locally
+ * (from cache or synthetic response), false if it should be forwarded to the backend.
+ */
+export function tryWarmResponse(body, requestId, warmState) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return false;
+    }
+    const method = parsed.method;
+    if (!method || !WARM_CACHEABLE.has(method))
+        return false;
+    const cached = warmState.cache[method];
+    if (!cached)
+        return false;
+    // Respond from cache
+    const response = JSON.stringify({
+        jsonrpc: '2.0',
+        id: requestId,
+        result: cached,
+    });
+    process.stdout.write(response + '\n');
+    log('DEBUG', `warm: served ${method} from cache`);
+    // For initialize, also send the initialized notification to the backend (fire-and-forget).
+    // Claude Code sends this too, but in warm mode we intercepted initialize so we handle it.
+    return true;
+}
+/**
+ * Handle a single parsed JSON-RPC message in warm mode.
+ * Returns true if the message was served locally (no need to forward to backend).
+ */
+export async function handleWarmLine(input, ws) {
+    const method = JSON.parse(input.body).method;
+    if (method === 'initialize') {
+        // Respond IMMEDIATELY — never block on ws.ready here.
+        // This is the critical path: Claude Code's 30s timeout applies to this response.
+        const result = ws.cache.initialize ?? syntheticInitializeResult();
+        process.stdout.write(JSON.stringify({ jsonrpc: '2.0', id: input.requestId, result }) + '\n');
+        log('DEBUG', `warm: served initialize ${ws.cache.initialize ? 'from cache' : 'synthetic'}`);
+        return true;
+    }
+    if (WARM_CACHEABLE.has(method)) {
+        // List methods: serve from cache immediately if available…
+        if (tryWarmResponse(input.body, input.requestId, ws))
+            return true;
+        // …otherwise wait for warm-up to complete, then try cache again before forwarding
+        await ws.ready;
+        if (tryWarmResponse(input.body, input.requestId, ws))
+            return true;
+        // Fall through to forward if warm-up failed or cache still empty
+    }
+    // Non-cacheable methods (tools/call etc): return false to forward normally.
+    // fetchWithRetry handles any residual 424s if the backend isn't warm yet.
+    return false;
+}
 // --- Main entry ---
 export function startProxy() {
     const config = validateEnv();
     const signer = createSigner(config);
     const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    // Start warm-up immediately. warmBackend() has no awaits before returning the WarmState
+    // object, so this promise resolves in the next microtask — effectively instant. The
+    // warmState.ready promise inside it is what takes minutes to resolve.
+    const warmStateP = config.warm
+        ? warmBackend(config, signer)
+        : null;
     let pending = Promise.resolve();
     rl.on('line', (line) => {
-        pending = pending.then(() => processLine(line, config, signer)).catch(() => { });
+        pending = pending.then(async () => {
+            if (warmStateP) {
+                const input = parseInputLine(line);
+                if (input) {
+                    const ws = await warmStateP; // resolves almost instantly
+                    if (await handleWarmLine(input, ws))
+                        return;
+                }
+            }
+            await processLine(line, config, signer);
+        }).catch(() => { });
     });
     rl.on('close', async () => {
         log('INFO', 'stdin closed, draining in-flight requests');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deotio/mcp-sigv4-proxy",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "stdio MCP proxy with AWS SigV4 signing — connect Claude Code to any IAM-authenticated MCP server using a named AWS profile",
   "type": "module",
   "bin": {
@@ -19,16 +19,16 @@
   "dependencies": {
     "@aws-sdk/credential-providers": "^3.0.0",
     "@aws-crypto/sha256-js": "^5.0.0",
-    "@smithy/protocol-http": "^4.0.0",
+    "@smithy/protocol-http": "^5.3.12",
     "@smithy/signature-v4": "^4.0.0"
   },
   "devDependencies": {
-    "@types/jest": "^29.0.0",
+    "@types/jest": "^30.0.0",
     "@types/node": "^22.0.0",
     "@typescript-eslint/eslint-plugin": "^7.0.0",
     "@typescript-eslint/parser": "^7.0.0",
     "eslint": "^8.0.0",
-    "jest": "^29.0.0",
+    "jest": "^30.3.0",
     "prettier": "^3.0.0",
     "ts-jest": "^29.0.0",
     "typescript": "^5.0.0"