@ikeytz/maps-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## 1.0.0
+
+- Erstes lokales Paket MAPS-M5 (C1/C2). Remote nur `https://maps.ikeytz.com/mcp`.
+- Publish npm = MAPS-E3, noch nicht.

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Mahmud Reza Kashani / ikeytz.
+
+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

package/README.md

@@ -0,0 +1,53 @@
+# @ikeytz/maps-mcp
+
+CLI + stdio-Proxy für **maps.ikeytz.com/mcp**. Anderes Paket als `@ikeytz/mcp` (www).
+
+| | |
+|--|--|
+| Bin | `ikeytz-maps-mcp` |
+| `mcpName` | `com.ikeytz/maps` |
+| Remote | `https://maps.ikeytz.com/mcp` |
+| Protocol | `2025-11-25` |
+
+**Publish (npm) = MAPS-E3**, noch nicht. Lokal aus diesem Repo:
+
+```bash
+node packages/maps-mcp/bin/ikeytz-maps-mcp.js --version
+node packages/maps-mcp/bin/ikeytz-maps-mcp.js list
+node packages/maps-mcp/bin/ikeytz-maps-mcp.js get_service_area --slug=pattonville
+```
+
+Nach Publish:
+
+```bash
+npm i -g @ikeytz/maps-mcp
+ikeytz-maps-mcp --version
+npx -y @ikeytz/maps-mcp help
+```
+
+Env (nicht `IKEYTZ_MCP_URL`):
+
+| Variable | Default |
+|----------|---------|
+| `IKEYTZ_MAPS_MCP_URL` | `https://maps.ikeytz.com/mcp` |
+| `IKEYTZ_MAPS_MCP_PROTOCOL` | `2025-11-25` |
+| `IKEYTZ_MAPS_MCP_TIMEOUT_MS` | `15000` |
+
+Ohne Args → stdio (Cursor/Claude):
+
+```json
+{
+  "mcpServers": {
+    "ikeytz-maps": {
+      "command": "npx",
+      "args": ["-y", "@ikeytz/maps-mcp"]
+    }
+  }
+}
+```
+
+Lokal vor Publish: `"command": "node"`, `"args": ["…/packages/maps-mcp/bin/ikeytz-maps-mcp.js"]`.
+
+www bleibt zweiter Eintrag → `@ikeytz/mcp` / `https://www.ikeytz.com/mcp`.
+
+Falsch: `ikeytz-mcp get_service_area --slug=pattonville` (das ist www).

