@deotio/mcp-sigv4-proxy 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,7 @@
 # @deotio/mcp-sigv4-proxy
 
+> **Note:** AWS publishes an official proxy for this use case: [`mcp-proxy-for-aws`](https://github.com/aws/mcp-proxy-for-aws). It is mature, feature-rich, and AWS-supported. **Use it unless you specifically need a Node.js solution.** This package exists for teams that don't have (or want) a Python runtime — it provides the same core functionality as a single `npx` command with zero Python dependencies.
+
 A stdio MCP proxy that signs requests with AWS SigV4 using the standard credential chain. Drop it into your `.mcp.json` as a `command` entry to connect Claude Code (or any MCP client) to IAM-authenticated MCP servers like AWS Bedrock AgentCore — with per-profile auth via `AWS_PROFILE`.
 
 ## Quick start
@@ -12,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.
+
 ## How it works
 
 ```
@@ -27,7 +30,7 @@ stdin (JSON-RPC) -> validate -> SigV4 sign -> HTTPS POST -> response relay -> st
 1. Reads JSON-RPC messages from stdin (one per line)
 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
+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
 
 ## Environment variables
@@ -36,8 +39,11 @@ stdin (JSON-RPC) -> validate -> SigV4 sign -> HTTPS POST -> response relay -> st
 |---|---|---|---|
 | `MCP_SERVER_URL` | yes | — | Full HTTPS URL of the target MCP HTTP endpoint |
 | `AWS_PROFILE` | no | SDK default chain | AWS named profile for signing |
-| `AWS_REGION` | no | `us-east-1` | AWS region for SigV4 signing |
-| `AWS_SERVICE` | no | `bedrock-agentcore` | SigV4 service name |
+| `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_LOG_LEVEL` | no | `ERROR` | Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `SILENT` |
 
 ## Prerequisites
 
@@ -49,12 +55,19 @@ bedrock-agentcore:InvokeAgentRuntime
 
 ## Security
 
-- **HTTPS-only** — `MCP_SERVER_URL` must use `https://`. Other schemes (`http://`, `file://`, `ftp://`) are rejected at startup to prevent SSRF.
+- **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.
 - **Buffer limits** — SSE streams are capped at 1 MB to prevent unbounded memory growth.
 
+## Documentation
+
+- [Why this package exists](doc/why.md) — the problem, the solution, and comparison with `mcp-proxy-for-aws`
+- [Getting started](doc/getting-started.md) — step-by-step setup guide
+- [Configuration](doc/configuration.md) — environment variables, credential methods, IAM permissions
+- [Troubleshooting](doc/troubleshooting.md) — common errors and debugging tips
+
 ## License
 
 Apache-2.0

package/dist/proxy.js

@@ -4,6 +4,41 @@ import { HttpRequest } from '@smithy/protocol-http';
 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 RETRY_BASE_MS = 1000;
+const LOG_LEVEL_ORDER = {
+    DEBUG: 0,
+    INFO: 1,
+    WARNING: 2,
+    ERROR: 3,
+    SILENT: 4,
+};
+let currentLogLevel = 'ERROR';
+export function setLogLevel(level) {
+    currentLogLevel = level;
+}
+export function log(level, message) {
+    if (LOG_LEVEL_ORDER[level] >= LOG_LEVEL_ORDER[currentLogLevel]) {
+        process.stderr.write(`mcp-sigv4-proxy: ${message}\n`);
+    }
+}
+// --- URL parsing ---
+export function parseEndpointUrl(hostname) {
+    const parts = hostname.split('.');
+    // bedrock-agentcore.us-east-1.amazonaws.com
+    if (parts.length >= 4 && parts.at(-2) === 'amazonaws' && parts.at(-1) === 'com') {
+        const service = parts.slice(0, -3).join('.');
+        const region = parts.at(-3);
+        if (service && region)
+            return { service, region };
+    }
+    // service.region.api.aws
+    if (parts.length === 4 && parts[2] === 'api' && parts[3] === 'aws') {
+        return { service: parts[0], region: parts[1] };
+    }
+    return null;
+}
 export function validateEnv() {
     if (!process.env.MCP_SERVER_URL) {
         process.stderr.write('mcp-sigv4-proxy: MCP_SERVER_URL is required\n');
@@ -15,15 +50,35 @@ export function validateEnv() {
         process.exit(1);
     }
     const url = new URL(process.env.MCP_SERVER_URL);
-    if (url.protocol !== 'https:') {
+    // Allow http:// for localhost (local development), require https:// for everything else
+    const isLocalhost = url.hostname === 'localhost' || url.hostname === '127.0.0.1' || url.hostname === '::1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && isLocalhost)) {
         process.stderr.write(`mcp-sigv4-proxy: MCP_SERVER_URL must use https:// (got ${url.protocol})\n`);
         process.exit(1);
     }
-    return {
-        url,
-        region: process.env.AWS_REGION ?? 'us-east-1',
-        service: process.env.AWS_SERVICE ?? 'bedrock-agentcore',
-    };
+    // Infer service and region from hostname, fall back to env vars / defaults
+    const inferred = parseEndpointUrl(url.hostname);
+    const region = process.env.AWS_REGION || inferred?.region || 'us-east-1';
+    const service = process.env.AWS_SERVICE || inferred?.service || 'bedrock-agentcore';
+    // Parse log level
+    const envLogLevel = (process.env.MCP_LOG_LEVEL ?? 'ERROR').toUpperCase();
+    if (envLogLevel in LOG_LEVEL_ORDER) {
+        setLogLevel(envLogLevel);
+    }
+    // Parse timeout
+    const timeoutMs = process.env.MCP_TIMEOUT
+        ? Number(process.env.MCP_TIMEOUT) * 1000
+        : DEFAULT_TIMEOUT_MS;
+    // Parse retries
+    const retries = process.env.MCP_RETRIES
+        ? Math.min(Math.max(0, Math.floor(Number(process.env.MCP_RETRIES))), 10)
+        : DEFAULT_RETRIES;
+    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 };
 }
 export function createSigner(config) {
     return new SignatureV4({
@@ -33,6 +88,7 @@ export function createSigner(config) {
         sha256: Sha256,
     });
 }
+// --- Input parsing ---
 export function parseInputLine(line) {
     const body = line.trim();
     if (!body)
@@ -42,18 +98,19 @@ export function parseInputLine(line) {
         parsed = JSON.parse(body);
     }
     catch {
-        process.stderr.write('mcp-sigv4-proxy: ignoring non-JSON input line\n');
+        log('WARNING', 'ignoring non-JSON input line');
         return null;
     }
     if (typeof parsed !== 'object' ||
         parsed === null ||
         parsed.jsonrpc !== '2.0') {
-        process.stderr.write('mcp-sigv4-proxy: ignoring non-JSON-RPC message\n');
+        log('WARNING', 'ignoring non-JSON-RPC message');
         return null;
     }
     const requestId = parsed.id ?? null;
     return { body, requestId };
 }
+// --- Request building ---
 export function buildHttpRequest(url, body) {
     return new HttpRequest({
         method: 'POST',
@@ -67,10 +124,49 @@ export function buildHttpRequest(url, body) {
         body,
     });
 }
+// --- Fetch with timeout and retries ---
+async function fetchWithTimeout(url, init, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function fetchWithRetry(url, init, timeoutMs, retries) {
+    let lastError;
+    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));
+                continue;
+            }
+            return response;
+        }
+        catch (err) {
+            lastError = err;
+            if (attempt < retries) {
+                const isTimeout = err instanceof DOMException && err.name === 'AbortError';
+                log('WARNING', `request ${isTimeout ? 'timed out' : 'failed'}, retrying (${attempt + 1}/${retries})`);
+                await sleep(RETRY_BASE_MS * Math.pow(2, attempt));
+            }
+        }
+    }
+    throw lastError;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// --- Response handling ---
 export async function handleResponse(response, requestId) {
     if (!response.ok) {
         const text = await response.text();
-        process.stderr.write(`mcp-sigv4-proxy: HTTP ${response.status}: ${text}\n`);
+        log('ERROR', `HTTP ${response.status}: ${text}`);
         process.stdout.write(JSON.stringify({
             jsonrpc: '2.0',
             id: requestId,
@@ -90,7 +186,7 @@ export async function handleResponse(response, requestId) {
                 break;
             buffer += decoder.decode(value, { stream: true });
             if (Buffer.byteLength(buffer) > MAX_SSE_BUFFER_BYTES) {
-                process.stderr.write('mcp-sigv4-proxy: SSE buffer exceeded 1 MB limit, aborting stream\n');
+                log('ERROR', 'SSE buffer exceeded 1 MB limit, aborting stream');
                 reader.cancel();
                 process.stdout.write(JSON.stringify({
                     jsonrpc: '2.0',
@@ -109,7 +205,7 @@ export async function handleResponse(response, requestId) {
                         process.stdout.write(data + '\n');
                     }
                     catch {
-                        process.stderr.write(`mcp-sigv4-proxy: dropping non-JSON SSE data: ${data.slice(0, 100)}\n`);
+                        log('WARNING', `dropping non-JSON SSE data: ${data.slice(0, 100)}`);
                     }
                 }
             }
@@ -123,53 +219,58 @@ export async function handleResponse(response, requestId) {
             process.stdout.write(trimmed + '\n');
         }
         catch {
-            process.stderr.write(`mcp-sigv4-proxy: dropping non-JSON response body: ${trimmed.slice(0, 100)}\n`);
+            log('WARNING', `dropping non-JSON response body: ${trimmed.slice(0, 100)}`);
         }
     }
 }
-export async function processLine(line, url, signer) {
+// --- Request processing ---
+export async function processLine(line, config, signer) {
     const input = parseInputLine(line);
     if (!input)
         return;
     const { body, requestId } = input;
-    const request = buildHttpRequest(url, body);
+    const request = buildHttpRequest(config.url, body);
     try {
         const signed = await signer.sign(request);
-        const response = await fetch(url.toString(), {
+        log('DEBUG', `-> POST ${config.url.pathname}`);
+        const response = await fetchWithRetry(config.url.toString(), {
             method: 'POST',
             headers: signed.headers,
             body,
-        });
+        }, config.timeoutMs, config.retries);
         await handleResponse(response, requestId);
     }
     catch (err) {
-        process.stderr.write(`mcp-sigv4-proxy: request failed: ${err}\n`);
+        const isTimeout = err instanceof DOMException && err.name === 'AbortError';
+        const message = isTimeout ? 'Request timed out' : 'Proxy request failed';
+        log('ERROR', `request failed: ${err}`);
         process.stdout.write(JSON.stringify({
             jsonrpc: '2.0',
             id: requestId,
-            error: { code: -32000, message: 'Proxy request failed' },
+            error: { code: -32000, message },
         }) + '\n');
     }
 }
+// --- Main entry ---
 export function startProxy() {
     const config = validateEnv();
     const signer = createSigner(config);
     const rl = readline.createInterface({ input: process.stdin, terminal: false });
     let pending = Promise.resolve();
     rl.on('line', (line) => {
-        pending = pending.then(() => processLine(line, config.url, signer)).catch(() => { });
+        pending = pending.then(() => processLine(line, config, signer)).catch(() => { });
     });
     rl.on('close', async () => {
-        process.stderr.write('mcp-sigv4-proxy: stdin closed, draining in-flight requests\n');
+        log('INFO', 'stdin closed, draining in-flight requests');
         await pending;
         process.exit(0);
     });
     process.on('SIGTERM', () => {
-        process.stderr.write('mcp-sigv4-proxy: received SIGTERM, shutting down\n');
+        log('INFO', 'received SIGTERM, shutting down');
         rl.close();
     });
     process.on('SIGINT', () => {
-        process.stderr.write('mcp-sigv4-proxy: received SIGINT, shutting down\n');
+        log('INFO', 'received SIGINT, shutting down');
         rl.close();
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deotio/mcp-sigv4-proxy",
-  "version": "0.1.0",
+  "version": "0.2.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": {