sap-adt-mcp 0.8.43 → 0.8.45

package/README.md

@@ -220,6 +220,43 @@ Turn it all off:
 | `reporting.includeArgs` | `true` | Include redacted tool args / repro args. Note: object names can appear here. |
 | `reporting.endpoint` | relay URL | Point at your own relay (see [`worker/`](worker/)). |
 
+### Local control panel
+
+A small HTML button panel for the **read-only** tools — search, grep, get_source,
+read_table, ATC, where-used, packages, transports, dumps, inactive objects — so
+you can poke at SAP from a browser without going through an agent.
+
+The trick: the panel is served **from inside the MCP process itself**, reusing
+the same tool handlers. So it is reachable **only while a session keeps the MCP
+connected** — close the session (or disconnect the MCP) and the process exits,
+taking the panel down with it. There is no standalone server to leave running.
+
+**Open it from a session (easiest).** Just ask the agent to open it — that calls
+the **`adt_open_panel`** tool, which starts the panel on demand and opens the URL
+in your browser. **`adt_close_panel`** stops it. In Claude Code the bundled
+**`/panel`** command does the same (`/panel`, `/panel url`, `/panel close`).
+Nothing listens until you ask — the socket opens only on that call.
+
+**Or auto-start at boot.** Set it in config or env and it comes up with the
+server:
+
+```json
+{ "panel": { "enabled": true, "port": 0 } }
+```
+
+…or `SAP_ADT_MCP_PANEL=1` (`SAP_ADT_MCP_PANEL_PORT` pins a port; `port: 0` / unset
+picks a random free one). On boot the server prints the URL, e.g.:
+
+```
+[sap-adt-mcp] panel: ready (read-only) → http://127.0.0.1:39555/?t=<token>
+```
+
+Safety: bound to `127.0.0.1` only, gated by a per-boot random **token** in that
+URL, and limited to a curated **read-only** allowlist — no write tool (set_source,
+activate, delete, lock, transport release) is reachable from a button, regardless
+of config. Each tool's form is rendered from its live input schema, and the
+system selector at the top targets any configured system.
+
 ## Connect a client
 
 ### Claude Code (CLI)
@@ -327,6 +364,13 @@ or rejecting credentials. Run this first when troubleshooting.
 | `adt_create_transport` | Create a new TR. | Refused under `readOnly: true`. Endpoint shape varies — see Caveats. |
 | `adt_release_transport` | Release a TR. | Refused under `readOnly: true`. |
 
