@bridge_gpt/mcp-server 0.2.12 → 0.2.13

package/build/sfcc/credentials.js

@@ -0,0 +1,136 @@
+/**
+ * SFCC credential resolution — dw.json only (D-2: no Bridge credential store).
+ *
+ * Precedence: explicit tool arg → environment variable → dw.json.
+ * Multi-sandbox detection fails loudly with actionable guidance; no silent
+ * first-pick. Secret values (client_secret, tokens) are never included in
+ * any returned or thrown string — only source and target are reported.
+ */
+import { ensureGitInfoExcluded } from "../git-ignore-utils.js";
+import { readFile, writeFile, mkdir } from "fs/promises";
+import path from "path";
+// ---------------------------------------------------------------------------
+// Environment variable names (precedence tier 2)
+// ---------------------------------------------------------------------------
+const ENV_HOSTNAME = "SFCC_HOSTNAME";
+const ENV_CLIENT_ID = "SFCC_CLIENT_ID";
+const ENV_CLIENT_SECRET = "SFCC_CLIENT_SECRET";
+/** Canonical dw.json filename. */
+const DW_JSON = "dw.json";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Redact-safe summary of a resolved hostname (no secrets). */
+function safeHostLabel(hostname) {
+    return hostname.split(".")[0] ?? hostname;
+}
+// ---------------------------------------------------------------------------
+// Main resolver
+// ---------------------------------------------------------------------------
+/**
+ * Resolve SFCC credentials with strict precedence and redacted error messages.
+ *
+ * @param explicitHostname - Optional instance hostname from tool argument (tier 1).
+ * @param env - Environment variables to check (tier 2). Defaults to `process.env`.
+ * @param deps - Optional filesystem I/O overrides for testing.
+ */
+export async function resolveSfccCredentials(explicitHostname, env = process.env, deps = {}) {
+    // --- Tier 1: explicit tool argument ---
+    if (explicitHostname) {
+        const clientId = env[ENV_CLIENT_ID];
+        const clientSecret = env[ENV_CLIENT_SECRET];
+        if (!clientId || !clientSecret) {
+            return {
+                ok: false,
+                error: `Explicit instance '${safeHostLabel(explicitHostname)}' provided but ` +
+                    `${ENV_CLIENT_ID} and/or ${ENV_CLIENT_SECRET} are not set in environment. ` +
+                    `Set them and retry.`,
+            };
+        }
+        return {
+            ok: true,
+            credentials: {
+                hostname: explicitHostname,
+                clientId,
+                clientSecret,
+                source: `explicit arg + env (${ENV_CLIENT_ID}/${ENV_CLIENT_SECRET})`,
+            },
+        };
+    }
+    // --- Tier 2: environment variables ---
+    const envHostname = env[ENV_HOSTNAME];
+    const envClientId = env[ENV_CLIENT_ID];
+    const envClientSecret = env[ENV_CLIENT_SECRET];
+    if (envHostname && envClientId && envClientSecret) {
+        return {
+            ok: true,
+            credentials: {
+                hostname: envHostname,
+                clientId: envClientId,
+                clientSecret: envClientSecret,
+                source: `env (${ENV_HOSTNAME}/${ENV_CLIENT_ID}/${ENV_CLIENT_SECRET})`,
+            },
+        };
+    }
+    // --- Tier 3: dw.json ---
+    const cwd = deps.cwd ?? process.cwd();
+    const rf = deps.readFile ?? ((p) => readFile(p, "utf-8"));
+    const wf = deps.writeFile ?? ((p, data) => writeFile(p, data, "utf-8"));
+    const mk = deps.mkdir ?? ((p, opts) => mkdir(p, opts));
+    // Ensure dw.json is excluded from git tracking.
+    try {
+        await ensureGitInfoExcluded(cwd, DW_JSON, { readFile: rf, writeFile: wf, mkdir: mk });
+    }
+    catch {
+        // Non-fatal — continue even if we can't update .git/info/exclude.
+    }
+    const dwJsonPath = path.join(cwd, DW_JSON);
+    let dwJson;
+    try {
+        const raw = await rf(dwJsonPath);
+        dwJson = JSON.parse(raw);
+    }
+    catch {
+        return {
+            ok: false,
+            error: "Could not read dw.json. Create a dw.json file in your project root " +
+                "with your SFCC sandbox credentials (hostname, client-id, client-secret).",
+        };
+    }
+    // Detect multiple sandbox configurations.
+    // dw.json may carry a top-level 'configs' array (multi-sandbox format) or just a single config.
+    const configs = Array.isArray(dwJson.configs)
+        ? dwJson.configs
+        : null;
+    if (configs && configs.length > 1) {
+        const instances = configs
+            .map((c) => safeHostLabel(String(c.hostname ?? c.host ?? "unknown")))
+            .join(", ");
+        return {
+            ok: false,
+            error: `dw.json contains multiple sandboxes (${instances}). ` +
+                `Pass an explicit 'instance' argument to select one: ${instances}.`,
+        };
+    }
+    // Extract single-config credentials — support both top-level and configs[0] shapes.
+    const cfg = configs && configs.length === 1 ? configs[0] : dwJson;
+    const hostname = String(cfg.hostname ?? cfg.host ?? "");
+    const clientId = String(cfg["client-id"] ?? cfg.clientId ?? cfg.client_id ?? "");
+    const clientSecret = String(cfg["client-secret"] ?? cfg.clientSecret ?? cfg.client_secret ?? "");
+    if (!hostname || !clientId || !clientSecret) {
+        return {
+            ok: false,
+            error: "dw.json is present but missing required fields (hostname, client-id, client-secret). " +
+                "Ensure all three fields are set.",
+        };
+    }
+    return {
+        ok: true,
+        credentials: {
+            hostname,
+            clientId,
+            clientSecret,
+            source: `dw.json (instance: ${safeHostLabel(hostname)})`,
+        },
+    };
+}

