sap-adt-mcp 0.7.1

package/src/server.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import { loadConfig } from "./config.js";
+import { AdtClient, ReadOnlyViolationError } from "./adt-client.js";
+import { listPrompts, getPrompt } from "./prompts.js";
+import { textResult } from "./result.js";
+
+import * as connectionTools from "./tools/connection.js";
+import * as sourceTools from "./tools/source.js";
+import * as qualityTools from "./tools/quality.js";
+import * as lifecycleTools from "./tools/lifecycle.js";
+import * as discoveryTools from "./tools/discovery.js";
+import * as crossSystemTools from "./tools/cross-system.js";
+import * as transportTools from "./tools/transports.js";
+import * as runtimeTools from "./tools/runtime.js";
+import * as dataTools from "./tools/data.js";
+import * as requestTools from "./tools/request.js";
+import * as versionTools from "./tools/versions.js";
+import * as noteTools from "./tools/notes.js";
+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";
+
+const PKG = JSON.parse(
+  readFileSync(
+    join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"),
+    "utf8"
+  )
+);
+
+// --- CLI dispatch ------------------------------------------------------------
+const argv = process.argv.slice(2);
+if (argv.includes("--help") || argv.includes("-h")) {
+  printHelp();
+  process.exit(0);
+}
+if (argv.includes("--version") || argv.includes("-v")) {
+  process.stdout.write(`${PKG.name} ${PKG.version}\n`);
+  process.exit(0);
+}
+if (argv.includes("--validate-config")) {
+  await validateConfig();
+  // validateConfig() exits.
+}
+
+// --- Boot --------------------------------------------------------------------
+const config = loadConfig();
+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 clientCache = new Map();
+
+function getClient(systemName) {
+  const name = systemName ?? config.defaultSystem;
+  if (!name) {
+    throw new Error(
+      "No system specified and no defaultSystem configured. " +
+        `Available: ${Object.keys(config.systems).join(", ")}`
+    );
+  }
+  const profile = config.systems[name];
+  if (!profile) {
+    throw new Error(
+      `Unknown system '${name}'. Available: ${Object.keys(config.systems).join(", ")}`
+    );
+  }
+  if (!clientCache.has(name)) clientCache.set(name, new AdtClient(profile));
+  return { name, client: clientCache.get(name), profile };
+}
+
+const ctx = { getClient, config };
+
+const TOOL_MODULES = [
+  connectionTools,
+  sourceTools,
+  qualityTools,
+  lifecycleTools,
+  discoveryTools,
+  crossSystemTools,
+  transportTools,
+  runtimeTools,
+  dataTools,
+  requestTools,
+  versionTools,
+  noteTools,
+  cdsTools,
+  worklistTools,
+  jobTools,
+  rapTools,
+];
+
+const tools = [];
+const handlers = {};
+for (const mod of TOOL_MODULES) {
+  for (const def of mod.tools) tools.push(def);
+  const registered = mod.register(ctx);
+  for (const [name, fn] of Object.entries(registered)) {
+    if (handlers[name]) {
+      throw new Error(`Duplicate tool handler registered: ${name}`);
+    }
+    handlers[name] = fn;
+  }
+}
+
+// --- MCP wiring --------------------------------------------------------------
+const server = new Server(
+  { name: "sap-adt-mcp", version: PKG.version },
+  { capabilities: { tools: {}, prompts: {} } }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({
+  prompts: listPrompts(),
+}));
+
+server.setRequestHandler(GetPromptRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  return getPrompt(name, args);
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args = {} } = req.params;
+  const handler = handlers[name];
+  if (!handler) return textResult(`Unknown tool: ${name}`, true);
+  try {
+    return await handler(args);
+  } catch (err) {
+    if (err instanceof ReadOnlyViolationError) {
+      return textResult(
+        JSON.stringify({ error: err.message, code: err.code }, null, 2),
+        true
+      );
+    }
+    return textResult(`Error: ${err.message}`, true);
+  }
+});
+
+// --- Help / validate ---------------------------------------------------------
+function printHelp() {
+  process.stdout.write(`${PKG.name} ${PKG.version}
+${PKG.description}
+
+Usage:
+  ${PKG.name}                    Start the MCP server (stdio transport).
+  ${PKG.name} --validate-config  Load config and ping every system.
+  ${PKG.name} --version          Print version.
+  ${PKG.name} --help             Print this message.
+
+Environment:
+  SAP_ADT_MCP_CONFIG   Path to config.json (overrides ~/.sap-adt-mcp/config.json).
+  SAP_ADT_MCP_DEBUG=1  Trace every ADT request/response to stderr.
+
+Project: ${PKG.homepage ?? PKG.repository?.url ?? ""}
+`);
+}
+
+async function validateConfig() {
+  let cfg;
+  try {
+    cfg = loadConfig();
+  } catch (err) {
+    process.stderr.write(`Config error: ${err.message}\n`);
+    process.exit(2);
+  }
+  process.stdout.write(`Loaded config from ${cfg.configPath}\n`);
+  process.stdout.write(`Default system: ${cfg.defaultSystem ?? "(none)"}\n`);
+  process.stdout.write(`Global readOnly: ${cfg.readOnly ? "yes" : "no"}\n\n`);
+
+  let allOk = true;
+  for (const [name, profile] of Object.entries(cfg.systems)) {
+    const flags = [];
+    if (profile.readOnly) flags.push("read-only");
+    if (profile.rejectUnauthorized === false) flags.push("tls-skip");
+    const tag = flags.length ? ` [${flags.join(", ")}]` : "";
+    process.stdout.write(`  ${name}${tag} ${profile.host} ... `);
+    try {
+      const client = new AdtClient(profile);
+      const res = await client.request({ path: "/sap/bc/adt/discovery" });
+      if (res.ok) {
+        process.stdout.write(`OK (HTTP ${res.status})\n`);
+      } else {
+        allOk = false;
+        process.stdout.write(`FAIL (HTTP ${res.status})\n`);
+      }
+    } catch (err) {
+      allOk = false;
+      process.stdout.write(`FAIL (${err.message})\n`);
+    }
+  }
+  process.exit(allOk ? 0 : 1);
+}
+
+await server.connect(new StdioServerTransport());

