@ikeytz/maps-mcp 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 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.
+
 ## 1.0.2
 
 - Drop private Git remote from npm metadata.

package/README.md

@@ -10,7 +10,7 @@ License: proprietary — LicenseRef-ikeytz-terms (see LICENSE; install & use OK;
 
 npm name `@ikeytz` = npm organization (namespace). Not the MCP server scope field.
 
-This is **not** `@ikeytz/mcp` (www, 42 tools, `https://www.ikeytz.com/mcp`).
+This is **not** `@ikeytz/mcp` (www, prices/FAQ). This server is **only** ikeytz maps: 52 Einsatzgebiete, Punkte, Embed, Discovery.
 
 ## For AI assistants (npm / discovery)
 
@@ -38,7 +38,7 @@ Install (Mac/Linux/Windows):
 
 ```bash
 npm i -g @ikeytz/maps-mcp
-ikeytz-maps-mcp --version   # z. B. 1.0.1
+ikeytz-maps-mcp --version   # z. B. 1.0.4
 ikeytz-maps-mcp update      # später: npm i -g @ikeytz/maps-mcp@latest
 ```
 
@@ -97,7 +97,8 @@ Discovery (`get_discovery`): Datei 1:1. `which` z. B. `llms`, `llms-keywords`, `
 ikeytz-maps-mcp                 # MCP stdio proxy (any MCP host) — keine Args
 ikeytz-maps-mcp help            # Usage + Flags (offline)
 ikeytz-maps-mcp update [ver]    # npm i -g @ikeytz/maps-mcp@latest
-ikeytz-maps-mcp list            # 7 Tools (offline) + global CLI flags
+ikeytz-maps-mcp list            # Tools (offline) + global CLI flags
+ikeytz-maps-mcp list --global   # nur globale Flags (wie ikeytz-mcp)
 ikeytz-maps-mcp describe NAME   # = ikeytz-maps-mcp NAME -h
 ikeytz-maps-mcp call NAME …     # oder: ikeytz-maps-mcp NAME …
 ```
@@ -112,6 +113,7 @@ ikeytz-maps-mcp call NAME …     # oder: ikeytz-maps-mcp NAME …
 | `--show-mcp-command` | curl 1a/1b/2 only |
 | `--raw` | JSON structuredContent |
 | `--json '{…}'` | Roh-Arguments |
+| `list --global` | nur globale Flags (offline) |
 
 ## Geo-Tools — Payload (vom Server, CLI spiegelt 1:1)
 
@@ -127,19 +129,45 @@ ikeytz-maps-mcp call NAME …     # oder: ikeytz-maps-mcp NAME …
 
 Volltext Geo: `ikeytz-maps-mcp get_discovery --which llms-orte-geo`
 
-## Alle 7 Tool-Befehle
+## Alle Tool-Befehle (HTTP + WebMCP + CLI, dieselbe Liste)
 
 | Befehl | Argumente |
 |--------|-----------|
 | `list_service_areas` | — |
-| `get_service_area` | `--slug` · `--plz` · `--name` |
+| `get_service_area` | `--slug` · `--plz` · `--name` (ein Treffer; PLZ = erster) |
 | `get_geo_office` | — |
 | `get_contact` | — |
 | `get_discovery` | `--which*` · `--offset` · `--limit` |
 | `get_llms_mcp_server` | — |
 | `get_llms_mcp_web` | — |
-
-Präfix immer `ikeytz-maps-mcp` (z. B. `ikeytz-maps-mcp get_service_area -h`).
+| `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_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` |
+| `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`).
 
 ## MCP hosts (any client — not only Cursor / Claude)
 
@@ -185,7 +213,7 @@ www bleibt **zweiter** Eintrag:
 
 `ikeytz-maps-mcp get_service_area --slug=pattonville`, `ikeytz-maps-mcp list_service_areas`, … — ohne MCP-Host.
 
-Alle Optionen nutzen dieselbe SSOT: `https://maps.ikeytz.com/mcp` (7 Tools, read/link only).
+Alle Optionen nutzen dieselbe SSOT: `https://maps.ikeytz.com/mcp` (read/link only, HTTP = WebMCP = CLI).
 
 ## Env
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikeytz/maps-mcp",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "mcpName": "com.ikeytz/maps",
   "description": "Official terminal CLI and MCP stdio proxy for maps.ikeytz.com. Not @ikeytz/mcp.",
   "type": "module",

package/src/cli.js

@@ -1,7 +1,83 @@
 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"];
+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"]);
+
+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",
+    "",
+    "Default tool output   payload only (no ok/tool/meta envelope)",
+    "  --name=value   --name value",
+  ];
+}
+
+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 formatToolHelp(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) ? "*" : " ";
+      lines.push(`  ${star} --${key.padEnd(16)} ${type}`);
+    }
+    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 — no MCP call (alias: --show-mcp-befehl)");
+  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`;
+}
 
 const HELP = `ikeytz-maps-mcp ${packageVersion()}
 Remote: ${mapsMcpUrl()}
@@ -10,24 +86,23 @@ 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               7 Tools (offline)
-describe <tool>    Schema (offline)
+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 (offline)
+<tool> -h          Args + CLI-Flags (offline)
 <tool> --show-mcp-command | --show-mcp-befehl
-<tool> --raw       volles JSON-RPC
+<tool> --raw       JSON structuredContent
 <tool> --json '{…}'
 
+${globalCliFlagsLines().join("\n")}
+
 Tools:
