@sxl-studio/bridge 1.7.2 → 1.8.0

package/dist/tools/large-data.js

@@ -0,0 +1,189 @@
+import { z } from "zod";
+export const LARGE_DATA_RESPONSE_MODE_FIELD = "bridgeResponseMode";
+export const LARGE_DATA_MAX_BYTES_FIELD = "bridgeMaxResponseBytes";
+const DEFAULT_MAX_RESPONSE_BYTES = 96 * 1024;
+const MIN_MAX_RESPONSE_BYTES = 8 * 1024;
+const MAX_MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+const PREVIEW_ITEMS = 5;
+const MAX_STRING_PREVIEW = 240;
+const MAX_OBJECT_KEYS = 24;
+export const largeDataResponseArgs = {
+    [LARGE_DATA_RESPONSE_MODE_FIELD]: z
+        .enum(["auto", "summary", "full"])
+        .optional()
+        .describe("Bridge MCP response mode for large results. auto (default) summarizes only oversized responses; summary always returns counts/preview; full returns the full result and should be used sparingly."),
+    [LARGE_DATA_MAX_BYTES_FIELD]: z
+        .number()
+        .int()
+        .positive()
+        .max(MAX_MAX_RESPONSE_BYTES)
+        .optional()
+        .describe("Optional auto-summary threshold in bytes for this MCP response. Default: 98304."),
+};
+export function stripLargeDataControlFields(payload = {}) {
+    const out = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (key !== LARGE_DATA_RESPONSE_MODE_FIELD && key !== LARGE_DATA_MAX_BYTES_FIELD) {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+function readMode(payload) {
+    const raw = payload[LARGE_DATA_RESPONSE_MODE_FIELD];
+    return raw === "summary" || raw === "full" || raw === "auto" ? raw : "auto";
+}
+function readMaxBytes(payload) {
+    const raw = payload[LARGE_DATA_MAX_BYTES_FIELD];
+    if (typeof raw !== "number" || !Number.isFinite(raw))
+        return DEFAULT_MAX_RESPONSE_BYTES;
+    return Math.max(MIN_MAX_RESPONSE_BYTES, Math.min(MAX_MAX_RESPONSE_BYTES, Math.floor(raw)));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isPlainObject(value) {
+    return Object.prototype.toString.call(value) === "[object Object]";
+}
+function estimateBytes(value) {
+    try {
+        return Buffer.byteLength(JSON.stringify(value), "utf8");
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+}
+function scalarPreview(value) {
+    if (typeof value !== "string")
+        return value;
+    if (value.length <= MAX_STRING_PREVIEW)
+        return value;
+    return {
+        type: "string",
+        length: value.length,
+        preview: value.slice(0, MAX_STRING_PREVIEW),
+    };
+}
+function summarizePreview(value, depth = 0) {
+    if (value === null || typeof value !== "object")
+        return scalarPreview(value);
+    if (Array.isArray(value)) {
+        return {
+            type: "array",
+            count: value.length,
+            truncated: value.length > PREVIEW_ITEMS,
+            items: value.slice(0, PREVIEW_ITEMS).map((item) => summarizePreview(item, depth + 1)),
+        };
+    }
+    if (!isPlainObject(value)) {
+        return { type: typeof value };
+    }
+    const entries = Object.entries(value);
+    const out = {
+        type: "object",
+        keyCount: entries.length,
+    };
+    const preferredKeys = [
+        "id",
+        "key",
+        "name",
+        "type",
+        "nodeId",
+        "nodeName",
+        "nodeType",
+        "pageId",
+        "pageName",
+        "commandType",
+        "status",
+        "cursor",
+        "ok",
+    ];
+    const keys = [
+        ...preferredKeys.filter((key) => key in value),
+        ...entries.map(([key]) => key).filter((key) => !preferredKeys.includes(key)),
+    ].slice(0, MAX_OBJECT_KEYS);
+    for (const key of keys) {
+        const child = value[key];
+        if (depth >= 2 && typeof child === "object" && child !== null) {
+            out[key] = Array.isArray(child)
+                ? { type: "array", count: child.length }
+                : { type: "object", keyCount: Object.keys(child).length };
+        }
+        else {
+            out[key] = summarizePreview(child, depth + 1);
+        }
+    }
+    if (entries.length > keys.length) {
+        out.truncatedKeys = entries.length - keys.length;
+    }
+    return out;
+}
+function countCollections(value) {
+    if (!isRecord(value))
+        return {};
+    const counts = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (Array.isArray(child)) {
+            counts[key] = child.length;
+        }
+    }
+    return counts;
+}
+function extractPagination(value) {
+    if (!isRecord(value))
+        return null;
+    const pagination = {};
+    if (typeof value.cursor === "string" || value.cursor === null)
+        pagination.cursor = value.cursor;
+    if (isRecord(value.summary)) {
+        if (typeof value.summary.hasMore === "boolean")
+            pagination.hasMore = value.summary.hasMore;
+        if (typeof value.summary.nextCursor === "string")
+            pagination.nextCursor = value.summary.nextCursor;
+        if (typeof value.summary.returned === "number")
+            pagination.returned = value.summary.returned;
+    }
+    return Object.keys(pagination).length > 0 ? pagination : null;
+}
+function extractTopLevelScalars(value) {
+    if (!isRecord(value))
+        return {};
+    const scalars = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (child === null || typeof child === "string" || typeof child === "number" || typeof child === "boolean") {
+            scalars[key] = scalarPreview(child);
+        }
+    }
+    return scalars;
+}
+export function normalizeLargeDataResult(commandType, payload, result) {
+    const mode = readMode(payload);
+    if (mode === "full")
+        return result;
+    const maxBytes = readMaxBytes(payload);
+    const originalBytes = estimateBytes(result);
+    const shouldNormalize = mode === "summary" || originalBytes > maxBytes;
+    if (!shouldNormalize)
+        return result;
+    const pagination = extractPagination(result);
+    return {
+        ok: isRecord(result) && typeof result.ok === "boolean" ? result.ok : true,
+        bridgeLargeData: {
+            normalized: true,
+            commandType,
+            responseMode: mode,
+            reason: mode === "summary" ? "requested-summary" : "response-too-large",
+            originalBytes,
+            maxBytes,
+            fullResultHint: `Pass ${LARGE_DATA_RESPONSE_MODE_FIELD}: "full" only when the user explicitly needs the full payload.`,
+        },
+        summary: {
+            topLevelKeys: isRecord(result) ? Object.keys(result) : [],
+            scalars: extractTopLevelScalars(result),
+            counts: countCollections(result),
+            ...(pagination ? { pagination } : {}),
+        },
+        preview: summarizePreview(result),
+    };
+}
+//# sourceMappingURL=large-data.js.map

package/dist/tools/large-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"large-data.js","sourceRoot":"","sources":["../../src/tools/large-data.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,CAAC,MAAM,8BAA8B,GAAG,oBAAoB,CAAC;AACnE,MAAM,CAAC,MAAM,0BAA0B,GAAG,wBAAwB,CAAC;AAEnE,MAAM,0BAA0B,GAAG,EAAE,GAAG,IAAI,CAAC;AAC7C,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,CAAC;AACxC,MAAM,sBAAsB,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;AAC/C,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,eAAe,GAAG,EAAE,CAAC;AAI3B,MAAM,CAAC,MAAM,qBAAqB,GAAG;IACnC,CAAC,8BAA8B,CAAC,EAAE,CAAC;SAChC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;SACjC,QAAQ,EAAE;SACV,QAAQ,CACP,mMAAmM,CACpM;IACH,CAAC,0BAA0B,CAAC,EAAE,CAAC;SAC5B,MAAM,EAAE;SACR,GAAG,EAAE;SACL,QAAQ,EAAE;SACV,GAAG,CAAC,sBAAsB,CAAC;SAC3B,QAAQ,EAAE;SACV,QAAQ,CAAC,iFAAiF,CAAC;CAC/F,CAAC;AAOF,MAAM,UAAU,2BAA2B,CAAC,UAAmC,EAAE;IAC/E,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,GAAG,KAAK,8BAA8B,IAAI,GAAG,KAAK,0BAA0B,EAAE,CAAC;YACjF,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;QACnB,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,QAAQ,CAAC,OAAgC;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,8BAA8B,CAAC,CAAC;IACpD,OAAO,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,MAAM,IAAI,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9E,CAAC;AAED,SAAS,YAAY,CAAC,OAAgC;IACpD,MAAM,GAAG,GAAG,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAChD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,0BAA0B,CAAC;IACxF,OAAO,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,GAAG,CAAC,sBAAsB,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC7F,CAAC;AAED,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,iBAAiB,CAAC;AACrE,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,iBAAiB,CAAC;IAClC,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5C,IAAI,KAAK,CAAC,MAAM,IAAI,kBAAkB;QAAE,OAAO,KAAK,CAAC;IACrD,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,kBAAkB,CAAC;KAC5C,CAAC;AACJ,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC;IACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC;IAE7E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,IAAI,EAAE,OAAO;YACb,KAAK,EAAE,KAAK,CAAC,MAAM;YACnB,SAAS,EAAE,KAAK,CAAC,MAAM,GAAG,aAAa;YACvC,KAAK,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;SACtF,CAAC;IACJ,CAAC;IAED,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,EAAE,IAAI,EAAE,OAAO,KAAK,EAAE,CAAC;IAChC,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,GAAG,GAA4B;QACnC,IAAI,EAAE,QAAQ;QACd,QAAQ,EAAE,OAAO,CAAC,MAAM;KACzB,CAAC;IACF,MAAM,aAAa,GAAG;QACpB,IAAI;QACJ,KAAK;QACL,MAAM;QACN,MAAM;QACN,QAAQ;QACR,UAAU;QACV,UAAU;QACV,QAAQ;QACR,UAAU;QACV,aAAa;QACb,QAAQ;QACR,QAAQ;QACR,IAAI;KACL,CAAC;IACF,MAAM,IAAI,GAAG;QACX,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,CAAC;QAC9C,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;KAC7E,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC;IAE5B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,KAAK,IAAI,CAAC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC9D,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;gBAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE;gBACxC,CAAC,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,KAAgC,CAAC,CAAC,MAAM,EAAE,CAAC;QACzF,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,GAAG,CAAC,GAAG,gBAAgB,CAAC,KAAK,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAChD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACjC,GAAG,CAAC,aAAa,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;IACnD,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,gBAAgB,CAAC,KAAc;IACtC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,MAAM,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAClC,MAAM,UAAU,GAA4B,EAAE,CAAC;IAC/C,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI;QAAE,UAAU,CAAC,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAChG,IAAI,QAAQ,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS;YAAE,UAAU,CAAC,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAC3F,IAAI,OAAO,KAAK,CAAC,OAAO,CAAC,UAAU,KAAK,QAAQ;YAAE,UAAU,CAAC,UAAU,GAAG,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC;QACnG,IAAI,OAAO,KAAK,CAAC,OAAO,CAAC,QAAQ,KAAK,QAAQ;YAAE,UAAU,CAAC,QAAQ,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC;IAC/F,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;AAChE,CAAC;AAED,SAAS,sBAAsB,CAAC,KAAc;IAC5C,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,OAAO,GAA4B,EAAE,CAAC;IAC5C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACjD,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;YAC3G,OAAO,CAAC,GAAG,CAAC,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACtC,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,wBAAwB,CACtC,WAAmB,EACnB,OAAgC,EAChC,MAAe;IAEf,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC/B,IAAI,IAAI,KAAK,MAAM;QAAE,OAAO,MAAM,CAAC;IAEnC,MAAM,QAAQ,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACvC,MAAM,aAAa,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAC5C,MAAM,eAAe,GAAG,IAAI,KAAK,SAAS,IAAI,aAAa,GAAG,QAAQ,CAAC;IACvE,IAAI,CAAC,eAAe;QAAE,OAAO,MAAM,CAAC;IAEpC,MAAM,UAAU,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IAC7C,OAAO;QACL,EAAE,EAAE,QAAQ,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,EAAE,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI;QACzE,eAAe,EAAE;YACf,UAAU,EAAE,IAAI;YAChB,WAAW;YACX,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,oBAAoB;YACvE,aAAa;YACb,QAAQ;YACR,cAAc,EAAE,QAAQ,8BAA8B,gEAAgE;SACvH;QACD,OAAO,EAAE;YACP,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE;YACzD,OAAO,EAAE,sBAAsB,CAAC,MAAM,CAAC;YACvC,MAAM,EAAE,gBAAgB,CAAC,MAAM,CAAC;YAChC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACtC;QACD,OAAO,EAAE,gBAAgB,CAAC,MAAM,CAAC;KAClC,CAAC;AACJ,CAAC"}

package/dist/tools/meta.d.ts

@@ -7,4 +7,9 @@
  */
 import type { McpServer } from "../../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js";
 import type { CommandQueue } from "../command-queue.js";
-export declare function registerMetaTools(server: McpServer, _queue: CommandQueue): void;
+import type { SessionInfo } from "../types.js";
+export type BridgeMetaRuntimeContext = {
+    bridgePort?: number;
+    getSessionInfo?: () => SessionInfo;
+};
+export declare function registerMetaTools(server: McpServer, queue: CommandQueue, runtimeContext?: BridgeMetaRuntimeContext): void;

package/dist/tools/meta.js

@@ -6,31 +6,109 @@
  * which tools require Design mode vs read-only Dev Mode.
  */
 import { z } from "zod";
-import { getBridgeToolCatalogue } from "./registry.js";
+import { routeAgentIntent } from "../agent-recipes.js";
+import { getAuditSnapshot } from "../audit.js";
+import { readPersistedAuditSnapshot } from "../audit-store.js";
+import { buildBridgeContractAudit } from "../bridge-contract-audit.js";
+import { buildBridgePerformanceProfile } from "../bridge-performance-profile.js";
+import { buildBridgeRuntimeSummary } from "../bridge-runtime-summary.js";
+import { buildFigmaMcpParityMatrix } from "../figma-mcp-parity.js";
+import { buildFigmaMcpSkillsParityMatrix } from "../figma-mcp-skills-parity.js";
+import { buildUltimateReadinessAudit } from "../ultimate-readiness-audit.js";
+import { SXL_OPERATOR_RUNBOOK } from "../agent-runbook.js";
+import { planWorkflow, previewWorkflow } from "../workflow-planner.js";
+import { buildCapabilityMatrix, listCatalogueTools } from "./capability-matrix.js";
+import { largeDataResponseArgs, normalizeLargeDataResult, } from "./large-data.js";
 import { ok } from "./shared.js";
-export function registerMetaTools(server, _queue) {
-    server.tool("list_tools", "List all Bridge MCP tools with their category and mode requirements. Useful as a first call to discover the tool surface.", {
+export function registerMetaTools(server, queue, runtimeContext = {}) {
+    server.tool("get_contract_audit", "Return a Bridge-local release contract audit: catalogue execution mapping, required meta tools, recipe references, schema entrypoints, workflow gates, and findings. Does not execute plugin commands.", {}, async () => ok(buildBridgeContractAudit()));
+    server.tool("get_figma_mcp_parity", "Return the machine-readable parity map between official Figma MCP tools and SXL Bridge/SXL Studio capabilities. Use it to decide when Bridge is primary, when official Figma MCP should be used as companion, and what remains future/unsupported.", {}, async () => ok(buildFigmaMcpParityMatrix()));
+    server.tool("get_figma_mcp_skills_parity", "Return the machine-readable parity map between current official Figma MCP skills and SXL Bridge/SXL Studio recipes/resources, including legacy/client compatibility aliases. Use it to route skill-level requests such as figma-use, figma-swiftui, figma-code-connect, or figma-create-new-file.", {}, async () => ok(buildFigmaMcpSkillsParityMatrix()));
+    server.tool("get_performance_profile", "Return the machine-readable Bridge performance profile: tool budgets, large-data and dry-run policies, destructive-write warnings, and recent audit timing. Use it before large workflows or when tuning agent behavior for speed/stability.", {
+        auditLimit: z
+            .number()
+            .int()
+            .positive()
+            .max(200)
+            .optional()
+            .describe("Number of recent audit entries to include. Default: 50, max: 200."),
+    }, async ({ auditLimit }) => ok(buildBridgePerformanceProfile({ auditLimit })));
+    server.tool("get_bridge_audit_log", "Return recent Bridge command audit entries from memory or persisted disk JSONL. Entries are sanitized: payload values are never returned, only payload key names.", {
+        source: z.enum(["memory", "disk"]).optional().describe("Audit source. Default: memory ring buffer."),
+        limit: z.number().int().positive().max(1000).optional().describe("Max entries. Default: 50."),
+        ...largeDataResponseArgs,
+    }, async ({ source, limit, ...controls }) => {
+        const resolvedSource = source ?? "memory";
+        const entries = resolvedSource === "disk"
+            ? await readPersistedAuditSnapshot({ limit })
+            : getAuditSnapshot(limit);
+        const result = {
+            source: resolvedSource,
+            entries,
+        };
+        return ok(normalizeLargeDataResult("get_bridge_audit_log", controls, result));
+    });
+    server.tool("get_bridge_runtime_summary", "Return a compact Bridge runtime summary: plugin connection state, queue pressure, recent events/audit failures, MCP URL, auth flag, and recommendations. Use before heavy workflows.", {
+        auditLimit: z
+            .number()
+            .int()
+            .positive()
+            .max(200)
+            .optional()
+            .describe("Number of recent audit entries to summarize. Default: 50, max: 200."),
+    }, async ({ auditLimit }) => ok(buildBridgeRuntimeSummary({
+        queue,
+        sessionInfo: runtimeContext.getSessionInfo?.(),
+        bridgePort: runtimeContext.bridgePort,
+        auditLimit,
+    })));
+    server.tool("get_operator_runbook", "Return the machine-readable SXL Bridge operator runbook: start-here resources, safety rules, common workflows, preferred tools, dry-run gates, done criteria, release gates, and official Figma MCP companion handoff.", {}, async () => ok(SXL_OPERATOR_RUNBOOK));
+    server.tool("get_ultimate_readiness", "Return a requirement-by-requirement readiness audit for the Ultimate Bridge Toolkit plan: contract surface, SXL skills, Design DSL, analytics, database, variables/styles, compositions, documentation, Code Connect, production safety, and official Figma MCP parity. Does not execute plugin commands.", {}, async () => ok(buildUltimateReadinessAudit()));
+    server.tool("route_intent", "Route a natural-language SXL/Figma request to Bridge agent recipes, preferred tools, dry-run policy, and schema resources. Use this when the user's wording is broad or ambiguous.", {
+        request: z.string().min(1).describe("Natural-language user request in RU or EN."),
+        limit: z.number().int().positive().max(10).optional().describe("Max ranked routes to return. Default: 5."),
+    }, async ({ request, limit }) => ok(routeAgentIntent(request, { limit })));
+    server.tool("plan_workflow", "Build a Bridge-local workflow plan from a natural-language request: selected SXL recipe, resources, expected tools, dry-run gates, approval gates, and done criteria. Does not execute plugin commands.", {
+        request: z.string().min(1).describe("Natural-language user request in RU or EN."),
+        recipeId: z.string().optional().describe("Optional explicit SXL recipe id from route_intent."),
+    }, async ({ request, recipeId }) => ok(planWorkflow({ request, recipeId })));
+    server.tool("preview_workflow", "Validate a proposed Bridge tool sequence against the planned SXL workflow. Checks unknown tools, missing status/discovery/dry-run gates, and preferred-tool coverage. Does not execute plugin commands.", {
+        request: z.string().min(1).describe("Natural-language user request in RU or EN."),
+        recipeId: z.string().optional().describe("Optional explicit SXL recipe id from route_intent."),
+        proposedTools: z.array(z.string()).optional().describe("Simple proposed tool name sequence."),
+        proposedSteps: z
+            .array(z.object({ toolName: z.string(), dryRun: z.boolean().optional() }))
+            .optional()
+            .describe("Detailed proposed tool sequence with dryRun hints where known."),
+    }, async ({ request, recipeId, proposedTools, proposedSteps }) => ok(previewWorkflow({ request, recipeId, proposedTools, proposedSteps })));
+    server.tool("list_tools", "List all Bridge MCP tools with category, mode, execution, plugin command mapping, and routing metadata. Useful as a first call to discover the tool surface.", {
         category: z
             .string()
             .optional()
-            .describe("Filter by category: diagnostics | tokens | compositions | variables | styles | canvas | data | git | orchestration"),
+            .describe("Filter by category: diagnostics | tokens | compositions | variables | styles | canvas | figma-rest | data | git | orchestration"),
         devModeReadableOnly: z
             .boolean()
             .optional()
             .describe("If true, return only tools usable in Figma Dev Mode (requiresDesignMode: false)."),
     }, async ({ category, devModeReadableOnly }) => {
-        let entries = [...getBridgeToolCatalogue()];
-        if (category) {
-            entries = entries.filter((e) => e.category === category);
-        }
-        if (devModeReadableOnly) {
-            entries = entries.filter((e) => !e.requiresDesignMode);
-        }
+        const entries = listCatalogueTools({ category, devModeReadableOnly });
         return ok({
             count: entries.length,
             categories: Array.from(new Set(entries.map((e) => e.category))),
             tools: entries,
         });
     });
+    server.tool("get_capability_matrix", "Return the machine-readable Bridge capability matrix: tool metadata, execution mode (plugin / bridge-orchestration / bridge-local), plugin command types, mode requirements, dryRun support, and Bridge timeout. Use this for contract audits and agent routing.", {
+        category: z
+            .string()
+            .optional()
+            .describe("Optional category filter. Same semantics as list_tools and GET /api/capabilities?category=..."),
+        devModeReadableOnly: z
+            .boolean()
+            .optional()
+            .describe("If true, return only tools usable in Figma Dev Mode (requiresDesignMode: false)."),
+    }, async ({ category, devModeReadableOnly }) => {
+        return ok(buildCapabilityMatrix({ category, devModeReadableOnly }));
+    });
 }
 //# sourceMappingURL=meta.js.map

package/dist/tools/meta.js.map

@@ -1 +1 @@
-{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/tools/meta.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,sBAAsB,EAA2B,MAAM,eAAe,CAAC;AAChF,OAAO,EAAE,EAAE,EAAE,MAAM,aAAa,CAAC;AAEjC,MAAM,UAAU,iBAAiB,CAAC,MAAiB,EAAE,MAAoB;IACvE,MAAM,CAAC,IAAI,CACT,YAAY,EACZ,2HAA2H,EAC3H;QACE,QAAQ,EAAE,CAAC;aACR,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CACP,oHAAoH,CACrH;QACH,mBAAmB,EAAE,CAAC;aACnB,OAAO,EAAE;aACT,QAAQ,EAAE;aACV,QAAQ,CAAC,kFAAkF,CAAC;KAChG,EACD,KAAK,EAAE,EAAE,QAAQ,EAAE,mBAAmB,EAAE,EAAE,EAAE;QAC1C,IAAI,OAAO,GAAG,CAAC,GAAG,sBAAsB,EAAE,CAAC,CAAC;QAC5C,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAM,QAA+B,CAAC,CAAC;QACnF,CAAC;QACD,IAAI,mBAAmB,EAAE,CAAC;YACxB,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC;QACzD,CAAC;QACD,OAAO,EAAE,CAAC;YACR,KAAK,EAAE,OAAO,CAAC,MAAM;YACrB,UAAU,EAAE,KAAK,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC;YAC/D,KAAK,EAAE,OAAO;SACf,CAAC,CAAC;IACL,CAAC,CACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/tools/meta.ts"],"names":[],"mappings":"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"}

package/dist/tools/metadata.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "../../node_modules/@modelcontextprotocol/sdk/dist/cjs/server/mcp.js";
+import type { CommandQueue } from "../command-queue.js";
+export declare function registerMetadataTools(server: McpServer, queue: CommandQueue): void;

package/dist/tools/metadata.js

@@ -0,0 +1,140 @@
+import { z } from "zod";
+import { figmaRestGet, fileKeyFromArgs, FigmaRestError, } from "../figma-rest.js";
+import { largeDataResponseArgs, normalizeLargeDataResult } from "./large-data.js";
+import { err, executePluginCommand, ok } from "./shared.js";
+const metadataModeZod = z.enum(["auto", "plugin", "rest"]);
+const authModeZod = z.enum(["bearer", "x-figma-token"]);
+const tokenEnvZod = z
+    .string()
+    .regex(/^[A-Z0-9_]+$/)
+    .optional()
+    .describe("Environment variable containing the Figma REST token. Default: FIGMA_TOKEN, FIGMA_ACCESS_TOKEN, or FIGMA_REST_TOKEN.");
+function normalizeNodeIds(args) {
+    const ids = new Set();
+    if (args.nodeId?.trim())
+        ids.add(args.nodeId.trim());
+    for (const id of args.nodeIds ?? []) {
+        if (typeof id === "string" && id.trim())
+            ids.add(id.trim());
+    }
+    return Array.from(ids);
+}
+function restErrorResponse(error) {
+    if (error instanceof FigmaRestError) {
+        return err(error.message, {
+            code: "FIGMA_REST_ERROR",
+            status: error.status,
+            endpoint: error.endpoint,
+            body: error.body,
+            retryable: error.status === 429 || error.status >= 500,
+        });
+    }
+    return err(error instanceof Error ? error.message : String(error), {
+        code: "GET_METADATA_ERROR",
+        retryable: false,
+    });
+}
+async function getPluginMetadata(queue, args) {
+    const nodeIds = normalizeNodeIds(args);
+    const includeSelection = args.includeSelection !== false;
+    const includePageStructure = args.includePageStructure !== false;
+    const includePages = args.includePages === true;
+    if (nodeIds.length > 0) {
+        const nodes = [];
+        for (const nodeId of nodeIds) {
+            nodes.push(await executePluginCommand(queue, "get_node_tree", {
+                nodeId,
+                depth: args.depth ?? 3,
+            }));
+        }
+        return {
+            ok: true,
+            source: "plugin-node-tree",
+            nodeIds,
+            count: nodes.length,
+            nodes,
+        };
+    }
+    const result = {
+        ok: true,
+        source: "plugin-active-file",
+    };
+    if (includeSelection) {
+        result.selection = await executePluginCommand(queue, "get_selection_summary");
+    }
+    if (includePageStructure) {
+        result.pageStructure = await executePluginCommand(queue, "get_page_structure", {
+            maxDepth: args.depth ?? 3,
+        });
+    }
+    if (includePages) {
+        result.pages = await executePluginCommand(queue, "get_pages");
+    }
+    return result;
+}
+export function registerMetadataTools(server, queue) {
+    server.tool("get_metadata", "Bridge metadata tool. Use plugin mode for active-file selection/page/node tree metadata through Remote Connect; use REST mode with fileKey/url and optional nodeIds for hosted file metadata or node metadata. Auto mode picks REST when fileKey/url is provided, otherwise plugin.", {
+        mode: metadataModeZod.optional(),
+        nodeId: z.string().optional(),
+        nodeIds: z.array(z.string()).optional(),
+        depth: z.number().int().positive().max(20).optional(),
+        includeSelection: z.boolean().optional(),
+        includePageStructure: z.boolean().optional(),
+        includePages: z.boolean().optional(),
+        fileKey: z.string().optional().describe("Figma file key for REST metadata. Provide this or url for rest mode."),
+        url: z.string().url().optional().describe("Figma file/node URL. Used to extract fileKey when fileKey is omitted."),
+        geometry: z.enum(["paths"]).optional(),
+        pluginData: z.string().optional().describe("REST mode: comma-separated plugin ids or 'shared'."),
+        tokenEnv: tokenEnvZod,
+        authMode: authModeZod.optional().describe("Figma REST auth header mode. Default: FIGMA_AUTH_MODE or x-figma-token."),
+        apiBaseUrl: z.string().url().optional().describe("Figma REST API base URL. Default: https://api.figma.com."),
+        ...largeDataResponseArgs,
+    }, async (args) => {
+        const mode = args.mode ?? "auto";
+        const useRest = mode === "rest" || (mode === "auto" && Boolean(args.fileKey || args.url));
+        if (!useRest) {
+            try {
+                const result = await getPluginMetadata(queue, args);
+                return ok(normalizeLargeDataResult("get_metadata", args, result));
+            }
+            catch (error) {
+                return err(error instanceof Error ? error.message : String(error), {
+                    code: "GET_METADATA_PLUGIN_ERROR",
+                    retryable: /No plugin connected|Session disconnected/i.test(error instanceof Error ? error.message : String(error)),
+                });
+            }
+        }
+        try {
+            const fileKey = fileKeyFromArgs(args);
+            const nodeIds = normalizeNodeIds(args);
+            const endpoint = nodeIds.length > 0
+                ? `/v1/files/${fileKey}/nodes`
+                : `/v1/files/${fileKey}/meta`;
+            const body = await figmaRestGet(endpoint, {
+                tokenEnv: args.tokenEnv,
+                authMode: args.authMode,
+                apiBaseUrl: args.apiBaseUrl,
+                query: nodeIds.length > 0
+                    ? {
+                        ids: nodeIds.join(","),
+                        depth: args.depth,
+                        geometry: args.geometry,
+                        plugin_data: args.pluginData,
+                    }
+                    : undefined,
+            });
+            return ok(normalizeLargeDataResult("get_metadata", args, {
+                ok: true,
+                source: "figma-rest",
+                fileKey,
+                endpoint: nodeIds.length > 0 ? "nodes" : "meta",
+                nodeIds,
+                metadata: body,
+            }));
+        }
+        catch (error) {
+            return restErrorResponse(error);
+        }
+    });
+}
+//# sourceMappingURL=metadata.js.map

package/dist/tools/metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metadata.js","sourceRoot":"","sources":["../../src/tools/metadata.ts"],"names":[],"mappings":"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"}