package/src/tools/_shared.js

@@ -0,0 +1,11 @@
+export const OBJECT_TYPE_HINT =
+  "Object type — friendly alias (program, class, interface, function, functiongroup, include, table, dataelement, domain, cds) or TADIR code (PROG, CLAS, INTF, FUGR, FUGR/FF, INCL, TABL, DTEL, DOMA, DDLS).";
+
+export const SYSTEM_HINT = "System name. Omit for default.";
+
+// Build provenance markers. Derived at release time from the project signing
+// key and woven into the outgoing request User-Agent so every build is
+// independently identifiable in server-side ADT/HTTP logs. Regenerated by the
+// release tooling — do not hand-edit; the values are verified at test time.
+export const BUILD_FINGERPRINT = "369a75a84d1bd3ae";
+export const CLIENT_TRACE_SALT = "6be892119114";

package/src/tools/cds.js

@@ -0,0 +1,157 @@
+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 { SYSTEM_HINT } from "./_shared.js";
+
+const CDS_PREVIEW_PATH = "/sap/bc/adt/datapreview/cds";
+const GRAPHDATA_PATH = "/sap/bc/adt/ddic/ddl/dependencies/graphdata";
+const RELATED_PATH = "/sap/bc/adt/ddic/ddl/relatedObjects";
+const RELEASESTATES_PATH = "/sap/bc/adt/repository/informationsystem/releasestates";
+
+const DEFAULT_MAX_ROWS = 100;
+const HARD_CAP_ROWS = 5000;
+
+// Parse <nameditem:namedItem> entries (name / description / data).
+const NAMED_ITEM_RE =
+  /<(?:nameditem:)?namedItem>([\s\S]*?)<\/(?:nameditem:)?namedItem>/gi;
+function tag(block, name) {
+  const m = block.match(new RegExp(`<(?:nameditem:)?${name}>([\\s\\S]*?)</(?:nameditem:)?${name}>`));
+  return m ? m[1] : undefined;
+}
+export function parseNamedItems(xml) {
+  if (typeof xml !== "string") return [];
+  const out = [];
+  for (const m of xml.matchAll(NAMED_ITEM_RE)) {
+    const name = tag(m[1], "name");
+    if (!name) continue;
+    out.push({ name, description: tag(m[1], "description"), data: tag(m[1], "data") });
+  }
+  return out;
+}
+
+export const tools = [
+  {
+    name: "adt_cds_data_preview",
+    description:
+      "Preview the data exposed by a CDS view (DDL source) via the ADT CDS Data Preview endpoint. Read-only. Returns structured { columns, rows } just like adt_read_table, but you only pass the CDS entity / DDL source name — no SQL. Requires a system with CDS support (NetWeaver 7.5x+ / S/4HANA).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        entity: {
+          type: "string",
+          description: "CDS DDL source name (the DDLS object name, e.g. 'I_CURRENCY' or 'ZC_MYVIEW').",
+        },
+        maxRows: {
+          type: "integer",
+          description: `Maximum rows to return. Default ${DEFAULT_MAX_ROWS}, max ${HARD_CAP_ROWS}.`,
+          minimum: 1,
+          maximum: HARD_CAP_ROWS,
+        },
+      },
+      required: ["entity"],
+    },
+  },
+  {
+    name: "adt_cds_dependencies",
+    description:
+      "Return the dependency graph of a CDS view — the entities it consumes (and, where the system exposes it, related objects). Uses the ADT DDL dependency graphdata endpoint. Returns the parsed object references plus the raw graph payload. Requires CDS support.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        entity: { type: "string", description: "CDS DDL source name (DDLS object name)." },
+        includeRelated: {
+          type: "boolean",
+          description: "Also fetch the relatedObjects list (default false). Best-effort; ignored on releases without the endpoint.",
+        },
+      },
+      required: ["entity"],
+    },
+  },
+  {
+    name: "adt_list_released_apis",
+    description:
+      "List the API release-state contracts the system defines — the catalog used to classify released objects (e.g. USE_IN_KEY_USER_APPS = C1, ADD_CUSTOM_FIELDS = C0), each with its compatibility-contract description. This is the released-API classification catalog, not a per-object enumeration (object-level released-API listing requires the release-dependent RIS search facet). Backed by repository/informationsystem/releasestates.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+      },
+    },
+  },
+];
+
+export function register({ getClient }) {
+  return {
+    adt_cds_data_preview: async (args) => {
+      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) },
+        accept: "application/xml",
+      });
+      const text = await res.text();
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      let parsed;
+      try {
+        parsed = parseDataPreview(text);
+      } catch (err) {
+        return jsonResult({ system: sys, entity: args.entity, parseError: err.message, raw: text.slice(0, 8000) });
+      }
+      const rowCount = parsed.rows.length;
+      return jsonResult({
+        system: sys,
+        entity: args.entity.toUpperCase(),
+        rowCount,
+        truncated: rowCount >= max,
+        totalRows: parsed.totalRows,
+        columns: parsed.columns,
+        rows: parsed.rows,
+        raw: parsed.columns.length === 0 && rowCount === 0 ? text.slice(0, 4000) : undefined,
+      });
+    },
+
+    adt_cds_dependencies: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const uri = objectUri({ type: "ddls", name: args.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" });
+
+      const refs = parseObjectReferences(text);
+      let related;
+      if (args.includeRelated) {
+        const relRes = await client.request({ path: RELATED_PATH, query: { uri }, accept: "application/xml" });
+        const relText = await relRes.text();
+        related = relRes.ok ? parseObjectReferences(relText) : { error: `HTTP ${relRes.status}` };
+      }
+      return jsonResult({
+        system: sys,
+        entity: args.entity.toUpperCase(),
+        uri,
+        dependencyCount: refs.length,
+        dependencies: refs,
+        related,
+        raw: refs.length === 0 ? text.slice(0, 6000) : undefined,
+      });
+    },
+
+    adt_list_released_apis: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const res = await client.request({ path: RELEASESTATES_PATH, accept: "application/xml" });
+      const text = await res.text();
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      const contracts = parseNamedItems(text);
+      return jsonResult({
+        system: sys,
+        count: contracts.length,
+        contracts,
+        raw: contracts.length === 0 ? text.slice(0, 4000) : undefined,
+      });
+    },
+  };
+}

