@h0wzy/mcp-shared 1.0.0

package/errors.js

@@ -0,0 +1,87 @@
+/**
+ * Detects if an error string represents a rate limit or quota exhaustion.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isRateLimitError(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return (
+    lower.includes('429') ||
+    lower.includes('resourceexhausted') ||
+    lower.includes('resource_exhausted') ||
+    lower.includes('quota') ||
+    lower.includes('rate limit') ||
+    lower.includes('ratelimit') ||
+    lower.includes('too many requests') ||
+    lower.includes('tokens per minute') ||
+    lower.includes('requests per minute') ||
+    lower.includes('usage limit') ||
+    lower.includes('limit exceeded') ||
+    lower.includes('exceeded your')
+  );
+}
+
+/**
+ * Detects if an error string represents an authentication or session expiry issue.
+ * @param {string} text
+ * @returns {boolean}
+ */
+export function isAuthError(text) {
+  if (!text) return false;
+  const lower = text.toLowerCase();
+  return (
+    lower.includes('unauthorized') ||
+    lower.includes('401') ||
+    lower.includes('not authenticated') ||
+    lower.includes('not logged in') ||
+    lower.includes('sign in') ||
+    lower.includes('login required') ||
+    lower.includes('auth token') ||
+    lower.includes('session expired')
+  );
+}
+
+/**
+ * Formats a provider error into a resilient MCP tool response that allows
+ * the calling host agent (e.g. Claude Code) to smoothly degrade or inform the user
+ * without aborting the session.
+ *
+ * @param {Object} options
+ * @param {string} options.provider e.g. "Google Antigravity (Gemini)" or "OpenAI Codex"
+ * @param {string} options.rawOutput
+ * @param {number} [options.exitCode]
+ * @returns {{ text: string, isError: boolean }}
+ */
+export function formatResilientResponse({ provider, rawOutput, exitCode }) {
+  const text = (rawOutput || '').trim();
+
+  if (isRateLimitError(text)) {
+    return {
+      isError: true,
+      text:
+        `⚠️ [${provider} Rate Limit / Quota Exhausted]\n` +
+        `The external provider returned a 429 / Resource Exhausted error:\n\n` +
+        `${text}\n\n` +
+        `💡 Fallback guidance for Host Agent: Do not retry immediately. Fall back to your internal reasoning to fulfill the user request, or inform the user that their ${provider} quota has been reached.`,
+    };
+  }
+
+  if (isAuthError(text)) {
+    return {
+      isError: true,
+      text:
+        `🔑 [${provider} Authentication Required]\n` +
+        `The CLI is not authenticated or the login session has expired:\n\n` +
+        `${text}\n\n` +
+        `💡 Guidance: Please sign in or check your local credentials for ${provider}.`,
+    };
+  }
+
+  return {
+    isError: true,
+    text:
+      `❌ [${provider} Execution Error (exit code ${exitCode ?? 'unknown'})]\n\n` +
+      `${text || '(No output produced)'}`,
+  };
+}

package/executor.js

@@ -0,0 +1,89 @@
+// H0wZy/mcp — Child Process Executor
+// Lazy, minimal, robust process runner with timeout and augmented PATH.
+
+import { spawn } from 'node:child_process';
+import { childEnvWithAugmentedPath } from './resolver.js';
+
+/**
+ * Spawns a process with timeout, path augmentation, and output capture.
+ *
+ * @param {string} command Path or name of the executable
+ * @param {string[]} [args=[]] Command line arguments
+ * @param {Object} [options={}]
+ * @param {string} [options.cwd] Current working directory
+ * @param {NodeJS.ProcessEnv} [options.env] Extra environment variables
+ * @param {number} [options.timeoutMs=180000] Timeout in ms (default: 3 minutes)
+ * @param {string} [options.toolName] Tool name to augment PATH for
+ * @returns {Promise<{ exitCode: number, stdout: string, stderr: string, ok: boolean, timedOut: boolean }>}
+ */
+export function executeProcess(command, args = [], options = {}) {
+  return new Promise((resolve) => {
+    const {
+      cwd = process.cwd(),
+      env = {},
+      timeoutMs = 180000,
+      toolName,
+    } = options;
+
+    const childEnv = {
+      ...childEnvWithAugmentedPath(toolName),
+      ...env,
+    };
+
+    const isWindows = process.platform === 'win32';
+    // On Windows, running .cmd or .bat without a shell will fail in spawn
+    const needsShell = isWindows && (command.toLowerCase().endsWith('.cmd') || command.toLowerCase().endsWith('.bat'));
+
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+
+    const child = spawn(command, args, {
+      cwd,
+      env: childEnv,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: needsShell,
+    });
+
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          timedOut = true;
+          try {
+            child.kill('SIGKILL');
+          } catch {
+            /* ignore kill failure if already exited */
+          }
+        }, timeoutMs)
+      : null;
+
+    child.stdout.on('data', (chunk) => {
+      stdout += chunk;
+    });
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+
+    child.on('error', (err) => {
+      if (timer) clearTimeout(timer);
+      resolve({
+        exitCode: -1,
+        stdout,
+        stderr: stderr || err.message,
+        ok: false,
+        timedOut,
+      });
+    });
+
+    child.on('close', (code) => {
+      if (timer) clearTimeout(timer);
+      resolve({
+        exitCode: code ?? 0,
+        stdout: stdout.trim(),
+        stderr: stderr.trim(),
+        ok: code === 0 && !timedOut,
+        timedOut,
+      });
+    });
+  });
+}

