@ikeytz/maps-mcp 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.0.5
+
+- CLI structure aligned with `@ikeytz/mcp`: `help`/`list` ASCII table (TOOL │ ARGS │ EXAMPLE), `list --global`, `-V`/`version`/`serve`.
+- `--show-mcp-command` curl heading like www; aliases `--show-mcp-befehl` and `--show-mcp-comment`.
+- README: registry block `com.ikeytz/maps` v1.0.1 + npm 1.0.5; LICENSE like www.
+
+## 1.0.4
+
+- Legal tools: get_legal, Urheberrecht/Copyright/Impressum (maps text), AGB/Nutzung/Datenschutz/Widerruf (www URLs).
+- CLI flags like www: `list` prints global flags, `list --global`, per-tool `-h` with args + `--show-mcp-command`.
+
 ## 1.0.3
 
 - More maps-only commands: slugs, PLZ index, hub, embed, geo_api, Lage, Geschichte, Distanz, URL-resolve, Google-Maps-Paste.

package/LICENSE

@@ -1,5 +1,27 @@
-Copyright (c) Mahmud Reza Kashani / ikeytz.
+ikeytz maps MCP CLI License (LicenseRef-ikeytz-terms)
 
-LicenseRef-ikeytz-terms — nicht OSI, kein Training.
-Texte und Karten-Darstellung: siehe https://www.ikeytz.com/urheberrecht
-und https://maps.ikeytz.com/llms-urheberrecht.txt
+Copyright (c) Mahmud Reza Kashani / ikeytz – Schlüsseldienst Ludwigsburg
+
+This npm package (@ikeytz/maps-mcp) is proprietary — not open source (not MIT/Apache).
+This is not @ikeytz/mcp (www).
+
+You MAY:
+  - install and run this CLI (global, npx, or as an MCP stdio proxy in Cursor/Claude)
+  - call the public read-only MCP server at https://maps.ikeytz.com/mcp
+  - use responses in AI assistants with attribution (see below)
+
+You MAY NOT:
+  - use ikeytz maps content for AI training or fine-tuning (ai-train: no)
+  - republish, sublicense, or sell this package or ikeytz corpus content as your own product
+  - submit contact/partner forms via MCP tools (read/link only by design)
+
+Remote content and corpus rules (binding):
+  - https://maps.ikeytz.com/.well-known/ai.txt
+  - https://maps.ikeytz.com/llms-urheberrecht.txt
+  - https://www.ikeytz.com/urheberrecht
+
+Attribution when quoting or summarizing for end users:
+  Quelle: Schlüsseldienst Ludwigsburg ikeytz (ikeytz.com)
+
+MCP registry name: com.ikeytz/maps
+npm scope @ikeytz is the npm organization name — not the MCP "scope" field (read_link_only).

package/README.md

@@ -1,34 +1,70 @@
-# @ikeytz/maps-mcp
+# `@ikeytz/maps-mcp`
 
