@deotio/mcp-sigv4-proxy 0.2.1 → 0.4.0

package/README.md

@@ -14,12 +14,13 @@ Add to your `.mcp.json`:
   "args": ["-y", "@deotio/mcp-sigv4-proxy"],
   "env": {
     "AWS_PROFILE": "dot-finops",
+    "AWS_REGION": "us-east-1",
     "MCP_SERVER_URL": "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/.../invocations?qualifier=DEFAULT"
   }
 }
 ```
 
-The service name (`bedrock-agentcore`) and region (`us-east-1`) are inferred from the URL automatically. Set `AWS_REGION` and `AWS_SERVICE` only when using non-standard endpoints.
+Always set `AWS_REGION` explicitly — the proxy can infer it from standard AWS hostnames, but `AWS_REGION` from your shell environment takes precedence and may point to a different region. `AWS_SERVICE` is inferred automatically and only needs to be set for non-standard endpoints.
 
 ## How it works
 
@@ -31,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
 
@@ -42,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
 
@@ -58,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

@@ -5,8 +5,13 @@ import { Sha256 } from '@aws-crypto/sha256-js';
 import readline from 'readline';
 export const MAX_SSE_BUFFER_BYTES = 1_048_576; // 1 MB
 const DEFAULT_TIMEOUT_MS = 180_000; // 180s, matches AWS proxy
-const DEFAULT_RETRIES = 0;
+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,
@@ -73,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({
@@ -145,10 +164,14 @@ async function fetchWithRetry(url, init, timeoutMs, retries) {
     for (let attempt = 0; attempt <= retries; attempt++) {
         try {
             const response = await fetchWithTimeout(url, init, timeoutMs);
-            // Only retry on 5xx server errors
-            if (response.status >= 500 && attempt < retries) {
-                log('WARNING', `HTTP ${response.status}, retrying (${attempt + 1}/${retries})`);
-                await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+            // Retry on 5xx server errors and 424 (AgentCore cold-start timeout)
+            const retryable = response.status >= 500 || response.status === 424;
+            if (retryable && attempt < retries) {
+                const delay = response.status === 424
+                    ? COLD_START_RETRY_MS * Math.pow(2, attempt)
+                    : RETRY_BASE_MS * Math.pow(2, attempt);
+                log('WARNING', `HTTP ${response.status}, retrying in ${delay}ms (${attempt + 1}/${retries})`);
+                await sleep(delay);
                 continue;
             }
             return response;
@@ -172,10 +195,22 @@ export async function handleResponse(response, requestId) {
     if (!response.ok) {
         const text = await response.text();
         log('ERROR', `HTTP ${response.status}: ${text}`);
+        // Extract the upstream message for the JSON-RPC error (if JSON, use .message; otherwise trim)
+        let detail = '';
+        try {
+            const parsed = JSON.parse(text);
+            if (typeof parsed.message === 'string')
+                detail = `: ${parsed.message}`;
+        }
+        catch {
+            const trimmed = text.trim();
+            if (trimmed.length > 0 && trimmed.length <= 200)
+                detail = `: ${trimmed}`;
+        }
         process.stdout.write(JSON.stringify({
             jsonrpc: '2.0',
             id: requestId,
-            error: { code: -32000, message: `HTTP ${response.status}` },
+            error: { code: -32000, message: `HTTP ${response.status}${detail}` },
         }) + '\n');
         return;
     }
@@ -256,14 +291,179 @@ export async function processLine(line, config, signer) {
         }) + '\n');
     }
 }
+const WARM_CACHEABLE = new Set([
+    'initialize', 'tools/list', 'resources/list', 'prompts/list',
+]);
+/**
+ * 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.0' },
+    };
+}
+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;
+}
 // --- Main entry ---
 export function startProxy() {
     const config = validateEnv();
     const signer = createSigner(config);
     const rl = readline.createInterface({ input: process.stdin, terminal: false });
+    // Start warm-up in background if enabled (non-blocking)
+    let warmState = null;
+    if (config.warm) {
+        warmBackend(config, signer).then((state) => { warmState = state; });
+    }
     let pending = Promise.resolve();
     rl.on('line', (line) => {
-        pending = pending.then(() => processLine(line, config, signer)).catch(() => { });
+        pending = pending.then(async () => {
+            // In warm mode, try to serve from cache first
+            if (warmState) {
+                const input = parseInputLine(line);
+                if (input) {
+                    // Wait for warm-up to finish before deciding
+                    const warmActive = await warmState.ready;
+                    if (warmActive && tryWarmResponse(input.body, input.requestId, warmState)) {
+                        return; // served from cache
+                    }
+                    // Fall through: warm mode inactive or method not cacheable — forward normally
+                }
+            }
+            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.2.1",
+  "version": "0.4.0",
   "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": {