package/build/sfcc/ocapi-shape.js

@@ -0,0 +1,77 @@
+/**
+ * OCAPI Data API paging-envelope normalizer.
+ *
+ * The SFCC OCAPI Data API wraps collection responses in a standard paging
+ * envelope. This module provides a typed extractor for the `data` array so
+ * sub-task read tools share one normalizer rather than each re-deriving the
+ * shape.
+ */
+/**
+ * Parse a raw OCAPI response body into a normalized envelope result.
+ *
+ * Returns `null` when `body` is not a valid OCAPI paging envelope (missing
+ * `data` array or `count` field), allowing callers to surface a structured
+ * error instead of crashing.
+ */
+export function normalizeOcapiPage(body) {
+    if (body === null ||
+        typeof body !== "object" ||
+        !Array.isArray(body.data) ||
+        typeof body.count !== "number") {
+        return null;
+    }
+    const envelope = body;
+    return {
+        items: envelope.data,
+        count: envelope.count,
+        total: envelope.total,
+        hasMore: envelope.next != null,
+    };
+}
+/**
+ * Permissive OCAPI response normalizer used by sub-task read tools.
+ *
+ * Handles all envelope forms observed in the wild:
+ *   - Standard wrapped envelope: { count, data, total?, start?, next? }
+ *   - Version-tagged envelope:   { _v, data, ... } (count may be absent)
+ *   - Bare array response:       [item, item, ...]
+ *   - Bare object response:      { id: "..." } (no data wrapper)
+ *   - Any other value:           returns empty items rather than throwing
+ *
+ * Unlike `normalizeOcapiPage`, this function never returns null and is
+ * forward-compatible with future OCAPI envelope shapes.
+ */
+export function normalizeOcapiBody(body) {
+    // Bare array
+    if (Array.isArray(body)) {
+        return { items: body, count: body.length, total: undefined, hasMore: false };
+    }
+    // Object forms
+    if (body !== null && typeof body === "object") {
+        const obj = body;
+        // Wrapped envelope: has a data array (with or without explicit count)
+        if (Array.isArray(obj.data)) {
+            const items = obj.data;
+            return {
+                items,
+                count: typeof obj.count === "number" ? obj.count : items.length,
+                total: typeof obj.total === "number" ? obj.total : undefined,
+                hasMore: obj.next != null,
+            };
+        }
+        // Bare object (single resource, no wrapping envelope)
+        return { items: [body], count: 1, total: undefined, hasMore: false };
+    }
+    // Non-object (null, string, number, etc.)
+    return { items: [], count: 0, total: undefined, hasMore: false };
+}
+/**
+ * SPEC §4.5 `value_type` mapper.
+ *
+ * Surfaces the raw REST-JSON underscored enum string unchanged (e.g.,
+ * "set_of_string", "enum_of_int"). Unknown / future values are passed through
+ * without dropping them — forward-compatible by design.
+ */
+export function mapValueType(value) {
+    return value;
+}