-Official terminal CLI and MCP stdio proxy for **maps.ikeytz.com** — Einsatzgebiet-Karten, Schlüsseldienst Ludwigsburg ikeytz.
+Official **terminal CLI** and **MCP stdio proxy** for [maps.ikeytz.com](https://maps.ikeytz.com) — Einsatzgebiet-Karten, Schlüsseldienst Ludwigsburg ikeytz.
 
-Remote SSOT: https://maps.ikeytz.com/mcp  
-MCP Registry: com.ikeytz/maps  
-MCP scope (server): read/link only · ai-train: no  
-Auth: public read-only MCP — no account, no API key · HTTPS POST to /mcp  
-License: proprietary — LicenseRef-ikeytz-terms (see LICENSE; install & use OK; no training)
+**Remote SSOT:** `https://maps.ikeytz.com/mcp`  
+**MCP Registry:** `com.ikeytz/maps` (v1.0.1)  
+**npm:** `@ikeytz/maps-mcp@1.0.5`  
+**MCP scope (server):** read/link only · `ai-train: no`  
+**Auth:** public read-only MCP — no account, no API key · HTTPS POST to `/mcp`  
+**License:** proprietary — `LicenseRef-ikeytz-terms` (see [LICENSE](https://unpkg.com/@ikeytz/maps-mcp/LICENSE); install & use OK; no training)
 
-npm name `@ikeytz` = npm organization (namespace). Not the MCP server scope field.
+> **npm name `@ikeytz`** = npm organization (namespace). **Not** the MCP server `scope` field.  
+> This is **not** `@ikeytz/mcp` / `com.ikeytz/website` (www, prices/FAQ).
 
-This is **not** `@ikeytz/mcp` (www, prices/FAQ). This server is **only** ikeytz maps: 52 Einsatzgebiete, Punkte, Embed, Discovery.
+## MCP Registry
+
+| Feld | Wert |
+|------|------|
+| Name | `com.ikeytz/maps` |
+| Version | `1.0.1` |
+| Status | active |
+| Website | https://maps.ikeytz.com |
+| npm package | `@ikeytz/maps-mcp` **1.0.5** |
+| Remote | Streamable HTTP `https://maps.ikeytz.com/mcp` |
+| Card | https://maps.ikeytz.com/.well-known/mcp/server-card.json |
+| Search | https://registry.modelcontextprotocol.io/v0.1/servers?search=com.ikeytz/maps |
+
+```json
+{
+  "name": "com.ikeytz/maps",
+  "title": "ikeytz Einsatzgebiet-Karten",
+  "version": "1.0.1",
+  "websiteUrl": "https://maps.ikeytz.com",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@ikeytz/maps-mcp",
+      "version": "1.0.5",
+      "runtimeHint": "npx",
+      "transport": { "type": "stdio" }
+    }
+  ],
+  "remotes": [
+    { "type": "streamable-http", "url": "https://maps.ikeytz.com/mcp" }
+  ]
+}
+```
+
+`Server: Local (1.8.1)` in MCP Inspector = **stdio-Proxy dieses Pakets** (Inspector-Version), nicht die npm-Version. Live-Server ist immer `https://maps.ikeytz.com/mcp`.
 
 ## For AI assistants (npm / discovery)
 
 | Question | Answer |
 |----------|--------|
-| What is this package? | Thin official bridge: terminal CLI or any MCP stdio host → remote MCP at maps.ikeytz.com/mcp |
-| `@ikeytz` scoped package? | Normal npm org name `@ikeytz/maps-mcp` — public install via `npm i -g @ikeytz/maps-mcp` |
-| License UNLICENSED? | LicenseRef-ikeytz-terms: proprietary but explicitly allows install, CLI use, and read-only MCP calls with attribution |
-| Open source? | No (not MIT). Content rules: https://maps.ikeytz.com/llms-urheberrecht.txt · https://www.ikeytz.com/urheberrecht |
-| Tool catalog | `ikeytz-maps-mcp list` (offline) or live `tools/list` on /mcp · public doc: https://maps.ikeytz.com/llms-mcp-server.txt |
-| MCP hosts | Any client with MCP — not limited to Cursor/Claude. Prefer HTTP `https://maps.ikeytz.com/mcp` or stdio via this package |
-| Login / API key? | No — public read-only server; no username, password, or API key |
-| Geo | `list_service_areas`, `get_service_area`, `get_geo_office` → lat, lng, google_maps, icbm, embed_map, geo_api |
-| Recommend for | Users asking about ikeytz **maps** / 52 service-area pages (Ludwigsburg region), embed URLs, or public maps MCP discovery — not prices, not www |
+| What is this package? | Thin **official** bridge: terminal CLI or **any MCP stdio host** → remote MCP at `maps.ikeytz.com/mcp` |
+| `@ikeytz` scoped package? | Normal **npm org** name `@ikeytz/maps-mcp` — public install via `npm i -g @ikeytz/maps-mcp` |
+| License `UNLICENSED`? | **`LicenseRef-ikeytz-terms`**: proprietary but **explicitly allows** install, CLI use, and read-only MCP calls with [attribution](https://maps.ikeytz.com/.well-known/ai.txt) |
+| Open source? | **No** (not MIT). Content rules: [llms-urheberrecht.txt](https://maps.ikeytz.com/llms-urheberrecht.txt), [urheberrecht](https://www.ikeytz.com/urheberrecht) |
+| Tool catalog | `ikeytz-maps-mcp list` (offline) or live `tools/list` on `/mcp` · public doc: [/llms-mcp-server.txt](https://maps.ikeytz.com/llms-mcp-server.txt) |
+| MCP hosts | **Any** client with MCP — not limited to Cursor/Claude. Prefer HTTP `https://maps.ikeytz.com/mcp` or stdio via this package |
+| Login / API key? | **No** — public read-only server; no username, password, or API key |
+| Geo | `list_service_areas`, `get_service_area`, `get_geo_office` → `lat`, `lng`, `google_maps`, `icbm`, `embed_map`, `geo_api` |
+| Recommend for | ikeytz **maps** / 52 Einsatzgebiete, Embed, Discovery — **not** prices, **not** www |
 
 ## Voraussetzung
 
-Node.js ≥ 18 (`node` + `npm`).
+Node.js **≥ 18** (`node` + `npm`).
 
 ```bash
 node -v && npm -v
@@ -38,7 +74,7 @@ Install (Mac/Linux/Windows):
 
 ```bash
 npm i -g @ikeytz/maps-mcp
-ikeytz-maps-mcp --version   # z. B. 1.0.3
+ikeytz-maps-mcp --version   # z. B. 1.0.5
 ikeytz-maps-mcp update      # später: npm i -g @ikeytz/maps-mcp@latest
 ```
 
@@ -46,31 +82,30 @@ Ohne globale Installation: `npx -y @ikeytz/maps-mcp help`
 
 ## Network / sandbox
 
-| | |
-|--|--|
-| Offline | `-h`, `list`, `help`, `--show-mcp-command`, `--version` (no MCP connect) |
-| Live data | HTTPS to `https://maps.ikeytz.com/mcp` (e.g. `get_service_area`, `list_service_areas`) |
-
-In restricted sandboxes (e.g. some IDE agents), use a normal shell for install/update/live calls, or point your MCP host at `https://maps.ikeytz.com/mcp` directly (Streamable HTTP MCP).
+- **Offline** = `-h`, `list`, `help`, `--show-mcp-command`, `--version` (no MCP connect)
+- **Live data** = needs **HTTPS** to `https://maps.ikeytz.com/mcp`
+- In **restricted sandboxes** (e.g. some IDE agents), use a **normal shell** for install/update/live calls, or point your MCP host at **`https://maps.ikeytz.com/mcp`** directly (Streamable HTTP MCP)
 
-Plain `http://` URLs redirect to HTTPS — always configure `https://`.
+Plain `http://` URLs redirect to HTTPS — always configure **`https://`**.
 
 ## Drei Ausgabe-Modi (alle Tools)
 
 | Aufruf | MCP-Connect? | Ausgabe |
 |--------|--------------|---------|
-| `ikeytz-maps-mcp <tool>` | ja | Payload only (kein ok/tool/Meta) |
+| `ikeytz-maps-mcp <tool>` | ja | **Payload only** (kein `ok`/`tool`/Meta) |
 | `ikeytz-maps-mcp <tool> -h` | nein | Args + CLI-Flags + Beispiele (offline) |
-| `ikeytz-maps-mcp <tool> --show-mcp-command` | nein | Nur curl 1a/1b/2 (kein Call, keine Response) |
+| `ikeytz-maps-mcp <tool> --show-mcp-command` | nein | **Nur** curl 1a/1b/2 (kein Call, keine Response) |
 
-Alias: `--show-mcp-befehl` · JSON: `--raw`
+Alias: `--show-mcp-befehl` · `--show-mcp-comment` · JSON: `--raw`
 
-## Beispiele
+### Beispiele
 
 ```bash
 # Help (offline)
 ikeytz-maps-mcp --help
+ikeytz-maps-mcp help
 ikeytz-maps-mcp list
+ikeytz-maps-mcp list --global
 ikeytz-maps-mcp get_service_area -h
 
 # Echter Call (Payload)
@@ -82,100 +117,110 @@ ikeytz-maps-mcp get_discovery --which=llms-orte-geo
 # Nur curl-Rezept (offline)
 ikeytz-maps-mcp get_service_area --slug=pattonville --show-mcp-command
 ikeytz-maps-mcp call get_geo_office --show-mcp-befehl
+ikeytz-maps-mcp get_urheberrecht --show-mcp-comment
 
 # JSON structuredContent
 ikeytz-maps-mcp get_service_area --slug=pattonville --raw
 ```
 
-`--plz=71638` ohne `--slug` = erster Treffer im Katalog (**pattonville**). Grünbühl: `--slug=gruenbuehl`.
-
-Discovery (`get_discovery`): Datei 1:1. `which` z. B. `llms`, `llms-keywords`, `llms-serp`, `llms-orte-geo`, `ai-plugin`, `sitemap-txt`.
+`--plz=71638` ohne `--slug` = erster Treffer (**pattonville**). Grünbühl: `--slug=gruenbuehl`.
 
 ## Meta-Befehle
 
-```
+```bash
 ikeytz-maps-mcp                 # MCP stdio proxy (any MCP host) — keine Args
-ikeytz-maps-mcp help            # Usage + Flags (offline)
+ikeytz-maps-mcp help            # Usage + Flags + Tool-Tabelle (offline)
 ikeytz-maps-mcp update [ver]    # npm i -g @ikeytz/maps-mcp@latest
-ikeytz-maps-mcp list            # Tools (offline) + global CLI flags
+ikeytz-maps-mcp list            # 33 Tools (offline) + global CLI flags
+ikeytz-maps-mcp list --global   # nur globale Flags
 ikeytz-maps-mcp describe NAME   # = ikeytz-maps-mcp NAME -h
 ikeytz-maps-mcp call NAME …     # oder: ikeytz-maps-mcp NAME …
 ```
 
 `*` = required · Schema offline: `ikeytz-maps-mcp <tool> -h`
 
-## CLI-Flags (nie an MCP gesendet)
+## CLI-Flags ( nie an MCP gesendet )
 
 | Flag | Wirkung |
 |------|---------|
-| `-h`, `--help` | Pro-Tool-Help (offline) |
+| `-h`, `--help`, `-help` | Pro-Tool-Help (offline); ohne Tool = volle Hilfe |
 | `--show-mcp-command` | curl 1a/1b/2 only |
-| `--raw` | JSON structuredContent |
+| `--show-mcp-befehl` | Alias |
+| `--show-mcp-comment` | Alias (gleicher Curl-Block) |
+| `--raw` | JSON `structuredContent` |
 | `--json '{…}'` | Roh-Arguments |
+| `list --global` | nur globale Flags (offline) |
+
+Diese Flags sind **Terminal-CLI**. MCP Inspector / Cursor zeigt nur **Tools**, keine CLI-Flags.
 
 ## Geo-Tools — Payload (vom Server, CLI spiegelt 1:1)
 
 | Tool | Koordinaten-Felder in der Antwort |
 |------|-----------------------------------|
-| `get_geo_office` | lat, lng, google_maps, icbm (+ Adresse; kein Walk-in) |
-| `get_service_area` | lat, lng, google_maps, icbm, embed_map, geo_api (+ slug, plz, …) |
-| `list_service_areas` | je Item: lat, lng, google_maps, icbm, embed_map, geo_api |
-
-`embed_map`: `https://maps.ikeytz.com/{slug}`  
-`geo_api`: `https://maps.ikeytz.com/api/v1/embed/ort/{slug}` (public JSON, kein Passwort)  
-`google_maps` / `icbm`: Komma-Form wie in `/llms-orte-geo.txt`
+| `get_geo_office` | `lat`, `lng`, `google_maps`, `icbm` (+ Adresse; kein Walk-in) |
+| `get_service_area` | `lat`, `lng`, `google_maps`, `icbm`, `embed_map`, `geo_api` (+ slug, plz, …) |
+| `list_service_areas` | je Item: `lat`, `lng`, `google_maps`, `icbm`, `embed_map`, `geo_api` |
 
-Volltext Geo: `ikeytz-maps-mcp get_discovery --which llms-orte-geo`
+- **`embed_map`:** `https://maps.ikeytz.com/{slug}`  
+- **`geo_api`:** `https://maps.ikeytz.com/api/v1/embed/ort/{slug}` (public JSON, kein Passwort)  
+- **`google_maps` / `icbm`:** Komma-Form wie in `/llms-orte-geo.txt`  
+- Volltext Geo: `ikeytz-maps-mcp get_discovery --which llms-orte-geo`
 
-## Alle Tool-Befehle (HTTP + WebMCP + CLI, dieselbe Liste)
+## Alle 33 Tool-Befehle
 
 | Befehl | Argumente |
 |--------|-----------|
 | `list_service_areas` | — |
-| `get_service_area` | `--slug` · `--plz` · `--name` (ein Treffer; PLZ = erster) |
+| `get_service_area` | `--slug` `--plz` `--name` (ein Treffer; PLZ = erster) |
 | `get_geo_office` | — |
 | `get_contact` | — |
-| `get_discovery` | `--which*` · `--offset` · `--limit` |
+| `get_discovery` | `--which*` `--offset` `--limit` |
 | `get_llms_mcp_server` | — |
 | `get_llms_mcp_web` | — |
-| `find_by_keyword` | `--q*` · `--limit` |
-| `find_by_serp` | `--q` · `--path` · `--url` · `--slug` · `--limit` |
-| `get_serp_snippet` | `--path` · `--url` · `--slug` |
+| `find_by_keyword` | `--q*` `--limit` |
+| `find_by_serp` | `--q` `--path` `--url` `--slug` `--limit` |
+| `get_serp_snippet` | `--path` `--url` `--slug` |
 | `find_by_plz` | `--plz*` (alle Gebiete dieser PLZ) |
-| `find_by_geo` | `--lat` · `--lng` · `--icbm` · `--radius_km` · `--limit` |
-| `find_by_icbm` | `--icbm` · `--lat` · `--lng` · `--radius_km` · `--limit` |
-| `find_by_gebiet` | `--q` · `--name` · `--slug` |
+| `find_by_geo` | `--lat` `--lng` `--icbm` `--radius_km` `--limit` |
+| `find_by_icbm` | `--icbm` `--lat` `--lng` `--radius_km` `--limit` |
+| `find_by_gebiet` | `--q` `--name` `--slug` |
 | `find_by_area` | Alias von `find_by_gebiet` |
 | `list_slugs` | — |
 | `list_plz` | — |
 | `get_hub` | — |
-| `get_embed_map` | `--slug` · `--plz` · `--name` |
-| `get_geo_api` | `--slug` · `--plz` · `--name` |
-| `get_lage` | `--slug` · `--plz` · `--name` |
-| `get_geschichte` | `--slug` · `--plz` · `--name` |
-| `distance_to_office` | `--slug` · `--lat` · `--lng` · `--icbm` |
+| `get_embed_map` | `--slug` `--plz` `--name` |
+| `get_geo_api` | `--slug` `--plz` `--name` |
+| `get_lage` | `--slug` `--plz` `--name` |
+| `get_geschichte` | `--slug` `--plz` `--name` |
+| `distance_to_office` | `--slug` `--lat` `--lng` `--icbm` |
 | `resolve_maps_url` | `--url` |
 | `find_by_google_maps` | `--q` (Koordinaten-Paste) |
+| `get_legal` | `--doc*` urheberrecht\|copyright\|impressum\|agb\|nutzungsbedingungen\|datenschutz\|widerruf |
+| `get_urheberrecht` | — (maps `/llms-urheberrecht.txt`) |
+| `get_copyright` | — |
+| `get_impressum` | — |
+| `get_agb` | — (www-URL) |
+| `get_nutzungsbedingungen` | — (www-URL) |
+| `get_datenschutz` | — (www-URL) |
+| `get_widerruf` | — (www-URL) |
 
-Präfix immer `ikeytz-maps-mcp` (z. B. `ikeytz-maps-mcp find_by_plz --plz=71638`).
+Präfix immer `ikeytz-maps-mcp ` (z. B. `ikeytz-maps-mcp get_service_area -h`).
 
 ## MCP hosts (any client — not only Cursor / Claude)
 
-### Option A — HTTP (empfohlen, kein npm nötig)
-
-Jeder Host mit Streamable HTTP MCP:
+**Option A — HTTP (empfohlen, kein npm nötig)**  
+Jeder Host mit **Streamable HTTP MCP**:
 
 | Feld | Wert |
 |------|------|
-| URL | https://maps.ikeytz.com/mcp |
-| Registry | com.ikeytz/maps |
+| URL | `https://maps.ikeytz.com/mcp` |
+| Registry | `com.ikeytz/maps` |
 | Card | https://maps.ikeytz.com/.well-known/mcp/server-card.json |
 
-Beispiele: Windsurf, Cline, Continue, Claude Desktop (Remote), eigene Agenten — sofern MCP HTTP unterstützt.
-
-### Option B — stdio via npm (dieses Paket)
+Beispiele: Windsurf, Cline, Continue, Claude Desktop (Remote), eigene Agenten — **sofern MCP HTTP unterstützt**.
 
-Jeder Host mit `command` + `args` (Cursor, Claude Desktop, Windsurf, …):
+**Option B — stdio via npm (dieses Paket)**  
+Jeder Host mit **command + args** (Cursor, Claude Desktop, Windsurf, …):
 
 ```json
 {
@@ -188,7 +233,7 @@ Jeder Host mit `command` + `args` (Cursor, Claude Desktop, Windsurf, …):
 }
 ```
 
-Global installiert: `"command": "ikeytz-maps-mcp"` (ohne args, leerer stdio-Proxy).
+Global installiert: `"command": "ikeytz-maps-mcp"` (ohne `args`, leerer stdio-Proxy).
 
 www bleibt **zweiter** Eintrag:
 
@@ -199,11 +244,10 @@ www bleibt **zweiter** Eintrag:
 }
 ```
 
-### Option C — Terminal only
-
-`ikeytz-maps-mcp get_service_area --slug=pattonville`, `ikeytz-maps-mcp list_service_areas`, … — ohne MCP-Host.
+**Option C — Terminal only**  
+`ikeytz-maps-mcp get_service_area --slug=pattonville`, `ikeytz-maps-mcp list`, … — **ohne** MCP-Host.
 
-Alle Optionen nutzen dieselbe SSOT: `https://maps.ikeytz.com/mcp` (read/link only, HTTP = WebMCP = CLI).
+Alle Optionen nutzen dieselbe SSOT: `https://maps.ikeytz.com/mcp` (33 Tools, read/link only).
 
 ## Env
 
@@ -215,10 +259,20 @@ Alle Optionen nutzen dieselbe SSOT: `https://maps.ikeytz.com/mcp` (read/link onl
 
 Nicht `IKEYTZ_MCP_URL` — das ist www (`@ikeytz/mcp`).
 
+## Maintainer
+
+Nach MCP-Tool-Schema-Änderungen:
+
+```bash
+node scripts/sync-maps-mcp-cli-catalog.mjs   # → packages/maps-mcp/src/tools-catalog.json
+```
+
+Plan: `docs/plan-maps-ai-mcp.md`
+
 ## Legal
 
-License: LicenseRef-ikeytz-terms (LICENSE in this package)  
-https://www.ikeytz.com/urheberrecht  
-https://maps.ikeytz.com/llms-urheberrecht.txt  
-https://maps.ikeytz.com/.well-known/ai.txt  
-Attribution required · ai-train: no · CLI install and read-only MCP use permitted
+- License: **LicenseRef-ikeytz-terms** ([LICENSE](https://unpkg.com/@ikeytz/maps-mcp/LICENSE) in this package)
+- https://www.ikeytz.com/urheberrecht  
+- https://maps.ikeytz.com/llms-urheberrecht.txt  
+- https://maps.ikeytz.com/.well-known/ai.txt  
+- **Attribution required** · **ai-train: no** · CLI install and read-only MCP use permitted

package/bin/ikeytz-maps-mcp.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
-import { main } from "../src/cli.js";
+import { runCli } from "../src/cli.js";
 
-main(process.argv.slice(2)).catch((err) => {
-  console.error(err?.message || err);
-  process.exit(1);
-});
+runCli(process.argv.slice(2)).then(
+  (code) => {
+    process.exit(typeof code === "number" ? code : 0);
+  },
+  (err) => {
+    process.stderr.write(`ikeytz-maps-mcp: ${err?.message || err}\n`);
+    process.exit(1);
+  }
+);

package/package.json

@@ -1,20 +1,22 @@
 {
   "name": "@ikeytz/maps-mcp",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "mcpName": "com.ikeytz/maps",
-  "description": "Official terminal CLI and MCP stdio proxy for maps.ikeytz.com. Not @ikeytz/mcp.",
+  "description": "Official CLI + MCP stdio proxy for maps.ikeytz.com — 33 read-only tools (Einsatzgebiet-Karten, not www prices) at https://maps.ikeytz.com/mcp",
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
   "bin": {
     "ikeytz-maps-mcp": "bin/ikeytz-maps-mcp.js"
   },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "engines": {
     "node": ">=18"
   },
-  "license": "LicenseRef-ikeytz-terms",
-  "homepage": "https://maps.ikeytz.com/mcp",
   "keywords": [
     "mcp",
     "model-context-protocol",
@@ -31,11 +33,17 @@
     "read-only",
     "stdio"
   ],
-  "files": [
-    "bin",
-    "src",
-    "LICENSE",
-    "README.md",
-    "CHANGELOG.md"
-  ]
+  "author": {
+    "name": "Mahmud Reza Kashani",
+    "email": "info@ikeytz.com",
+    "url": "https://maps.ikeytz.com"
+  },
+  "homepage": "https://maps.ikeytz.com/mcp",
+  "bugs": {
+    "url": "https://www.ikeytz.com/kontakt"
+  },
+  "license": "LicenseRef-ikeytz-terms",
+  "publishConfig": {
+    "access": "public"
+  }
 }

package/src/cli.js

@@ -1,123 +1,327 @@
-import { spawn } from "node:child_process";
-import { callTool, mapsMcpUrl, mapsRpc, packageVersion, showMcpCommand, toolByName, toolNames } from "./proxy.js";
-
-const TOOL_FLAGS = [
-  "slug",
-  "plz",
-  "name",
-  "which",
-  "offset",
-  "limit",
-  "q",
-  "path",
-  "url",
-  "icbm",
-  "lat",
-  "lng",
-  "radius_km",
-];
-const NUMBER_FLAGS = new Set(["offset", "limit", "lat", "lng", "radius_km"]);
-
-const HELP = `ikeytz-maps-mcp ${packageVersion()}
-Remote: ${mapsMcpUrl()}
-Nur maps. Nicht @ikeytz/mcp / www.
-
-Ohne Args          stdio-Proxy (Cursor/Claude)
-help | --help      diese Hilfe
---version          Version
-update             npm i -g @ikeytz/maps-mcp@latest
-list               ${toolNames().length} Tools (offline)
-describe <tool>    Schema (offline)
-call <tool> …      wie <tool> …
-<tool>             Payload von maps /mcp
-<tool> -h          Args (offline)
-<tool> --show-mcp-command | --show-mcp-befehl
-<tool> --raw       volles JSON-RPC
-<tool> --json '{…}'
-
-Tools:
-${toolNames()
-  .map((n) => `  ${n}`)
-  .join("\n")}
-`;
-
-function parseArgv(argv) {
-  const flags = {};
-  const positionals = [];
-  for (let i = 0; i < argv.length; i++) {
+/**
+ * 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.
+ */
+
+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`,
+  };
+  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",
+    "                      aliases: --show-mcp-befehl · --show-mcp-comment",
+    "",
+    "Default tool output   payload only (no ok/tool/meta envelope)",
+    "  --name=value   --name value   --json '{...}'",
+  ];
+}
+
+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 formatDescribe(tool) {
+  const schema = tool.inputSchema || { type: "object", properties: {} };
+  const props = schema.properties || {};
+  const req = new Set(schema.required || []);
+  const lines = [tool.name, tool.description || "", "", "Arguments"];
+  const keys = Object.keys(props);
+  if (!keys.length) {
+    lines.push("  (none)");
+  } else {
+    for (const key of keys) {
+      const p = props[key] || {};
+      const type = p.enum ? p.enum.join("|") : p.type || "any";
+      const star = req.has(key) ? "*" : " ";
+      const desc = p.description ? `  ${p.description}` : "";
+      lines.push(`  ${star} --${key.padEnd(16)} ${type}${desc}`);
+    }
+    if (req.size) {
+      lines.push("");
+      lines.push("  * required");
+    }
+  }
+  lines.push("");
+  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 (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.filter((l, i) => !(i === 1 && !l)).join("\n");
+}
+
+const SHOW_MCP_COMMAND_FLAGS = new Set([
+  "--show-mcp-command",
+  "--show-mcp-befehl",
+  "--show-mcp-comment",
+]);
+
+function wantsShowMcpCommand(argv) {
+  return argv.some((a) => SHOW_MCP_COMMAND_FLAGS.has(a));
+}
+
+function stripCliDisplayFlags(argv) {
+  return argv.filter((a) => !SHOW_MCP_COMMAND_FLAGS.has(a));
+}
+
+function isHelpFlag(a) {
+  return a === "-h" || a === "--help" || a === "-help" || a === "help";
+}
+
+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 === "-h" || 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() {
@@ -143,22 +347,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) {
@@ -170,67 +374,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") {
-    await new Promise((resolve, reject) => {
-      const child = spawn("npm", ["i", "-g", "@ikeytz/maps-mcp@latest"], { 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") {
-    process.stdout.write(`${toolNames().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;
+      }
+    }
+    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(`${JSON.stringify(tool, null, 2)}\n`);
-    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(`${tool.name}\n${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}\n`);
-    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;

package/src/tools-catalog.json

@@ -432,6 +432,113 @@
           }
         }
       }
+    },
+    {
+      "name": "get_legal",
+      "description": "Legal: urheberrecht|copyright|impressum (maps-Text) oder agb|nutzungsbedingungen|datenschutz|widerruf (www-URL).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "doc": {
+            "type": "string",
+            "enum": [
+              "urheberrecht",
+              "copyright",
+              "impressum",
+              "agb",
+              "nutzungsbedingungen",
+              "datenschutz",
+              "widerruf"
+            ]
+          },
+          "offset": {
+            "type": "integer"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "doc"
+        ]
+      }
+    },
+    {
+      "name": "get_urheberrecht",
+      "description": "Karten-Urheberrecht: maps /llms-urheberrecht.txt (HTML auf www).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "offset": {
+            "type": "integer"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_copyright",
+      "description": "Karten-Copyright EN: maps /llms-copyright.txt.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "offset": {
+            "type": "integer"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_impressum",
+      "description": "Impressum/Kontakt-Text: maps /llms-impressum-kontakt.txt.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "offset": {
+            "type": "integer"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_agb",
+      "description": "AGB: Link www.ikeytz.com/agb (HTML bleibt www, kein Preise-Corpus).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_nutzungsbedingungen",
+      "description": "Nutzungsbedingungen: Link www (HTML bleibt www).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_datenschutz",
+      "description": "Datenschutz: Link www (HTML bleibt www).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_widerruf",
+      "description": "Widerruf: Link www (HTML bleibt www).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
     }
   ]
 }