package/bin/ikeytz-maps-mcp.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { main } from "../src/cli.js";
+
+main(process.argv.slice(2)).catch((err) => {
+  console.error(err?.message || err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@ikeytz/maps-mcp",
+  "version": "1.0.0",
+  "mcpName": "com.ikeytz/maps",
+  "description": "Read/Link MCP CLI for maps.ikeytz.com. Not @ikeytz/mcp.",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "ikeytz-maps-mcp": "bin/ikeytz-maps-mcp.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "LicenseRef-ikeytz-terms",
+  "files": [
+    "bin",
+    "src",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://vmd199268.contaboserver.net/ikeytz-geo/ikeytz-geo-stack.git",
+    "directory": "packages/maps-mcp"
+  }
+}

package/src/cli.js

@@ -0,0 +1,225 @@
+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 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               7 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:
+  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
+`;
+
+function parseArgv(argv) {
+  const flags = {};
+  const positionals = [];
+  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 === "--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("--")) {
+      const eq = a.indexOf("=");
+      if (eq > 0) flags[a.slice(2, eq)] = a.slice(eq + 1);
+      else {
+        const key = a.slice(2);
+        const next = argv[i + 1];
+        if (next && !next.startsWith("-")) {
+          flags[key] = next;
+          i += 1;
+        } else flags[key] = true;
+      }
+    } else positionals.push(a);
+  }
+  return { flags, positionals };
+}
+
+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] = key === "offset" || key === "limit" ? Number(flags[key]) : String(flags[key]);
+    }
+  }
+  return args;
+}
+
+function printPayload(rpc, raw) {
+  if (raw) {
+    process.stdout.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) };
+  }
+  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);
+}
+
+async function runStdioProxy() {
+  let sessionId = "";
+  let buf = Buffer.alloc(0);
+  process.stdin.on("data", (chunk) => {
+    buf = Buffer.concat([buf, chunk]);
+    (async () => {
+      while (true) {
+        let parsed;
+        try {
+          parsed = readStdioMessage(buf);
+        } catch (err) {
+          writeStdio({ jsonrpc: "2.0", id: null, error: { code: -32700, message: String(err.message || err) } });
+          buf = Buffer.alloc(0);
+          break;
+        }
+        if (!parsed) break;
+        buf = parsed.rest;
+        if (!parsed.json) continue;
+        const msg = parsed.json;
+        const method = msg.method;
+        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);
+          } else if (method === "notifications/initialized" || method === "initialized") {
+            const out = await mapsRpc("notifications/initialized", msg.params || {}, {
+              notification: true,
+              sessionId,
+            });
+            sessionId = out.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);
+          }
+        } catch (err) {
+          if (id !== undefined) {
+            writeStdio({ jsonrpc: "2.0", id, error: { code: -32000, message: String(err.message || err) } });
+          }
+        }
+      }
+    })();
+  });
+}
+
+export async function main(argv) {
+  const { flags, positionals } = parseArgv(argv);
+
+  if (flags.version && positionals.length === 0) {
+    process.stdout.write(`${packageVersion()}\n`);
+    return;
+  }
+  if (argv.length === 0) {
+    await runStdioProxy();
+    return;
+  }
+
+  const cmd = positionals[0] || "";
+  if (flags.help && positionals.length === 0) {
+    process.stdout.write(HELP);
+    return;
+  }
+  if (cmd === "help" || cmd === "--help") {
+    process.stdout.write(HELP);
+    return;
+  }
+  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 === "list") {
+    process.stdout.write(`${toolNames().join("\n")}\n`);
+    return;
+  }
+  if (cmd === "describe") {
+    const name = positionals[1];
+    const tool = toolByName(name);
+    if (!tool) {
+      console.error(`unknown tool: ${name || "(fehlt)"}`);
+      process.exitCode = 1;
+      return;
+    }
+    process.stdout.write(`${JSON.stringify(tool, null, 2)}\n`);
+    return;
+  }
+
+  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 (flags.help) {
+    process.stdout.write(`${tool.name}\n${tool.description}\n${JSON.stringify(tool.inputSchema, null, 2)}\n`);
+    return;
+  }
+  const args = argsFromFlags(flags);
+  if (flags.showMcp) {
+    process.stdout.write(showMcpCommand(toolName, args));
+    return;
+  }
+  const rpc = await callTool(toolName, args);
+  printPayload(rpc, flags.raw);
+}

package/src/proxy.js

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = join(dirname(fileURLToPath(import.meta.url)), "..");
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+export const CATALOG = JSON.parse(readFileSync(join(root, "src/tools-catalog.json"), "utf8"));
+
+export const DEFAULT_URL = "https://maps.ikeytz.com/mcp";
+export const DEFAULT_PROTOCOL = "2025-11-25";
+
+export function mapsMcpUrl() {
+  return process.env.IKEYTZ_MAPS_MCP_URL || DEFAULT_URL;
+}
+
+export function mapsMcpProtocol() {
+  return process.env.IKEYTZ_MAPS_MCP_PROTOCOL || DEFAULT_PROTOCOL;
+}
+
+export function mapsMcpTimeoutMs() {
+  const n = Number(process.env.IKEYTZ_MAPS_MCP_TIMEOUT_MS || 15000);
+  return Number.isFinite(n) && n > 0 ? n : 15000;
+}
+
+export function packageVersion() {
+  return pkg.version;
+}
+
+export function toolByName(name) {
+  return (CATALOG.tools || []).find((t) => t.name === name) || null;
+}
+
+export function toolNames() {
+  return (CATALOG.tools || []).map((t) => t.name);
+}
+
+export async function mapsRpc(method, params, { id = 1, sessionId, notification = false } = {}) {
+  const url = mapsMcpUrl();
+  if (url.includes("geo.ikeytz.com") || url.includes("www.ikeytz.com/mcp")) {
+    throw new Error("IKEYTZ_MAPS_MCP_URL muss maps.ikeytz.com/mcp sein");
+  }
+  const body = notification
+    ? { jsonrpc: "2.0", method, params: params || {} }
+    : { jsonrpc: "2.0", id, method, params: params || {} };
+  const headers = {
+    "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
+    "MCP-Protocol-Version": mapsMcpProtocol(),
+  };
+  if (sessionId) headers["Mcp-Session-Id"] = sessionId;
+  const res = await fetch(url, {
+    method: "POST",
+    headers,
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(mapsMcpTimeoutMs()),
+  });
+  const nextSession = res.headers.get("mcp-session-id") || sessionId || "";
+  if (notification) {
+    return { sessionId: nextSession, status: res.status, json: null };
+  }
+  const json = await res.json();
+  return { sessionId: nextSession, status: res.status, json };
+}
+
+export async function withSession(fn) {
+  const init = await mapsRpc("initialize", {
+    protocolVersion: mapsMcpProtocol(),
+    capabilities: {},
+    clientInfo: { name: "ikeytz-maps-mcp", version: packageVersion() },
+  });
+  if (init.json?.error) throw new Error(init.json.error.message || "initialize failed");
+  const sessionId = init.sessionId;
+  await mapsRpc("notifications/initialized", {}, { notification: true, sessionId });
+  return fn(sessionId);
+}
+
+export async function callTool(name, args = {}) {
+  return withSession(async (sessionId) => {
+    const out = await mapsRpc("tools/call", { name, arguments: args }, { id: 2, sessionId });
+    if (out.json?.error) {
+      const err = new Error(out.json.error.message || "tools/call failed");
+      err.rpc = out.json;
+      throw err;
+    }
+    return out.json;
+  });
+}
+
+export function showMcpCommand(name, args = {}) {
+  const url = mapsMcpUrl();
+  const proto = mapsMcpProtocol();
+  const payload = JSON.stringify({
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: { name, arguments: args },
+  });
+  return `# 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 '${payload}'
+`;
+}

package/src/tools-catalog.json

@@ -0,0 +1,103 @@
+{
+  "tools": [
+    {
+      "name": "list_service_areas",
+      "description": "Alle 52 Einsatzgebiete auf maps.ikeytz.com (Punkte, keine Polygone).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_service_area",
+      "description": "Ein Einsatzgebiet. Lookup: slug → plz (erster Treffer) → name (Substring).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "slug": {
+            "type": "string"
+          },
+          "plz": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    {
+      "name": "get_geo_office",
+      "description": "Gewerbesitz Ludwigsburg. Kein Walk-in.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_contact",
+      "description": "NAP: Handy, Festnetz, Fax, E-Mail, WhatsApp, Adresse.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_discovery",
+      "description": "1:1 Spiegel einer maps-Discovery-Datei (llms, robots, plugin, sitemap, …).",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "which": {
+            "type": "string",
+            "enum": [
+              "llms",
+              "llms-full",
+              "llms-index",
+              "llms-keywords",
+              "llms-serp",
+              "llms-impressum-kontakt",
+              "llms-orte-geo",
+              "llms-urheberrecht",
+              "llms-copyright",
+              "llms-mcp-server",
+              "llms-mcp-web",
+              "robots",
+              "sitemap-txt",
+              "sitemap-xml",
+              "ai-txt",
+              "ai-plugin",
+              "answer-engine",
+              "ai-catalog"
+            ]
+          },
+          "offset": {
+            "type": "integer"
+          },
+          "limit": {
+            "type": "integer"
+          }
+        },
+        "required": [
+          "which"
+        ]
+      }
+    },
+    {
+      "name": "get_llms_mcp_server",
+      "description": "Katalog llms-mcp-server.txt",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    },
+    {
+      "name": "get_llms_mcp_web",
+      "description": "Katalog llms-mcp-web.txt",
+      "inputSchema": {
+        "type": "object",
+        "properties": {}
+      }
+    }
+  ]
+}