+### Control panel
+
+| Tool | Purpose | Notes |
+| --- | --- | --- |
+| `adt_open_panel` | Start the local read-only HTML control panel and return its URL. | Opens the URL in the browser by default (`open: false` to just return it). Reachable only while this session keeps the MCP connected. See [Local control panel](#local-control-panel). |
+| `adt_close_panel` | Stop the panel. | It also stops on its own when the session ends. |
+
 ### Escape hatch
 
 `adt_request` — direct ADT REST call. Use this when a niche endpoint isn't

package/config.example.json

@@ -11,6 +11,10 @@
   "audit": {
     "enabled": true
   },
+  "panel": {
+    "enabled": false,
+    "port": 0
+  },
   "systems": {
     "DEV": {
       "host": "https://sap-dev.example.com:44300",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-adt-mcp",
-  "version": "0.8.43",
+  "version": "0.8.45",
   "mcpName": "io.github.yzonur/sap-adt-mcp",
   "description": "MCP server giving Claude live access to SAP systems via ADT (ABAP Development Tools) REST. Read source, search, run syntax checks, and edit ABAP objects from any MCP-compatible client.",
   "type": "module",
@@ -21,7 +21,7 @@
   },
   "scripts": {
     "start": "node src/server.js",
-    "test": "node --test test/adt-error.test.js test/atc-bulk.test.js test/audit.test.js test/cds.test.js test/data-preview.test.js test/diff.test.js test/dump-feed.test.js test/grep-source.test.js test/jobs.test.js test/lifecycle-activate.test.js test/lock.test.js test/mcp-bug-fixes.test.js test/node-structure.test.js test/notes.test.js test/object-create.test.js test/object-references.test.js test/object-uris.test.js test/prompts.test.js test/provenance.test.js test/rap-scaffold.test.js test/reporter.test.js test/security.test.js test/source-chunked.test.js test/source-guard.test.js test/source-pagination.test.js test/syntax-context.test.js test/tools-shape.test.js test/versions.test.js test/worklist.test.js",
+    "test": "node --test test/adt-error.test.js test/atc-bulk.test.js test/audit.test.js test/cds.test.js test/data-preview.test.js test/diff.test.js test/dump-feed.test.js test/grep-source.test.js test/jobs.test.js test/lifecycle-activate.test.js test/lock.test.js test/mcp-bug-fixes.test.js test/node-structure.test.js test/notes.test.js test/object-create.test.js test/object-references.test.js test/object-uris.test.js test/panel.test.js test/prompts.test.js test/provenance.test.js test/rap-scaffold.test.js test/reporter.test.js test/security.test.js test/source-chunked.test.js test/source-guard.test.js test/source-pagination.test.js test/syntax-context.test.js test/tools-shape.test.js test/versions.test.js test/worklist.test.js",
     "lint": "eslint src test"
   },
   "keywords": [

package/src/config.js

@@ -51,10 +51,36 @@ export function loadConfig() {
     systems,
     reporting: parseReporting(raw.reporting),
     audit: parseAudit(raw.audit),
+    panel: parsePanel(raw.panel),
     configPath,
   };
 }
 
+// Local read-only HTTP control panel. OFF by default — it opens a listening
+// socket, which an stdio MCP otherwise never does. Enable via config or env.
+//   "panel": { "enabled": true, "port": 0 }   (port 0 = random free port)
+//   SAP_ADT_MCP_PANEL=1            (also accepts true/yes/on; 0/false/no/off forces off)
+//   SAP_ADT_MCP_PANEL_PORT=39555  (overrides config port)
+// The panel lives inside the MCP process: it is reachable only while this
+// Claude session keeps the MCP connected, and dies the moment the process exits.
+// It is bound to 127.0.0.1 and gated by a per-boot random token.
+function parsePanel(raw) {
+  const envVal = String(process.env.SAP_ADT_MCP_PANEL ?? "").toLowerCase();
+  const envOn = ["1", "true", "yes", "on"].includes(envVal);
+  const envOff = ["0", "false", "no", "off"].includes(envVal);
+  const r = raw && typeof raw === "object" ? raw : {};
+  const enabled = envOn ? true : envOff ? false : r.enabled === true;
+
+  const envPort = Number.parseInt(process.env.SAP_ADT_MCP_PANEL_PORT ?? "", 10);
+  const port = Number.isInteger(envPort)
+    ? envPort
+    : Number.isInteger(r.port)
+      ? r.port
+      : 0; // 0 → OS picks a free port
+
+  return { enabled, port, host: "127.0.0.1" };
+}
+
 // Local write-audit trail (JSONL). On by default; disable via config or env.
 //   "audit": { "enabled": false, "path": "/custom/audit.log" }
 //   SAP_ADT_MCP_AUDIT=0   (also accepts false/no/off)

package/src/object-uris.js

@@ -73,8 +73,21 @@ export function normalizeType(input) {
   return aliased ?? upper;
 }
 
+// ADT types arrive either as a bare key (CLAS, SRVD) or in TADIR-style
+// TYPE/SUBTYPE form (SRVD/SRV, CLAS/OC, DDLS/DF). The subtype only changes the
+// endpoint for function-group members (FUGR/FF module, FUGR/I include); for
+// every other kind it is decoration, so collapse X/Y to its base type X. Without
+// this, a TYPE/SUBTYPE input misses the dispatch table and throws "Unsupported
+// object type".
+function collapseSubtype(t) {
+  if (t.includes("/") && t !== "FUGR/FF" && t !== "FUGR/I") {
+    return t.split("/")[0];
+  }
+  return t;
+}
+
 export function objectUri({ type, name, group }) {
-  const t = normalizeType(type);
+  const t = collapseSubtype(normalizeType(type));
   if (typeof name !== "string" || name.length === 0) {
     throw new Error("Object name is required");
   }
@@ -145,7 +158,7 @@ export const METADATA_XML_ACCEPT = {
 };
 
 export function sourceUri({ type, name, group, include }) {
-  const t = normalizeType(type);
+  const t = collapseSubtype(normalizeType(type));
   const base = objectUri({ type: t, name, group });
 
   if (t === "CLAS") {

package/src/panel.js

@@ -0,0 +1,456 @@
+import http from "node:http";
+import crypto from "node:crypto";
+
+// ---------------------------------------------------------------------------
+// Local, read-only HTTP control panel.
+//
+// It lives INSIDE the MCP process and reuses the exact same tool handlers the
+// MCP exposes. That gives the "only works while the session is open" property
+// for free: Claude spawns this process when it connects the MCP and kills it
+// when the session ends, taking the HTTP listener down with it. Nothing else
+// keeps it alive.
+//
+// Safety: bound to 127.0.0.1, gated by a per-boot random token, and — most
+// importantly — the allowlist below contains ONLY read-only tools. A button
+// can never write to SAP because no write tool is reachable from here.
+// ---------------------------------------------------------------------------
+
+// Curated read-only set. `name` must match a registered tool; the input form
+// for each is rendered from that tool's real inputSchema, so it stays in sync.
+const PANEL_TOOLS = [
+  { name: "adt_list_systems", label: "Sistemleri Listele", cat: "Bağlantı" },
+  { name: "adt_ping", label: "Ping / Bağlantı Testi", cat: "Bağlantı" },
+  { name: "adt_search_objects", label: "Obje Ara (isim)", cat: "Keşif" },
+  { name: "adt_grep_source", label: "Kaynak İçinde Ara (grep)", cat: "Keşif" },
+  { name: "adt_browse_package", label: "Paket İçeriği", cat: "Keşif" },
+  { name: "adt_where_used", label: "Nerede Kullanılıyor", cat: "Keşif" },
+  { name: "adt_get_source", label: "Kaynak Kodu Getir", cat: "Kaynak" },
+  { name: "adt_read_table", label: "Tablo Oku (SELECT)", cat: "Veri" },
+  { name: "adt_run_atc", label: "ATC Çalıştır", cat: "Kalite" },
+  { name: "adt_list_inactive_objects", label: "Aktif Olmayan Objeler", cat: "Yaşam döngüsü" }, // prettier-ignore
+  { name: "adt_list_transports", label: "Transport'ları Listele", cat: "Transport" },
+  { name: "adt_list_dumps", label: "Dump'ları Listele (ST22)", cat: "Runtime" },
+  { name: "adt_get_dump", label: "Dump Detayı", cat: "Runtime" },
+];
+
+function timingSafeEqualStr(a, b) {
+  const ba = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ba.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ba, bb);
+}
+
+// Reject anything whose Host header isn't loopback — cheap DNS-rebinding guard.
+function hostIsLoopback(hostHeader) {
+  if (!hostHeader) return false;
+  const host = hostHeader.split(":")[0].toLowerCase();
+  return host === "127.0.0.1" || host === "localhost" || host === "[::1]";
+}
+
+function readBody(req, limit = 1_000_000) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      size += c.length;
+      if (size > limit) {
+        reject(new Error("body too large"));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+}
+
+// Flatten an MCP tool result ({ content:[{text}], isError }) to { text, isError }.
+function flattenResult(out) {
+  const text = (out?.content ?? [])
+    .filter((c) => c && c.type === "text")
+    .map((c) => c.text)
+    .join("\n");
+  return { text, isError: Boolean(out?.isError) };
+}
+
+// Build the static "view" (allowlist + descriptors + meta + html) from the live
+// registry. Done once; the token is per-listen, not part of the view.
+function buildView({ tools, handlers, config, version }) {
+  const allow = new Map(PANEL_TOOLS.map((t) => [t.name, t]));
+  const descriptors = [];
+  for (const item of PANEL_TOOLS) {
+    const def = tools.find((t) => t.name === item.name);
+    if (!def || typeof handlers[item.name] !== "function") continue; // tool not present
+    descriptors.push({
+      name: def.name,
+      label: item.label,
+      cat: item.cat,
+      description: def.description ?? "",
+      schema: def.inputSchema ?? { type: "object", properties: {}, required: [] },
+    });
+  }
+  const meta = {
+    version,
+    systems: Object.keys(config.systems),
+    defaultSystem: config.defaultSystem ?? null,
+    readOnly: Boolean(config.readOnly),
+    tools: descriptors,
+  };
+  return { allow, meta, html: renderHtml() };
+}
+
+function makeServer({ allow, meta, html, handlers, token }) {
+  return http.createServer(async (req, res) => {
+    try {
+      if (!hostIsLoopback(req.headers.host)) {
+        res.writeHead(403).end("forbidden");
+        return;
+      }
+      const url = new URL(req.url, "http://127.0.0.1");
+
+      // The page itself is harmless without the token (every data call needs it),
+      // so serve it on GET / regardless. The JS reads the token from its own URL.
+      if (req.method === "GET" && url.pathname === "/") {
+        res.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+        res.end(html);
+        return;
+      }
+
+      // Everything below requires the token.
+      const supplied =
+        req.headers["x-panel-token"] || url.searchParams.get("t") || "";
+      if (!timingSafeEqualStr(supplied, token)) {
+        res.writeHead(401, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "bad or missing token" }));
+        return;
+      }
+
+      if (req.method === "GET" && url.pathname === "/meta") {
+        res.writeHead(200, { "content-type": "application/json" });
+        res.end(JSON.stringify(meta));
+        return;
+      }
+
+      if (req.method === "POST" && url.pathname === "/call") {
+        const body = await readBody(req);
+        let payload;
+        try {
+          payload = JSON.parse(body || "{}");
+        } catch {
+          res.writeHead(400, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "invalid JSON body" }));
+          return;
+        }
+        const name = payload?.name;
+        const args = payload?.args ?? {};
+        if (!allow.has(name) || typeof handlers[name] !== "function") {
+          // Hard wall: only curated read-only tools are reachable.
+          res.writeHead(403, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: `tool not allowed: ${name}` }));
+          return;
+        }
+        try {
+          const out = await handlers[name](args);
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(JSON.stringify(flattenResult(out)));
+        } catch (err) {
+          res.writeHead(200, { "content-type": "application/json" });
+          res.end(
+            JSON.stringify({ text: `Error: ${err.message}`, isError: true })
+          );
+        }
+        return;
+      }
+
+      res.writeHead(404).end("not found");
+    } catch (err) {
+      try {
+        res.writeHead(500).end(String(err?.message ?? err));
+      } catch {
+        /* response already sent */
+      }
+    }
+  });
+}
+
+// --- Singleton lifecycle -----------------------------------------------------
+// The panel is a process-wide singleton: server.js wires the live registry in
+// once via configurePanel(), and the adt_open_panel / adt_close_panel tools (or
+// boot auto-start) flip it on and off. Only one listener ever exists.
+let configured = null; // { handlers, config, log, view }
+let running = null; // { server, token, url }
+
+export function configurePanel({ tools, handlers, config, version, log }) {
+  configured = {
+    handlers,
+    config,
+    log: typeof log === "function" ? log : () => {},
+    view: buildView({ tools, handlers, config, version }),
+  };
+}
+
+export function isPanelConfigured() {
+  return Boolean(configured);
+}
+
+export function isPanelRunning() {
+  return Boolean(running);
+}
+
+export function getPanelUrl() {
+  return running?.url ?? null;
+}
+
+// Start the listener if it isn't already up. Resolves with the tokenized URL.
+export function ensurePanelStarted() {
+  if (!configured) {
+    return Promise.reject(new Error("panel not configured"));
+  }
+  if (running) {
+    return Promise.resolve({ url: running.url, alreadyRunning: true });
+  }
+  const { handlers, config, log, view } = configured;
+  const token = crypto.randomBytes(24).toString("hex");
+  const server = makeServer({ ...view, handlers, token });
+
+  return new Promise((resolve, reject) => {
+    const onError = (err) => {
+      server.removeListener("listening", onListening);
+      log(`error: ${err.message}`, true);
+      reject(err);
+    };
+    const onListening = () => {
+      server.removeListener("error", onError);
+      server.on("error", (err) => log(`error: ${err.message}`, true));
+      server.on("close", () => {
+        if (running?.server === server) running = null;
+      });
+      const { port } = server.address();
+      const url = `http://${config.panel.host}:${port}/?t=${token}`;
+      running = { server, token, url };
+      log(`ready (read-only) → ${url}`);
+      resolve({ url, alreadyRunning: false });
+    };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(config.panel.port, config.panel.host);
+  });
+}
+
+// Stop the listener. Returns the URL that was being served, or null if it wasn't up.
+export function stopPanel() {
+  if (!running) return null;
+  const { server, url } = running;
+  running = null;
+  server.close();
+  return url;
+}
+
+// Convenience used by boot auto-start and tests: configure + start in one call.
+// Returns { server, getUrl } once listening (test-friendly shape preserved).
+export function startPanel(opts) {
+  configurePanel(opts);
+  const { handlers, config, view } = configured;
+  const token = crypto.randomBytes(24).toString("hex");
+  const server = makeServer({ ...view, handlers, token });
+  server.on("error", (err) => configured.log(`error: ${err.message}`, true));
+  server.on("close", () => {
+    if (running?.server === server) running = null;
+  });
+  server.listen(config.panel.port, config.panel.host, () => {
+    const { port } = server.address();
+    const url = `http://${config.panel.host}:${port}/?t=${token}`;
+    running = { server, token, url };
+    configured.log(`ready (read-only) → ${url}`);
+  });
+  return {
+    server,
+    getUrl: () => {
+      const addr = server.address();
+      return addr
+        ? `http://${config.panel.host}:${addr.port}/?t=${token}`
+        : null;
+    },
+  };
+}
+
+// --- The served page (single self-contained document) -----------------------
+function renderHtml() {
+  // Token comes from this page's own ?t=… ; meta + forms are fetched at load.
+  return `<!doctype html>
+<html lang="tr">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>SAP ADT — Kontrol Paneli</title>
+<style>
+  :root { color-scheme: dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.45 -apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,sans-serif;
+    background:#0f1116; color:#e6e8ee; }
+  header { padding:14px 20px; border-bottom:1px solid #222633; display:flex; gap:14px;
+    align-items:center; position:sticky; top:0; background:#0f1116; z-index:5; flex-wrap:wrap; }
+  header h1 { font-size:16px; margin:0; font-weight:600; }
+  .pill { font-size:11px; padding:2px 8px; border-radius:999px; background:#1b2030; color:#9aa3b8; }
+  .pill.ro { background:#13361f; color:#5fd38a; }
+  .pill.warn { background:#3a2417; color:#e0a06a; }
+  label.sysrow { margin-left:auto; font-size:12px; color:#9aa3b8; display:flex; gap:6px; align-items:center; }
+  select, input, textarea { background:#161a24; color:#e6e8ee; border:1px solid #2a3142;
+    border-radius:6px; padding:6px 8px; font:inherit; }
+  textarea { width:100%; min-height:54px; resize:vertical; font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:12px; }
+  main { padding:18px 20px; display:grid; grid-template-columns:repeat(auto-fill,minmax(320px,1fr)); gap:14px; }
+  .card { background:#141822; border:1px solid #232838; border-radius:10px; padding:14px; }
+  .card h3 { margin:0 0 2px; font-size:14px; }
+  .cat { font-size:10px; text-transform:uppercase; letter-spacing:.06em; color:#717a90; }
+  .desc { color:#8b93a7; font-size:11px; margin:4px 0 10px; max-height:48px; overflow:auto; }
+  .field { margin-bottom:8px; }
+  .field label { display:block; font-size:11px; color:#9aa3b8; margin-bottom:3px; }
+  .field label .req { color:#e0716a; }
+  .field input, .field textarea { width:100%; }
+  button.run { background:#2f6df6; color:#fff; border:none; border-radius:7px; padding:8px 14px;
+    font:inherit; font-weight:600; cursor:pointer; }
+  button.run:hover { background:#4079f8; }
+  button.run:disabled { opacity:.5; cursor:default; }
+  pre.out { margin:10px 0 0; background:#0b0d13; border:1px solid #202635;
+    border-radius:7px; padding:10px; max-height:340px; overflow:auto; white-space:pre-wrap;
+    word-break:break-word; font-family:ui-monospace,SFMono-Regular,Menlo,monospace; font-size:11.5px; }
+  pre.out.err { border-color:#5a2a2a; color:#f0a3a3; }
+  pre.out:empty { display:none; }
+  .muted { color:#717a90; }
+  #boot { padding:40px 20px; color:#8b93a7; }
+</style>
+</head>
+<body>
+<header>
+  <h1>SAP ADT — Kontrol Paneli</h1>
+  <span class="pill ro">read-only</span>
+  <span id="ver" class="pill"></span>
+  <span id="globalro" class="pill warn" style="display:none">sistem global read-only</span>
+  <label class="sysrow">Sistem:
+    <select id="system"></select>
+  </label>
+</header>
+<div id="boot">Yükleniyor… <span class="muted">(MCP process'i ile aynı ömürde — session kapanınca bu sayfa ölür)</span></div>
+<main id="cards" style="display:none"></main>
+<script>
+const TOKEN = new URLSearchParams(location.search).get("t") || "";
+const $ = (s,el=document)=>el.querySelector(s);
+
+async function call(name, args){
+  const r = await fetch("/call", {
+    method:"POST",
+    headers:{ "content-type":"application/json", "x-panel-token":TOKEN },
+    body: JSON.stringify({ name, args })
+  });
+  if(!r.ok){ return { text:"HTTP "+r.status+" — "+(await r.text()), isError:true }; }
+  return r.json();
+}
+
+function fieldFor(key, prop, required){
+  const wrap = document.createElement("div"); wrap.className="field";
+  const lab = document.createElement("label");
+  lab.innerHTML = key + (required?' <span class="req">*</span>':'') ;
+  if(prop.description){ lab.title = prop.description; }
+  wrap.appendChild(lab);
+  let input;
+  const t = prop.type;
+  if(t==="boolean"){
+    input=document.createElement("input"); input.type="checkbox";
+    input.style.width="auto";
+  } else if(t==="integer"||t==="number"){
+    input=document.createElement("input"); input.type="number";
+    if(prop.minimum!=null) input.min=prop.minimum;
+    if(prop.maximum!=null) input.max=prop.maximum;
+  } else if(t==="array"||t==="object"){
+    input=document.createElement("textarea");
+    input.placeholder="JSON, örn: "+(t==="array"?'[{"name":"...","type":"..."}]':'{}');
+  } else if(Array.isArray(prop.enum)){
+    input=document.createElement("select");
+    const blank=document.createElement("option"); blank.value=""; blank.textContent="(varsayılan)";
+    input.appendChild(blank);
+    for(const v of prop.enum){ const o=document.createElement("option"); o.value=v; o.textContent=v; input.appendChild(o); }
+  } else {
+    input=document.createElement("input"); input.type="text";
+  }
+  input.dataset.key=key; input.dataset.jtype=t||"string";
+  if(prop.description) input.title=prop.description;
+  wrap.appendChild(input);
+  return wrap;
+}
+
+function collect(card){
+  const args={};
+  for(const el of card.querySelectorAll("[data-key]")){
+    const k=el.dataset.key, t=el.dataset.jtype;
+    if(el.type==="checkbox"){ if(el.checked) args[k]=true; continue; }
+    const raw=el.value.trim();
+    if(raw==="") continue;
+    if(t==="integer"){ args[k]=parseInt(raw,10); }
+    else if(t==="number"){ args[k]=Number(raw); }
+    else if(t==="array"||t==="object"){
+      try { args[k]=JSON.parse(raw); } catch(e){ throw new Error(k+": geçersiz JSON"); }
+    }
+    else args[k]=raw;
+  }
+  return args;
+}
+
+function buildCard(tool, getSystem){
+  const card=document.createElement("section"); card.className="card";
+  const cat=document.createElement("div"); cat.className="cat"; cat.textContent=tool.cat; card.appendChild(cat);
+  const h=document.createElement("h3"); h.textContent=tool.label; card.appendChild(h);
+  const d=document.createElement("div"); d.className="desc"; d.textContent=tool.description; card.appendChild(d);
+
+  const props=tool.schema.properties||{};
+  const req=new Set(tool.schema.required||[]);
+  for(const key of Object.keys(props)){
+    if(key==="system") continue; // handled by the global system selector
+    card.appendChild(fieldFor(key, props[key], req.has(key)));
+  }
+  const btn=document.createElement("button"); btn.className="run"; btn.textContent="Çalıştır"; card.appendChild(btn);
+  const out=document.createElement("pre"); out.className="out"; card.appendChild(out);
+
+  btn.addEventListener("click", async ()=>{
+    let args;
+    try { args=collect(card); } catch(e){ out.className="out err"; out.textContent=e.message; return; }
+    const sys=getSystem();
+    if(sys) args.system=sys;
+    btn.disabled=true; const old=btn.textContent; btn.textContent="Çalışıyor…";
+    out.className="out"; out.textContent="";
+    try {
+      const res=await call(tool.name, args);
+      out.className="out"+(res.isError?" err":"");
+      out.textContent=res.text||"(boş yanıt)";
+    } catch(e){ out.className="out err"; out.textContent=String(e.message||e); }
+    finally { btn.disabled=false; btn.textContent=old; }
+  });
+  return card;
+}
+
+(async function init(){
+  let meta;
+  try {
+    const r=await fetch("/meta",{headers:{"x-panel-token":TOKEN}});
+    if(!r.ok) throw new Error("HTTP "+r.status);
+    meta=await r.json();
+  } catch(e){
+    $("#boot").textContent="Panel'e bağlanılamadı: "+e.message+" — token geçersiz ya da session kapandı.";
+    return;
+  }
+  $("#ver").textContent="v"+meta.version;
+  if(meta.readOnly) $("#globalro").style.display="";
+  const sel=$("#system");
+  for(const s of meta.systems){ const o=document.createElement("option"); o.value=s; o.textContent=s; sel.appendChild(o); }
+  if(meta.defaultSystem) sel.value=meta.defaultSystem;
+  const getSystem=()=>sel.value||"";
+
+  const cards=$("#cards");
+  for(const tool of meta.tools){ cards.appendChild(buildCard(tool, getSystem)); }
+  $("#boot").style.display="none";
+  cards.style.display="";
+})();
+</script>
+</body>
+</html>`;
+}

