@bridge_gpt/mcp-server 0.2.36 → 0.2.37

package/build/sfcc/read-result.js

@@ -0,0 +1,158 @@
+/**
+ * SFCC read boundary, layered on the universal SFCC result contract (BAPI-759,
+ * generalized by BAPI-766).
+ *
+ * This module owns the *read-specific* concerns: OCAPI fault-message extraction,
+ * the read-boundary error wrapper, and the fixed read messages. The envelope
+ * itself — normalization, serialization, and the `isError` predicate — lives in
+ * `sfcc-result.ts` and is shared with the write and WebDAV log surfaces, so
+ * there is exactly one implementation for the whole SFCC surface.
+ *
+ * Read handlers never construct an error envelope inline — they call
+ * `formatSfccReadFailure`, which is re-exported here as a thin delegate to the
+ * shared formatter.
+ *
+ * The unified guarantees (`isError: true` on every failure, and a body that
+ * parses as `{ error: { code, status, message, source, details } }`) are
+ * documented in `sfcc-result.ts`. An object-valued OCAPI body is preserved
+ * verbatim under `error.details` (`_v`, `fault.type`, `fault.message`,
+ * `fault.arguments` and any other upstream field), so upstream data is never
+ * discarded and never collides with the Bridge-owned envelope fields.
+ */
+import { z } from "zod";
+import { formatSfccFailure } from "./sfcc-result.js";
+export { formatSfccReadFailure } from "./sfcc-result.js";
+// ---------------------------------------------------------------------------
+// Fixed messages
+// ---------------------------------------------------------------------------
+/**
+ * The one message returned for an unexpected throw. Bridge-authored and fixed:
+ * the thrown value is never serialized, so a credential, token, request header,
+ * or stack frame carried by the exception cannot reach the caller.
+ */
+export const SFCC_INTERNAL_ERROR_MESSAGE = "An unexpected internal error occurred while handling this SFCC read. " +
+    "The underlying failure detail is withheld from this response to avoid " +
+    "leaking credentials or internal state.";
+/** The one message returned when arguments fail schema validation at the read boundary. */
+export const SFCC_VALIDATION_ERROR_MESSAGE = "Arguments failed schema validation before any OCAPI call was made. " +
+    "See error.details.issues for the offending fields.";
+/** Bridge-authored fallback used when an OCAPI body carries no usable `fault.message`. */
+export function ocapiFallbackMessage(status) {
+    return (`The SFCC OCAPI Data API returned HTTP ${status} for this read and supplied no ` +
+        `fault message. The upstream response body is preserved under error.details.`);
+}
+// ---------------------------------------------------------------------------
+// OCAPI read failures
+// ---------------------------------------------------------------------------
+/** True for a plain (non-array, non-null) object. */
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Format a non-OK OCAPI read response through the shared formatter.
+ *
+ * The message is the upstream `fault.message` when it is a non-empty string,
+ * otherwise a stable Bridge-authored fallback — raw response text is never
+ * promoted into `error.message`. The whole upstream body is preserved under
+ * `error.details`.
+ *
+ * `upstreamHttpStatus` exists for the case where Bridge reports a status other
+ * than the one HTTP returned. The OCAPI client does not currently normalize a
+ * read status (`ocapiGet`/`ocapiPost` surface `Response.status` verbatim), so
+ * in practice the two are equal and the field is omitted; the parameter keeps
+ * the seam honest if a normalization step is ever introduced.
+ */
+export function formatOcapiReadFailure(result, upstreamHttpStatus) {
+    return formatSfccFailure({
+        code: "OCAPI_FAULT",
+        status: result.status,
+        message: ocapiFaultMessage(result.body, result.status),
+        source: "ocapi",
+        details: result.body,
+        upstreamHttpStatus,
+    });
+}
+/** Pull a usable human-readable message out of an OCAPI fault body. */
+function ocapiFaultMessage(body, status) {
+    if (isPlainObject(body) && isPlainObject(body.fault)) {
+        const faultMessage = body.fault.message;
+        if (typeof faultMessage === "string" && faultMessage.trim() !== "") {
+            return faultMessage;
+        }
+    }
+    return ocapiFallbackMessage(status);
+}
+// ---------------------------------------------------------------------------
+// Read boundary
+// ---------------------------------------------------------------------------
+/**
+ * Recognize a Zod/schema failure without matching on the exception message.
+ *
+ * `instanceof` covers the normal case. The structural fallback covers a
+ * ZodError produced by a second copy of Zod (a duplicated dependency or a
+ * module-mocked import), where the prototype chain differs but the contract
+ * — a `ZodError` name plus an `issues` array — does not.
+ */
+function isSchemaFailure(err) {
+    if (err instanceof z.ZodError)
+        return true;
+    return (typeof err === "object" &&
+        err !== null &&
+        err.name === "ZodError" &&
+        Array.isArray(err.issues));
+}
+/** Reduce Zod issues to field path + code + message; nothing else is disclosed. */
+function safeZodIssues(err) {
+    const issues = Array.isArray(err.issues) ? err.issues : [];
+    return issues.map((issue) => ({
+        path: Array.isArray(issue.path) ? issue.path.map(String).join(".") : "",
+        code: typeof issue.code === "string" ? issue.code : "invalid",
+        message: typeof issue.message === "string" ? issue.message : "Invalid input.",
+    }));
+}
+/**
+ * Wrap a read tool callback so no failure escapes as a raw throw.
+ *
+ * This is the outermost project-owned callback for every SFCC read tool. It
+ * converts:
+ *
+ *   - a recognized Zod/schema failure → `VALIDATION_ERROR` (400, source `tool`)
+ *   - any other thrown value          → `INTERNAL_ERROR` (500, source `tool`)
+ *
+ * A result the inner handler *returns* — success or an already-formatted
+ * failure — is passed through untouched, so a gate rejection keeps its
+ * `NOT_CONFIGURED` code rather than being reclassified.
+ *
+ * Note on ordering: the MCP SDK validates `inputSchema` before invoking this
+ * callback and turns a rejection into its own `isError: true` result, so the
+ * transport path is already a tool result rather than a transport error. This
+ * boundary covers the paths the SDK does not: the handler's own `schema.parse`,
+ * in-process dispatch through `TOOL_HANDLERS` (which bypasses SDK validation
+ * entirely), and every unexpected throw from the gate, the OCAPI client, or the
+ * output seam.
+ */
+export function withSfccReadErrorBoundary(handler) {
+    return async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (err) {
+            if (isSchemaFailure(err)) {
+                return formatSfccFailure({
+                    code: "VALIDATION_ERROR",
+                    status: 400,
+                    message: SFCC_VALIDATION_ERROR_MESSAGE,
+                    source: "tool",
+                    details: { issues: safeZodIssues(err) },
+                });
+            }
+            return formatSfccFailure({
+                code: "INTERNAL_ERROR",
+                status: 500,
+                message: SFCC_INTERNAL_ERROR_MESSAGE,
+                source: "tool",
+                details: {},
+            });
+        }
+    };
+}

