@phidiassj/aiyoperps-mcp-bridge 0.8.1 → 0.8.4

package/README.md

@@ -20,6 +20,18 @@ Or via environment variable:
 AIYOPERPS_MCP_URL=http://127.0.0.1:5078/mcp npx -y @phidiassj/aiyoperps-mcp-bridge
 ```
 
+Health check only:
+
+```bash
+npx -y @phidiassj/aiyoperps-mcp-bridge --health-check --url http://127.0.0.1:5078/mcp
+```
+
+Startup validation before entering stdio mode:
+
+```bash
+npx -y @phidiassj/aiyoperps-mcp-bridge --startup-ping --url http://127.0.0.1:5078/mcp
+```
+
 ## Typical MCP config
 
 ```json
@@ -30,6 +42,7 @@ AIYOPERPS_MCP_URL=http://127.0.0.1:5078/mcp npx -y @phidiassj/aiyoperps-mcp-brid
       "args": [
         "-y",
         "@phidiassj/aiyoperps-mcp-bridge",
+        "--startup-ping",
         "--url",
         "http://127.0.0.1:5078/mcp"
       ]

package/bin/aiyoperps-mcp-bridge.js

@@ -3,44 +3,66 @@
 
 const { stdin, stdout, stderr, exit, argv, env } = require('node:process');
 
-const endpoint = resolveEndpoint(argv.slice(2));
+const options = parseOptions(argv.slice(2));
+const endpoint = options.url;
 let buffer = Buffer.alloc(0);
 let expectedBodyLength = null;
 
-stderr.write(`[aiyoperps-mcp-bridge] forwarding stdio MCP to ${endpoint}\n`);
-
-stdin.on('data', chunk => {
-  buffer = Buffer.concat([buffer, chunk]);
-  tryProcessBuffer();
-});
-
-stdin.on('end', () => {
-  stderr.write('[aiyoperps-mcp-bridge] stdin closed\n');
+if (options.help) {
+  stdout.write(buildHelpText());
   exit(0);
-});
+}
 