package/build/sfcc/output.js

@@ -0,0 +1,39 @@
+/**
+ * SFCC output helpers — thin wrappers around the host index.ts seams.
+ *
+ * Re-exports the truncation + docs-path utilities through a stable sfcc/
+ * interface so sub-task read tools import from here instead of reaching into
+ * the host module directly. This boundary makes a future extraction cheap.
+ */
+import path from "path";
+import { mkdir, writeFile } from "fs/promises";
+/** Maximum characters returned inline; content beyond this is saved locally. */
+export const SFCC_MAX_INLINE = 50_000;
+/** Truncation note appended to truncated payloads. */
+function truncationNote(savedPath) {
+    return `\n\n[Response truncated — full payload saved to ${savedPath}]`;
+}
+/**
+ * If `text` exceeds `SFCC_MAX_INLINE`, save it to `dir/filename` and return a
+ * truncated version with a local-path note. Otherwise returns `text` unchanged.
+ *
+ * Write failures are non-fatal: the full (un-truncated) text is returned with
+ * a warning rather than throwing.
+ */
+export async function truncateAndSaveIfNeeded(text, dir, filename, deps = {}) {
+    if (text.length <= SFCC_MAX_INLINE) {
+        return text;
+    }
+    const mk = deps.mkdir ?? mkdir;
+    const wf = deps.writeFile ?? writeFile;
+    const filePath = path.join(dir, filename);
+    try {
+        await mk(dir, { recursive: true });
+        await wf(filePath, text, "utf-8");
+    }
+    catch (err) {
+        return (text +
+            `\n\nWarning: response was NOT truncated because local save failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    return text.slice(0, SFCC_MAX_INLINE) + truncationNote(filePath);
+}

package/build/sfcc/permissions.js

@@ -0,0 +1,136 @@
+/**
+ * check_permissions — SFCC OCAPI access probe.
+ *
+ * Issues a harmless GET /system_object_definitions probe. On 200: reports the
+ * detected OCAPI version. On 401/403: prints the exact OCAPI Settings JSON to
+ * paste in Business Manager, split into read-only (v1) vs. write/import (v2)
+ * grant blocks.
+ */
+import { ocapiGet } from "./client.js";
+import { normalizeOcapiPage } from "./ocapi-shape.js";
+import { DEFAULT_OCAPI_VERSION } from "./config.js";
+// ---------------------------------------------------------------------------
+// OCAPI Settings JSON template
+// Operators paste this in: Administration > Site Development > Open Commerce API Settings → Data API tab.
+// ---------------------------------------------------------------------------
+const OCAPI_SETTINGS_READ_ONLY = (ocapiVersion) => JSON.stringify({
+    _v: ocapiVersion,
+    clients: [
+        {
+            client_id: "<YOUR_CLIENT_ID>",
+            resources: [
+                {
+                    resource_id: "/system_object_definitions",
+                    methods: ["get"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+                {
+                    resource_id: "/system_object_definitions/**",
+                    methods: ["get"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+            ],
+        },
+    ],
+}, null, 2);
+const OCAPI_SETTINGS_WRITE_IMPORT = (ocapiVersion) => JSON.stringify({
+    _v: ocapiVersion,
+    clients: [
+        {
+            client_id: "<YOUR_CLIENT_ID>",
+            resources: [
+                {
+                    resource_id: "/system_object_definitions",
+                    methods: ["get", "put", "patch", "delete"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+                {
+                    resource_id: "/system_object_definitions/**",
+                    methods: ["get", "put", "patch", "delete"],
+                    read_attributes: "(**)",
+                    write_attributes: "(**)",
+                },
+            ],
+        },
+    ],
+}, null, 2);
+// ---------------------------------------------------------------------------
+// Tool implementation
+// ---------------------------------------------------------------------------
+/**
+ * Probe OCAPI access via GET /system_object_definitions.
+ *
+ * @param credentials - Resolved SFCC credentials (hostname + clientId/Secret).
+ * @param ocapiVersion - OCAPI version to probe (defaults to DEFAULT_OCAPI_VERSION).
+ */
+export async function checkPermissionsTool(credentials, ocapiVersion = DEFAULT_OCAPI_VERSION) {
+    let result;
+    try {
+        result = await ocapiGet("/system_object_definitions", credentials, ocapiVersion);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `OCAPI probe failed: ${msg}\n\n` +
+                        ocapiSettingsInstructions(ocapiVersion),
+                },
+            ],
+        };
+    }
+    if (result.ok) {
+        const normalized = normalizeOcapiPage(result.body);
+        const itemCount = normalized ? normalized.count : "unknown";
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `✓ OCAPI access confirmed.\n` +
+                        `  Instance: ${credentials.hostname.split(".")[0]}\n` +
+                        `  OCAPI version: ${ocapiVersion}\n` +
+                        `  GET /system_object_definitions: ${itemCount} items returned`,
+                },
+            ],
+        };
+    }
+    if (result.status === 401 || result.status === 403) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `HTTP ${result.status}: OCAPI access denied for instance ${credentials.hostname.split(".")[0]}.\n\n` +
+                        ocapiSettingsInstructions(ocapiVersion),
+                },
+            ],
+        };
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Unexpected OCAPI response: HTTP ${result.status}.\n` +
+                    `Ensure your sandbox is running and the hostname in dw.json is correct.`,
+            },
+        ],
+    };
+}
+function ocapiSettingsInstructions(ocapiVersion) {
+    return (`To grant OCAPI access, paste the JSON below in Business Manager:\n` +
+        `  Administration > Site Development > Open Commerce API Settings → Data API tab\n\n` +
+        `--- READ-ONLY GRANTS (v1 — required now) ---\n` +
+        `${OCAPI_SETTINGS_READ_ONLY(ocapiVersion)}\n\n` +
+        `--- WRITE/IMPORT GRANTS (v2 — forward-looking, paste once) ---\n` +
+        `${OCAPI_SETTINGS_WRITE_IMPORT(ocapiVersion)}\n\n` +
+        `Replace <YOUR_CLIENT_ID> with the client_id from your dw.json.`);
+}
+/**
+ * Build the check_permissions handler bound to the gate-resolved credentials.
+ */
+export function buildCheckPermissionsHandler(withGate) {
+    return withGate(async (_args, credentials) => checkPermissionsTool(credentials));
+}

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