package/build/sfcc/reads-custom-object-def.js

@@ -20,7 +20,9 @@ import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
+import { formatOcapiReadFailure, withSfccReadErrorBoundary } from "./read-result.js";
 import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { applyProjectionToBody, projectionInputFor, projectionQueryEntries, } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
 // Annotations (SPEC: read-only against developer sandboxes)
@@ -39,17 +41,19 @@ const customObjectAttributesGetInput = z.object({
         .string()
         .describe('Known custom object type identifier, e.g. a custom type id starting with "c_". ' +
         "OCAPI cannot enumerate custom object types — the type must already be known."),
+    projection: projectionInputFor("attribute_collection"),
 });
 const customObjectAttributeSearchInput = z.object({
     object_type: z
         .string()
         .describe('Known custom object type to search within, e.g. a custom type id starting with "c_". ' +
         "OCAPI cannot enumerate custom object types — the type must already be known."),
-    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for a text search across id and display_name, " +
-        "or a structured OCAPI query object (term_query, filtered_query, etc.)."),
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. A plain string is a case-insensitive substring match across " +
+        "id and display_name; a structured OCAPI query object passes through unchanged."),
     start: z.number().optional().describe("Zero-based offset for paging."),
     count: z.number().optional().describe("Maximum number of results to return."),
     sorts: z.array(z.any()).optional().describe("Array of OCAPI sort descriptors."),