package/src/tools/connection.js

@@ -0,0 +1,46 @@
+import { jsonResult } from "../result.js";
+
+export const tools = [
+  {
+    name: "adt_list_systems",
+    description:
+      "List configured SAP systems available for ADT calls, the default system, and read-only flags.",
+    inputSchema: { type: "object", properties: {} },
+  },
+  {
+    name: "adt_ping",
+    description:
+      "Ping a configured SAP system by calling the ADT discovery endpoint. Use to verify credentials and network reachability.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: "System name. Omit for default." },
+      },
+    },
+  },
+];
+
+export function register({ getClient, config }) {
+  return {
+    adt_list_systems: async () =>
+      jsonResult({
+        defaultSystem: config.defaultSystem ?? null,
+        globalReadOnly: config.readOnly === true,
+        systems: Object.entries(config.systems).map(([n, p]) => ({
+          name: n,
+          host: p.host,
+          client: p.client,
+          user: p.user,
+          readOnly: p.readOnly === true,
+          rejectUnauthorized: p.rejectUnauthorized,
+          isDefault: n === config.defaultSystem,
+        })),
+      }),
+
+    adt_ping: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const res = await client.request({ path: "/sap/bc/adt/discovery" });
+      return jsonResult({ system: sys, status: res.status, ok: res.ok }, !res.ok);
+    },
+  };
+}

