mobygate 0.3.0

package/mcp-inspect.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+/**
+ * mcp-inspect.mjs — raw MCP tool response inspector
+ *
+ * Purpose: diagnose whether an MCP server (e.g. Paper, Pencil) actually
+ * returns binary image content, or whether the image is being dropped by
+ * a client-side bridge (e.g. Hermes) during normalization.
+ *
+ * This connects directly to the MCP server over stdio, bypassing Hermes
+ * entirely. If the tool returns image content here, the problem is
+ * client-side; if it returns empty, the problem is in the MCP server.
+ *
+ * USAGE
+ *   # List available tools
+ *   node mcp-inspect.mjs --cmd "<server-exe>" --args '["<arg1>",...]' --list
+ *
+ *   # Call a tool and dump raw response
+ *   node mcp-inspect.mjs --cmd "<server-exe>" --args '["<arg1>",...]' \
+ *     --tool <tool-name> --params '{"key":"value"}'
+ *
+ *   # Env vars for the child
+ *   node mcp-inspect.mjs --cmd "..." --env '{"API_KEY":"foo"}' --tool ...
+ *
+ * EXAMPLE (hypothetical Paper MCP server)
+ *   node mcp-inspect.mjs \
+ *     --cmd "npx" --args '["-y","@paper/mcp-server"]' \
+ *     --tool get_screenshot --params '{"artboard":"WL-0"}'
+ *
+ * OUTPUT
+ *   - Summary of content blocks by type, with sizes
+ *   - First/last 60 chars of any base64 image payload (to confirm bytes are real)
+ *   - Full raw JSON response (pretty-printed) at the end
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';
+
+// ---------- Arg parsing ----------
+
+function parseArgs(argv) {
+  const out = { list: false, params: {}, args: [], env: {}, transport: 'http' };
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    switch (a) {
+      case '--cmd': out.cmd = next; i++; break;
+      case '--args': out.args = JSON.parse(next); i++; break;
+      case '--env': out.env = JSON.parse(next); i++; break;
+      case '--url': out.url = next; i++; break;
+      case '--transport': out.transport = next; i++; break; // http | sse
+      case '--tool': out.tool = next; i++; break;
+      case '--params': out.params = JSON.parse(next); i++; break;
+      case '--list': out.list = true; break;
+      case '--help':
+      case '-h':
+        printUsage();
+        process.exit(0);
+      default:
+        console.error(`Unknown arg: ${a}`);
+        printUsage();
+        process.exit(1);
+    }
+  }
+  if (!out.cmd && !out.url) { console.error('ERROR: provide --cmd (stdio) or --url (http/sse)'); printUsage(); process.exit(1); }
+  if (!out.list && !out.tool) { console.error('ERROR: provide --tool <name> or --list'); process.exit(1); }
+  return out;
+}
+
+function printUsage() {
+  console.error(`
+Usage: node mcp-inspect.mjs --cmd "<exe>" [--args '["..."]'] [--env '{...}'] \\
+                            (--list | --tool <name> [--params '{...}'])
+
+Connects to an MCP server over stdio and dumps the raw response payload.
+Useful to verify whether binary image data is reaching the MCP boundary
+before any client-side normalization (e.g. Hermes) strips it.
+`);
+}
+
+// ---------- Content-block summary ----------
+
+function summarizeContent(content) {
+  if (!Array.isArray(content)) return `content is not an array: ${typeof content}`;
+  const rows = [];
+  for (let i = 0; i < content.length; i++) {
+    const block = content[i];
+    const type = block?.type || 'unknown';
+    if (type === 'text') {
+      const text = block.text || '';
+      rows.push(`  [${i}] text — ${text.length} chars: ${JSON.stringify(text.slice(0, 80))}${text.length > 80 ? '…' : ''}`);
+    } else if (type === 'image') {
+      const data = block.data || '';
+      const mime = block.mimeType || '?';
+      const approxBytes = Math.floor(data.length * 0.75); // base64 → bytes
+      const head = data.slice(0, 60);
+      const tail = data.slice(-20);
+      rows.push(`  [${i}] image — mime=${mime}, base64=${data.length} chars (~${approxBytes} bytes)`);
+      rows.push(`        head: ${head}${data.length > 80 ? `…${tail}` : ''}`);
+    } else if (type === 'resource') {
+      rows.push(`  [${i}] resource — uri=${block.resource?.uri || '?'}`);
+    } else {
+      rows.push(`  [${i}] ${type} — ${JSON.stringify(block).slice(0, 140)}`);
+    }
+  }
+  return rows.join('\n') || '  (empty)';
+}
+
+// ---------- Main ----------
+
+async function main() {
+  const opts = parseArgs(process.argv);
+
+  let transport;
+  if (opts.url) {
+    console.log(`[${opts.transport}] ${opts.url}`);
+    const url = new URL(opts.url);
+    transport = opts.transport === 'sse'
+      ? new SSEClientTransport(url)
+      : new StreamableHTTPClientTransport(url);
+  } else {
+    console.log(`[spawn] ${opts.cmd} ${opts.args.map((a) => JSON.stringify(a)).join(' ')}`);
+    transport = new StdioClientTransport({
+      command: opts.cmd,
+      args: opts.args,
+      env: { ...process.env, ...opts.env },
+    });
+  }
+
+  const client = new Client(
+    { name: 'mcp-inspect', version: '0.1.0' },
+    { capabilities: {} }
+  );
+
+  try {
+    await client.connect(transport);
+    console.log('[connected]');
+
+    if (opts.list) {
+      const res = await client.listTools();
+      console.log(`\n=== Tools (${res.tools?.length || 0}) ===`);
+      for (const t of res.tools || []) {
+        console.log(`  ${t.name} — ${t.description?.slice(0, 80) || '(no description)'}`);
+      }
+      console.log('\n--- raw listTools response ---');
+      console.log(JSON.stringify(res, null, 2));
+    } else {
+      console.log(`\n[call] tool=${opts.tool} params=${JSON.stringify(opts.params)}`);
+      const started = Date.now();
+      const res = await client.callTool({ name: opts.tool, arguments: opts.params });
+      const dur = Date.now() - started;
+
+      console.log(`\n=== Response (${dur}ms) ===`);
+      console.log(`isError: ${res.isError === true ? 'YES' : 'no'}`);
+      console.log(`content blocks: ${Array.isArray(res.content) ? res.content.length : '(not an array)'}`);
+      if (Array.isArray(res.content)) {
+        const byType = {};
+        for (const b of res.content) byType[b.type || 'unknown'] = (byType[b.type || 'unknown'] || 0) + 1;
+        console.log(`by type: ${JSON.stringify(byType)}`);
+      }
+
+      console.log('\n--- content summary ---');
+      console.log(summarizeContent(res.content));
+
+      console.log('\n--- raw response JSON ---');
+      // Truncate image base64 in the pretty-print to keep output readable;
+      // we already showed head/tail above.
+      const safe = JSON.parse(JSON.stringify(res, (key, val) => {
+        if (key === 'data' && typeof val === 'string' && val.length > 200) {
+          return `${val.slice(0, 80)}…[${val.length - 100} chars elided]…${val.slice(-20)}`;
+        }
+        return val;
+      }));
+      console.log(JSON.stringify(safe, null, 2));
+    }
+  } catch (e) {
+    console.error(`\n[ERROR] ${e.message}`);
+    if (e.stack) console.error(e.stack.split('\n').slice(0, 4).join('\n'));
+    process.exit(1);
+  } finally {
+    try { await client.close(); } catch {}
+  }
+}
+
+main();

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "mobygate",
+  "version": "0.3.0",
+  "description": "OpenAI-compatible local proxy for Claude Max. The Möbius-strip gateway: OpenAI shape in, Claude Max out.",
+  "type": "module",
+  "main": "server.js",
+  "bin": {
+    "mobygate": "./bin/mobygate.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "dev": "node --watch server.js",
+    "up": "npm install && node server.js",
+    "auth:status": "node scripts/auth-status.js",
+    "auth:status:quick": "node scripts/auth-status.js --quick",
+    "auth:refresh": "node scripts/auth-refresh.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.112",
+    "express": "^5.1.0",
+    "js-yaml": "^4.1.1",
+    "uuid": "^11.1.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/khnfrhn/mobygate.git"
+  },
+  "homepage": "https://github.com/khnfrhn/mobygate#readme",
+  "bugs": {
+    "url": "https://github.com/khnfrhn/mobygate/issues"
+  },
+  "author": "Farhan Khan",
+  "license": "MIT",
+  "keywords": [
+    "claude",
+    "claude-max",
+    "anthropic",
+    "openai-compatible",
+    "proxy",
+    "gateway",
+    "llm",
+    "ai",
+    "agent-sdk",
+    "localhost",
+    "dashboard"
+  ],
+  "files": [
+    "bin",
+    "lib",
+    "scripts",
+    "launchd",
+    "server.js",
+    "index.html",
+    "mcp-inspect.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ]
+}

package/scripts/auth-helper.js

@@ -0,0 +1,198 @@
+/**
+ * Auth helper — bridges the proxy to Claude Code's CLI auth machinery.
+ *
+ * The Claude Agent SDK reads OAuth credentials from the macOS keychain
+ * ("Claude Code-credentials") via the bundled CLI. The SDK is supposed to
+ * silently refresh the access token on 401, but in practice it sometimes
+ * eats the refresh path and surfaces the 401 to the caller. This module
+ * provides three things:
+ *
+ *   getAuthStatus()    — shells `claude auth status --json` (loggedIn,
+ *                        authMethod, email, etc.). The CLI does NOT report
+ *                        token expiry directly, so we treat "loggedIn:true"
+ *                        as necessary-but-not-sufficient and pair it with
+ *                        a real probe when the caller needs verification.
+ *
+ *   forceRefresh()     — fires a 1-token `claude -p` probe. If the access
+ *                        token is expired the CLI will silently refresh
+ *                        using the still-valid refresh token. Returns
+ *                        { ok, refreshed, durationMs, output } so callers
+ *                        can log loudly.
+ *
+ *   runWithAuthRetry() — wrap an SDK `query()` consumer. On 401-shaped
+ *                        errors, call forceRefresh() and retry the
+ *                        producer once. Idempotent because we only retry
+ *                        the failure that comes BEFORE the first chunk
+ *                        is yielded — we never replay mid-stream.
+ */
+
+import { spawn } from 'child_process';
+
+// Default to the bare binary name so PATH lookup works on every platform.
+// - macOS/Linux: typically ~/.local/bin/claude (on PATH after standard install)
+// - Windows: claude.cmd or claude.exe on PATH after MSI / `npm install -g`
+// If yours isn't on PATH, set CLAUDE_BIN to an absolute path.
+const CLAUDE_BIN = process.env.CLAUDE_BIN || 'claude';
+const IS_WINDOWS = process.platform === 'win32';
+const PROBE_TIMEOUT_MS = 30_000;
+
+function runClaude(args, { timeoutMs = PROBE_TIMEOUT_MS, input } = {}) {
+  return new Promise((resolve) => {
+    // On Windows, spawn can't execute .cmd/.bat shim wrappers without a
+    // shell. Rather than `shell: true` + args-array (deprecated in Node
+    // 20+ as DEP0190), we invoke cmd.exe explicitly with a quoted command
+    // string we build ourselves.
+    let proc;
+    if (IS_WINDOWS) {
+      const quote = (s) => /[\s"]/.test(s) ? `"${String(s).replace(/"/g, '""')}"` : String(s);
+      const cmdline = [quote(CLAUDE_BIN), ...args.map(quote)].join(' ');
+      proc = spawn('cmd.exe', ['/c', cmdline], { stdio: ['pipe', 'pipe', 'pipe'] });
+    } else {
+      proc = spawn(CLAUDE_BIN, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    }
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      proc.kill('SIGKILL');
+    }, timeoutMs);
+    proc.stdout.on('data', (d) => { stdout += d.toString(); });
+    proc.stderr.on('data', (d) => { stderr += d.toString(); });
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ code: -1, stdout, stderr: stderr + '\n' + err.message, timedOut });
+    });
+    proc.on('close', (code) => {
+      clearTimeout(timer);
+      resolve({ code, stdout, stderr, timedOut });
+    });
+    if (input != null) {
+      proc.stdin.write(input);
+      proc.stdin.end();
+    } else {
+      proc.stdin.end();
+    }
+  });
+}
+
+export async function getAuthStatus() {
+  const { code, stdout, stderr } = await runClaude(['auth', 'status', '--json'], { timeoutMs: 10_000 });
+  if (code !== 0) {
+    return { ok: false, loggedIn: false, error: stderr.trim() || `claude auth status exited ${code}` };
+  }
+  try {
+    const parsed = JSON.parse(stdout);
+    return { ok: true, ...parsed };
+  } catch (e) {
+    return { ok: false, loggedIn: false, error: `failed to parse claude auth status output: ${e.message}` };
+  }
+}
+
+/**
+ * Force the SDK/CLI to refresh its access token.
+ *
+ * Strategy: fire a 1-token print-mode query. If the access token is expired,
+ * the CLI's auth layer will detect the 401 from Anthropic and silently swap
+ * in a fresh access token via the refresh_token grant. Then it succeeds.
+ * If the token was already fresh, this just returns instantly.
+ *
+ * We can't observe "did a refresh actually happen" from outside — the CLI
+ * doesn't print that. We only know "after this, the token is valid OR we
+ * couldn't make it valid".
+ */
+export async function forceRefresh() {
+  const start = Date.now();
+  // -p forces print-mode round-trip. --max-turns 1 caps it at a single turn.
+  // We pipe '' to stdin to avoid hanging on TTY detection.
+  const { code, stdout, stderr, timedOut } = await runClaude(
+    ['-p', 'reply with the single word OK', '--max-turns', '1'],
+    { timeoutMs: 30_000, input: '' }
+  );
+  const durationMs = Date.now() - start;
+  if (timedOut) {
+    return { ok: false, refreshed: false, durationMs, error: 'probe timed out — refresh may still be in flight' };
+  }
+  if (code !== 0) {
+    return { ok: false, refreshed: false, durationMs, error: stderr.trim() || `probe exited ${code}`, output: stdout.trim() };
+  }
+  return { ok: true, refreshed: true, durationMs, output: stdout.trim() };
+}
+
+/**
+ * True if the error looks like an auth failure from Anthropic.
+ */
+export function is401Error(err) {
+  if (!err) return false;
+  const msg = err.message || String(err);
+  if (err.status === 401 || err.statusCode === 401) return true;
+  if (/\b401\b/.test(msg)) return true;
+  if (/authentication_error|Invalid authentication credentials|invalid_grant|unauthorized/i.test(msg)) return true;
+  return false;
+}
+
+/**
+ * True if a completion result TEXT looks like an auth failure the SDK
+ * surfaced inline instead of throwing. Long-running proxies hit this
+ * after ~8h when the SDK's cached creds expire and Anthropic returns 401,
+ * but the SDK emits the error body as result text rather than an exception.
+ *
+ * Pattern seen in practice:
+ *   "Failed to authenticate. API Error: 401 {\"type\":\"error\",..."
+ */
+export function isAuthFailureText(text) {
+  if (!text || typeof text !== 'string') return false;
+  if (/Failed to authenticate.*401/i.test(text)) return true;
+  if (/"type"\s*:\s*"authentication_error"/i.test(text)) return true;
+  if (/Invalid authentication credentials/i.test(text)) return true;
+  return false;
+}
+
+// Thrown when we detect an auth failure in result-message text so the
+// outer runWithAuthRetry wrapper treats it the same as a real 401 exception.
+export class AuthFailureInResultText extends Error {
+  constructor(text) {
+    super(`Auth failure surfaced as result text: ${text.slice(0, 160)}`);
+    this.name = 'AuthFailureInResultText';
+    this.statusCode = 401;
+    this.resultText = text;
+  }
+}
+
+/**
+ * Wrap an SDK query() consumer with one-shot auth retry.
+ *
+ * Usage:
+ *   await runWithAuthRetry({
+ *     attempt: async () => {
+ *       for await (const m of query({...})) { ... }
+ *     },
+ *     onRefreshing: () => console.log('refreshing...'),
+ *     onRetry: () => console.log('retrying...'),
+ *   });
+ *
+ * The `attempt` fn must be safe to invoke twice. If the first failure happens
+ * AFTER you've started writing to a response stream, you should set
+ * `bailIfStarted: () => boolean` so we don't retry mid-stream.
+ */
+export async function runWithAuthRetry({ attempt, onRefreshing, onRetry, bailIfStarted }) {
+  try {
+    return await attempt();
+  } catch (err) {
+    if (!is401Error(err)) throw err;
+    if (bailIfStarted && bailIfStarted()) {
+      // Stream already started — can't safely retry.
+      throw err;
+    }
+    if (onRefreshing) onRefreshing(err);
+    const refresh = await forceRefresh();
+    if (!refresh.ok) {
+      const e = new Error(`401 from Anthropic and proxy refresh failed: ${refresh.error || 'unknown'}`);
+      e.cause = err;
+      e.refreshAttempt = refresh;
+      throw e;
+    }
+    if (onRetry) onRetry(refresh);
+    return await attempt();
+  }
+}

package/scripts/auth-refresh.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Standalone auth refresher — meant to be run from cron / launchd.
+ *
+ * Forces the Claude Code CLI to validate (and silently refresh) its OAuth
+ * access token. Prints a single JSON line so log output stays grep-able.
+ *
+ * Exit codes:
+ *   0  — token is valid (refreshed if needed)
+ *   2  — not logged in (manual `claude auth login` required)
+ *   3  — refresh probe failed (network? Anthropic outage?)
+ *   1  — unexpected error
+ *
+ * Usage:
+ *   node scripts/auth-refresh.js
+ *   npm run auth:refresh
+ */
+
+import { getAuthStatus, forceRefresh } from './auth-helper.js';
+
+function emit(obj) {
+  process.stdout.write(JSON.stringify({ ts: new Date().toISOString(), ...obj }) + '\n');
+}
+
+try {
+  const status = await getAuthStatus();
+  if (!status.ok || !status.loggedIn) {
+    emit({ stage: 'status', ok: false, status, hint: 'run: claude auth login' });
+    process.exit(2);
+  }
+  const refresh = await forceRefresh();
+  if (!refresh.ok) {
+    emit({ stage: 'refresh', ok: false, status, refresh });
+    process.exit(3);
+  }
+  emit({ stage: 'done', ok: true, email: status.email, subscription: status.subscriptionType, durationMs: refresh.durationMs });
+  process.exit(0);
+} catch (e) {
+  emit({ stage: 'error', ok: false, error: e.message, stack: e.stack });
+  process.exit(1);
+}

package/scripts/auth-status.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * CLI wrapper that prints auth status as JSON, including a real probe.
+ *
+ * Unlike `claude auth status --json` which only checks "does a token object
+ * exist on disk", this also fires a 1-token probe to verify the access
+ * token is actually accepted by Anthropic right now. That's the difference
+ * between "loggedIn:true" (cheap) and "verified:true" (real).
+ *
+ * Pass --quick to skip the probe.
+ *
+ * Usage:
+ *   node scripts/auth-status.js
+ *   node scripts/auth-status.js --quick
+ *   npm run auth:status
+ */
+
+import { getAuthStatus, forceRefresh } from './auth-helper.js';
+
+const quick = process.argv.includes('--quick');
+
+const status = await getAuthStatus();
+let verified = null;
+let probe = null;
+if (!quick && status.ok && status.loggedIn) {
+  probe = await forceRefresh();
+  verified = !!probe.ok;
+}
+
+const out = {
+  ts: new Date().toISOString(),
+  ...status,
+  ...(quick ? {} : { verified, probeMs: probe?.durationMs, probeError: probe?.error }),
+};
+process.stdout.write(JSON.stringify(out, null, 2) + '\n');
+process.exit(status.ok && status.loggedIn && (quick || verified) ? 0 : 1);