-stdin.on('error', error => {
-  stderr.write(`[aiyoperps-mcp-bridge] stdin error: ${error.message}\n`);
+bootstrap().catch(error => {
+  logError(`[aiyoperps-mcp-bridge] startup failed: ${error.message}`);
   exit(1);
 });
 
+async function bootstrap() {
+  if (options.healthCheck || options.startupPing) {
+    await pingUpstream();
+    if (options.healthCheck && !options.startupPing) {
+      logInfo(`[aiyoperps-mcp-bridge] health check ok ${endpoint}`);
+      exit(0);
+      return;
+    }
+  }
+
+  logInfo(`[aiyoperps-mcp-bridge] forwarding stdio MCP to ${endpoint}`);
+
+  stdin.on('data', chunk => {
+    buffer = Buffer.concat([buffer, chunk]);
+    tryProcessBuffer();
+  });
+
+  stdin.on('end', () => {
+    logInfo('[aiyoperps-mcp-bridge] stdin closed');
+    exit(0);
+  });
+
+  stdin.on('error', error => {
+    logError(`[aiyoperps-mcp-bridge] stdin error: ${error.message}`);
+    exit(1);
+  });
+}
+
 function tryProcessBuffer() {
   while (true) {
     if (expectedBodyLength === null) {
-      const headerEndIndex = buffer.indexOf('\r\n\r\n');
-      if (headerEndIndex === -1) {
+      const headerInfo = findHeaderBoundary(buffer);
+      if (!headerInfo) {
         return;
       }
 
-      const headerText = buffer.subarray(0, headerEndIndex).toString('utf8');
+      const headerText = buffer.subarray(0, headerInfo.index).toString('utf8');
       const lengthMatch = /content-length:\s*(\d+)/i.exec(headerText);
       if (!lengthMatch) {
-        stderr.write('[aiyoperps-mcp-bridge] invalid MCP frame: missing Content-Length\n');
+        logError('[aiyoperps-mcp-bridge] invalid MCP frame: missing Content-Length');
         exit(1);
       }
 
       expectedBodyLength = Number.parseInt(lengthMatch[1], 10);
-      buffer = buffer.subarray(headerEndIndex + 4);
+      buffer = buffer.subarray(headerInfo.bodyOffset);
     }
 
     if (buffer.length < expectedBodyLength) {
@@ -52,12 +74,33 @@ function tryProcessBuffer() {
     expectedBodyLength = null;
 
     handleMessage(body).catch(error => {
-      stderr.write(`[aiyoperps-mcp-bridge] message handling failed: ${error.stack || error.message}\n`);
+      logError(`[aiyoperps-mcp-bridge] message handling failed: ${error.stack || error.message}`);
       exit(1);
     });
   }
 }
 
+function findHeaderBoundary(sourceBuffer) {
+  const crlfIndex = sourceBuffer.indexOf('\r\n\r\n');
+  const lfIndex = sourceBuffer.indexOf('\n\n');
+
+  if (crlfIndex === -1 && lfIndex === -1) {
+    return null;
+  }
+
+  if (crlfIndex !== -1 && (lfIndex === -1 || crlfIndex <= lfIndex)) {
+    return {
+      index: crlfIndex,
+      bodyOffset: crlfIndex + 4
+    };
+  }
+
+  return {
+    index: lfIndex,
+    bodyOffset: lfIndex + 2
+  };
+}
+
 async function handleMessage(bodyBuffer) {
   const bodyText = bodyBuffer.toString('utf8');
   let payload;
@@ -65,7 +108,7 @@ async function handleMessage(bodyBuffer) {
   try {
     payload = JSON.parse(bodyText);
   } catch (error) {
-    stderr.write(`[aiyoperps-mcp-bridge] invalid JSON from client: ${error.message}\n`);
+    logError(`[aiyoperps-mcp-bridge] invalid JSON from client: ${error.message}`);
     writeFrame(JSON.stringify({
       jsonrpc: '2.0',
       error: {
@@ -81,7 +124,7 @@ async function handleMessage(bodyBuffer) {
   try {
     response = await postJson(endpoint, payload);
   } catch (error) {
-    stderr.write(`[aiyoperps-mcp-bridge] upstream request failed: ${error.message}\n`);
+    logError(`[aiyoperps-mcp-bridge] upstream request failed: ${error.message}`);
     writeFrame(JSON.stringify({
       jsonrpc: '2.0',
       error: {
@@ -97,23 +140,51 @@ async function handleMessage(bodyBuffer) {
 }
 
 async function postJson(url, payload) {
-  const response = await fetch(url, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify(payload)
-  });
-
-  const text = await response.text();
-  if (!response.ok) {
-    throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
-  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), options.timeoutMs);
 
   try {
-    return JSON.parse(text);
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json'
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+
+    const text = await response.text();
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${text || response.statusText}`);
+    }
+
+    try {
+      return JSON.parse(text);
+    } catch (error) {
+      throw new Error(`Invalid JSON from AiyoPerps MCP endpoint: ${error.message}`);
+    }
   } catch (error) {
-    throw new Error(`Invalid JSON from AiyoPerps MCP endpoint: ${error.message}`);
+    if (error && error.name === 'AbortError') {
+      throw new Error(`Request timeout after ${options.timeoutMs}ms`);
+    }
+
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function pingUpstream() {
+  const response = await postJson(endpoint, {
+    jsonrpc: '2.0',
+    id: 'startup-ping',
+    method: 'ping',
+    params: {}
+  });
+
+  if (!response || response.error) {
+    const message = response?.error?.message || 'Unexpected MCP ping failure.';
+    throw new Error(message);
   }
 }
 
@@ -123,19 +194,92 @@ function writeFrame(jsonText) {
   stdout.write(Buffer.concat([header, body]));
 }
 
-function resolveEndpoint(args) {
-  const fallback = env.AIYOPERPS_MCP_URL || 'http://127.0.0.1:5078/mcp';
+function parseOptions(args) {
+  const options = {
+    url: env.AIYOPERPS_MCP_URL || 'http://127.0.0.1:5078/mcp',
+    healthCheck: false,
+    startupPing: false,
+    quiet: false,
+    help: false,
+    timeoutMs: 5000
+  };
 
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
     if (arg.startsWith('--url=')) {
-      return arg.slice('--url='.length);
+      options.url = arg.slice('--url='.length);
+      continue;
     }
 
     if (arg === '--url' && index + 1 < args.length) {
-      return args[index + 1];
+      options.url = args[index + 1];
+      index += 1;
+      continue;
+    }
+
+    if (arg === '--health-check') {
+      options.healthCheck = true;
+      continue;
+    }
+
+    if (arg === '--startup-ping') {
+      options.startupPing = true;
+      continue;
+    }
+
+    if (arg === '--quiet') {
+      options.quiet = true;
+      continue;
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg.startsWith('--timeout-ms=')) {
+      options.timeoutMs = parseTimeout(arg.slice('--timeout-ms='.length), options.timeoutMs);
+      continue;
+    }
+
+    if (arg === '--timeout-ms' && index + 1 < args.length) {
+      options.timeoutMs = parseTimeout(args[index + 1], options.timeoutMs);
+      index += 1;
     }
   }
 
-  return fallback;
+  return options;
+}
+
+function parseTimeout(raw, fallback) {
+  const value = Number.parseInt(raw, 10);
+  return Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+function buildHelpText() {
+  return [
+    'AiyoPerps MCP Bridge',
+    '',
+    'Usage:',
+    '  npx -y @phidiassj/aiyoperps-mcp-bridge [options]',
+    '',
+    'Options:',
+    '  --url <endpoint>       Target HTTP MCP endpoint (default: http://127.0.0.1:5078/mcp)',
+    '  --health-check         Verify the upstream MCP endpoint with a ping and exit',
+    '  --startup-ping         Ping the upstream MCP endpoint before entering stdio mode',
+    '  --timeout-ms <ms>      Request timeout for health/startup ping and upstream calls (default: 5000)',
+    '  --quiet                Suppress bridge diagnostic messages on stderr',
+    '  --help, -h             Show this help message',
+    ''
+  ].join('\n');
+}
+
+function logInfo(message) {
+  if (!options.quiet) {
+    stderr.write(`${message}\n`);
+  }
+}
+
+function logError(message) {
+  stderr.write(`${message}\n`);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phidiassj/aiyoperps-mcp-bridge",
-  "version": "0.8.1",
+  "version": "0.8.4",
   "description": "Stdio MCP bridge for the AiyoPerps local HTTP MCP endpoint.",
   "license": "MIT",
   "bin": {