@@ -0,0 +1,119 @@
+/**
+ * SFCC custom-object-definition introspection read tools (BAPI-402, T4–T5).
+ *
+ * Implements:
+ *   custom_object_definition_list — GET  /custom_object_definitions
+ *   custom_object_definition_get  — GET  /custom_object_definitions/{type}
+ *
+ * Both tools are read-only, run behind the T1 call-time gate, and route
+ * oversized payloads through the sfcc/output.ts truncate-and-save seam.
+ *
+ * Note: custom object TYPE creation/update is NOT available via OCAPI REST.
+ * It is a v2 metadata-import capability (metadata XML → WebDAV → import job).
+ */
+import path from "path";
+import { z } from "zod";
+import { ocapiGet } from "./client.js";
+import { withSfccGate } from "./tool-wrapper.js";
+import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { truncateAndSaveIfNeeded } from "./output.js";
+// ---------------------------------------------------------------------------
+// Annotations (SPEC: read-only against developer sandboxes)
+// ---------------------------------------------------------------------------
+const READ_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+const customObjectListInput = z.object({
+    count: z.number().optional().describe("Maximum number of custom object types to return."),
+    start: z.number().optional().describe("Zero-based offset for paging."),
+});
+const customObjectGetInput = z.object({
+    object_type: z
+        .string()
+        .describe('Custom object type identifier, e.g. "GiftCertificate" or a custom type id starting with "c_".'),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function safeTimestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function safeType(objectType) {
+    return encodeURIComponent(objectType).replace(/%/g, "_");
+}
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+async function saveAndReturn(text, dir, filename) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+    return textResult(output);
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+function buildCustomObjectListHandler(gateDeps, getDocsDir) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        const { count, start } = customObjectListInput.parse(args);
+        const queryParams = {};
+        if (count !== undefined)
+            queryParams.count = String(count);
+        if (start !== undefined)
+            queryParams.start = String(start);
+        const queryStr = Object.keys(queryParams).length > 0
+            ? "?" + new URLSearchParams(queryParams).toString()
+            : "";
+        const result = await ocapiGet(`/custom_object_definitions${queryStr}`, credentials);
+        if (!result.ok) {
+            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+        }
+        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-list-${safeTimestamp()}.json`);
+    });
+}
+function buildCustomObjectGetHandler(gateDeps, getDocsDir) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        const { object_type } = customObjectGetInput.parse(args);
+        const encodedType = encodeURIComponent(object_type);
+        const result = await ocapiGet(`/custom_object_definitions/${encodedType}`, credentials);
+        if (!result.ok) {
+            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+        }
+        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-${safeType(object_type)}-${safeTimestamp()}.json`);
+    });
+}
+/**
+ * Register the two SFCC custom-object-definition introspection read tools.
+ *
+ * Called from `registerSfccTools` — no direct `index.ts` edits needed.
+ */
+export function registerSfccCustomObjectDefReadTools(registerTool, deps) {
+    const { gateDeps, getDocsDir } = deps;
+    registerTool("custom_object_definition_list", {
+        description: "List all custom object type definitions from the developer sandbox via " +
+            "GET /custom_object_definitions. Read-only introspection; type definitions cannot be created " +
+            "or updated via OCAPI (v2 metadata-import only). " +
+            "Optional `count` and `start` for paging. Oversized outputs auto-saved locally.",
+        inputSchema: customObjectListInput,
+        annotations: READ_ANNOTATIONS,
+    }, buildCustomObjectListHandler(gateDeps, getDocsDir));
+    registerTool("custom_object_definition_get", {
+        description: "Retrieve an EXISTING custom object type from the developer sandbox via " +
+            "GET /custom_object_definitions/{type}. " +
+            "Returns the type with key_definition and attribute_definitions/attribute_groups. " +
+            "Read-only introspection; type definitions cannot be created or updated via OCAPI " +
+            "(v2 metadata-import only). Oversized payloads auto-saved locally.",
+        inputSchema: customObjectGetInput,
+        annotations: READ_ANNOTATIONS,
+    }, buildCustomObjectGetHandler(gateDeps, getDocsDir));
+}

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

