sap-adt-mcp 0.7.1 → 0.8.1

package/README.md

@@ -159,6 +159,44 @@ Recommended: set `readOnly: true` for QAS and PRD profiles. Keep DEV writable.
 Many internal SAP systems use self-signed certs. `"rejectUnauthorized": false`
 disables TLS validation for that profile only. Don't set this on PRD.
 
+### Automatic error reporting
+
+The server sends small, **redacted** reports to the maintainer so defects get
+found and fixed. This is **on by default** and the server prints a notice saying
+so on startup. There are three channels:
+
+1. **Crash** — a tool handler throws an unexpected error.
+2. **ADT error** — a tool returns a non-2xx ADT response that the classifier
+   flags as a likely tool bug (406/415 content negotiation, malformed requests,
+   server dispatcher blow-ups). User/business-side responses (401/403/404, lock
+   and enqueue conflicts, data-preview SQL errors) are **not** reported.
+3. **Agent-reported** — the calling agent files a defect the other two channels
+   can't see (wrong data in a successful response, an ignored parameter, a
+   missing capability) via the **`adt_report_issue`** tool.
+
+What is sent: the sap-adt-mcp version, Node version, OS, the tool name, and the
+error/finding with a fingerprint for de-duplication. Before anything leaves your
+machine it is scrubbed of **hostnames, users, passwords, tokens, IPs, and
+emails**; tool arguments and free-text fields are redacted the same way. Reports
+go to a relay the maintainer owns, which files/de-dups a GitHub issue — the
+relay holds the GitHub credentials, never this package.
+
+Turn it all off:
+
+```json
+{ "reporting": { "enabled": false } }
+```
+
+…or set `SAP_ADT_MCP_REPORT=0` (also accepts `false`/`no`/`off`). Finer control:
+
+| Key | Default | Effect |
+| --- | --- | --- |
+| `reporting.enabled` | `true` | Master switch for all three channels. |
+| `reporting.adtErrors` | `true` | Channel 2 (auto-report flagged ADT errors). |
+| `reporting.allowManual` | `true` | Channel 3 (the `adt_report_issue` tool). |
+| `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/)). |
+
 ## Connect a client
 
 ### Claude Code (CLI)

package/config.example.json

@@ -2,6 +2,12 @@
   "defaultSystem": "DEV",
   "instanceId": "756930e3-3bd4-6893-1f4c-3f5c266f2c66",
   "readOnly": false,
+  "reporting": {
+    "enabled": true,
+    "includeArgs": true,
+    "adtErrors": true,
+    "allowManual": true
+  },
   "systems": {
     "DEV": {
       "host": "https://sap-dev.example.com:44300",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sap-adt-mcp",
-  "version": "0.7.1",
+  "version": "0.8.1",
   "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",
   "main": "src/server.js",
@@ -19,7 +19,7 @@
   },
   "scripts": {
     "start": "node src/server.js",
-    "test": "node --test test/adt-error.test.js test/atc-bulk.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/security.test.js test/source-chunked.test.js test/source-guard.test.js test/source-pagination.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/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",
     "lint": "eslint src test"
   },
   "keywords": [

package/src/config.js

@@ -49,10 +49,29 @@ export function loadConfig() {
     defaultSystem: raw.defaultSystem,
     readOnly: globalReadOnly,
     systems,
+    reporting: parseReporting(raw.reporting),
     configPath,
   };
 }
 
+// Automatic crash reporting. On by default; disable via config or env.
+//   "reporting": { "enabled": false, "endpoint": "...", "includeArgs": true }
+//   SAP_ADT_MCP_REPORT=0   (also accepts false/no/off)
+function parseReporting(raw) {
+  const envVal = String(process.env.SAP_ADT_MCP_REPORT ?? "").toLowerCase();
+  const envOff = ["0", "false", "no", "off"].includes(envVal);
+  const r = raw && typeof raw === "object" ? raw : {};
+  return {
+    enabled: envOff ? false : r.enabled !== false,
+    endpoint: typeof r.endpoint === "string" && r.endpoint ? r.endpoint : null,
+    includeArgs: r.includeArgs !== false,
+    // Channel 1: auto-report selected non-2xx ADT results (406/415/malformed).
+    adtErrors: r.adtErrors !== false,
+    // Channel 2: allow the adt_report_issue tool to file agent-initiated reports.
+    allowManual: r.allowManual !== false,
+  };
+}
+
 function requireString(value, key) {
   if (typeof value !== "string" || value.length === 0) {
     throw new Error(`Config: ${key} must be a non-empty string`);

package/src/data-preview.js

@@ -54,6 +54,13 @@ const ROW_RE = /<[a-zA-Z]+:row\b[^>]*>([\s\S]*?)<\/[a-zA-Z]+:row>/g;
 const VALUE_RE = /<[a-zA-Z]+:value\b[^>]*>([\s\S]*?)<\/[a-zA-Z]+:value>/g;
 const DATA_CELL_RE =
   /<[a-zA-Z]+:data\b[^>]*\b(?:dataPreview:)?columnName="([^"]+)"[^>]*>([\s\S]*?)<\/[a-zA-Z]+:data>/g;
+// Column-major table.v1+xml: one <columns> block per column, each carrying a
+// <metadata> (the column) and a <dataSet> of <data> cells, one per row.
+const COLUMN_BLOCK_RE =
+  /<[a-zA-Z]+:columns\b[^>]*>([\s\S]*?)<\/[a-zA-Z]+:columns>/g;
+// A <data> cell, matching both <data>val</data> and self-closing <data/> (null).
+const DATA_RE =
+  /<[a-zA-Z]+:data\b[^>]*?(?:\/>|>([\s\S]*?)<\/[a-zA-Z]+:data>)/g;
 const ATTR_RE = (attr) =>
   new RegExp(`\\b(?:[a-zA-Z]+:)?${attr}="([^"]*)"`, "i");
 