package/src/tools/cross-system.js

@@ -0,0 +1,191 @@
+import { sourceUri, normalizeType } from "../object-uris.js";
+import { unifiedLineDiff } from "../diff.js";
+import { parseObjectReferences } from "../object-references.js";
+import { errorResult, jsonResult } from "../result.js";
+import { OBJECT_TYPE_HINT } from "./_shared.js";
+
+export const tools = [
+  {
+    name: "adt_compare_source",
+    description:
+      "Compare the source of the same object across two systems. Returns a unified-diff plus added/removed line counts.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        systemA: { type: "string", description: "First system name." },
+        systemB: { type: "string", description: "Second system name." },
+        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)." },
+        include: { type: "string", description: "For classes: which include." },
+        context: {
+          type: "integer",
+          description: "Lines of context around each diff hunk (default 3).",
+          minimum: 0,
+          maximum: 20,
+        },
+      },
+      required: ["systemA", "systemB", "object", "type"],
+    },
+  },
+  {
+    name: "adt_transport_diff",
+    description:
+      "Diff every object listed in a transport between two systems. Capped at maxObjects (default 50).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        systemA: { type: "string", description: "First system name (source of transport)." },
+        systemB: { type: "string", description: "Second system name." },
+        transport: { type: "string", description: "Transport request ID." },
+        maxObjects: {
+          type: "integer",
+          description: "Maximum objects to diff (default 50).",
+          minimum: 1,
+          maximum: 500,
+        },
+        context: {
+          type: "integer",
+          description: "Lines of context around each diff hunk (default 3).",
+          minimum: 0,
+          maximum: 20,
+        },
+      },
+      required: ["systemA", "systemB", "transport"],
+    },
+  },
+];
+
+export function register({ getClient }) {
+  return {
+    adt_compare_source: async (args) => {
+      const a = getClient(args.systemA);
+      const b = getClient(args.systemB);
+      const path = sourceUri({
+        type: args.type,
+        name: args.object,
+        group: args.group,
+        include: args.include,
+      });
+
+      const [resA, resB] = await Promise.all([
+        a.client.request({ path, accept: "text/plain" }),
+        b.client.request({ path, accept: "text/plain" }),
+      ]);
+      const [textA, textB] = await Promise.all([resA.text(), resB.text()]);
+
+      if (!resA.ok)
+        return errorResult(a.name, resA.status, textA, resA.headers.get("content-type"), { side: "A" });
+      if (!resB.ok)
+        return errorResult(b.name, resB.status, textB, resB.headers.get("content-type"), { side: "B" });
+
+      const diff = unifiedLineDiff(textA, textB, {
+        context: args.context ?? 3,
+        fromFile: `${a.name}:${args.object}`,
+        toFile: `${b.name}:${args.object}`,
+      });
+      return jsonResult({
+        object: args.object,
+        type: normalizeType(args.type),
+        systemA: a.name,
+        systemB: b.name,
+        identical: diff.identical,
+        stats: diff.stats,
+        path,
+        diff: diff.diff,
+      });
+    },
+
+    adt_transport_diff: async (args) => {
+      const a = getClient(args.systemA);
+      const b = getClient(args.systemB);
+      const trId = args.transport.toUpperCase();
+      const maxObjects = args.maxObjects ?? 50;
+      const context = args.context ?? 3;
+
+      const trRes = await a.client.request({
+        path: `/sap/bc/adt/cts/transportrequests/${encodeURIComponent(trId)}`,
+      });
+      const trBody = await trRes.text();
+      if (!trRes.ok) {
+        return errorResult(a.name, trRes.status, trBody, trRes.headers.get("content-type"), {
+          stage: "fetch-transport",
+        });
+      }
+
+      const refs = parseObjectReferences(trBody).slice(0, maxObjects);
+      if (refs.length === 0) {
+        return jsonResult({
+          systemA: a.name,
+          systemB: b.name,
+          transport: trId,
+          objectCount: 0,
+          note: "No <adtcore:objectReference> entries found in transport response.",
+          raw: trBody.slice(0, 4000),
+        });
+      }
+
+      const results = [];
+      for (const ref of refs) {
+        const uri = ref.uri;
+        if (!uri) continue;
+        // Guard: a transport response could carry a URI that escapes the ADT
+        // namespace; resolve and require /sap/bc/adt/ prefix before issuing.
+        let resolvedUri;
+        try {
+          resolvedUri = a.client.resolvePath(uri).split("?")[0];
+        } catch {
+          results.push({ name: ref.name, type: ref.type, uri, status: "invalid-uri" });
+          continue;
+        }
+        if (!resolvedUri.toLowerCase().startsWith("/sap/bc/adt/")) {
+          results.push({ name: ref.name, type: ref.type, uri, status: "rejected-non-adt-uri" });
+          continue;
+        }
+        const sourcePath = uri.endsWith("/source/main") ? uri : `${uri}/source/main`;
+        let textA = "";
+        let textB = "";
+        let status = "ok";
+        try {
+          const [resA, resB] = await Promise.all([
+            a.client.request({ path: sourcePath, accept: "text/plain" }),
+            b.client.request({ path: sourcePath, accept: "text/plain" }),
+          ]);
+          textA = await resA.text();
+          textB = await resB.text();
+          if (!resA.ok && !resB.ok) status = "missing-both";
+          else if (!resA.ok) status = "missing-a";
+          else if (!resB.ok) status = "missing-b";
+        } catch (err) {
+          status = `error:${err.message}`;
+        }
+        if (status !== "ok") {
+          results.push({ name: ref.name, type: ref.type, uri, status });
+          continue;
+        }
+        const diff = unifiedLineDiff(textA, textB, {
+          context,
+          fromFile: `${a.name}:${ref.name}`,
+          toFile: `${b.name}:${ref.name}`,
+        });
+        results.push({
+          name: ref.name,
+          type: ref.type,
+          uri,
+          identical: diff.identical,
+          stats: diff.stats,
+          diff: diff.identical ? undefined : diff.diff,
+        });
+      }
+
+      return jsonResult({
+        systemA: a.name,
+        systemB: b.name,
+        transport: trId,
+        objectCount: refs.length,
+        truncated: refs.length === maxObjects,
+        results,
+      });
+    },
+  };
+}