+    projection: projectionInputFor("attribute_search"),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -63,30 +67,34 @@ function safeType(objectType) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-async function saveAndReturn(text, dir, filename) {
-    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+async function saveAndReturn(text, dir, filename, page) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename, page);
     return textResult(output);
 }
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 function buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type } = customObjectAttributesGetInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, projection } = customObjectAttributesGetInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
-        const result = await ocapiGet(`/custom_object_definitions/${encodedType}/attribute_definitions`, credentials);
+        const queryEntries = projectionQueryEntries("attribute_collection", projection);
+        const queryStr = Object.keys(queryEntries).length > 0
+            ? "?" + new URLSearchParams(queryEntries).toString()
+            : "";
+        const result = await ocapiGet(`/custom_object_definitions/${encodedType}/attribute_definitions${queryStr}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `custom-object-def-attributes-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, query, start, count, sorts } = customObjectAttributeSearchInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, query, start, count, sorts, projection } = customObjectAttributeSearchInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
         // Coerce plain string queries into OCAPI text_query shape
         const resolvedQuery = typeof query === "string"
@@ -99,15 +107,16 @@ function buildCustomObjectAttributeSearchHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         if (sorts !== undefined)
             postBody.sorts = sorts;
+        applyProjectionToBody(postBody, "attribute_search", projection);
         const result = await ocapiPost(`/custom_object_definitions/${encodedType}/attribute_definition_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `custom-object-def-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the two SFCC custom-object-definition introspection read tools.
@@ -119,16 +128,18 @@ export function registerSfccCustomObjectDefReadTools(registerTool, deps) {
     registerTool("custom_object_definition_attributes_get", {
         description: "Retrieve attribute definitions for a KNOWN custom object type via " +
             "GET /custom_object_definitions/{type}/attribute_definitions. " +
+            "Returns each attribute's full schema by default. " +
             "OCAPI cannot enumerate types — object_type is required. " +
-            "Type creation is v2 metadata-import only, not OCAPI. Oversized payloads auto-saved locally.",
+            "Type creation is v2 metadata-import only. Oversized payloads auto-saved locally.",
         inputSchema: customObjectAttributesGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildCustomObjectAttributesGetHandler(gateDeps, getDocsDir));
     registerTool("custom_object_definition_attribute_search", {
         description: "Search attribute definitions within a KNOWN custom object type via " +
             "POST /custom_object_definitions/{type}/attribute_definition_search. " +
-            "OCAPI cannot enumerate types — object_type is required. " +
-            "Pass a string or structured OCAPI query. Type creation is v2 metadata-import only. " +
+            "Returns each attribute's full schema by default. " +
+            "OCAPI cannot enumerate types; object_type is required. " +
+            "Pass a string or OCAPI query. Type creation is v2 metadata-import only. " +
             "Oversized results auto-saved locally.",
         inputSchema: customObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,

package/build/sfcc/reads-site-preference.js

@@ -9,6 +9,27 @@
  * All three tools are read-only, run behind the T1 call-time gate, and route
  * oversized payloads through the sfcc/output.ts truncate-and-save seam.
  *
+ * PREFERENCE VALUES ARE NOT AVAILABLE HERE (BAPI-767).
+ * `preference_search` returns hits shaped `{_type, id}` and nothing more.
+ * Verified live against a developer sandbox (OCAPI v25_6): supplying
+ * `?select=(**)` changes the response not at all — zero hits gain a `value`
+ * key. That is why these two tools take no `projection` input while
+ * `site_preference_group_list` does: a projection that cannot alter the
+ * response is a flag with no observable effect.
+ *
+ * The consequence is a genuine caller-facing limitation, stated in both tool
+ * descriptions rather than left to be discovered: an ids-only read cannot
+ * distinguish "preference not set" from "preference set to the empty string".
+ *
+ * It is also, for now, accidentally protective. A name-heuristic scan of all 19
+ * preference groups on the tested sandbox found secret-named preferences in six
+ * of them — including one literally named `client_id` — and none of them expose
+ * a value through this endpoint. No redaction seam is built here because there
+ * is no value-bearing path to redact. If OCAPI ever starts returning values,
+ * redaction must be added on the raw body BEFORE normalization, serialization,
+ * truncation, or save, so one placement covers both the inline response and the
+ * docs/tmp/sfcc/ save path.
+ *
  * NOTE: SCAPI Preferences API (sfcc.preferences) is intentionally NOT used.
  * This keeps the tool context on the OCAPI Data API, preserving the single
  * AM-OAuth boundary established in T1. Do not "modernize" these tools onto
@@ -18,7 +39,9 @@ import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
+import { formatOcapiReadFailure, formatSfccReadFailure, withSfccReadErrorBoundary, } from "./read-result.js";
 import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { projectionInputFor, projectionQueryEntries } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
 // Annotations (SPEC: read-only against developer sandboxes)
@@ -53,6 +76,7 @@ const sitePreferenceSearchInput = z.object({
 const sitePreferenceGroupListInput = z.object({
     count: z.number().optional().describe("Maximum number of site preference groups to return."),
     start: z.number().optional().describe("Zero-based offset for paging."),
+    projection: projectionInputFor("broad_list"),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -66,18 +90,37 @@ function safeGroup(group) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-async function saveAndReturn(text, dir, filename) {
-    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+async function saveAndReturn(text, dir, filename, page) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename, page);
     return textResult(output);
 }
-// D-5: reject any non-sandbox instance context (safer than silently proceeding)
+/**
+ * D-5: reject any non-sandbox instance context (safer than silently proceeding).
+ *
+ * The rejection decision is unchanged; BAPI-759 moved its representation to the
+ * shared formatter, so the guardrail fails at the protocol level like every
+ * other SFCC failure. Details carry non-sensitive guard metadata only — the
+ * rejected value is caller-supplied and enum-constrained.
+ *
+ * BAPI-766 reworded the message only. It used to open with "v1", which reads as
+ * an API version while OCAPI simultaneously reports `_v: "25.6"` in the same
+ * session; the constraint belongs to this Bridge tool, not to a version. The
+ * status, code, source, decision, and `details` payload are untouched.
+ */
 function rejectIfNotSandbox(instance) {
     if (instance !== "sandbox") {
-        return textResult(JSON.stringify({
-            error: "VALIDATION_ERROR",
+        return formatSfccReadFailure({
+            code: "VALIDATION_ERROR",
             status: 400,
-            message: `v1 only supports the 'sandbox' instance context. Received: '${instance}'.`,
-        }, null, 2));
+            message: `The Bridge site-preference tool only supports the 'sandbox' instance ` +
+                `context. Received: '${instance}'.`,
+            source: "tool",
+            details: {
+                guard: "sandbox_only",
+                received_instance: instance,
+                supported_instances: ["sandbox"],
+            },
+        });
     }
     return null;
 }
@@ -85,7 +128,7 @@ function rejectIfNotSandbox(instance) {
 // Handlers
 // ---------------------------------------------------------------------------
 export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
         const { group, instance, start, count } = sitePreferenceGetInput.parse(args);
         const guard = rejectIfNotSandbox(instance);
         if (guard)
@@ -100,16 +143,16 @@ export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         const result = await ocapiPost(`/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-get-${safeGroup(group)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-get-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
         const { group, instance, query, start, count, sorts } = sitePreferenceSearchInput.parse(args);
         const guard = rejectIfNotSandbox(instance);
         if (guard)
@@ -128,18 +171,20 @@ export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
             postBody.sorts = sorts;
         const result = await ocapiPost(`/site_preferences/preference_groups/${encodedGroup}/${instance}/preference_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-search-${safeGroup(group)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { count, start } = sitePreferenceGroupListInput.parse(args);
-        const queryParams = {};
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start, projection } = sitePreferenceGroupListInput.parse(args);
+        const queryParams = {
+            ...projectionQueryEntries("broad_list", projection),
+        };
         if (count !== undefined)
             queryParams.count = String(count);
         if (start !== undefined)
@@ -149,13 +194,13 @@ export function buildSitePreferenceGroupListHandler(gateDeps, getDocsDir) {
             : "";
         const result = await ocapiGet(`/system_object_definitions/SitePreferences/attribute_groups${queryStr}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `site-preference-group-list-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the three SFCC site-preference introspection read tools.
@@ -173,18 +218,19 @@ export function registerSitePreferenceTools(registerTool, deps) {
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceGroupListHandler(gateDeps, getDocsDir));
     registerTool("site_preference_get", {
-        description: "Read effective preferences for a site preference group from the developer sandbox " +
-            "via a match-all POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
-            "Read-only, sandbox-only. Accepts optional `start`/`count` paging in the POST body. " +
-            "Oversized payloads are auto-saved locally.",
+        description: "List preference IDENTIFIERS for a site preference group from the developer sandbox via a match-all " +
+            "POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
+            "Returns ids only, NOT values — 'unset' and 'empty string' are indistinguishable. " +
+            "Read-only, sandbox-only. Optional start/count paging. Oversized payloads auto-saved locally.",
         inputSchema: sitePreferenceGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceGetHandler(gateDeps, getDocsDir));
     registerTool("site_preference_search", {
-        description: "Search/filter preferences within a site preference group from the developer sandbox " +
-            "via POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
-            "Read-only; v1 sandbox only. Pass a plain string for id-only text search or a structured " +
-            "OCAPI query object. Oversized results are auto-saved locally.",
+        description: "Search preference IDENTIFIERS within a site preference group via " +
+            "POST /site_preferences/preference_groups/{group}/sandbox/preference_search. " +
+            "Returns ids only — this endpoint does not expose values. Read-only; v1 sandbox only. " +
+            "Pass a plain string for id-only text search or a structured OCAPI query. " +
+            "Oversized results auto-saved locally.",
         inputSchema: sitePreferenceSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildSitePreferenceSearchHandler(gateDeps, getDocsDir));

package/build/sfcc/reads-system-object.js

@@ -13,7 +13,9 @@ import path from "path";
 import { z } from "zod";
 import { ocapiGet, ocapiPost } from "./client.js";
 import { withSfccGate } from "./tool-wrapper.js";
+import { formatOcapiReadFailure, withSfccReadErrorBoundary } from "./read-result.js";
 import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { applyProjectionToBody, projectionInputFor, projectionQueryEntries, } from "./read-projection.js";
 import { truncateAndSaveIfNeeded } from "./output.js";
 // ---------------------------------------------------------------------------
 // Annotations (SPEC: read-only against developer sandboxes)
@@ -30,19 +32,23 @@ const READ_ANNOTATIONS = {
 const systemObjectListInput = z.object({
     count: z.number().optional().describe("Maximum number of system object types to return."),
     start: z.number().optional().describe("Zero-based offset for paging."),
+    projection: projectionInputFor("broad_list"),
 });
+// No `projection` field: GET /system_object_definitions/{type} already returns
+// its complete document and ignores `select` (verified live — 13 keys with and
+// without it). A flag here would have no observable effect, which is the defect
+// BAPI-760 removed from this same tool. See read-projection.ts.
 const systemObjectGetInput = z.object({
     object_type: z.string().describe("System object type identifier, e.g. \"Product\" or \"Order\"."),
-    expand_attribute_definitions: z.boolean().optional().describe("When true, include the full attribute definition list in the response. " +
-        "May produce a large payload — auto-saved locally when oversized."),
 });
 const systemObjectAttributeSearchInput = z.object({
     object_type: z.string().describe("System object type to search within, e.g. \"Order\"."),
-    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for a text search across id and display_name, " +
-        "or a structured OCAPI query object (term_query, filtered_query, etc.)."),
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. A plain string is a case-insensitive substring match across " +
+        "id and display_name; a structured OCAPI query object passes through unchanged."),
     start: z.number().optional().describe("Zero-based offset for paging."),
     count: z.number().optional().describe("Maximum number of results to return."),
     sorts: z.array(z.any()).optional().describe("Array of OCAPI sort descriptors."),
+    projection: projectionInputFor("attribute_search"),
 });
 // ---------------------------------------------------------------------------
 // Helpers
@@ -56,17 +62,19 @@ function safeType(objectType) {
 function textResult(text) {
     return { content: [{ type: "text", text }] };
 }
-async function saveAndReturn(text, dir, filename) {
-    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+async function saveAndReturn(text, dir, filename, page) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename, page);
     return textResult(output);
 }
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
 function buildSystemObjectListHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { count, start } = systemObjectListInput.parse(args);
-        const queryParams = {};
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start, projection } = systemObjectListInput.parse(args);
+        const queryParams = {
+            ...projectionQueryEntries("broad_list", projection),
+        };
         if (count !== undefined)
             queryParams.count = String(count);
         if (start !== undefined)
@@ -76,34 +84,31 @@ function buildSystemObjectListHandler(gateDeps, getDocsDir) {
             : "";
         const result = await ocapiGet(`/system_object_definitions${queryStr}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-list-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildSystemObjectGetHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, expand_attribute_definitions } = systemObjectGetInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type } = systemObjectGetInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
-        const expandParam = expand_attribute_definitions === true
-            ? "?expand=attribute_definitions"
-            : "";
-        const result = await ocapiGet(`/system_object_definitions/${encodedType}${expandParam}`, credentials);
+        const result = await ocapiGet(`/system_object_definitions/${encodedType}`, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-get-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir) {
-    return withSfccGate(gateDeps, async (args, credentials) => {
-        const { object_type, query, start, count, sorts } = systemObjectAttributeSearchInput.parse(args);
+    return withSfccReadErrorBoundary(withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type, query, start, count, sorts, projection } = systemObjectAttributeSearchInput.parse(args);
         const encodedType = encodeURIComponent(object_type);
         // Coerce plain string queries into OCAPI text_query shape
         const resolvedQuery = typeof query === "string"
@@ -116,15 +121,16 @@ function buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir) {
             postBody.count = count;
         if (sorts !== undefined)
             postBody.sorts = sorts;
+        applyProjectionToBody(postBody, "attribute_search", projection);
         const result = await ocapiPost(`/system_object_definitions/${encodedType}/attribute_definition_search`, postBody, credentials);
         if (!result.ok) {
-            return textResult(JSON.stringify({ error: `OCAPI error`, status: result.status, body: result.body }, null, 2));
+            return formatOcapiReadFailure(result);
         }
         const normalized = normalizeOcapiBody(result.body);
         const text = JSON.stringify(normalized, null, 2);
         const dir = path.join(await getDocsDir(), "sfcc");
-        return saveAndReturn(text, dir, `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`);
-    });
+        return saveAndReturn(text, dir, `system-object-search-${safeType(object_type)}-${safeTimestamp()}.json`, normalized.page);
+    }));
 }
 /**
  * Register the three SFCC system-object introspection read tools.
@@ -137,25 +143,25 @@ export function registerSystemObjectReadTools(registerTool, deps) {
         description: "List all system object types from the developer sandbox via " +
             "GET /system_object_definitions. Read-only. " +
             "Accepts optional `count` and `start` for paging (OCAPI default pagination applies when omitted). " +
-            "Oversized outputs are auto-saved locally and previewed inline.",
+            "Returns ids only by default; pass projection=full for all fields. " +
+            "Oversized outputs are auto-saved locally.",
         inputSchema: systemObjectListInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectListHandler(gateDeps, getDocsDir));
     registerTool("system_object_get", {
-        description: "Retrieve a system object type from the developer sandbox. Read-only. " +
+        description: "Retrieve a system object type definition from the developer sandbox. Read-only. " +
             "GET /system_object_definitions/{type}. " +
-            "Prefer system_object_attribute_search for targeted attribute lookups — " +
-            "use this for a full type dump or expanded attribute list " +
-            "(expand_attribute_definitions=true). Oversized payloads are auto-saved locally.",
+            "Prefer system_object_attribute_search for targeted attribute lookups. " +
+            "Oversized payloads are auto-saved locally.",
         inputSchema: systemObjectGetInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectGetHandler(gateDeps, getDocsDir));
     registerTool("system_object_attribute_search", {
         description: "Search attribute definitions for a system object type. Read-only. " +
             "POST /system_object_definitions/{type}/attribute_definition_search. " +
-            "Prefer over system_object_get+expand for targeted c_ attribute lookups. " +
-            "Pass a plain string for text search or a structured OCAPI query object. " +
-            "Oversized results are auto-saved locally.",
+            "Use for targeted c_ attribute lookups; returns each attribute's full schema by default. " +
+            "Pass a plain string for text search or a structured OCAPI query. " +
+            "Oversized results auto-saved locally.",
         inputSchema: systemObjectAttributeSearchInput,
         annotations: READ_ANNOTATIONS,
     }, buildSystemObjectAttributeSearchHandler(gateDeps, getDocsDir));