sap-adt-mcp 0.7.1

package/src/tools/jobs.js

@@ -0,0 +1,107 @@
+import { escapeXml } from "../xml.js";
+import { errorResult, jsonResult, textResult } from "../result.js";
+import { SYSTEM_HINT } from "./_shared.js";
+
+// Background-job (SM36/SM37) and spool (SP01) integration over ADT.
+//
+// IMPORTANT: standard ABAP systems do NOT expose background-job scheduling or
+// spool reading through ADT REST — there is no registered ADT collection for
+// either (verified against on-prem NetWeaver). These tools attempt a plausible
+// endpoint and degrade gracefully (available:false + hint) so an agent can fall
+// back to SM36/SM37/SP01. Treat them as experimental; positive paths are
+// unverified and depend on a custom/extension ADT service being installed.
+
+const JOBS_PATH = "/sap/bc/adt/scheduling/jobs";
+const SPOOL_PATH = "/sap/bc/adt/scheduling/spools";
+
+function isResourceNotFound(status, body) {
+  return status === 404 || (typeof body === "string" && /ExceptionResourceNotFound/.test(body));
+}
+
+function unavailable(sys, feature, status, body) {
+  return jsonResult({
+    system: sys,
+    available: false,
+    hint:
+      `${feature} is not exposed via ADT REST on this system. ` +
+      "Use SM36/SM37 (jobs) or SP01 (spool) in the SAP GUI. " +
+      "No standardized ADT background-processing API exists on classic NetWeaver.",
+    status,
+    raw: typeof body === "string" ? body.slice(0, 400) : undefined,
+  });
+}
+
+export const tools = [
+  {
+    name: "adt_schedule_job",
+    description:
+      "Schedule an ABAP background job (SM36 analog) that runs a report with a variant. WRITE operation — subject to read-only mode. EXPERIMENTAL: no standardized ADT job-scheduling API exists on classic NetWeaver; on systems without an extension service the response carries available:false. Prefer SM36 for anything important.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        jobName: { type: "string", description: "Background job name." },
+        program: { type: "string", description: "ABAP report/program to run." },
+        variant: { type: "string", description: "Optional report variant." },
+        startImmediately: {
+          type: "boolean",
+          description: "Start as soon as a work process is free (default true).",
+        },
+      },
+      required: ["jobName", "program"],
+    },
+  },
+  {
+    name: "adt_read_spool",
+    description:
+      "Read the output (spool list) of a background job / spool request (SP01 analog). EXPERIMENTAL — see adt_schedule_job for availability constraints; returns available:false on systems without an ADT spool service.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        spoolId: { type: "string", description: "Spool request number." },
+      },
+      required: ["spoolId"],
+    },
+  },
+];
+
+export function register({ getClient }) {
+  return {
+    adt_schedule_job: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      if (!args.jobName || !args.program) {
+        return textResult("adt_schedule_job: `jobName` and `program` are required.", true);
+      }
+      const startImmediately = args.startImmediately !== false;
+      const body =
+        `<?xml version="1.0" encoding="UTF-8"?>` +
+        `<job:job xmlns:job="http://www.sap.com/adt/scheduling" job:name="${escapeXml(args.jobName)}" ` +
+        `job:program="${escapeXml(args.program)}"` +
+        (args.variant ? ` job:variant="${escapeXml(args.variant)}"` : "") +
+        ` job:startImmediately="${startImmediately}"/>`;
+      const res = await client.request({
+        method: "POST",
+        path: JOBS_PATH,
+        headers: { "Content-Type": "application/xml" },
+        body,
+      });
+      const text = await res.text();
+      if (isResourceNotFound(res.status, text)) return unavailable(sys, "Background-job scheduling", res.status, text);
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"), { stage: "schedule" });
+      return jsonResult({ system: sys, jobName: args.jobName, status: "scheduled", result: text });
+    },
+
+    adt_read_spool: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const res = await client.request({
+        path: `${SPOOL_PATH}/${encodeURIComponent(String(args.spoolId))}`,
+        accept: "text/plain",
+      });
+      const text = await res.text();
+      if (isResourceNotFound(res.status, text)) return unavailable(sys, "Spool reading", res.status, text);
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      return jsonResult({ system: sys, spoolId: args.spoolId, available: true, content: text });
+    },
+  };
+}