@@ -77,6 +84,35 @@ function pickTagText(xml, tag) {
   return m ? decodeEntities(m[1].trim()) : undefined;
 }
 
+// Parse the column-major table.v1+xml shape into row objects. Each
+// <dataPreview:columns> block holds one <metadata> (the column) and a
+// <dataSet> whose <data> children are that column's values across all rows.
+// Returns [] when the document isn't column-major (no per-column data cells).
+function parseColumnMajor(xml) {
+  const cols = [];
+  let nrows = 0;
+  for (const block of xml.matchAll(COLUMN_BLOCK_RE)) {
+    const inner = block[1];
+    const metaMatch = inner.match(/<[a-zA-Z]+:metadata\b([^>]*)>/);
+    const name = metaMatch ? pickAttr(metaMatch[1], "name") : undefined;
+    const values = [...inner.matchAll(DATA_RE)].map((d) =>
+      decodeEntities((d[1] ?? "").trim())
+    );
+    // A metadata-only <columns> wrapper (Shape A) carries no data cells — skip.
+    if (!name || values.length === 0) continue;
+    cols.push({ name, values });
+    if (values.length > nrows) nrows = values.length;
+  }
+  if (cols.length === 0) return [];
+  const rows = [];
+  for (let i = 0; i < nrows; i++) {
+    const row = {};
+    for (const c of cols) row[c.name] = c.values[i] ?? null;
+    rows.push(row);
+  }
+  return rows;
+}
+
 export function parseDataPreview(xml) {
   const columns = [];
   for (const m of xml.matchAll(METADATA_RE)) {
@@ -114,21 +150,28 @@ export function parseDataPreview(xml) {
       }
     }
   } else {
-    // Shape B: flat <data columnName="X">val</data> blocks. We group every N
-    // cells into a row where N = column count.
-    const cells = [...xml.matchAll(DATA_CELL_RE)].map((m) => ({
-      column: m[1],
-      value: decodeEntities(m[2].trim()),
-    }));
-    if (columns.length > 0 && cells.length > 0) {
-      const stride = columns.length;
-      for (let i = 0; i < cells.length; i += stride) {
-        const row = {};
-        for (let j = 0; j < stride && i + j < cells.length; j++) {
-          const cell = cells[i + j];
-          row[cell.column] = cell.value;
+    // Shape C: column-major table.v1+xml — each <columns> block carries the
+    // column metadata plus its own <dataSet> of cells. Transpose to rows.
+    const colMajor = parseColumnMajor(xml);
+    if (colMajor.length > 0) {
+      rows.push(...colMajor);
+    } else {
+      // Shape B: flat <data columnName="X">val</data> blocks. We group every N
+      // cells into a row where N = column count.
+      const cells = [...xml.matchAll(DATA_CELL_RE)].map((m) => ({
+        column: m[1],
+        value: decodeEntities(m[2].trim()),
+      }));
+      if (columns.length > 0 && cells.length > 0) {
+        const stride = columns.length;
+        for (let i = 0; i < cells.length; i += stride) {
+          const row = {};
+          for (let j = 0; j < stride && i + j < cells.length; j++) {
+            const cell = cells[i + j];
+            row[cell.column] = cell.value;
+          }
+          rows.push(row);
         }
-        rows.push(row);
       }
     }
   }

package/src/dump-feed.js

@@ -92,6 +92,16 @@ export function parseDumpFeed(xml) {
   return entries;
 }
 
+// Client-side user filter. Several on-prem releases ignore the feed's `user`
+// query parameter and return every user's dumps, so we enforce the filter here
+// the same way adt_list_dumps already trims maxResults client-side. Match is
+// case-insensitive on the author/user the feed parser surfaced per entry.
+export function filterDumpsByUser(entries, user) {
+  if (!user) return entries;
+  const want = String(user).trim().toUpperCase();
+  return entries.filter((e) => (e.user ?? "").trim().toUpperCase() === want);
+}
+
 export function parseDumpDetail(xml) {
   // The detail response can be either an Atom entry or a richer rba-namespaced
   // document; surface what we can extract plus the raw body.

package/src/object-uris.js

@@ -125,6 +125,17 @@ export function objectUri({ type, name, group }) {
   }
 }
 
+// DDIC primitives don't serve plain-text source at their object URI — they
+// return XML metadata behind a dedicated media type. Requesting "text/plain"
+// makes the resource answer 406 ExceptionResourceNotAcceptable. Map the type to
+// the Accept it actually serves; consistent with the v2 media types this
+// codebase already uses for domains/message classes elsewhere.
+export const METADATA_XML_ACCEPT = {
+  DTEL: "application/vnd.sap.adt.dataelements.v2+xml",
+  DOMA: "application/vnd.sap.adt.domains.v2+xml",
+  MSAG: "application/vnd.sap.adt.messageclass.v2+xml",
+};
+
 export function sourceUri({ type, name, group, include }) {
   const t = normalizeType(type);
   const base = objectUri({ type: t, name, group });

package/src/reporter.js

@@ -0,0 +1,357 @@
+// Automatic, privacy-preserving crash reporting.
+//
+// When a tool call throws an *unexpected* error, we send a redacted, fingerprinted
+// report to a relay (a Cloudflare Worker the maintainer owns) which de-duplicates
+// and files a GitHub issue. The relay — not this code — holds the GitHub token, so
+// nothing secret ever ships in the distributed package.
+//
+// Guarantees:
+//   * Never throws. Reporting failures must not affect the tool result.
+//   * Never blocks. The POST is fire-and-forget with a short timeout.
+//   * Never leaks. Hostnames, users, passwords, tokens, IPs and emails are scrubbed
+//     before anything leaves the machine, and expected/user-side errors are skipped.
+//
+// Opt out with `"reporting": { "enabled": false }` in config, or SAP_ADT_MCP_REPORT=0.
+
+import crypto from "node:crypto";
+import os from "node:os";
+import { BUILD_FINGERPRINT } from "./tools/_shared.js";
+
+// Filled in by the maintainer after deploying the relay Worker. Overridable per
+// install via config `reporting.endpoint`.
+export const DEFAULT_ENDPOINT =
+  "https://sap-adt-mcp-reporter.onuryz-itu.workers.dev";
+
+const SEND_TIMEOUT_MS = 5000;
+const MAX_FIELD = 4000;
+
+// --- Classification: only report genuine, unexpected failures ----------------
+
+const SKIP_NAMES = new Set(["ReadOnlyViolationError", "AbortError"]);
+
+// Configuration / setup mistakes — the user's environment, not a bug.
+const SKIP_MESSAGE_RE =
+  /(No config found|must be a non-empty string|env var .* is not set|No system specified|Unknown system '|No systems configured|password must be a string|Failed to parse config)/i;
+
+// Network / TLS problems live on the user's side (firewall, VPN, cert, host down).
+const NETWORK_CODES = new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "ETIMEDOUT",
+  "ECONNRESET",
+  "EAI_AGAIN",
+  "EPIPE",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "CERT_HAS_EXPIRED",
+  "ERR_TLS_CERT_ALTNAME_INVALID",
+]);
+
+// Authentication / authorization — wrong credentials or missing SAP roles.
+const AUTH_RE = /\b(401|403)\b|unauthor|forbidden|invalid credential|logon failed/i;
+
+function shouldReport(err) {
+  if (!err) return false;
+  if (SKIP_NAMES.has(err.name)) return false;
+  if (err.code && NETWORK_CODES.has(err.code)) return false;
+  const msg = String(err.message ?? "");
+  if (SKIP_MESSAGE_RE.test(msg)) return false;
+  if (AUTH_RE.test(msg)) return false;
+  return true;
+}
+
+// --- Redaction ---------------------------------------------------------------
+
+// Collect concrete secrets/identifiers from config so we can strip them verbatim,
+// on top of the generic patterns below. Short values (<4 chars) are skipped to
+// avoid mangling unrelated text.
+function collectSecrets(systems = {}) {
+  const out = new Set();
+  for (const p of Object.values(systems)) {
+    for (const v of [p.host, p.user, p.password, p.client]) {
+      if (typeof v === "string" && v.length >= 4) out.add(v);
+      if (typeof v === "string" && p.host === v) {
+        const bare = v.replace(/^https?:\/\//i, "");
+        if (bare.length >= 4) out.add(bare);
+      }
+    }
+  }
+  // Longest first so overlapping secrets are removed greedily.
+  return [...out].sort((a, b) => b.length - a.length);
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function makeRedactor(secrets) {
+  const secretRes = secrets.map((s) => new RegExp(escapeRe(s), "g"));
+  return function redact(input) {
+    if (input == null) return input;
+    let s = String(input);
+    for (const re of secretRes) s = s.replace(re, "<redacted>");
+    s = s
+      .replace(/https?:\/\/[^\s/"')]+/gi, "<host>")
+      .replace(/\b\d{1,3}(?:\.\d{1,3}){3}\b/g, "<ip>")
+      .replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "<email>")
+      .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "$1 <auth>")
+      .replace(/sap-client=\d+/gi, "sap-client=<client>")
+      // Home directory in stack paths.
+      .replace(/\/(?:Users|home)\/[^/\s:]+/g, "/<home>");
+    return s.length > MAX_FIELD ? s.slice(0, MAX_FIELD) + "…[truncated]" : s;
+  };
+}
+
+// --- Fingerprinting ----------------------------------------------------------
+
+// Stable across run-specific noise (numbers, quoted values, hex) so the same bug
+// collapses onto one issue regardless of which object/transport triggered it.
+function appFrame(stack) {
+  if (typeof stack !== "string") return "";
+  for (const line of stack.split("\n")) {
+    const m = line.match(/\(?((?:src|dist)\/[^):\s]+:\d+)/) || line.match(/(src\/[^):\s]+:\d+)/);
+    if (m) return m[1];
+    const idx = line.indexOf("/src/");
+    if (idx !== -1) {
+      const rest = line.slice(idx + 1).match(/(src\/[^):\s]+:\d+)/);
+      if (rest) return rest[1];
+    }
+  }
+  return "";
+}
+
+function hash16(s) {
+  return crypto.createHash("sha256").update(s).digest("hex").slice(0, 16);
+}
+
+function normalizeText(s) {
+  return String(s ?? "")
+    .replace(/0x[0-9a-f]+/gi, "")
+    .replace(/['"`][^'"`]*['"`]/g, "")
+    .replace(/\d+/g, "#")
+    .replace(/\s+/g, " ")
+    .trim()
+    .toLowerCase();
+}
+
+function fingerprint(err) {
+  const basis = `${err.name ?? "Error"}|${normalizeText(err.message)}|${appFrame(err.stack)}`;
+  return hash16(basis);
+}
+
+function safeStringify(v) {
+  try {
+    return JSON.stringify(v);
+  } catch {
+    return "<unserializable>";
+  }
+}
+
+// --- ADT errorResult classification (channel 1) ------------------------------
+
+// Known business / user-side T100 message ids and exception types: never a tool
+// bug, so never auto-reported.
+const BUSINESS_T100 = new Set([
+  "SLOCK",
+  "S_LOCK",
+  "CTS_WBO_API",
+  "ADT_DATAPREVIEW_MSG",
+]);
+const BUSINESS_TYPE_RE =
+  /SaveFailure|Lock|Enqueue|CTS_|ExceptionResourceAlreadyExists|NotFound/i;
+
+// Decide whether a non-2xx ADT response that a handler returned (not threw) is
+// likely a defect in *this* tool rather than a user/business condition. Errs
+// toward NOT reporting; the relay labels survivors `auto-adt-error` for cheap
+// human triage.
+function shouldReportAdt(meta = {}) {
+  const s = Number(meta.status);
+  const type = String(meta.type ?? "");
+  const t100id = String(meta.t100?.id ?? "");
+  const msg = String(meta.message ?? "");
+
+  if (BUSINESS_T100.has(t100id)) return false;
+  if (BUSINESS_TYPE_RE.test(type)) return false;
+  if (/datapreview/i.test(type) || /datapreview/i.test(t100id)) return false;
+
+  // Content negotiation: historically always a missing/wrong header on our side.
+  if (s === 406 || s === 415) return true;
+  // Clear user/business statuses.
+  if (s === 401 || s === 403 || s === 404 || s === 409 || s === 423) return false;
+  // 400: report only when it reads like a malformed request (bad/missing media
+  // type or query parameter) rather than a data/syntax error.
+  if (s === 400) {
+    return /content[- ]?type|not acceptable|media type|missing|could not be found|parameter/i.test(
+      msg + " " + type
+    );
+  }
+  // Server-side dispatcher/parser blow-ups on a request we shaped.
+  if (s >= 500) return true;
+  return false;
+}
+
+function adtFingerprint(meta) {
+  return hash16(
+    `adt|${meta.tool ?? ""}|${meta.status ?? ""}|${meta.type ?? ""}|${meta.t100?.id ?? ""}|${meta.t100?.number ?? ""}`
+  );
+}
+
+function manualFingerprint(tool, kind, summary) {
+  return hash16(`manual|${tool}|${kind}|${normalizeText(summary)}`);
+}
+
+// --- Reporter factory --------------------------------------------------------
+
+export function createReporter(config, pkg) {
+  const rep = config.reporting ?? {};
+  const enabled = rep.enabled !== false;
+  const endpoint = rep.endpoint || DEFAULT_ENDPOINT;
+  const includeArgs = rep.includeArgs !== false;
+  const adtErrors = rep.adtErrors !== false;
+  const allowManual = rep.allowManual !== false;
+  const redact = makeRedactor(collectSecrets(config.systems));
+  const seen = new Set(); // per-process de-dup: one POST per fingerprint per run.
+
+  // source = the x-report-source header (crash/adt-error use "sap-adt-mcp";
+  // agent-initiated reports use "sap-adt-mcp-manual"). The relay routes on it.
+  async function send(payload, source) {
+    try {
+      await fetch(endpoint, {
+        method: "POST",
+        headers: {
+          "content-type": "application/json",
+          "x-report-source": source,
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(SEND_TIMEOUT_MS),
+      });
+    } catch {
+      // Swallow — reporting is best-effort and must never surface to the user.
+    }
+  }
+
+  function envelope(kind, fingerprint) {
+    return {
+      kind,
+      fingerprint,
+      build: BUILD_FINGERPRINT,
+      version: pkg.version,
+      node: process.version,
+      os: `${os.platform()} ${os.release()}`,
+      timestamp: new Date().toISOString(),
+    };
+  }
+
+  // Channel 0 — crash: a tool handler threw an unexpected error.
+  function report(err, context = {}) {
+    try {
+      if (!enabled) return;
+      if (!shouldReport(err)) return;
+      const fp = fingerprint(err);
+      if (seen.has(fp)) return;
+      seen.add(fp);
+
+      const payload = {
+        ...envelope("crash", fp),
+        tool: context.tool ?? null,
+        errorName: err.name ?? "Error",
+        message: redact(err.message ?? ""),
+        stack: redact(err.stack ?? ""),
+      };
+      if (includeArgs && context.args !== undefined) {
+        payload.args = redact(safeStringify(context.args));
+      }
+      return send(payload, "sap-adt-mcp");
+    } catch {
+      // A reporter that crashes the tool would be worse than no reporter.
+    }
+  }
+
+  // Channel 1 — adt-error: a handler RETURNED a non-2xx ADT result that the
+  // classifier judges a likely tool defect (content negotiation, malformed
+  // request, server dispatcher blow-up).
+  function reportAdtError(meta = {}) {
+    try {
+      if (!enabled || !adtErrors) return;
+      if (!shouldReportAdt(meta)) return;
+      const fp = adtFingerprint(meta);
+      if (seen.has(fp)) return;
+      seen.add(fp);
+
+      const payload = {
+        ...envelope("adt-error", fp),
+        tool: meta.tool ?? null,
+        status: meta.status ?? null,
+        errorType: meta.type ?? null,
+        namespace: meta.namespace ?? null,
+        t100: meta.t100 ?? null,
+        message: redact(meta.message ?? ""),
+      };
+      if (includeArgs && meta.args !== undefined) {
+        payload.args = redact(safeStringify(meta.args));
+      }
+      return send(payload, "sap-adt-mcp");
+    } catch {
+      // best-effort
+    }
+  }
+
+  // Channel 2 — manual: the calling agent files a defect the classifier can't
+  // see (wrong data in a 200, ignored parameter, missing capability). Returns a
+  // small status object to the tool so the agent gets feedback.
+  function reportManual(input = {}) {
+    try {
+      if (!enabled) return { ok: false, reason: "reporting disabled" };
+      if (!allowManual) return { ok: false, reason: "manual reporting disabled" };
+      const tool = String(input.tool ?? "").trim();
+      const summary = String(input.summary ?? "").trim();
+      if (!tool || !summary) {
+        return { ok: false, reason: "tool and summary are required" };
+      }
+      const issueKind = input.kind === "enhancement" ? "enhancement" : "bug";
+      const fp = manualFingerprint(tool, issueKind, summary);
+
+      const payload = {
+        ...envelope("manual", fp),
+        tool,
+        issueKind,
+        summary: redact(summary),
+        expected: input.expected ? redact(String(input.expected)) : undefined,
+        actual: input.actual ? redact(String(input.actual)) : undefined,
+      };
+      if (includeArgs && input.reproArgs !== undefined) {
+        payload.reproArgs = redact(safeStringify(input.reproArgs));
+      }
+      // Explicit user action — no per-process de-dup here; the relay collapses
+      // repeats onto one issue by fingerprint.
+      send(payload, "sap-adt-mcp-manual");
+      return { ok: true, fingerprint: fp, issueKind };
+    } catch {
+      return { ok: false, reason: "internal error" };
+    }
+  }
+
+  return {
+    enabled,
+    endpoint,
+    adtErrors,
+    allowManual,
+    report,
+    reportAdtError,
+    reportManual,
+  };
+}
+
+// Exposed for unit tests.
+export const _internals = {
+  shouldReport,
+  shouldReportAdt,
+  fingerprint,
+  adtFingerprint,
+  manualFingerprint,
+  collectSecrets,
+  makeRedactor,
+};

package/src/result.js

@@ -10,7 +10,7 @@ export function jsonResult(value, isError = false) {
 
 export function errorResult(system, status, body, contentType, extra = {}) {
   const parsed = parseAdtError(body, contentType);
-  return jsonResult(
+  const result = jsonResult(
     {
       system,
       status,
@@ -20,4 +20,20 @@ export function errorResult(system, status, body, contentType, extra = {}) {
     },
     true
   );
+  // Attach structured metadata for the crash-report wrapper to classify against,
+  // without changing the content the client sees. Non-enumerable so it never
+  // serializes into the MCP result.
+  Object.defineProperty(result, "_adtError", {
+    value: {
+      system,
+      status,
+      type: parsed?.type,
+      namespace: parsed?.namespace,
+      t100: parsed?.properties?.t100,
+      message: parsed?.message ?? parsed?.localizedMessage,
+      stage: extra.stage,
+    },
+    enumerable: false,
+  });
+  return result;
 }

package/src/server.js

@@ -14,6 +14,7 @@ import { loadConfig } from "./config.js";
 import { AdtClient, ReadOnlyViolationError } from "./adt-client.js";
 import { listPrompts, getPrompt } from "./prompts.js";
 import { textResult } from "./result.js";
+import { createReporter } from "./reporter.js";
 
 import * as connectionTools from "./tools/connection.js";
 import * as sourceTools from "./tools/source.js";
@@ -31,6 +32,7 @@ import * as cdsTools from "./tools/cds.js";
 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";
 
 const PKG = JSON.parse(
   readFileSync(
@@ -60,6 +62,16 @@ process.stderr.write(
   `[${PKG.name}] v${PKG.version} — loaded ${Object.keys(config.systems).length} system(s) from ${config.configPath}; default=${config.defaultSystem ?? "none"}${config.readOnly ? " (global read-only)" : ""}\n`
 );
 
+const reporter = createReporter(config, PKG);
+if (reporter.enabled) {
+  process.stderr.write(
+    `[${PKG.name}] automatic error reporting is ON. On an unexpected crash, an ` +
+      `anonymous, redacted report (no hostnames, users, passwords, or business data) ` +
+      `is sent to the maintainer to help fix bugs. Disable with ` +
+      `"reporting": { "enabled": false } in config or SAP_ADT_MCP_REPORT=0.\n`
+  );
+}
+
 const clientCache = new Map();
 
 function getClient(systemName) {
@@ -80,7 +92,7 @@ function getClient(systemName) {
   return { name, client: clientCache.get(name), profile };
 }
 
-const ctx = { getClient, config };
+const ctx = { getClient, config, reporter };
 
 const TOOL_MODULES = [
   connectionTools,
@@ -99,6 +111,7 @@ const TOOL_MODULES = [
   worklistTools,
   jobTools,
   rapTools,
+  reportTools,
 ];
 
 const tools = [];
@@ -136,7 +149,14 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   const handler = handlers[name];
   if (!handler) return textResult(`Unknown tool: ${name}`, true);
   try {
-    return await handler(args);
+    const out = await handler(args);
+    // A handler that RETURNED a non-2xx ADT result (vs threw) carries structured
+    // metadata on _adtError — let the reporter's classifier decide if it's a
+    // likely tool defect worth auto-filing. Fire-and-forget; never throws.
+    if (out && out._adtError) {
+      reporter.reportAdtError({ tool: name, args, ...out._adtError });
+    }
+    return out;
   } catch (err) {
     if (err instanceof ReadOnlyViolationError) {
       return textResult(
@@ -144,6 +164,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         true
       );
     }
+    reporter.report(err, { tool: name, args }); // fire-and-forget; never throws
     return textResult(`Error: ${err.message}`, true);
   }
 });

package/src/tools/quality.js

@@ -1,4 +1,4 @@
-import { objectUri } from "../object-uris.js";
+import { objectUri, sourceUri, normalizeType } from "../object-uris.js";
 import { escapeXml } from "../xml.js";
 import { parseObjectReferences } from "../object-references.js";
 import { errorResult, jsonResult } from "../result.js";
@@ -131,10 +131,34 @@ async function runAtcWorklist(client, sys, { uris, checkVariant, maxResults }) {
   };
 }
 
+// Normalize a caller-supplied include context into an ADT object URI. Accepts a
+// full ADT path as-is; treats a bare token as a program name.
+export function toContextUri(input) {
+  const s = String(input).trim();
+  if (s.startsWith("/")) return s;
+  return `/sap/bc/adt/programs/programs/${encodeURIComponent(s.toLowerCase())}`;
+}
+
+// Best-effort: resolve an include's first main program via its /mainprograms
+// sub-resource. Any failure (older release, no main program, 4xx) returns
+// undefined so the check still runs (and the response carries a hint).
+async function deriveMainProgram(client, includeObjUri) {
+  try {
+    const res = await client.request({ path: `${includeObjUri}/mainprograms` });
+    if (!res.ok) return undefined;
+    const text = await res.text();
+    const m = text.match(/adtcore:uri="([^"]+)"/i);
+    return m ? m[1].replace(/&/g, "&") : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export const tools = [
   {
     name: "adt_syntax_check",
-    description: "Run an ADT syntax check on an object. Returns the raw <chkrun:reports> XML.",
+    description:
+      "Run an ADT syntax check on an object. Returns the raw <chkrun:reports> XML. Includes only compile in the context of a main program: for type=include, pass `context` (the main program / function group), otherwise the check returns status='notProcessed'. When omitted for an include, the tool tries to auto-resolve the include's first main program.",
     inputSchema: {
       type: "object",
       properties: {
@@ -142,6 +166,11 @@ export const tools = [
         object: { type: "string", description: "Object name." },
         type: { type: "string", description: OBJECT_TYPE_HINT },
         group: { type: "string", description: "Function group (for FUGR/FF or FUGR/I)." },
+        context: {
+          type: "string",
+          description:
+            "Main-program context for checking an include. Either a full ADT object URI (e.g. '/sap/bc/adt/functions/groups/v61a' or '/sap/bc/adt/programs/programs/zmain') or a bare program name. Only used for includes; auto-resolved from the include's main programs when omitted.",
+        },
       },
       required: ["object", "type"],
     },
@@ -258,15 +287,35 @@ export function register({ getClient }) {
   return {
     adt_syntax_check: async (args) => {
       const { client, name: sys } = getClient(args.system);
-      const objUri = objectUri({
+      const t = normalizeType(args.type);
+      const isInclude = t === "INCL" || t === "FUGR/I";
+
+      let checkUri = objectUri({
         type: args.type,
         name: args.object,
         group: args.group,
       });
+      let contextUri;
+      if (isInclude) {
+        contextUri = args.context
+          ? toContextUri(args.context)
+          : await deriveMainProgram(client, checkUri);
+        // Includes are checked through their source URI with the main program
+        // attached as ?context= (the form ADT itself uses in include links).
+        const incSource = sourceUri({
+          type: args.type,
+          name: args.object,
+          group: args.group,
+        });
+        checkUri = contextUri
+          ? `${incSource}?context=${encodeURIComponent(contextUri)}`
+          : incSource;
+      }
+
       const body =
         `<?xml version="1.0" encoding="UTF-8"?>` +
         `<chkrun:checkObjectList xmlns:chkrun="http://www.sap.com/adt/checkrun" xmlns:adtcore="http://www.sap.com/adt/core">` +
-        `<chkrun:checkObject adtcore:uri="${escapeXml(objUri)}"/>` +
+        `<chkrun:checkObject adtcore:uri="${escapeXml(checkUri)}"/>` +
         `</chkrun:checkObjectList>`;
       const res = await client.request({
         method: "POST",
@@ -277,7 +326,20 @@ export function register({ getClient }) {
       });
       const text = await res.text();
       if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
-      return jsonResult({ system: sys, object: args.object, result: text });
+      const notProcessed = /chkrun:status="notProcessed"/i.test(text);
+      return jsonResult({
+        system: sys,
+        object: args.object,
+        context: contextUri,
+        result: text,
+        ...(isInclude && notProcessed
+          ? {
+              hint:
+                "Include not processed — no main-program context resolved. Pass `context` " +
+                "(the main program / function group ADT URI, e.g. '/sap/bc/adt/programs/programs/zmain').",
+            }
+          : {}),
+      });
     },
 
     adt_run_unit_tests: async (args) => {

package/src/tools/report.js

@@ -0,0 +1,72 @@
+import { jsonResult } from "../result.js";
+
+export const tools = [
+  {
+    name: "adt_report_issue",
+    description:
+      "File a bug or enhancement about a sap-adt-mcp TOOL back to the maintainer. The report is redacted (hosts, users, passwords, IPs, emails stripped), de-duplicated, and becomes a GitHub issue. Use this for defects the automatic crash reporter cannot see: wrong data in an otherwise-successful response, a parameter that is silently ignored, or a missing capability. Do NOT use it for problems in the user's ABAP code or SAP system — only for defects in this MCP server's own tools.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        tool: {
+          type: "string",
+          description:
+            "The sap-adt-mcp tool the issue is about, e.g. 'adt_read_table'.",
+        },
+        kind: {
+          type: "string",
+          enum: ["bug", "enhancement"],
+          description:
+            "bug = a tool produces wrong/missing output; enhancement = a missing capability. Default bug.",
+        },
+        summary: {
+          type: "string",
+          description:
+            "One-line summary of the defect. Used in the issue title and the de-duplication key.",
+        },
+        expected: { type: "string", description: "What you expected to happen." },
+        actual: { type: "string", description: "What actually happened." },
+        reproArgs: {
+          type: "object",
+          description:
+            "Optional tool arguments that reproduce the issue. Redacted like every report (hosts/users/secrets stripped); suppressed entirely when reporting.includeArgs is off.",
+        },
+      },
+      required: ["tool", "summary"],
+    },
+  },
+];
+
+export function register({ reporter }) {
+  return {
+    adt_report_issue: async (args) => {
+      if (!reporter) {
+        return jsonResult({ ok: false, reason: "reporter unavailable" });
+      }
+      const r = reporter.reportManual({
+        tool: args.tool,
+        kind: args.kind,
+        summary: args.summary,
+        expected: args.expected,
+        actual: args.actual,
+        reproArgs: args.reproArgs,
+      });
+      if (!r || !r.ok) {
+        return jsonResult({
+          ok: false,
+          reason: r?.reason ?? "not submitted",
+          hint:
+            "Reporting may be disabled (reporting.enabled / reporting.allowManual in config, or SAP_ADT_MCP_REPORT=0).",
+        });
+      }
+      return jsonResult({
+        ok: true,
+        submitted: true,
+        kind: r.issueKind,
+        fingerprint: r.fingerprint,
+        note:
+          "Submitted to the maintainer's relay; it will appear as a de-duplicated GitHub issue.",
+      });
+    },
+  };
+}

package/src/tools/runtime.js

@@ -3,6 +3,7 @@ import {
   parseDumpFeed,
   parseDumpMetadata,
   parseDumpChapters,
+  filterDumpsByUser,
   CRITICAL_CHAPTER_KEYS,
 } from "../dump-feed.js";
 import { SYSTEM_HINT } from "./_shared.js";
@@ -22,7 +23,8 @@ export const tools = [
         system: { type: "string", description: SYSTEM_HINT },
         user: {
           type: "string",
-          description: "Filter by the user who triggered the dump.",
+          description:
+            "Filter by the user who triggered the dump (case-insensitive). Enforced client-side — several on-prem releases ignore the server-side user filter.",
         },
         host: {
           type: "string",
@@ -140,12 +142,16 @@ export function register({ getClient }) {
         });
       }
       // Server-side cap is unreliable; some on-prem releases return every
-      // available entry regardless of maxResults. Trim client-side. Strip
-      // the per-entry summary too — on real systems it's a 10+KB HTML chunk
-      // (chapter index + back-link) that bloats list responses past the
-      // tool-output token limit. Agents that need detail call adt_get_dump.
+      // available entry regardless of maxResults. The `user` feed filter is
+      // likewise ignored on several releases, so enforce it client-side before
+      // trimming. Strip the per-entry summary too — on real systems it's a
+      // 10+KB HTML chunk (chapter index + back-link) that bloats list responses
+      // past the tool-output token limit. Agents that need detail call
+      // adt_get_dump.
       const total = entries.length;
-      const trimmed = entries.slice(0, max).map((e) => {
+      const filtered = filterDumpsByUser(entries, args.user);
+      const matched = filtered.length;
+      const trimmed = filtered.slice(0, max).map((e) => {
         // eslint-disable-next-line no-unused-vars
         const { summary, ...rest } = e;
         return rest;
@@ -154,7 +160,8 @@ export function register({ getClient }) {
         system: sys,
         count: trimmed.length,
         totalReturnedByServer: total,
-        truncated: total > trimmed.length,
+        matchedFilter: args.user ? matched : undefined,
+        truncated: matched > trimmed.length,
         dumps: trimmed,
         raw: trimmed.length === 0 ? text.slice(0, 4000) : undefined,
       });

package/src/tools/source.js

@@ -1,4 +1,4 @@
-import { sourceUri, objectUri, normalizeType } from "../object-uris.js";
+import { sourceUri, objectUri, normalizeType, METADATA_XML_ACCEPT } from "../object-uris.js";
 import { acquireLock, releaseLock } from "../lock.js";
 import { errorResult, jsonResult } from "../result.js";
 import { OBJECT_TYPE_HINT, SYSTEM_HINT } from "./_shared.js";
@@ -120,7 +120,7 @@ export const tools = [
   {
     name: "adt_get_source",
     description:
-      "Fetch the ABAP source of an object (program, class, interface, function module, include, CDS, table). Returns plain text. For sources larger than the MCP per-call output cap (~64 KB), use firstLine/lastLine to paginate or onlyMethod to slice a single method body.",
+      "Fetch the ABAP source of an object (program, class, interface, function module, include, CDS, table). Returns plain text. DDIC primitives without plain-text source (data element, domain, message class) return their ADT XML metadata instead (format: 'xml'). For sources larger than the MCP per-call output cap (~64 KB), use firstLine/lastLine to paginate or onlyMethod to slice a single method body.",
     inputSchema: {
       type: "object",
       properties: {
@@ -273,12 +273,35 @@ export function register({ getClient }) {
   return {
     adt_get_source: async (args) => {
       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,
       });
+
+      // DDIC primitives (data element / domain / message class) have no
+      // plain-text source — fetch their XML metadata with the right media type
+      // (text/plain would 406) and return it as-is.
+      const metaAccept = METADATA_XML_ACCEPT[t];
+      if (metaAccept) {
+        const res = await client.request({ path, accept: metaAccept });
+        const text = await res.text();
+        if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+        return jsonResult({
+          system: sys,
+          object: args.object,
+          type: t,
+          path,
+          format: "xml",
+          source: text,
+          bytes: text.length,
+          totalLines: text.split(/\r?\n/).length,
+          note: `${t} has no plain-text source; returning ADT XML metadata (${metaAccept.split("+")[0]}+xml).`,
+        });
+      }
+
       const res = await client.request({ path, accept: "text/plain" });
       const text = await res.text();
       if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));