package/index.js

@@ -0,0 +1,5 @@
+// H0wZy/mcp — Shared Module Index
+export * from './server.js';
+export * from './executor.js';
+export * from './resolver.js';
+export * from './errors.js';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@h0wzy/mcp-shared",
+  "version": "1.0.0",
+  "description": "Shared cross-platform utilities, binary resolvers, resilient error handlers, and generic MCP stdio server for H0wZy/mcp",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    "./server": "./server.js",
+    "./executor": "./executor.js",
+    "./resolver": "./resolver.js",
+    "./errors": "./errors.js",
+    ".": "./index.js"
+  },
+  "author": "Marcos (H0wZy) <h0wzymarcos@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/H0wZy/mcp.git",
+    "directory": "shared"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/resolver.js

@@ -0,0 +1,174 @@
+import { statSync, accessSync, constants, realpathSync } from 'node:fs';
+import { delimiter, dirname, isAbsolute, join, sep } from 'node:path';
+import { homedir } from 'node:os';
+
+const isWindows = process.platform === 'win32';
+
+/**
+ * Returns candidate names for a binary, accounting for Windows PATHEXT.
+ * @param {string} name
+ * @returns {string[]}
+ */
+export function candidateNames(name) {
+  if (!isWindows) return [name];
+  const pathext = (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM').split(';').filter(Boolean);
+  if (pathext.some((ext) => name.toLowerCase().endsWith(ext.toLowerCase()))) {
+    return [name];
+  }
+  // On Windows, test valid executable extensions first before extensionless
+  const withExts = pathext.map((ext) =>
+    ext.startsWith('.') ? `${name}${ext.toLowerCase()}` : `${name}.${ext.toLowerCase()}`
+  );
+  return [...withExts, name];
+}
+
+/**
+ * Checks whether a file exists and is executable.
+ * @param {string} path
+ * @returns {boolean}
+ */
+export function isExecutable(path) {
+  try {
+    const stat = statSync(path);
+    if (!stat.isFile()) return false;
+  } catch {
+    return false;
+  }
+
+  if (isWindows) {
+    // On Windows, file must match PATHEXT to be executable via spawn/CreateProcess
+    const pathext = (process.env.PATHEXT || '.EXE;.CMD;.BAT;.COM')
+      .toLowerCase()
+      .split(';')
+      .filter(Boolean);
+    const lower = path.toLowerCase();
+    return pathext.some((ext) => lower.endsWith(ext.startsWith('.') ? ext : `.${ext}`));
+  }
+
+  try {
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Known default locations per tool across Windows, macOS, and Linux.
+ * @param {string} toolName
+ * @returns {string[]}
+ */
+export function getKnownToolDirs(toolName) {
+  const home = homedir();
+  const dirs = [dirname(process.execPath)];
+
+  if (isWindows) {
+    const appData = process.env.APPDATA;
+    const localAppData = process.env.LOCALAPPDATA || (home ? join(home, 'AppData', 'Local') : '');
+
+    if (toolName === 'agy') {
+      if (localAppData) dirs.push(join(localAppData, 'agy', 'bin'));
+      dirs.push(join(home, '.local', 'bin'));
+      dirs.push(join(home, 'AppData', 'Local', 'Programs', 'agy'));
+    } else if (toolName === 'codex') {
+      if (appData) dirs.push(join(appData, 'npm'));
+      if (localAppData) dirs.push(join(localAppData, 'Programs', 'codex'));
+      dirs.push(join(home, '.local', 'bin'));
+    } else if (toolName === 'claude') {
+      dirs.push(join(home, '.local', 'bin'));
+      if (appData) dirs.push(join(appData, 'npm'));
+    }
+  } else {
+    dirs.push(
+      join(home, '.local', 'bin'),
+      '/opt/homebrew/bin',
+      '/usr/local/bin',
+      '/usr/bin',
+      '/bin',
+      join(home, '.npm-global', 'bin'),
+      join(home, '.bun', 'bin'),
+      join(home, '.volta', 'bin')
+    );
+  }
+
+  return dirs;
+}
+
+/**
+ * Resolves a binary path searching explicit overrides, known directories, and PATH.
+ * @param {string} name Base executable name (e.g. 'agy', 'codex', 'claude')
+ * @param {string} [overrideEnvVar] Optional environment variable name (e.g. 'AGY_BIN')
+ * @returns {string|null} Absolute path to executable or null if not found
+ */
+export function resolveBinary(name, overrideEnvVar) {
+  if (overrideEnvVar && process.env[overrideEnvVar]) {
+    const override = process.env[overrideEnvVar].trim();
+    if (isExecutable(override)) return override;
+  }
+
+  if (isAbsolute(name) || name.includes(sep) || name.includes('/')) {
+    if (isExecutable(name)) return name;
+  }
+
+  const searchDirs = [];
+  const seen = new Set();
+
+  const addDir = (d) => {
+    if (d && !seen.has(d)) {
+      seen.add(d);
+      searchDirs.push(d);
+    }
+  };
+
+  // 1. Tool-specific known locations
+  for (const d of getKnownToolDirs(name)) addDir(d);
+
+  // 2. PATH directories using platform delimiter (; on Windows, : on POSIX)
+  const pathDirs = (process.env.PATH || '').split(delimiter).filter(Boolean);
+  for (const d of pathDirs) addDir(d);
+
+  // 3. Search for candidates
+  const candidates = candidateNames(name);
+  for (const dir of searchDirs) {
+    for (const cand of candidates) {
+      const fullPath = join(dir, cand);
+      if (isExecutable(fullPath)) {
+        try {
+          const real = realpathSync(fullPath);
+          // Filter out macOS Electron app bundle wrappers that aren't the CLI
+          if (real.includes('Antigravity.app')) continue;
+        } catch {
+          // Keep candidate if realpath resolution fails
+        }
+        return fullPath;
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Returns a child process environment with PATH augmented by known tool directories.
+ * @param {string} [toolName]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function childEnvWithAugmentedPath(toolName) {
+  const current = (process.env.PATH || '').split(delimiter).filter(Boolean);
+  const merged = [];
+  const seen = new Set();
+
+  const add = (d) => {
+    if (d && !seen.has(d)) {
+      seen.add(d);
+      merged.push(d);
+    }
+  };
+
+  for (const d of current) add(d);
+  if (toolName) {
+    for (const d of getKnownToolDirs(toolName)) add(d);
+  }
+
+  return { ...process.env, PATH: merged.join(delimiter) };
+}

package/server.js

@@ -0,0 +1,125 @@
+// H0wZy/mcp — Generic JSON-RPC 2.0 stdio MCP Server
+// Lazy, robust, zero-dependency server engine handling the complete MCP lifecycle.
+
+import readline from 'node:readline';
+import { formatResilientResponse } from './errors.js';
+
+/**
+ * @typedef {Object} MCPTool
+ * @property {string} name
+ * @property {string} description
+ * @property {Object} inputSchema
+ * @property {(args: any) => Promise<{ text: string, isError?: boolean } | string>} handler
+ */
+
+/**
+ * Creates an MCP server instance over stdio.
+ *
+ * @param {Object} config
+ * @param {string} config.name Server name (e.g. "antigravity", "codex")
+ * @param {string} config.version Server semantic version
+ * @param {MCPTool[]} config.tools Tools exposed by this server
+ * @returns {{ start: () => void, handleMessage: (msg: any) => Promise<any> }}
+ */
+export function createMcpServer({ name, version, tools = [] }) {
+  const toolMap = new Map(tools.map((t) => [t.name, t]));
+
+  function send(msg) {
+    process.stdout.write(JSON.stringify(msg) + '\n');
+  }
+
+  function ok(id, result) {
+    send({ jsonrpc: '2.0', id, result });
+  }
+
+  function fail(id, code, message) {
+    send({ jsonrpc: '2.0', id, error: { code, message } });
+  }
+
+  async function handleMessage(msg) {
+    if (!msg || typeof msg !== 'object') return;
+    const { id, method, params } = msg;
+
+    // Notifications carry no id and expect no response
+    if (method === 'notifications/initialized' || method === 'initialized') return;
+
+    switch (method) {
+      case 'initialize':
+        return ok(id, {
+          protocolVersion: params?.protocolVersion || '2025-06-18',
+          capabilities: { tools: {} },
+          serverInfo: { name, version: version || '1.0.0' },
+        });
+
+      case 'ping':
+        return ok(id, {});
+
+      case 'tools/list':
+        return ok(id, {
+          tools: tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            inputSchema: t.inputSchema,
+          })),
+        });
+
+      case 'tools/call': {
+        const toolName = params?.name;
+        const args = params?.arguments || {};
+        const tool = toolMap.get(toolName);
+
+        if (!tool) {
+          return fail(id, -32602, `Unknown tool: ${toolName}`);
+        }
+
+        try {
+          const result = await tool.handler(args);
+          if (typeof result === 'string') {
+            return ok(id, {
+              content: [{ type: 'text', text: result }],
+              isError: false,
+            });
+          }
+
+          return ok(id, {
+            content: [{ type: 'text', text: result.text || '' }],
+            isError: Boolean(result.isError),
+          });
+        } catch (err) {
+          const formatted = formatResilientResponse({
+            provider: name,
+            rawOutput: err?.message || String(err),
+          });
+          return ok(id, {
+            content: [{ type: 'text', text: formatted.text }],
+            isError: true,
+          });
+        }
+      }
+
+      default:
+        if (id !== undefined) {
+          fail(id, -32601, `Method not found: ${method}`);
+        }
+    }
+  }
+
+  function start() {
+    const rl = readline.createInterface({
+      input: process.stdin,
+      terminal: false,
+    });
+    rl.on('line', async (line) => {
+      const trimmed = line.trim();
+      if (!trimmed) return;
+      try {
+        const msg = JSON.parse(trimmed);
+        await handleMessage(msg);
+      } catch {
+        // Ignore unparseable lines silently per JSON-RPC over stdio
+      }
+    });
+  }
+
+  return { start, handleMessage };
+}

package/test/server.test.js

@@ -0,0 +1,78 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createMcpServer } from '../server.js';
+import { resolveBinary } from '../resolver.js';
+import { isRateLimitError, isAuthError } from '../errors.js';
+
+test('createMcpServer responds to initialize, ping, and tools/list', async () => {
+  let lastOutput = null;
+  const originalWrite = process.stdout.write;
+  process.stdout.write = (chunk) => {
+    lastOutput = JSON.parse(chunk.toString().trim());
+    return true;
+  };
+
+  try {
+    const server = createMcpServer({
+      name: 'test-server',
+      version: '1.2.3',
+      tools: [
+        {
+          name: 'test_tool',
+          description: 'A test tool',
+          inputSchema: { type: 'object' },
+          handler: async () => 'Hello from test tool!',
+        },
+      ],
+    });
+
+    // 1. initialize
+    await server.handleMessage({ jsonrpc: '2.0', id: 1, method: 'initialize' });
+    assert.equal(lastOutput.id, 1);
+    assert.equal(lastOutput.result.serverInfo.name, 'test-server');
+    assert.equal(lastOutput.result.serverInfo.version, '1.2.3');
+
+    // 2. ping
+    await server.handleMessage({ jsonrpc: '2.0', id: 2, method: 'ping' });
+    assert.equal(lastOutput.id, 2);
+    assert.deepEqual(lastOutput.result, {});
+
+    // 3. tools/list
+    await server.handleMessage({ jsonrpc: '2.0', id: 3, method: 'tools/list' });
+    assert.equal(lastOutput.id, 3);
+    assert.equal(lastOutput.result.tools.length, 1);
+    assert.equal(lastOutput.result.tools[0].name, 'test_tool');
+
+    // 4. tools/call
+    await server.handleMessage({
+      jsonrpc: '2.0',
+      id: 4,
+      method: 'tools/call',
+      params: { name: 'test_tool', arguments: {} },
+    });
+    assert.equal(lastOutput.id, 4);
+    assert.equal(lastOutput.result.isError, false);
+    assert.equal(lastOutput.result.content[0].text, 'Hello from test tool!');
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+});
+
+test('resolver finds executables on system or honors override', () => {
+  const nodeBin = resolveBinary('node');
+  assert.ok(nodeBin, 'node executable should be resolved on all platforms');
+  assert.match(nodeBin, /node(\.exe)?$/i);
+
+  // Verify override support
+  process.env.TEST_CUSTOM_BIN = process.execPath;
+  const custom = resolveBinary('custom', 'TEST_CUSTOM_BIN');
+  assert.equal(custom, process.execPath);
+  delete process.env.TEST_CUSTOM_BIN;
+});
+
+test('errors detects rate limits and auth errors', () => {
+  assert.equal(isRateLimitError('ResourceExhausted: Quota exceeded 429'), true);
+  assert.equal(isRateLimitError('Normal response'), false);
+  assert.equal(isAuthError('Please sign in with: agy login'), true);
+  assert.equal(isAuthError('Success'), false);
+});