package/src/tools/lifecycle.js

@@ -0,0 +1,314 @@
+import { objectUri, normalizeType } from "../object-uris.js";
+import { escapeXml } from "../xml.js";
+import { acquireLock, releaseLock } from "../lock.js";
+import { buildCreateRequest } from "../object-create.js";
+import { errorResult, jsonResult, textResult } from "../result.js";
+import { OBJECT_TYPE_HINT, SYSTEM_HINT } from "./_shared.js";
+
+export const tools = [
+  {
+    name: "adt_activate",
+    description:
+      "Activate one or more ABAP objects. In multi-developer scenarios where the object's components are locked in a separate task under the same transport, set processRedoneOOSourceVersionOnly=true to ask SAP to re-activate only the redone OO source versions (bypasses the 'Object components locked in request and separate task' 403).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        objects: {
+          type: "array",
+          description: "Objects to activate.",
+          items: {
+            type: "object",
+            properties: {
+              name: { type: "string" },
+              type: { type: "string", description: OBJECT_TYPE_HINT },
+              group: { type: "string" },
+            },
+            required: ["name", "type"],
+          },
+        },
+        processRedoneOOSourceVersionOnly: {
+          type: "boolean",
+          description:
+            "Forward as isProcessRedoneOOSourceVerOnly=true on the ADT activate URL. Use to recover from CTS 'Object components locked in request and separate task' 403s.",
+        },
+        preauditRequested: {
+          type: "boolean",
+          description:
+            "Override the preauditRequested query parameter. Defaults to true.",
+        },
+      },
+      required: ["objects"],
+    },
+  },
+  {
+    name: "adt_create_object",
+    description:
+      "Create a new ABAP object in a package. Supported types: program, class, interface, include, functiongroup, function, cds, accesscontrol, metadataext, behaviordef, messageclass. Refused under read-only mode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        name: { type: "string", description: "New object name (Z*/Y* or namespace)." },
+        type: { type: "string", description: OBJECT_TYPE_HINT },
+        package: { type: "string", description: "Target package." },
+        description: { type: "string", description: "Short description." },
+        group: {
+          type: "string",
+          description: "Function group (required when creating a function module).",
+        },
+        programType: {
+          type: "string",
+          description: "Program subtype, e.g. 'executableProgram' or 'modulePool'. Default: executableProgram.",
+        },
+        responsible: {
+          type: "string",
+          description: "Responsible user. Defaults to the profile's logon user.",
+        },
+        transport: {
+          type: "string",
+          description: "Transport request ID to assign the new object to.",
+        },
+      },
+      required: ["name", "type", "package", "description"],
+    },
+  },
+  {
+    name: "adt_delete_object",
+    description: "Delete an ABAP object. Acquires a lock and issues DELETE. Refused under read-only mode.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        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)." },
+        transport: { type: "string", description: "Transport request ID (corrNr)." },
+      },
+      required: ["object", "type"],
+    },
+  },
+  {
+    name: "adt_lock",
+    description:
+      "Acquire a stateful lock on an ABAP object. Returns a lockHandle to reuse across multiple adt_set_source calls. On CTS conflicts the error includes longText and t100 details (which TR is blocking, who owns it) so the caller can recover.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        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)." },
+        accessMode: {
+          type: "string",
+          description: "Lock access mode. Default: MODIFY.",
+        },
+        transport: {
+          type: "string",
+          description:
+            "Transport request ID (sent as corrNr on the LOCK call). Use to scope the lock to a specific TR when the object is locked in another task under the same TR.",
+        },
+      },
+      required: ["object", "type"],
+    },
+  },
+  {
+    name: "adt_unlock",
+    description: "Release a stateful lock previously acquired with adt_lock.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        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)." },
+        lockHandle: { type: "string", description: "The lockHandle returned by adt_lock." },
+      },
+      required: ["object", "type", "lockHandle"],
+    },
+  },
+];
+
+export function register({ getClient }) {
+  return {
+    adt_activate: async (args) => {
+      if (!Array.isArray(args.objects) || args.objects.length === 0) {
+        return textResult(
+          "adt_activate: `objects` is required — non-empty array of { name, type[, group] }. " +
+            "Did you pass singular `objectName`/`objectType`? Wrap them: " +
+            "`objects: [{ name: '…', type: '…' }]`.",
+          true
+        );
+      }
+      for (let i = 0; i < args.objects.length; i++) {
+        const o = args.objects[i];
+        if (!o || typeof o.name !== "string" || typeof o.type !== "string") {
+          return textResult(
+            `adt_activate: objects[${i}] must be { name: string, type: string }.`,
+            true
+          );
+        }
+      }
+      const { client, name: sys } = getClient(args.system);
+      const refs = args.objects
+        .map((o) => {
+          const uri = objectUri({ type: o.type, name: o.name, group: o.group });
+          return `<adtcore:objectReference adtcore:uri="${escapeXml(uri)}" adtcore:name="${escapeXml(o.name.toUpperCase())}"/>`;
+        })
+        .join("");
+      const body =
+        `<?xml version="1.0" encoding="UTF-8"?>` +
+        `<adtcore:objectReferences xmlns:adtcore="http://www.sap.com/adt/core">${refs}</adtcore:objectReferences>`;
+      const preaudit =
+        typeof args.preauditRequested === "boolean"
+          ? args.preauditRequested
+            ? "true"
+            : "false"
+          : "true";
+      const query = { method: "activate", preauditRequested: preaudit };
+      if (args.processRedoneOOSourceVersionOnly) {
+        query.isProcessRedoneOOSourceVerOnly = "true";
+      }
+      const res = await client.request({
+        method: "POST",
+        path: "/sap/bc/adt/activation",
+        query,
+        headers: { "Content-Type": "application/xml" },
+        body,
+      });
+      const text = await res.text();
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      return jsonResult({ system: sys, status: res.status, result: text });
+    },
+
+    adt_create_object: async (args) => {
+      const { client, name: sys, profile } = getClient(args.system);
+      let req;
+      try {
+        req = buildCreateRequest({
+          type: args.type,
+          name: args.name,
+          package: args.package,
+          description: args.description,
+          group: args.group,
+          programType: args.programType,
+          responsible: args.responsible ?? profile.user,
+        });
+      } catch (err) {
+        return textResult(`Error: ${err.message}`, true);
+      }
+      const query = {};
+      if (args.transport) query.corrNr = args.transport;
+      const res = await client.request({
+        method: "POST",
+        path: req.path,
+        query,
+        headers: { "Content-Type": req.contentType },
+        body: req.body,
+      });
+      const text = await res.text();
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      const newUri = objectUri({
+        type: args.type,
+        name: args.name,
+        group: args.group,
+      });
+      return jsonResult({
+        system: sys,
+        name: args.name.toUpperCase(),
+        type: normalizeType(args.type),
+        package: args.package.toUpperCase(),
+        objectUri: newUri,
+        status: "created",
+        httpStatus: res.status,
+      });
+    },
+
+    adt_delete_object: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const objUri = objectUri({
+        type: args.type,
+        name: args.object,
+        group: args.group,
+      });
+      const lock = await acquireLock(client, objUri, { corrNr: args.transport });
+      if (!lock.ok) {
+        return errorResult(sys, lock.status, lock.body, lock.contentType, {
+          stage: "lock",
+        });
+      }
+      const query = { lockHandle: lock.handle };
+      if (args.transport) query.corrNr = args.transport;
+      const res = await client.request({
+        method: "DELETE",
+        path: objUri,
+        query,
+        headers: { "X-sap-adt-sessiontype": "stateful" },
+      });
+      const text = await res.text();
+      if (!res.ok) {
+        try {
+          await releaseLock(client, objUri, lock.handle);
+        } catch {
+          // ignore
+        }
+        return errorResult(sys, res.status, text, res.headers.get("content-type"), {
+          stage: "delete",
+        });
+      }
+      return jsonResult({
+        system: sys,
+        object: args.object,
+        type: normalizeType(args.type),
+        status: "deleted",
+        httpStatus: res.status,
+      });
+    },
+
+    adt_lock: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const objUri = objectUri({
+        type: args.type,
+        name: args.object,
+        group: args.group,
+      });
+      const lock = await acquireLock(client, objUri, {
+        accessMode: args.accessMode ?? "MODIFY",
+        corrNr: args.transport,
+      });
+      if (!lock.ok) {
+        return errorResult(sys, lock.status, lock.body, lock.contentType, {
+          stage: "lock",
+        });
+      }
+      return jsonResult({
+        system: sys,
+        object: args.object,
+        type: normalizeType(args.type),
+        objectUri: objUri,
+        lockHandle: lock.handle,
+        accessMode: args.accessMode ?? "MODIFY",
+        ...(args.transport ? { transport: args.transport } : {}),
+      });
+    },
+
+    adt_unlock: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const objUri = objectUri({
+        type: args.type,
+        name: args.object,
+        group: args.group,
+      });
+      const res = await releaseLock(client, objUri, args.lockHandle);
+      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: normalizeType(args.type),
+        status: "unlocked",
+        httpStatus: res.status,
+      });
+    },
+  };
+}