-  list_service_areas
-  get_service_area --slug=… | --plz=… | --name=…
-  get_geo_office
-  get_contact
-  get_discovery --which=llms|llms-orte-geo|ai-plugin|…
-  get_llms_mcp_server
-  get_llms_mcp_web
+${toolNames()
+  .map((n) => `  ${n}`)
+  .join("\n")}
 `;
 
 function parseArgv(argv) {
@@ -36,7 +111,8 @@ function parseArgv(argv) {
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--raw") flags.raw = true;
-    else if (a === "-h" || a === "--help") flags.help = 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] || "";
@@ -62,7 +138,7 @@ function argsFromFlags(flags) {
   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] = key === "offset" || key === "limit" ? Number(flags[key]) : String(flags[key]);
+      args[key] = NUMBER_FLAGS.has(key) ? Number(flags[key]) : String(flags[key]);
     }
   }
   return args;
@@ -181,14 +257,19 @@ export async function main(argv) {
     return;
   }
   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@latest"], { stdio: "inherit" });
+      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 === "list") {
-    process.stdout.write(`${toolNames().join("\n")}\n`);
+    if (flags.global) {
+      process.stdout.write(`${globalCliFlagsLines().join("\n")}\n`);
+      return;
+    }
+    process.stdout.write(`${toolNames().join("\n")}\n\n${globalCliFlagsLines().join("\n")}\n`);
     return;
   }
   if (cmd === "describe") {
@@ -199,7 +280,7 @@ export async function main(argv) {
       process.exitCode = 1;
       return;
     }
-    process.stdout.write(`${JSON.stringify(tool, null, 2)}\n`);
+    process.stdout.write(formatToolHelp(tool));
     return;
   }
 
@@ -212,7 +293,7 @@ export async function main(argv) {
     return;
   }
   if (flags.help) {
-    process.stdout.write(`${tool.name}\n${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}\n`);
+    process.stdout.write(formatToolHelp(tool));
     return;
   }
   const args = argsFromFlags(flags);

package/src/tools-catalog.json

@@ -68,7 +68,8 @@
               "ai-txt",
               "ai-plugin",
               "answer-engine",
-              "ai-catalog"
+              "ai-catalog",
+              "agent-skills"
             ]
           },
           "offset": {
@@ -98,6 +99,446 @@
         "type": "object",
         "properties": {}
       }
+    },
+    {
+      "name": "find_by_keyword",
+      "description": "Suche in maps llms-keywords.txt (Keyword → maps-URL). Nicht www.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "q"
+        ]
+      }
+    },
+    {
+      "name": "find_by_serp",
+      "description": "Suche in maps llms-serp.txt (Title/H1/Description/URL).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_serp_snippet",
+      "description": "Ein SERP-Block für path, url oder slug (maps llms-serp.txt).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "path": {
+            "type": "string"
+          },
+          "url": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          },
+          "q": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "find_by_plz",
+      "description": "Alle Einsatzgebiete mit dieser PLZ (nicht nur der erste Treffer).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "plz": {
+            "type": "string"
+          },
+          "q": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "plz"
+        ]
+      }
+    },
+    {
+      "name": "find_by_geo",
+      "description": "Gebiete nach lat/lng, optional radius_km, sonst die nächsten.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "lat": {
+            "type": "number"
+          },
+          "lng": {
+            "type": "number"
+          },
+          "icbm": {
+            "type": "string"
+          },
+          "radius_km": {
+            "type": "number"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "find_by_icbm",
+      "description": "Gebiete nach ICBM (lat, lng) — nächste Punkte / optional radius_km.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "icbm": {
+            "type": "string"
+          },
+          "lat": {
+            "type": "number"
+          },
+          "lng": {
+            "type": "number"
+          },
+          "radius_km": {
+            "type": "number"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "name": "find_by_gebiet",
+      "description": "Gebiete nach Name oder slug (mehrere Treffer, Umlaut ok).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "find_by_area",
+      "description": "Alias von find_by_gebiet (Name/Slug, mehrere Treffer).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "slug": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "list_slugs",
+      "description": "Alle 52 maps-Slugs (ikeytz Einsatzgebiete).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "list_plz",
+      "description": "PLZ → welche maps-Gebiete (Mehrfach-PLZ sichtbar).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_hub",
+      "description": "Karten-Hub maps.ikeytz.com/ — 52 Gebiete, keine Visitenkarte.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_embed_map",
+      "description": "Kanonische Karten-URL https://maps.ikeytz.com/{slug}.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_geo_api",
+      "description": "Public Embed-JSON URL für ein Gebiet (Punkt + Grenze, nicht geo-Cockpit).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_lage",
+      "description": "Lage-Text eines Einsatzgebiets (Karte / Visitenkarte).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_geschichte",
+      "description": "Geschichte-Text eines Einsatzgebiets (Karte / Visitenkarte).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "distance_to_office",
+      "description": "Luftlinie Gebiet oder Koordinate → Gewerbesitz (kein Walk-in).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          },
+          "lat": {
+            "type": "number"
+          },
+          "lng": {
+            "type": "number"
+          },
+          "icbm": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "resolve_maps_url",
+      "description": "maps.ikeytz.com-URL → Hub oder Gebiet.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "url": {
+            "type": "string"
+          },
+          "path": {
+            "type": "string"
+          },
+          "q": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "find_by_google_maps",
+      "description": "Koordinaten-Paste (Google Maps / ICBM) → nächste ikeytz-Gebiete.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "q": {
+            "type": "string"
+          },
+          "icbm": {
+            "type": "string"
+          },
+          "lat": {
+            "type": "number"
+          },
+          "lng": {
+            "type": "number"
+          },
+          "radius_km": {
+            "type": "number"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        }
+      }
+    },
+    {
+      "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": {}
+      }
     }
   ]
 }