@ikeytz/maps-mcp 1.0.4 → 1.0.6

package/src/cli.js

@@ -1,52 +1,166 @@
-import { spawn } from "node:child_process";
-import { callTool, mapsMcpUrl, mapsRpc, packageVersion, showMcpCommand, toolByName, toolNames } from "./proxy.js";
+/**
+ * Human terminal CLI over the same remote MCP SSOT (maps.ikeytz.com).
+ * Subcommands: help | list | describe | call | <toolName>
+ * No args → stdio proxy (MCP hosts).
+ * Structure aligned with @ikeytz/mcp (ikeytz-mcp) — other remote, maps-only tools.
+ */
 
-const TOOL_FLAGS = [
-  "slug",
-  "plz",
-  "name",
-  "which",
-  "offset",
-  "limit",
-  "q",
-  "path",
-  "url",
-  "icbm",
-  "lat",
-  "lng",
-  "radius_km",
-  "doc",
-];
-const NUMBER_FLAGS = new Set(["offset", "limit", "lat", "lng", "radius_km"]);
+import { spawnSync } from "node:child_process";
+import { stderr as log, stdout as out } from "node:process";
+import {
+  CATALOG,
+  callTool,
+  mapsMcpProtocol,
+  mapsMcpUrl,
+  mapsRpc,
+  packageVersion,
+  toolByName,
+} from "./proxy.js";
+
+function catalogTools() {
+  return CATALOG.tools || [];
+}
+
+function exampleForTool(name) {
+  const p = "ikeytz-maps-mcp";
+  const map = {
+    list_service_areas: `${p} list_service_areas`,
+    get_service_area: `${p} get_service_area --slug=pattonville`,
+    get_geo_office: `${p} get_geo_office`,
+    get_contact: `${p} get_contact`,
+    get_discovery: `${p} get_discovery --which=llms-urheberrecht`,
+    get_llms_mcp_server: `${p} get_llms_mcp_server`,
+    get_llms_mcp_web: `${p} get_llms_mcp_web`,
+    find_by_keyword: `${p} find_by_keyword --q=Pattonville --limit=5`,
+    find_by_serp: `${p} find_by_serp --q=Grünbühl`,
+    get_serp_snippet: `${p} get_serp_snippet --slug=pattonville`,
+    find_by_plz: `${p} find_by_plz --plz=71638`,
+    find_by_geo: `${p} find_by_geo --lat=48.873174 --lng=9.224754`,
+    find_by_icbm: `${p} find_by_icbm --icbm=48.873174,9.224754`,
+    find_by_gebiet: `${p} find_by_gebiet --q=Grünbühl`,
+    find_by_area: `${p} find_by_area --q=Grünbühl`,
+    list_slugs: `${p} list_slugs`,
+    list_plz: `${p} list_plz`,
+    get_hub: `${p} get_hub`,
+    get_embed_map: `${p} get_embed_map --slug=pattonville`,
+    get_geo_api: `${p} get_geo_api --slug=pattonville`,
+    get_lage: `${p} get_lage --slug=pattonville`,
+    get_geschichte: `${p} get_geschichte --slug=pattonville`,
+    distance_to_office: `${p} distance_to_office --slug=pattonville`,
+    resolve_maps_url: `${p} resolve_maps_url --url=https://maps.ikeytz.com/pattonville`,
+    find_by_google_maps: `${p} find_by_google_maps --q=48.873174,9.224754`,
+    get_legal: `${p} get_legal --doc=urheberrecht`,
+    get_urheberrecht: `${p} get_urheberrecht`,
+    get_copyright: `${p} get_copyright`,
+    get_impressum: `${p} get_impressum`,
+    get_agb: `${p} get_agb`,
+    get_nutzungsbedingungen: `${p} get_nutzungsbedingungen`,
+    get_datenschutz: `${p} get_datenschutz`,
+    get_widerruf: `${p} get_widerruf`,
+    site_overview: `${p} site_overview --locale=de`,
+    get_business_identity: `${p} get_business_identity --locale=de`,
+    list_nav: `${p} list_nav --locale=de`,
+    list_footer: `${p} list_footer --locale=de`,
+    list_locales: `${p} list_locales`,
+    resolve_locale_url: `${p} resolve_locale_url --path=/pattonville --locale=de`,
+    get_prices: `${p} get_prices --locale=de`,
+    get_about: `${p} get_about --locale=de`,
+    get_links: `${p} get_links --locale=de`,
+    get_llms_txt: `${p} get_llms_txt`,
+    get_sitemap_txt: `${p} get_sitemap_txt`,
+    compose_tel_mobile: `${p} compose_tel_mobile`,
+    compose_mailto: `${p} compose_mailto`,
+  };
+  return map[name] || `${p} ${name}`;
+}
+
+function argHint(tool) {
+  const props = Object.keys(tool.inputSchema?.properties || {});
+  const req = tool.inputSchema?.required || [];
+  if (!props.length) return "";
+  return props.map((k) => (req.includes(k) ? `--${k}*` : `--${k}`)).join(" ");
+}
+
+function formatToolsAsciiTable(rows) {
+  const n = rows.length;
+  const cn = String(n).length;
+  const c0 = Math.max(4, ...rows.map((r) => r.tool.length), "TOOL".length);
+  const c1 = Math.max(4, ...rows.map((r) => r.args.length), "ARGS".length);
+  const pad = (s, w, align = "left") => {
+    const t = String(s);
+    if (t.length >= w) return t;
+    const sp = " ".repeat(w - t.length);
+    return align === "right" ? sp + t : t + sp;
+  };
+  const rule = `${"─".repeat(cn)}─┼─${"─".repeat(c0)}─┼─${"─".repeat(c1)}─┼─${"─".repeat(7)}`;
+  const lines = [`${pad("#", cn, "right")} │ ${pad("TOOL", c0)} │ ${pad("ARGS", c1)} │ EXAMPLE`, rule];
+  rows.forEach((r, i) => {
+    lines.push(
+      `${pad(String(i + 1), cn, "right")} │ ${pad(r.tool, c0)} │ ${pad(r.args, c1)} │ ${r.example}`
+    );
+    lines.push(rule);
+  });
+  return lines;
+}
 
 function globalCliFlagsLines() {
   return [
+    "",
     "Global CLI flags (every tool — not sent to MCP)",
     "  -h, --help, -help   per-tool help (offline)",
     "  --raw               JSON structuredContent",
-    "  --show-mcp-command  curl 1a/1b/2 only — no MCP call (alias: --show-mcp-befehl)",
-    "  --json '{…}'        raw MCP arguments",
+    "  --show-mcp-command  curl 1a/1b/2 only — no MCP call",
+    "                      aliases: --show-mcp-befehl · --show-mcp-comment",
     "",
     "Default tool output   payload only (no ok/tool/meta envelope)",
-    "  --name=value   --name value",
+    "  --name=value   --name value   --json '{...}'",
   ];
 }
 