package/src/tools/notes.js

@@ -0,0 +1,147 @@
+import { errorResult, jsonResult, textResult } from "../result.js";
+import { SYSTEM_HINT } from "./_shared.js";
+
+// SAP Note (SNOTE / Note Assistant) integration over ADT.
+//
+// IMPORTANT: a stable SAP Note ADT REST API is only present on systems that ship
+// the Note Assistant ADT plug-in (modern S/4HANA). Classic NetWeaver stacks do
+// NOT expose it — every call returns ExceptionResourceNotFound. These tools
+// detect that and respond with available:false + a hint rather than a raw 404,
+// so an agent can fall back to GUI SNOTE. The endpoint shape used here
+// (/sap/bc/adt/cwb/notes/{id}) is the documented Note Assistant path; treat
+// these tools as experimental until verified against an S/4 system.
+
+const NOTES_BASE = "/sap/bc/adt/cwb/notes";
+
+function normalizeNoteId(raw) {
+  const s = String(raw).trim();
+  // SAP note numbers are numeric; ADT expects the zero-padded canonical form.
+  if (/^\d+$/.test(s)) return s.padStart(10, "0");
+  return s;
+}
+
+function isResourceNotFound(status, body) {
+  return (
+    status === 404 ||
+    (typeof body === "string" && /ExceptionResourceNotFound/.test(body))
+  );
+}
+
+function unavailable(sys, noteId, status, body) {
+  return jsonResult({
+    system: sys,
+    note: noteId,
+    available: false,
+    hint:
+      "The SAP Note ADT API (Note Assistant) is not available on this system. " +
+      "It ships with modern S/4HANA only; classic NetWeaver has no SNOTE REST endpoint. " +
+      "Use transaction SNOTE in the SAP GUI instead.",
+    status,
+    raw: typeof body === "string" ? body.slice(0, 600) : undefined,
+  });
+}
+
+export const tools = [
+  {
+    name: "adt_get_note",
+    description:
+      "Fetch SAP Note metadata (title, component, version, type, implementation prerequisites) via the Note Assistant ADT API. EXPERIMENTAL — only available on systems shipping the SNOTE ADT plug-in (modern S/4HANA). On systems without it the response carries available:false and a hint to use GUI SNOTE.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        note: { type: "string", description: "SAP Note number (e.g. '3076322'). Zero-padding is applied automatically." },
+      },
+      required: ["note"],
+    },
+  },
+  {
+    name: "adt_check_note_status",
+    description:
+      "Report the implementation status of a SAP Note in the system (e.g. can be implemented / obsolete / fully implemented / partially implemented). EXPERIMENTAL — see adt_get_note for availability constraints.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        note: { type: "string", description: "SAP Note number." },
+      },
+      required: ["note"],
+    },
+  },
+  {
+    name: "adt_implement_note",
+    description:
+      "Implement (download + apply) a SAP Note via the Note Assistant ADT API. WRITE operation — subject to read-only mode and requires a transport. EXPERIMENTAL and potentially disruptive: implementing a note changes system objects. Only available on systems shipping the SNOTE ADT plug-in. Prefer GUI SNOTE for anything non-trivial.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        system: { type: "string", description: SYSTEM_HINT },
+        note: { type: "string", description: "SAP Note number to implement." },
+        transport: { type: "string", description: "Transport request ID to record the implementation under." },
+      },
+      required: ["note"],
+    },
+  },
+];
+
+export function register({ getClient }) {
+  return {
+    adt_get_note: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const noteId = normalizeNoteId(args.note);
+      const res = await client.request({
+        path: `${NOTES_BASE}/${encodeURIComponent(noteId)}`,
+        accept: "application/xml",
+      });
+      const text = await res.text();
+      if (isResourceNotFound(res.status, text)) return unavailable(sys, noteId, res.status, text);
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      return jsonResult({ system: sys, note: noteId, available: true, result: text });
+    },
+
+    adt_check_note_status: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const noteId = normalizeNoteId(args.note);
+      const res = await client.request({
+        path: `${NOTES_BASE}/${encodeURIComponent(noteId)}`,
+        accept: "application/xml",
+      });
+      const text = await res.text();
+      if (isResourceNotFound(res.status, text)) return unavailable(sys, noteId, res.status, text);
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"));
+      // Surface the implementation status attribute if the payload exposes one.
+      const m = text.match(/(?:implementationStatus|status)="([^"]+)"/i);
+      return jsonResult({
+        system: sys,
+        note: noteId,
+        available: true,
+        status: m ? m[1] : null,
+        raw: m ? undefined : text.slice(0, 2000),
+      });
+    },
+
+    adt_implement_note: async (args) => {
+      const { client, name: sys } = getClient(args.system);
+      const noteId = normalizeNoteId(args.note);
+      if (!args.transport) {
+        return textResult(
+          "adt_implement_note: `transport` is required — implementing a note records object changes under a transport request.",
+          true,
+        );
+      }
+      const body =
+        `<?xml version="1.0" encoding="UTF-8"?>` +
+        `<note:implementation xmlns:note="http://www.sap.com/adt/cwb/notes" note:id="${noteId}" note:corrNr="${args.transport}"/>`;
+      const res = await client.request({
+        method: "POST",
+        path: `${NOTES_BASE}/${encodeURIComponent(noteId)}/deployments`,
+        headers: { "Content-Type": "application/xml" },
+        body,
+      });
+      const text = await res.text();
+      if (isResourceNotFound(res.status, text)) return unavailable(sys, noteId, res.status, text);
+      if (!res.ok) return errorResult(sys, res.status, text, res.headers.get("content-type"), { stage: "implement" });
+      return jsonResult({ system: sys, note: noteId, status: "implemented", transport: args.transport, result: text });
+    },
+  };
+}