package/src/server.js

@@ -16,6 +16,7 @@ import { listPrompts, getPrompt } from "./prompts.js";
 import { textResult } from "./result.js";
 import { createReporter } from "./reporter.js";
 import { createAuditLog, toolContext } from "./audit.js";
+import { configurePanel, ensurePanelStarted } from "./panel.js";
 
 import * as connectionTools from "./tools/connection.js";
 import * as sourceTools from "./tools/source.js";
@@ -34,6 +35,7 @@ import * as worklistTools from "./tools/worklist.js";
 import * as jobTools from "./tools/jobs.js";
 import * as rapTools from "./tools/rap.js";
 import * as reportTools from "./tools/report.js";
+import * as panelTools from "./tools/panel.js";
 
 const PKG = JSON.parse(
   readFileSync(
@@ -123,6 +125,7 @@ const TOOL_MODULES = [
   jobTools,
   rapTools,
   reportTools,
+  panelTools,
 ];
 
 const tools = [];
@@ -237,4 +240,23 @@ async function validateConfig() {
   process.exit(allOk ? 0 : 1);
 }
 
+// --- Local control panel -----------------------------------------------------
+// Always WIRED so the adt_open_panel tool can start it on demand ("paneli aç"),
+// but it does not listen until either that tool is called or config.panel.enabled
+// auto-starts it at boot. Either way it serves a read-only HTML button panel from
+// inside this process — reachable only while this session keeps the MCP connected,
+// and it dies when the process exits.
+configurePanel({
+  tools,
+  handlers,
+  config,
+  version: PKG.version,
+  log: (msg) => process.stderr.write(`[${PKG.name}] panel: ${msg}\n`),
+});
+if (config.panel?.enabled) {
+  ensurePanelStarted().catch((err) =>
+    process.stderr.write(`[${PKG.name}] panel: ${err.message}\n`)
+  );
+}
+
 await server.connect(new StdioServerTransport());

package/src/tools/cds.js

@@ -1,7 +1,7 @@
 import { objectUri } from "../object-uris.js";
 import { parseDataPreview } from "../data-preview.js";
 import { parseObjectReferences } from "../object-references.js";
-import { errorResult, jsonResult } from "../result.js";
+import { errorResult, jsonResult, textResult } from "../result.js";
 import { SYSTEM_HINT } from "./_shared.js";
 
 const CDS_PREVIEW_PATH = "/sap/bc/adt/datapreview/cds";
@@ -86,12 +86,21 @@ export const tools = [
 export function register({ getClient }) {
   return {
     adt_cds_data_preview: async (args) => {
+      // `entity` is the documented field, but callers reach for `name`/`cdsName`;
+      // accept those too and fail cleanly rather than throwing on `.toUpperCase`.
+      const entity = args.entity ?? args.name ?? args.cdsName;
+      if (typeof entity !== "string" || entity.length === 0) {
+        return textResult(
+          "adt_cds_data_preview: `entity` is required (the CDS view/entity name, e.g. 'I_CompanyCode').",
+          true
+        );
+      }
       const { client, name: sys } = getClient(args.system);
       const max = Math.min(args.maxRows ?? DEFAULT_MAX_ROWS, HARD_CAP_ROWS);
       const res = await client.request({
         method: "POST",
         path: CDS_PREVIEW_PATH,
-        query: { ddlSourceName: args.entity.toUpperCase(), rowNumber: String(max) },
+        query: { ddlSourceName: entity.toUpperCase(), rowNumber: String(max) },
         accept: "application/xml",
       });
       const text = await res.text();
@@ -100,12 +109,12 @@ export function register({ getClient }) {
       try {
         parsed = parseDataPreview(text);
       } catch (err) {
-        return jsonResult({ system: sys, entity: args.entity, parseError: err.message, raw: text.slice(0, 8000) });
+        return jsonResult({ system: sys, entity, parseError: err.message, raw: text.slice(0, 8000) });
       }
       const rowCount = parsed.rows.length;
       return jsonResult({
         system: sys,
-        entity: args.entity.toUpperCase(),
+        entity: entity.toUpperCase(),
         rowCount,
         truncated: rowCount >= max,
         totalRows: parsed.totalRows,
@@ -116,8 +125,15 @@ export function register({ getClient }) {
     },
 
     adt_cds_dependencies: async (args) => {
+      const entity = args.entity ?? args.name ?? args.cdsName;
+      if (typeof entity !== "string" || entity.length === 0) {
+        return textResult(
+          "adt_cds_dependencies: `entity` is required (the CDS view/entity name, e.g. 'I_CompanyCode').",
+          true
+        );
+      }
       const { client, name: sys } = getClient(args.system);
-      const uri = objectUri({ type: "ddls", name: args.entity });
+      const uri = objectUri({ type: "ddls", name: entity });
       const res = await client.request({ path: GRAPHDATA_PATH, query: { uri }, accept: "application/xml" });
       const text = await res.text();
       if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"), { stage: "graphdata" });
@@ -131,7 +147,7 @@ export function register({ getClient }) {
       }
       return jsonResult({
         system: sys,
-        entity: args.entity.toUpperCase(),
+        entity: entity.toUpperCase(),
         uri,
         dependencyCount: refs.length,
         dependencies: refs,

package/src/tools/discovery.js

@@ -315,8 +315,9 @@ export function register({ getClient }) {
 
     adt_list_packages: async (args) => {
       // `package` is the field name on the sibling adt_browse_package tool, so
-      // callers reach for it here too — accept it as an alias for `root`.
-      const rootArg = args.root ?? args.package;
+      // callers reach for it here too — accept it (and a bare `name`) as an
+      // alias for `root`.
+      const rootArg = args.root ?? args.package ?? args.name;
       if (typeof rootArg !== "string" || rootArg.length === 0) {
         return textResult(
           "adt_list_packages: `root` is required (the root package to walk from, e.g. 'ZFLEET').",

package/src/tools/panel.js

@@ -0,0 +1,92 @@
+import { exec } from "node:child_process";
+import { jsonResult } from "../result.js";
+import {
+  ensurePanelStarted,
+  stopPanel,
+  isPanelRunning,
+  getPanelUrl,
+} from "../panel.js";
+
+// Best-effort "open this URL in the user's browser". Never throws.
+function openInBrowser(url) {
+  const cmd =
+    process.platform === "darwin"
+      ? "open"
+      : process.platform === "win32"
+        ? "start \"\""
+        : "xdg-open";
+  return new Promise((resolve) => {
+    try {
+      exec(`${cmd} "${url}"`, (err) => resolve(!err));
+    } catch {
+      resolve(false);
+    }
+  });
+}
+
+export const tools = [
+  {
+    name: "adt_open_panel",
+    description:
+      "Open the local, read-only SAP control panel: an HTML page with buttons for the read-only tools (search, grep source, get source, read table, ATC, where-used, packages, transports, dumps, inactive objects). Returns the URL to open. The panel is served from inside THIS MCP process, so it works only while this session keeps the MCP connected and dies when the session ends. Bound to 127.0.0.1, gated by a per-boot random token, read-only tools only — no write tool is reachable. By default also opens the URL in the local default browser.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        open: {
+          type: "boolean",
+          description:
+            "Also open the URL in the local default browser. Default true. Set false to just return the URL.",
+        },
+      },
+    },
+  },
+  {
+    name: "adt_close_panel",
+    description:
+      "Stop the local control panel started by adt_open_panel. (It also stops on its own when this MCP session ends.)",
+    inputSchema: { type: "object", properties: {} },
+  },
+];
+
+export function register() {
+  return {
+    adt_open_panel: async (args = {}) => {
+      let info;
+      try {
+        info = await ensurePanelStarted();
+      } catch (err) {
+        return jsonResult(
+          {
+            ok: false,
+            error: `Could not start panel: ${err.message}`,
+          },
+          true
+        );
+      }
+      const wantOpen = args.open !== false;
+      const browserOpened = wantOpen ? await openInBrowser(info.url) : false;
+      return jsonResult({
+        ok: true,
+        url: info.url,
+        alreadyRunning: info.alreadyRunning,
+        browserOpened,
+        readOnly: true,
+        note:
+          "Open this URL in a browser. The panel lives inside this MCP process — " +
+          "it closes automatically when the session ends. Read-only tools only.",
+      });
+    },
+
+    adt_close_panel: async () => {
+      const wasRunning = isPanelRunning();
+      const stoppedUrl = stopPanel();
+      return jsonResult({
+        ok: true,
+        wasRunning,
+        stoppedUrl,
+        stillRunning: isPanelRunning(),
+        currentUrl: getPanelUrl(),
+      });
+    },
+  };
+}

package/src/tools/source.js

@@ -286,13 +286,26 @@ export function register({ getClient }) {
         return textResult("adt_get_source: `type` is required (e.g. 'class', 'program', 'dataelement').", true);
       }
       const { client, name: sys } = getClient(args.system);
-      const t = normalizeType(args.type);
-      const path = sourceUri({
-        type: args.type,
-        name: args.object,
-        group: args.group,
-        include: args.include,
-      });
+      let t;
+      let path;
+      try {
+        t = normalizeType(args.type);
+        path = sourceUri({
+          type: args.type,
+          name: args.object,
+          group: args.group,
+          include: args.include,
+        });
+      } catch (err) {
+        // Unknown/unsupported object types (e.g. WAPA) reach the dispatch
+        // tables and throw. Return that as a clean tool error with an escape
+        // hatch hint instead of letting it surface as a crash.
+        return textResult(
+          `adt_get_source: ${err.message}. If this type has no high-level mapping yet, ` +
+            `fetch it with adt_request against its ADT source URI.`,
+          true
+        );
+      }
 
       // DDIC primitives (data element / domain / message class) have no
       // plain-text source — fetch their XML metadata with the right media type