-function exampleForTool(name) {
-  const examples = {
-    get_service_area: "ikeytz-maps-mcp get_service_area --slug=pattonville",
-    get_discovery: "ikeytz-maps-mcp get_discovery --which=llms-urheberrecht",
-    find_by_plz: "ikeytz-maps-mcp find_by_plz --plz=71638",
-    get_legal: "ikeytz-maps-mcp get_legal --doc=urheberrecht",
-    get_urheberrecht: "ikeytz-maps-mcp get_urheberrecht",
-    get_agb: "ikeytz-maps-mcp get_agb",
-    get_nutzungsbedingungen: "ikeytz-maps-mcp get_nutzungsbedingungen",
-    get_lage: "ikeytz-maps-mcp get_lage --slug=pattonville",
-  };
-  return examples[name] || `ikeytz-maps-mcp ${name}`;
+function printHumanHelp(tools) {
+  const lines = [
+    `ikeytz-maps-mcp ${packageVersion()}`,
+    `Remote  ${mapsMcpUrl()}`,
+    `Registry  com.ikeytz/maps`,
+    "Nur maps. Nicht @ikeytz/mcp / www.",
+    "",
+    "Usage",
+    "  ikeytz-maps-mcp                         MCP proxy (Cursor/Claude)",
+    "  ikeytz-maps-mcp --version               package version (offline)",
+    "  ikeytz-maps-mcp help                    this help (offline, no MCP connect)",
+    "  ikeytz-maps-mcp update [version]        npm i -g @ikeytz/maps-mcp@latest",
+    "  ikeytz-maps-mcp list                    tool table (offline) + global flags",
+    "  ikeytz-maps-mcp list --global           global CLI flags only (offline)",
+    "  ikeytz-maps-mcp describe <tool>         args + examples (offline)",
+    "  ikeytz-maps-mcp call <tool> [flags]",
+    "  ikeytz-maps-mcp <tool> [flags]          same as call",
+    "  ikeytz-maps-mcp <tool> -h               per-tool help (offline, same as describe)",
+    "  ikeytz-maps-mcp <tool> --show-mcp-command",
+    "",
+    ...globalCliFlagsLines().slice(1),
+    "",
+  ];
+  if (tools?.length) {
+    const rows = [...tools]
+      .sort((a, b) => a.name.localeCompare(b.name))
+      .map((t) => ({
+        tool: t.name,
+        args: argHint(t) || "—",
+        example: exampleForTool(t.name),
+      }));
+    lines.push(`Tools  ${rows.length}  (A–Z numbered, * = required)`);
+    lines.push("");
+    lines.push(...formatToolsAsciiTable(rows));
+    lines.push("");
+    lines.push("Tip  ikeytz-maps-mcp describe get_service_area");
+  } else {
+    lines.push("Tools  ikeytz-maps-mcp list  (offline) · ikeytz-maps-mcp <tool> -h for args");
+  }
+  lines.push("");
+  out.write(`${lines.join("\n")}\n`);
 }
 
-function formatToolHelp(tool) {
+function formatDescribe(tool) {
   const schema = tool.inputSchema || { type: "object", properties: {} };
   const props = schema.properties || {};
   const req = new Set(schema.required || []);
@@ -59,7 +173,8 @@ function formatToolHelp(tool) {
       const p = props[key] || {};
       const type = p.enum ? p.enum.join("|") : p.type || "any";
       const star = req.has(key) ? "*" : " ";
-      lines.push(`  ${star} --${key.padEnd(16)} ${type}`);
+      const desc = p.description ? `  ${p.description}` : "";
+      lines.push(`  ${star} --${key.padEnd(16)} ${type}${desc}`);
     }
     if (req.size) {
       lines.push("");
@@ -70,119 +185,156 @@ function formatToolHelp(tool) {
   lines.push("CLI flags (not sent to MCP)");
   lines.push("  -h, --help, -help  this help (offline, no MCP call)");
   lines.push("  --raw              JSON structuredContent");
-  lines.push("  --show-mcp-command   curl 1a/1b/2 only — no MCP call (alias: --show-mcp-befehl)");
+  lines.push("  --show-mcp-command   curl 1a/1b/2 only (aliases: --show-mcp-befehl, --show-mcp-comment)");
   lines.push("");
   lines.push("Examples");
   lines.push(`  ${exampleForTool(tool.name)}`);
   lines.push(`  ikeytz-maps-mcp ${tool.name} -h`);
   lines.push(`  ikeytz-maps-mcp ${tool.name} --show-mcp-command`);
-  return `${lines.join("\n")}\n`;
+  return lines.filter((l, i) => !(i === 1 && !l)).join("\n");
 }
 
-const HELP = `ikeytz-maps-mcp ${packageVersion()}
-Remote: ${mapsMcpUrl()}
-Nur maps. Nicht @ikeytz/mcp / www.
+const SHOW_MCP_COMMAND_FLAGS = new Set([
+  "--show-mcp-command",
+  "--show-mcp-befehl",
+  "--show-mcp-comment",
+]);
 
-Ohne Args          stdio-Proxy (Cursor/Claude)
-help | --help      diese Hilfe
---version          Version
-update [ver]       npm i -g @ikeytz/maps-mcp@latest
-list               ${toolNames().length} Tools (offline) + global CLI flags
-list --global      nur globale CLI-Flags (offline)
-describe <tool>    Args + Flags + Beispiele (offline)
-call <tool> …      wie <tool> …
-<tool>             Payload von maps /mcp
-<tool> -h          Args + CLI-Flags (offline)
-<tool> --show-mcp-command | --show-mcp-befehl
-<tool> --raw       JSON structuredContent
-<tool> --json '{…}'
+function wantsShowMcpCommand(argv) {
+  return argv.some((a) => SHOW_MCP_COMMAND_FLAGS.has(a));
+}
 
-${globalCliFlagsLines().join("\n")}
+function stripCliDisplayFlags(argv) {
+  return argv.filter((a) => !SHOW_MCP_COMMAND_FLAGS.has(a));
+}
 
-Tools:
-${toolNames()
-  .map((n) => `  ${n}`)
-  .join("\n")}
-`;
+function isHelpFlag(a) {
+  return a === "-h" || a === "--help" || a === "-help" || a === "help";
+}
 
-function parseArgv(argv) {
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
+function parseToolArgs(argv) {
+  const args = {};
+  let i = 0;
+  while (i < argv.length) {
     const a = argv[i];
-    if (a === "--raw") flags.raw = true;
-    else if (a === "--global") flags.global = true;
-    else if (a === "-h" || a === "--help" || a === "-help") flags.help = true;
-    else if (a === "--version") flags.version = true;
-    else if (a === "--show-mcp-command" || a === "--show-mcp-befehl") flags.showMcp = true;
-    else if (a === "--json") flags.json = argv[++i] || "";
-    else if (a.startsWith("--json=")) flags.json = a.slice(7);
-    else if (a.startsWith("--")) {
+    if (a === "--json") {
+      const raw = argv[i + 1];
+      if (!raw) throw new Error("--json needs a JSON object");
+      const parsed = JSON.parse(raw);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("--json must be an object");
+      }
+      Object.assign(args, parsed);
+      i += 2;
+      continue;
+    }
+    if (a.startsWith("--json=")) {
+      Object.assign(args, JSON.parse(a.slice("--json=".length)));
+      i += 1;
+      continue;
+    }
+    if (a.startsWith("--")) {
       const eq = a.indexOf("=");
-      if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
-      else {
-        const key = a.slice(2);
+      let key;
+      let val;
+      if (eq > 2) {
+        key = a.slice(2, eq);
+        val = a.slice(eq + 1);
+        i += 1;
+      } else {
+        key = a.slice(2);
         const next = argv[i + 1];
-        if (next && !next.startsWith("-")) {
-          flags[key] = next;
+        if (!next || next.startsWith("-")) {
+          val = true;
           i += 1;
-        } else flags[key] = true;
+        } else {
+          val = next;
+          i += 2;
+        }
       }
-    } else positionals.push(a);
+      if (val === "true") val = true;
+      else if (val === "false") val = false;
+      else if (typeof val === "string" && /^-?\d+(\.\d+)?$/.test(val)) val = Number(val);
+      args[key] = val;
+      continue;
+    }
+    throw new Error(`Unexpected argument: ${a}`);
   }
-  return { flags, positionals };
+  return args;
 }
 
-function argsFromFlags(flags) {
-  const args = {};
-  if (flags.json) Object.assign(args, JSON.parse(flags.json));
-  for (const key of TOOL_FLAGS) {
-    if (flags[key] != null && flags[key] !== true) {
-      args[key] = NUMBER_FLAGS.has(key) ? Number(flags[key]) : String(flags[key]);
-    }
+function formatMcpCurlHeading(toolName, callArgs = {}) {
+  const url = mapsMcpUrl();
+  const proto = mapsMcpProtocol();
+  const argsObj = callArgs && typeof callArgs === "object" ? callArgs : {};
+  const argsJson = JSON.stringify(argsObj);
+  const callBody = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: { name: toolName, arguments: argsObj },
+  });
+  const dq = (s) => String(s).replace(/'/g, `'\\''`);
+  const tool = toolByName(toolName);
+  const blurb = tool?.description || `Remote MCP tools/call · ${toolName}`;
+  const parts = [`ikeytz-maps-mcp ${toolName}`];
+  for (const [k, v] of Object.entries(argsObj)) {
+    if (v === undefined) continue;
+    parts.push(`--${k}=${v}`);
   }
-  return args;
+  const bar = "═".repeat(56);
+  const thin = "─".repeat(56);
+  return [
+    bar,
+    `MCP tool   ${toolName}`,
+    `What       ${blurb}`,
+    `CLI        ${parts.join(" ")}`,
+    `Args       ${argsJson}`,
+    `Registry   com.ikeytz/maps`,
+    `Remote     ${url}`,
+    thin,
+    `Equivalent curl (same MCP call)`,
+    "",
+    `# 1a) Session-ID holen`,
+    `SID=$(curl -sS -D - -o /tmp/ikeytz-maps-mcp-init.json -X POST '${url}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H 'Accept: application/json' \\`,
+    `  -H 'MCP-Protocol-Version: ${proto}' \\`,
+    `  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"${proto}","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}' \\`,
+    `  | awk -F': ' 'tolower($1)=="mcp-session-id"{gsub(/\\r/,"",$2); print $2; exit}')`,
+    `echo "SID=$SID"`,
+    "",
+    `# 1b) initialized`,
+    `curl -sS -X POST '${url}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H 'Accept: application/json' \\`,
+    `  -H 'MCP-Protocol-Version: ${proto}' \\`,
+    `  -H "Mcp-Session-Id: $SID" \\`,
+    `  -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' >/dev/null`,
+    "",
+    `# 2) Tool`,
+    `curl -sS -X POST '${url}' \\`,
+    `  -H 'Content-Type: application/json' \\`,
+    `  -H 'Accept: application/json' \\`,
+    `  -H 'MCP-Protocol-Version: ${proto}' \\`,
+    `  -H "Mcp-Session-Id: $SID" \\`,
+    `  -d '${dq(callBody)}'`,
+    bar,
+  ].join("\n");
 }
 
-function printPayload(rpc, raw) {
+function printCallResult(rpc, { raw = false } = {}) {
   if (raw) {
-    process.stdout.write(`${JSON.stringify(rpc, null, 2)}\n`);
+    out.write(`${JSON.stringify(rpc, null, 2)}\n`);
     return;
   }
   const data = rpc?.result?.structuredContent ?? rpc?.result ?? rpc;
-  process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
-}
-
-function readStdioMessage(buf) {
-  const text = buf.toString("utf8");
-  const headerEnd = text.indexOf("\r\n\r\n");
-  const altEnd = text.indexOf("\n\n");
-  if (headerEnd >= 0 || (altEnd >= 0 && /content-length:/i.test(text.slice(0, altEnd + 2)))) {
-    const split = headerEnd >= 0 ? headerEnd : altEnd;
-    const sep = headerEnd >= 0 ? 4 : 2;
-    const header = text.slice(0, split);
-    const m = header.match(/content-length:\s*(\d+)/i);
-    if (!m) return null;
-    const len = Number(m[1]);
-    const start = split + sep;
-    const body = Buffer.from(text, "utf8").subarray(start);
-    if (body.length < len) return null;
-    const json = JSON.parse(body.subarray(0, len).toString("utf8"));
-    return { json, rest: body.subarray(len) };
+  if (data && typeof data === "object") {
+    const { ok, tool, locale, related, attribution, ...payload } = data;
+    out.write(`${JSON.stringify(Object.keys(payload).length ? payload : data, null, 2)}\n`);
+    return;
   }
-  const nl = text.indexOf("\n");
-  if (nl < 0) return null;
-  const line = text.slice(0, nl).trim();
-  const rest = Buffer.from(text.slice(nl + 1), "utf8");
-  if (!line) return { json: null, rest };
-  return { json: JSON.parse(line), rest };
-}
-
-function writeStdio(msg) {
-  const json = JSON.stringify(msg);
-  const body = Buffer.from(json, "utf8");
-  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
-  process.stdout.write(body);
+  out.write(`${JSON.stringify(data, null, 2)}\n`);
 }
 
 async function runStdioProxy() {
@@ -208,22 +360,22 @@ async function runStdioProxy() {
         const id = msg.id;
         try {
           if (method === "initialize") {
-            const out = await mapsRpc("initialize", msg.params || {}, { id: id ?? 1 });
-            sessionId = out.sessionId || sessionId;
-            writeStdio(out.json);
+            const res = await mapsRpc("initialize", msg.params || {}, { id: id ?? 1 });
+            sessionId = res.sessionId || sessionId;
+            writeStdio(res.json);
           } else if (method === "notifications/initialized" || method === "initialized") {
-            const out = await mapsRpc("notifications/initialized", msg.params || {}, {
+            const res = await mapsRpc("notifications/initialized", msg.params || {}, {
               notification: true,
               sessionId,
             });
-            sessionId = out.sessionId || sessionId;
+            sessionId = res.sessionId || sessionId;
             if (id !== undefined) writeStdio({ jsonrpc: "2.0", id, result: {} });
           } else if (id === undefined) {
             await mapsRpc(method, msg.params || {}, { notification: true, sessionId });
           } else {
-            const out = await mapsRpc(method, msg.params || {}, { id, sessionId });
-            sessionId = out.sessionId || sessionId;
-            writeStdio(out.json);
+            const res = await mapsRpc(method, msg.params || {}, { id, sessionId });
+            sessionId = res.sessionId || sessionId;
+            writeStdio(res.json);
           }
         } catch (err) {
           if (id !== undefined) {
@@ -235,72 +387,131 @@ async function runStdioProxy() {
   });
 }
 
-export async function main(argv) {
-  const { flags, positionals } = parseArgv(argv);
-
-  if (flags.version && positionals.length === 0) {
-    process.stdout.write(`${packageVersion()}\n`);
-    return;
+function readStdioMessage(buf) {
+  const text = buf.toString("utf8");
+  const headerEnd = text.indexOf("\r\n\r\n");
+  const altEnd = text.indexOf("\n\n");
+  if (headerEnd >= 0 || (altEnd >= 0 && /content-length:/i.test(text.slice(0, altEnd + 2)))) {
+    const split = headerEnd >= 0 ? headerEnd : altEnd;
+    const sep = headerEnd >= 0 ? 4 : 2;
+    const header = text.slice(0, split);
+    const m = header.match(/content-length:\s*(\d+)/i);
+    if (!m) return null;
+    const len = Number(m[1]);
+    const start = split + sep;
+    const body = Buffer.from(text, "utf8").subarray(start);
+    if (body.length < len) return null;
+    return { json: JSON.parse(body.subarray(0, len).toString("utf8")), rest: body.subarray(len) };
   }
-  if (argv.length === 0) {
+  const nl = text.indexOf("\n");
+  if (nl < 0) return null;
+  const line = text.slice(0, nl).trim();
+  const rest = Buffer.from(text.slice(nl + 1), "utf8");
+  if (!line) return { json: null, rest };
+  return { json: JSON.parse(line), rest };
+}
+
+function writeStdio(msg) {
+  const json = JSON.stringify(msg);
+  const body = Buffer.from(json, "utf8");
+  process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+  process.stdout.write(body);
+}
+
+export async function runCli(argv) {
+  const args = [...argv];
+  if (args.length === 0) {
     await runStdioProxy();
-    return;
+    return 0;
   }
 
-  const cmd = positionals[0] || "";
-  if (flags.help && positionals.length === 0) {
-    process.stdout.write(HELP);
-    return;
+  const cmd = args[0];
+  if (cmd === "-V" || cmd === "--version" || cmd === "-v" || cmd === "version") {
+    out.write(`${packageVersion()}\n`);
+    return 0;
   }
-  if (cmd === "help" || cmd === "--help") {
-    process.stdout.write(HELP);
-    return;
+  if (isHelpFlag(cmd) && args.length === 1) {
+    printHumanHelp(catalogTools());
+    return 0;
   }
-  if (cmd === "update") {
-    const ver = positionals[1] ? String(positionals[1]).replace(/^@/, "") : "latest";
-    await new Promise((resolve, reject) => {
-      const child = spawn("npm", ["i", "-g", `@ikeytz/maps-mcp@${ver}`], { stdio: "inherit" });
-      child.on("exit", (code) => (code === 0 ? resolve() : reject(new Error(`npm exit ${code}`))));
-    });
-    return;
+  if (cmd === "serve" || cmd === "proxy") {
+    await runStdioProxy();
+    return 0;
+  }
+  if (cmd === "update" || cmd === "upgrade") {
+    const spec = args[1] && !args[1].startsWith("-") ? args[1] : "latest";
+    const pkg = spec === "latest" ? "@ikeytz/maps-mcp@latest" : `@ikeytz/maps-mcp@${spec}`;
+    log.write(`Updating ${pkg}…\n`);
+    const r = spawnSync("npm", ["i", "-g", "--prefer-online", pkg], { stdio: "inherit", shell: false });
+    if (r.status !== 0) return r.status || 1;
+    log.write(`Done. New terminal → ikeytz-maps-mcp --version\n`);
+    return 0;
   }
   if (cmd === "list") {
-    if (flags.global) {
-      process.stdout.write(`${globalCliFlagsLines().join("\n")}\n`);
-      return;
+    const rest = args.slice(1);
+    for (const a of rest) {
+      if (a !== "--global") {
+        log.write(`Usage: ikeytz-maps-mcp list [--global]\n`);
+        return 2;
+      }
     }
-    process.stdout.write(`${toolNames().join("\n")}\n\n${globalCliFlagsLines().join("\n")}\n`);
-    return;
+    if (rest.includes("--global")) {
+      out.write(`${globalCliFlagsLines().join("\n")}\n`);
+      return 0;
+    }
+    const rows = catalogTools().map((t) => ({
+      tool: t.name,
+      args: argHint(t) || "—",
+      example: exampleForTool(t.name),
+    }));
+    out.write([...formatToolsAsciiTable(rows), ...globalCliFlagsLines()].join("\n") + "\n");
+    return 0;
   }
-  if (cmd === "describe") {
-    const name = positionals[1];
-    const tool = toolByName(name);
-    if (!tool) {
-      console.error(`unknown tool: ${name || "(fehlt)"}`);
-      process.exitCode = 1;
-      return;
+
+  let toolName;
+  let rest;
+  if (cmd === "describe" || cmd === "call") {
+    toolName = args[1];
+    rest = args.slice(2);
+    if (!toolName) {
+      log.write(`Usage: ikeytz-maps-mcp ${cmd} <toolName> …\n`);
+      return 2;
     }
-    process.stdout.write(formatToolHelp(tool));
-    return;
+  } else {
+    toolName = cmd;
+    rest = args.slice(1);
   }
 
-  const toolName = cmd === "call" ? positionals[1] : cmd;
-  const tool = toolByName(toolName);
-  if (!tool) {
-    console.error(`unknown command: ${cmd}\n`);
-    process.stdout.write(HELP);
-    process.exitCode = 1;
-    return;
+  if (cmd === "describe" || rest.some(isHelpFlag)) {
+    const tool = toolByName(toolName);
+    if (!tool) {
+      log.write(`Unknown tool: ${toolName}\n`);
+      return 1;
+    }
+    out.write(`${formatDescribe(tool)}\n`);
+    return 0;
   }
-  if (flags.help) {
-    process.stdout.write(formatToolHelp(tool));
-    return;
+
+  const wantRaw = rest.includes("--raw");
+  const showMcp = wantsShowMcpCommand(rest);
+  let callArgs;
+  try {
+    callArgs = parseToolArgs(stripCliDisplayFlags(rest.filter((a) => a !== "--raw")));
+  } catch (err) {
+    log.write(`${err.message || err}\n`);
+    return 2;
   }
-  const args = argsFromFlags(flags);
-  if (flags.showMcp) {
-    process.stdout.write(showMcpCommand(toolName, args));
-    return;
+
+  if (showMcp) {
+    out.write(`${formatMcpCurlHeading(toolName, callArgs)}\n`);
+    return 0;
   }
-  const rpc = await callTool(toolName, args);
-  printPayload(rpc, flags.raw);
+
+  const rpc = await callTool(toolName, callArgs);
+  printCallResult(rpc, { raw: wantRaw });
+  if (rpc?.result?.isError || rpc?.error) process.exitCode = 1;
+  return process.exitCode || 0;
 }
+
+/** @deprecated use runCli — kept for older bin */
+export const main = runCli;