@@ -0,0 +1,158 @@
+/**
+ * SFCC site-preference introspection read tools (BAPI-403, T6 — optional).
+ *
+ * Implements:
+ *   site_preference_get    — GET  /site_preferences/preference_groups/{group}/{instance}
+ *   site_preference_search — POST /site_preferences/preference_groups/{group}/{instance}/preference_search
+ *
+ * Both tools are read-only, run behind the T1 call-time gate, and route
+ * oversized payloads through the sfcc/output.ts truncate-and-save seam.
+ *
+ * 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
+ * SCAPI without understanding the auth-surface implications.
+ */
+import path from "path";
+import { z } from "zod";
+import { ocapiGet, ocapiPost } from "./client.js";
+import { withSfccGate } from "./tool-wrapper.js";
+import { normalizeOcapiBody } from "./ocapi-shape.js";
+import { truncateAndSaveIfNeeded } from "./output.js";
+// ---------------------------------------------------------------------------
+// Annotations (SPEC: read-only against developer sandboxes)
+// ---------------------------------------------------------------------------
+const READ_ANNOTATIONS = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+// ---------------------------------------------------------------------------
+// Input schemas
+// ---------------------------------------------------------------------------
+const INSTANCE_ENUM = z.enum(["staging", "development", "sandbox", "production"]);
+const INSTANCE_DESCRIBE = "OCAPI instance context. v1 supports the 'sandbox' context only; " +
+    "any other value is rejected with a validation error. Defaults to 'sandbox'.";
+const sitePreferenceGetInput = z.object({
+    group: z.string().describe("Preference group ID, e.g. 'Account' or 'General'."),
+    instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
+    start: z.number().optional().describe("Zero-based offset for paging."),
+    count: z.number().optional().describe("Maximum number of preferences to return."),
+});
+const sitePreferenceSearchInput = z.object({
+    group: z.string().describe("Preference group ID to search within."),
+    instance: INSTANCE_ENUM.optional().default("sandbox").describe(INSTANCE_DESCRIBE),
+    query: z.union([z.string(), z.record(z.string(), z.any())]).describe("Search query. Pass a plain string for text search across preference ids and values, " +
+        "or a structured OCAPI query object (term_query, filtered_query, etc.)."),
+    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."),
+});
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function safeTimestamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+function safeGroup(group) {
+    return encodeURIComponent(group).replace(/%/g, "_");
+}
+function textResult(text) {
+    return { content: [{ type: "text", text }] };
+}
+async function saveAndReturn(text, dir, filename) {
+    const output = await truncateAndSaveIfNeeded(text, dir, filename);
+    return textResult(output);
+}
+// D-5: reject any non-sandbox instance context (safer than silently proceeding)
+function rejectIfNotSandbox(instance) {
+    if (instance !== "sandbox") {
+        return textResult(JSON.stringify({
+            error: "VALIDATION_ERROR",
+            status: 400,
+            message: `v1 only supports the 'sandbox' instance context. Received: '${instance}'.`,
+        }, null, 2));
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+export function buildSitePreferenceGetHandler(gateDeps, getDocsDir) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        const { group, instance, start, count } = sitePreferenceGetInput.parse(args);
+        const guard = rejectIfNotSandbox(instance);
+        if (guard)
+            return guard;
+        const encodedGroup = encodeURIComponent(group);
+        const queryParams = {};
+        if (start !== undefined)
+            queryParams.start = String(start);
+        if (count !== undefined)
+            queryParams.count = String(count);
+        const queryStr = Object.keys(queryParams).length > 0
+            ? "?" + new URLSearchParams(queryParams).toString()
+            : "";
+        const result = await ocapiGet(`/site_preferences/preference_groups/${encodedGroup}/${instance}${queryStr}`, credentials);
+        if (!result.ok) {
+            return textResult(JSON.stringify({ error: "OCAPI error", status: result.status, body: result.body }, null, 2));
+        }
+        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`);
+    });
+}
+export function buildSitePreferenceSearchHandler(gateDeps, getDocsDir) {
+    return withSfccGate(gateDeps, async (args, credentials) => {
+        const { group, instance, query, start, count, sorts } = sitePreferenceSearchInput.parse(args);
+        const guard = rejectIfNotSandbox(instance);
+        if (guard)
+            return guard;
+        const encodedGroup = encodeURIComponent(group);
+        // Coerce plain string queries into OCAPI text_query shape
+        const resolvedQuery = typeof query === "string"
+            ? { text_query: { fields: ["id", "value"], search_phrase: query } }
+            : query;
+        const postBody = { query: resolvedQuery };
+        if (start !== undefined)
+            postBody.start = start;
+        if (count !== undefined)
+            postBody.count = count;
+        if (sorts !== undefined)
+            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));
+        }
+        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`);
+    });
+}
+/**
+ * Register the two SFCC site-preference introspection read tools.
+ *
+ * Called from `registerSfccTools` — no direct `index.ts` edits needed.
+ */
+export function registerSitePreferenceTools(registerTool, deps) {
+    const { gateDeps, getDocsDir } = deps;
+    registerTool("site_preference_get", {
+        description: "Read effective preferences for a site preference group from the developer sandbox " +
+            "via GET /site_preferences/preference_groups/{group}/sandbox. Read-only; v1 supports " +
+            "sandboxes only (non-sandbox instances are rejected). Accepts optional `start` and " +
+            "`count` for paging. Oversized payloads are auto-saved locally and previewed inline.",
+        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 text search or a structured " +
+            "OCAPI query object. Oversized results are auto-saved locally.",
+        inputSchema: sitePreferenceSearchInput,
+        annotations: READ_ANNOTATIONS,
+    }, buildSitePreferenceSearchHandler(gateDeps, getDocsDir));
+}