@ufira/vibma 0.2.2 → 0.3.1

package/dist/tools/endpoint.cjs

@@ -0,0 +1,119 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tools/endpoint.ts
+var endpoint_exports = {};
+__export(endpoint_exports, {
+  createDispatcher: () => createDispatcher,
+  endpointSchema: () => endpointSchema,
+  paginate: () => paginate,
+  pickFields: () => pickFields
+});
+module.exports = __toCommonJS(endpoint_exports);
+var import_zod2 = require("zod");
+
+// src/utils/coercion.ts
+var import_zod = require("zod");
+var flexJson = (inner) => import_zod.z.preprocess((v) => {
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  }
+  return v;
+}, inner);
+
+// src/tools/endpoint.ts
+function pickFields(obj, fields) {
+  if (fields.includes("*")) return obj;
+  const keep = /* @__PURE__ */ new Set([...fields, "id", "name", "type"]);
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    if (keep.has(key)) out[key] = obj[key];
+  }
+  return out;
+}
+function paginate(items, offset = 0, limit = 100) {
+  const sliced = items.slice(offset, offset + limit);
+  return { totalCount: items.length, returned: sliced.length, offset, limit, items: sliced };
+}
+var DEFAULT_TIERS = {
+  get: "read",
+  list: "read",
+  create: "create",
+  update: "edit",
+  delete: "edit"
+};
+function endpointSchema(methods, capsOrExtra, extraOrTiers, methodTiers) {
+  let caps;
+  let extra;
+  if (capsOrExtra && "create" in capsOrExtra && "edit" in capsOrExtra && typeof capsOrExtra.create === "boolean") {
+    caps = capsOrExtra;
+    extra = extraOrTiers;
+  } else {
+    extra = capsOrExtra;
+  }
+  let filtered = methods;
+  if (caps) {
+    const tiers = { ...DEFAULT_TIERS, ...methodTiers };
+    filtered = methods.filter((m) => {
+      const tier = tiers[m] ?? "edit";
+      if (tier === "read") return true;
+      if (tier === "create") return caps.create;
+      if (tier === "edit") return caps.edit;
+      return false;
+    });
+  }
+  const schema = {
+    method: import_zod2.z.enum(filtered)
+  };
+  if (filtered.includes("get") || filtered.includes("delete")) {
+    schema.id = import_zod2.z.string().optional().describe("Resource ID (get, delete)");
+  }
+  if (filtered.includes("get") || filtered.includes("list")) {
+    schema.fields = flexJson(import_zod2.z.array(import_zod2.z.string())).optional().describe('Property whitelist (get/list). Identity fields (id, name, type) always included. Omit for stubs on list, full detail on get. Pass ["*"] for all fields.');
+  }
+  if (filtered.includes("list")) {
+    schema.offset = import_zod2.z.coerce.number().optional().describe("Skip N items for pagination (default 0)");
+    schema.limit = import_zod2.z.coerce.number().optional().describe("Max items per page (default 100)");
+  }
+  return { ...schema, ...extra };
+}
+function createDispatcher(handlers) {
+  const supported = Object.keys(handlers).join(", ");
+  return async (params) => {
+    const method = params.method;
+    const handler = handlers[method];
+    if (!handler) throw new Error(`Method '${method}' not supported. Available: ${supported}`);
+    let result = await handler(params);
+    if (method === "get" && params.fields?.length && result && typeof result === "object") {
+      result = pickFields(result, params.fields);
+    }
+    return result;
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createDispatcher,
+  endpointSchema,
+  paginate,
+  pickFields
+});
+//# sourceMappingURL=endpoint.cjs.map

package/dist/tools/endpoint.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/endpoint.ts","../../src/utils/coercion.ts"],"sourcesContent":["/**\n * Shared endpoint infrastructure.\n *\n * Every resource endpoint follows the same contract:\n *   create  → items[{...}]                        → { results: [{id}, ...] }\n *   get     → { id, fields? }                     → resource object (field-filtered)\n *   list    → { filters?, fields?, offset, limit } → { totalCount, returned, offset, limit, items: [...] }\n *   update  → items[{...}]                        → { results: [\"ok\", ...] }\n *   delete  → { id } or items[{id}]               → \"ok\" or { results: [\"ok\", ...] }\n *\n * MCP side:  endpointSchema()\n * Figma side: createDispatcher() + paginate()\n */\n\nimport { z } from \"zod\";\nimport { flexJson } from \"../utils/coercion\";\nimport type { Capabilities } from \"./types\";\n\n// ─── Method Types ────────────────────────────────────────────────\n\nexport type EndpointMethod = \"create\" | \"get\" | \"list\" | \"update\" | \"delete\";\n\n// ─── Response Types ──────────────────────────────────────────────\n\n/** Batch response envelope (create, update, delete). Produced by batchHandler. */\nexport interface BatchResponse<T = { id: string }> {\n  results: Array<T | \"ok\" | { error: string }>;\n  warnings?: string[];\n  deferred?: string;\n}\n\n/** Paginated list response envelope. */\nexport interface ListResponse<T = Record<string, any>> {\n  totalCount: number;\n  returned: number;\n  offset: number;\n  limit: number;\n  items: T[];\n}\n\n// ─── Discriminated Param Types ───────────────────────────────────\n//\n// Each endpoint specializes these with its own create/update item\n// types and list filters. Example:\n//\n//   type StyleParams = EndpointParams<StyleCreateItem, StyleUpdateItem, { type?: string }>;\n//\n\nexport type EndpointParams<\n  TCreate = Record<string, any>,\n  TUpdate = Record<string, any>,\n  TListFilters = Record<string, never>,\n> =\n  | { method: \"create\"; items: TCreate[] }\n  | { method: \"get\"; id: string; fields?: string[] }\n  | ({ method: \"list\"; fields?: string[]; offset?: number; limit?: number } & TListFilters)\n  | { method: \"update\"; items: TUpdate[] }\n  | { method: \"delete\"; id?: string; items?: Array<{ id: string }> };\n\n// ─── Helpers ────────────────────────────────────────────────────\n\n/**\n * Top-level field filter for get/list responses.\n * Always preserves identity fields (id, name, type).\n * Pass [\"*\"] to return all fields.\n */\nexport function pickFields(obj: Record<string, any>, fields: string[]): Record<string, any> {\n  if (fields.includes(\"*\")) return obj;\n  const keep = new Set([...fields, \"id\", \"name\", \"type\"]);\n  const out: Record<string, any> = {};\n  for (const key of Object.keys(obj)) {\n    if (keep.has(key)) out[key] = obj[key];\n  }\n  return out;\n}\n\n/**\n * Paginate an array of items. Default limit: 100.\n * Call from list handlers after assembling the full result set.\n */\nexport function paginate<T>(items: T[], offset = 0, limit = 100): ListResponse<T> {\n  const sliced = items.slice(offset, offset + limit);\n  return { totalCount: items.length, returned: sliced.length, offset, limit, items: sliced };\n}\n\n// ─── Schema Builder ──────────────────────────────────────────────\n\n/** Maps each endpoint method to the minimum tier required to use it. */\nexport type MethodTier = \"read\" | \"create\" | \"edit\";\n\nconst DEFAULT_TIERS: Record<string, MethodTier> = {\n  get: \"read\", list: \"read\", create: \"create\", update: \"edit\", delete: \"edit\",\n};\n\n/**\n * Build standard endpoint Zod schema fields.\n *\n * Always includes `method`. Auto-adds:\n * - `id` when get/delete are in the method list\n * - `fields` when get or list are in the method list\n * - `offset`/`limit` when list is in the method list\n * Merge endpoint-specific fields (items, list filters) via `extra`.\n *\n * When `caps` is provided, methods are filtered by tier — only methods\n * whose tier is enabled appear in the enum.\n */\nexport function endpointSchema(\n  methods: string[],\n  capsOrExtra?: Capabilities | Record<string, z.ZodTypeAny>,\n  extraOrTiers?: Record<string, z.ZodTypeAny>,\n  methodTiers?: Record<string, MethodTier>,\n): Record<string, z.ZodTypeAny> {\n  // Overload resolution: (methods, extra?) or (methods, caps, extra?, tiers?)\n  let caps: Capabilities | undefined;\n  let extra: Record<string, z.ZodTypeAny> | undefined;\n\n  if (capsOrExtra && (\"create\" in capsOrExtra) && (\"edit\" in capsOrExtra)\n      && typeof (capsOrExtra as any).create === \"boolean\") {\n    caps = capsOrExtra as Capabilities;\n    extra = extraOrTiers;\n  } else {\n    extra = capsOrExtra as Record<string, z.ZodTypeAny> | undefined;\n    // methodTiers and extraOrTiers are unused in the legacy call signature\n  }\n\n  // Filter methods by capabilities\n  let filtered = methods;\n  if (caps) {\n    const tiers = { ...DEFAULT_TIERS, ...methodTiers };\n    filtered = methods.filter(m => {\n      const tier = tiers[m] ?? \"edit\"; // unknown methods default to edit\n      if (tier === \"read\") return true;\n      if (tier === \"create\") return caps!.create;\n      if (tier === \"edit\") return caps!.edit;\n      return false;\n    });\n  }\n\n  const schema: Record<string, z.ZodTypeAny> = {\n    method: z.enum(filtered as [string, ...string[]]),\n  };\n  if (filtered.includes(\"get\") || filtered.includes(\"delete\")) {\n    schema.id = z.string().optional().describe(\"Resource ID (get, delete)\");\n  }\n  if (filtered.includes(\"get\") || filtered.includes(\"list\")) {\n    schema.fields = flexJson(z.array(z.string())).optional()\n      .describe('Property whitelist (get/list). Identity fields (id, name, type) always included. Omit for stubs on list, full detail on get. Pass [\"*\"] for all fields.');\n  }\n  if (filtered.includes(\"list\")) {\n    schema.offset = z.coerce.number().optional().describe(\"Skip N items for pagination (default 0)\");\n    schema.limit = z.coerce.number().optional().describe(\"Max items per page (default 100)\");\n  }\n  return { ...schema, ...extra };\n}\n\n// ─── Figma Dispatcher ────────────────────────────────────────────\n\ntype MethodHandlers = Record<string, (params: any) => Promise<any>>;\n\n/**\n * Create a Figma handler that dispatches on `params.method`.\n * Only methods with registered handlers are allowed.\n * Automatically applies `fields` filtering on get responses.\n */\nexport function createDispatcher(handlers: MethodHandlers) {\n  const supported = Object.keys(handlers).join(\", \");\n  return async (params: any): Promise<any> => {\n    const method = params.method as EndpointMethod;\n    const handler = handlers[method];\n    if (!handler) throw new Error(`Method '${method}' not supported. Available: ${supported}`);\n    let result = await handler(params);\n    // Auto-apply fields filtering on get responses (full detail by default)\n    if (method === \"get\" && params.fields?.length && result && typeof result === \"object\") {\n      result = pickFields(result, params.fields);\n    }\n    return result;\n  };\n}\n","import { z } from \"zod\";\n\n// AI agents (Claude, GPT, etc.) frequently pass numbers as strings\n// (\"10\" instead of 10), booleans as strings (\"true\" instead of true),\n// and objects/arrays as JSON strings. These helpers add resilient\n// coercion so tools don't fail on valid-but-mistyped input.\n\n/** Coerce \"true\"/\"false\"/\"1\"/\"0\" strings to boolean */\nexport const flexBool = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (v === \"true\" || v === \"1\") return true;\n    if (v === \"false\" || v === \"0\") return false;\n    return v;\n  }, inner);\n\n/** Coerce JSON strings to parsed values (for objects/arrays that agents may stringify) */\nexport const flexJson = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (typeof v === \"string\") {\n      try {\n        return JSON.parse(v);\n      } catch {\n        return v;\n      }\n    }\n    return v;\n  }, inner);\n\n/** Coerce numeric strings only when they're valid numbers (safe for use inside unions) */\nexport const flexNum = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (typeof v === \"string\") {\n      const n = Number(v);\n      if (!isNaN(n) && v.trim() !== \"\") return n;\n    }\n    return v;\n  }, inner);\n"],"mappings":"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","names":["import_zod"]}

package/dist/tools/endpoint.d.cts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { Capabilities } from './types.cjs';
+import '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Shared endpoint infrastructure.
+ *
+ * Every resource endpoint follows the same contract:
+ *   create  → items[{...}]                        → { results: [{id}, ...] }
+ *   get     → { id, fields? }                     → resource object (field-filtered)
+ *   list    → { filters?, fields?, offset, limit } → { totalCount, returned, offset, limit, items: [...] }
+ *   update  → items[{...}]                        → { results: ["ok", ...] }
+ *   delete  → { id } or items[{id}]               → "ok" or { results: ["ok", ...] }
+ *
+ * MCP side:  endpointSchema()
+ * Figma side: createDispatcher() + paginate()
+ */
+
+type EndpointMethod = "create" | "get" | "list" | "update" | "delete";
+/** Batch response envelope (create, update, delete). Produced by batchHandler. */
+interface BatchResponse<T = {
+    id: string;
+}> {
+    results: Array<T | "ok" | {
+        error: string;
+    }>;
+    warnings?: string[];
+    deferred?: string;
+}
+/** Paginated list response envelope. */
+interface ListResponse<T = Record<string, any>> {
+    totalCount: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    items: T[];
+}
+type EndpointParams<TCreate = Record<string, any>, TUpdate = Record<string, any>, TListFilters = Record<string, never>> = {
+    method: "create";
+    items: TCreate[];
+} | {
+    method: "get";
+    id: string;
+    fields?: string[];
+} | ({
+    method: "list";
+    fields?: string[];
+    offset?: number;
+    limit?: number;
+} & TListFilters) | {
+    method: "update";
+    items: TUpdate[];
+} | {
+    method: "delete";
+    id?: string;
+    items?: Array<{
+        id: string;
+    }>;
+};
+/**
+ * Top-level field filter for get/list responses.
+ * Always preserves identity fields (id, name, type).
+ * Pass ["*"] to return all fields.
+ */
+declare function pickFields(obj: Record<string, any>, fields: string[]): Record<string, any>;
+/**
+ * Paginate an array of items. Default limit: 100.
+ * Call from list handlers after assembling the full result set.
+ */
+declare function paginate<T>(items: T[], offset?: number, limit?: number): ListResponse<T>;
+/** Maps each endpoint method to the minimum tier required to use it. */
+type MethodTier = "read" | "create" | "edit";
+/**
+ * Build standard endpoint Zod schema fields.
+ *
+ * Always includes `method`. Auto-adds:
+ * - `id` when get/delete are in the method list
+ * - `fields` when get or list are in the method list
+ * - `offset`/`limit` when list is in the method list
+ * Merge endpoint-specific fields (items, list filters) via `extra`.
+ *
+ * When `caps` is provided, methods are filtered by tier — only methods
+ * whose tier is enabled appear in the enum.
+ */
+declare function endpointSchema(methods: string[], capsOrExtra?: Capabilities | Record<string, z.ZodTypeAny>, extraOrTiers?: Record<string, z.ZodTypeAny>, methodTiers?: Record<string, MethodTier>): Record<string, z.ZodTypeAny>;
+type MethodHandlers = Record<string, (params: any) => Promise<any>>;
+/**
+ * Create a Figma handler that dispatches on `params.method`.
+ * Only methods with registered handlers are allowed.
+ * Automatically applies `fields` filtering on get responses.
+ */
+declare function createDispatcher(handlers: MethodHandlers): (params: any) => Promise<any>;
+
+export { type BatchResponse, type EndpointMethod, type EndpointParams, type ListResponse, type MethodTier, createDispatcher, endpointSchema, paginate, pickFields };

package/dist/tools/endpoint.d.ts

@@ -0,0 +1,94 @@
+import { z } from 'zod';
+import { Capabilities } from './types.js';
+import '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Shared endpoint infrastructure.
+ *
+ * Every resource endpoint follows the same contract:
+ *   create  → items[{...}]                        → { results: [{id}, ...] }
+ *   get     → { id, fields? }                     → resource object (field-filtered)
+ *   list    → { filters?, fields?, offset, limit } → { totalCount, returned, offset, limit, items: [...] }
+ *   update  → items[{...}]                        → { results: ["ok", ...] }
+ *   delete  → { id } or items[{id}]               → "ok" or { results: ["ok", ...] }
+ *
+ * MCP side:  endpointSchema()
+ * Figma side: createDispatcher() + paginate()
+ */
+
+type EndpointMethod = "create" | "get" | "list" | "update" | "delete";
+/** Batch response envelope (create, update, delete). Produced by batchHandler. */
+interface BatchResponse<T = {
+    id: string;
+}> {
+    results: Array<T | "ok" | {
+        error: string;
+    }>;
+    warnings?: string[];
+    deferred?: string;
+}
+/** Paginated list response envelope. */
+interface ListResponse<T = Record<string, any>> {
+    totalCount: number;
+    returned: number;
+    offset: number;
+    limit: number;
+    items: T[];
+}
+type EndpointParams<TCreate = Record<string, any>, TUpdate = Record<string, any>, TListFilters = Record<string, never>> = {
+    method: "create";
+    items: TCreate[];
+} | {
+    method: "get";
+    id: string;
+    fields?: string[];
+} | ({
+    method: "list";
+    fields?: string[];
+    offset?: number;
+    limit?: number;
+} & TListFilters) | {
+    method: "update";
+    items: TUpdate[];
+} | {
+    method: "delete";
+    id?: string;
+    items?: Array<{
+        id: string;
+    }>;
+};
+/**
+ * Top-level field filter for get/list responses.
+ * Always preserves identity fields (id, name, type).
+ * Pass ["*"] to return all fields.
+ */
+declare function pickFields(obj: Record<string, any>, fields: string[]): Record<string, any>;
+/**
+ * Paginate an array of items. Default limit: 100.
+ * Call from list handlers after assembling the full result set.
+ */
+declare function paginate<T>(items: T[], offset?: number, limit?: number): ListResponse<T>;
+/** Maps each endpoint method to the minimum tier required to use it. */
+type MethodTier = "read" | "create" | "edit";
+/**
+ * Build standard endpoint Zod schema fields.
+ *
+ * Always includes `method`. Auto-adds:
+ * - `id` when get/delete are in the method list
+ * - `fields` when get or list are in the method list
+ * - `offset`/`limit` when list is in the method list
+ * Merge endpoint-specific fields (items, list filters) via `extra`.
+ *
+ * When `caps` is provided, methods are filtered by tier — only methods
+ * whose tier is enabled appear in the enum.
+ */
+declare function endpointSchema(methods: string[], capsOrExtra?: Capabilities | Record<string, z.ZodTypeAny>, extraOrTiers?: Record<string, z.ZodTypeAny>, methodTiers?: Record<string, MethodTier>): Record<string, z.ZodTypeAny>;
+type MethodHandlers = Record<string, (params: any) => Promise<any>>;
+/**
+ * Create a Figma handler that dispatches on `params.method`.
+ * Only methods with registered handlers are allowed.
+ * Automatically applies `fields` filtering on get responses.
+ */
+declare function createDispatcher(handlers: MethodHandlers): (params: any) => Promise<any>;
+
+export { type BatchResponse, type EndpointMethod, type EndpointParams, type ListResponse, type MethodTier, createDispatcher, endpointSchema, paginate, pickFields };

package/dist/tools/endpoint.js

@@ -0,0 +1,92 @@
+// src/tools/endpoint.ts
+import { z as z2 } from "zod";
+
+// src/utils/coercion.ts
+import { z } from "zod";
+var flexJson = (inner) => z.preprocess((v) => {
+  if (typeof v === "string") {
+    try {
+      return JSON.parse(v);
+    } catch {
+      return v;
+    }
+  }
+  return v;
+}, inner);
+
+// src/tools/endpoint.ts
+function pickFields(obj, fields) {
+  if (fields.includes("*")) return obj;
+  const keep = /* @__PURE__ */ new Set([...fields, "id", "name", "type"]);
+  const out = {};
+  for (const key of Object.keys(obj)) {
+    if (keep.has(key)) out[key] = obj[key];
+  }
+  return out;
+}
+function paginate(items, offset = 0, limit = 100) {
+  const sliced = items.slice(offset, offset + limit);
+  return { totalCount: items.length, returned: sliced.length, offset, limit, items: sliced };
+}
+var DEFAULT_TIERS = {
+  get: "read",
+  list: "read",
+  create: "create",
+  update: "edit",
+  delete: "edit"
+};
+function endpointSchema(methods, capsOrExtra, extraOrTiers, methodTiers) {
+  let caps;
+  let extra;
+  if (capsOrExtra && "create" in capsOrExtra && "edit" in capsOrExtra && typeof capsOrExtra.create === "boolean") {
+    caps = capsOrExtra;
+    extra = extraOrTiers;
+  } else {
+    extra = capsOrExtra;
+  }
+  let filtered = methods;
+  if (caps) {
+    const tiers = { ...DEFAULT_TIERS, ...methodTiers };
+    filtered = methods.filter((m) => {
+      const tier = tiers[m] ?? "edit";
+      if (tier === "read") return true;
+      if (tier === "create") return caps.create;
+      if (tier === "edit") return caps.edit;
+      return false;
+    });
+  }
+  const schema = {
+    method: z2.enum(filtered)
+  };
+  if (filtered.includes("get") || filtered.includes("delete")) {
+    schema.id = z2.string().optional().describe("Resource ID (get, delete)");
+  }
+  if (filtered.includes("get") || filtered.includes("list")) {
+    schema.fields = flexJson(z2.array(z2.string())).optional().describe('Property whitelist (get/list). Identity fields (id, name, type) always included. Omit for stubs on list, full detail on get. Pass ["*"] for all fields.');
+  }
+  if (filtered.includes("list")) {
+    schema.offset = z2.coerce.number().optional().describe("Skip N items for pagination (default 0)");
+    schema.limit = z2.coerce.number().optional().describe("Max items per page (default 100)");
+  }
+  return { ...schema, ...extra };
+}
+function createDispatcher(handlers) {
+  const supported = Object.keys(handlers).join(", ");
+  return async (params) => {
+    const method = params.method;
+    const handler = handlers[method];
+    if (!handler) throw new Error(`Method '${method}' not supported. Available: ${supported}`);
+    let result = await handler(params);
+    if (method === "get" && params.fields?.length && result && typeof result === "object") {
+      result = pickFields(result, params.fields);
+    }
+    return result;
+  };
+}
+export {
+  createDispatcher,
+  endpointSchema,
+  paginate,
+  pickFields
+};
+//# sourceMappingURL=endpoint.js.map

package/dist/tools/endpoint.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/endpoint.ts","../../src/utils/coercion.ts"],"sourcesContent":["/**\n * Shared endpoint infrastructure.\n *\n * Every resource endpoint follows the same contract:\n *   create  → items[{...}]                        → { results: [{id}, ...] }\n *   get     → { id, fields? }                     → resource object (field-filtered)\n *   list    → { filters?, fields?, offset, limit } → { totalCount, returned, offset, limit, items: [...] }\n *   update  → items[{...}]                        → { results: [\"ok\", ...] }\n *   delete  → { id } or items[{id}]               → \"ok\" or { results: [\"ok\", ...] }\n *\n * MCP side:  endpointSchema()\n * Figma side: createDispatcher() + paginate()\n */\n\nimport { z } from \"zod\";\nimport { flexJson } from \"../utils/coercion\";\nimport type { Capabilities } from \"./types\";\n\n// ─── Method Types ────────────────────────────────────────────────\n\nexport type EndpointMethod = \"create\" | \"get\" | \"list\" | \"update\" | \"delete\";\n\n// ─── Response Types ──────────────────────────────────────────────\n\n/** Batch response envelope (create, update, delete). Produced by batchHandler. */\nexport interface BatchResponse<T = { id: string }> {\n  results: Array<T | \"ok\" | { error: string }>;\n  warnings?: string[];\n  deferred?: string;\n}\n\n/** Paginated list response envelope. */\nexport interface ListResponse<T = Record<string, any>> {\n  totalCount: number;\n  returned: number;\n  offset: number;\n  limit: number;\n  items: T[];\n}\n\n// ─── Discriminated Param Types ───────────────────────────────────\n//\n// Each endpoint specializes these with its own create/update item\n// types and list filters. Example:\n//\n//   type StyleParams = EndpointParams<StyleCreateItem, StyleUpdateItem, { type?: string }>;\n//\n\nexport type EndpointParams<\n  TCreate = Record<string, any>,\n  TUpdate = Record<string, any>,\n  TListFilters = Record<string, never>,\n> =\n  | { method: \"create\"; items: TCreate[] }\n  | { method: \"get\"; id: string; fields?: string[] }\n  | ({ method: \"list\"; fields?: string[]; offset?: number; limit?: number } & TListFilters)\n  | { method: \"update\"; items: TUpdate[] }\n  | { method: \"delete\"; id?: string; items?: Array<{ id: string }> };\n\n// ─── Helpers ────────────────────────────────────────────────────\n\n/**\n * Top-level field filter for get/list responses.\n * Always preserves identity fields (id, name, type).\n * Pass [\"*\"] to return all fields.\n */\nexport function pickFields(obj: Record<string, any>, fields: string[]): Record<string, any> {\n  if (fields.includes(\"*\")) return obj;\n  const keep = new Set([...fields, \"id\", \"name\", \"type\"]);\n  const out: Record<string, any> = {};\n  for (const key of Object.keys(obj)) {\n    if (keep.has(key)) out[key] = obj[key];\n  }\n  return out;\n}\n\n/**\n * Paginate an array of items. Default limit: 100.\n * Call from list handlers after assembling the full result set.\n */\nexport function paginate<T>(items: T[], offset = 0, limit = 100): ListResponse<T> {\n  const sliced = items.slice(offset, offset + limit);\n  return { totalCount: items.length, returned: sliced.length, offset, limit, items: sliced };\n}\n\n// ─── Schema Builder ──────────────────────────────────────────────\n\n/** Maps each endpoint method to the minimum tier required to use it. */\nexport type MethodTier = \"read\" | \"create\" | \"edit\";\n\nconst DEFAULT_TIERS: Record<string, MethodTier> = {\n  get: \"read\", list: \"read\", create: \"create\", update: \"edit\", delete: \"edit\",\n};\n\n/**\n * Build standard endpoint Zod schema fields.\n *\n * Always includes `method`. Auto-adds:\n * - `id` when get/delete are in the method list\n * - `fields` when get or list are in the method list\n * - `offset`/`limit` when list is in the method list\n * Merge endpoint-specific fields (items, list filters) via `extra`.\n *\n * When `caps` is provided, methods are filtered by tier — only methods\n * whose tier is enabled appear in the enum.\n */\nexport function endpointSchema(\n  methods: string[],\n  capsOrExtra?: Capabilities | Record<string, z.ZodTypeAny>,\n  extraOrTiers?: Record<string, z.ZodTypeAny>,\n  methodTiers?: Record<string, MethodTier>,\n): Record<string, z.ZodTypeAny> {\n  // Overload resolution: (methods, extra?) or (methods, caps, extra?, tiers?)\n  let caps: Capabilities | undefined;\n  let extra: Record<string, z.ZodTypeAny> | undefined;\n\n  if (capsOrExtra && (\"create\" in capsOrExtra) && (\"edit\" in capsOrExtra)\n      && typeof (capsOrExtra as any).create === \"boolean\") {\n    caps = capsOrExtra as Capabilities;\n    extra = extraOrTiers;\n  } else {\n    extra = capsOrExtra as Record<string, z.ZodTypeAny> | undefined;\n    // methodTiers and extraOrTiers are unused in the legacy call signature\n  }\n\n  // Filter methods by capabilities\n  let filtered = methods;\n  if (caps) {\n    const tiers = { ...DEFAULT_TIERS, ...methodTiers };\n    filtered = methods.filter(m => {\n      const tier = tiers[m] ?? \"edit\"; // unknown methods default to edit\n      if (tier === \"read\") return true;\n      if (tier === \"create\") return caps!.create;\n      if (tier === \"edit\") return caps!.edit;\n      return false;\n    });\n  }\n\n  const schema: Record<string, z.ZodTypeAny> = {\n    method: z.enum(filtered as [string, ...string[]]),\n  };\n  if (filtered.includes(\"get\") || filtered.includes(\"delete\")) {\n    schema.id = z.string().optional().describe(\"Resource ID (get, delete)\");\n  }\n  if (filtered.includes(\"get\") || filtered.includes(\"list\")) {\n    schema.fields = flexJson(z.array(z.string())).optional()\n      .describe('Property whitelist (get/list). Identity fields (id, name, type) always included. Omit for stubs on list, full detail on get. Pass [\"*\"] for all fields.');\n  }\n  if (filtered.includes(\"list\")) {\n    schema.offset = z.coerce.number().optional().describe(\"Skip N items for pagination (default 0)\");\n    schema.limit = z.coerce.number().optional().describe(\"Max items per page (default 100)\");\n  }\n  return { ...schema, ...extra };\n}\n\n// ─── Figma Dispatcher ────────────────────────────────────────────\n\ntype MethodHandlers = Record<string, (params: any) => Promise<any>>;\n\n/**\n * Create a Figma handler that dispatches on `params.method`.\n * Only methods with registered handlers are allowed.\n * Automatically applies `fields` filtering on get responses.\n */\nexport function createDispatcher(handlers: MethodHandlers) {\n  const supported = Object.keys(handlers).join(\", \");\n  return async (params: any): Promise<any> => {\n    const method = params.method as EndpointMethod;\n    const handler = handlers[method];\n    if (!handler) throw new Error(`Method '${method}' not supported. Available: ${supported}`);\n    let result = await handler(params);\n    // Auto-apply fields filtering on get responses (full detail by default)\n    if (method === \"get\" && params.fields?.length && result && typeof result === \"object\") {\n      result = pickFields(result, params.fields);\n    }\n    return result;\n  };\n}\n","import { z } from \"zod\";\n\n// AI agents (Claude, GPT, etc.) frequently pass numbers as strings\n// (\"10\" instead of 10), booleans as strings (\"true\" instead of true),\n// and objects/arrays as JSON strings. These helpers add resilient\n// coercion so tools don't fail on valid-but-mistyped input.\n\n/** Coerce \"true\"/\"false\"/\"1\"/\"0\" strings to boolean */\nexport const flexBool = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (v === \"true\" || v === \"1\") return true;\n    if (v === \"false\" || v === \"0\") return false;\n    return v;\n  }, inner);\n\n/** Coerce JSON strings to parsed values (for objects/arrays that agents may stringify) */\nexport const flexJson = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (typeof v === \"string\") {\n      try {\n        return JSON.parse(v);\n      } catch {\n        return v;\n      }\n    }\n    return v;\n  }, inner);\n\n/** Coerce numeric strings only when they're valid numbers (safe for use inside unions) */\nexport const flexNum = <T extends z.ZodTypeAny>(inner: T) =>\n  z.preprocess((v) => {\n    if (typeof v === \"string\") {\n      const n = Number(v);\n      if (!isNaN(n) && v.trim() !== \"\") return n;\n    }\n    return v;\n  }, inner);\n"],"mappings":"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","names":["z","z"]}

package/dist/tools/registry.cjs

@@ -0,0 +1,73 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/tools/registry.ts
+var registry_exports = {};
+__export(registry_exports, {
+  registerTools: () => registerTools
+});
+module.exports = __toCommonJS(registry_exports);
+
+// src/tools/types.ts
+var MAX_RESPONSE_CHARS = 5e4;
+function mcpJson(data) {
+  const text = JSON.stringify(data);
+  if (text.length <= MAX_RESPONSE_CHARS) {
+    return { content: [{ type: "text", text }] };
+  }
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        _error: "response_too_large",
+        _sizeKB: Math.round(text.length / 1024),
+        warning: "Response exceeds safe size. Use 'depth', 'fields', 'limit', or 'summaryOnly' parameters to reduce response size."
+      })
+    }]
+  };
+}
+function mcpError(prefix, error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: `${prefix}: ${msg}` }] };
+}
+
+// src/tools/registry.ts
+function registerTools(server, sendCommand, caps, tools) {
+  for (const tool of tools) {
+    if (tool.tier === "create" && !caps.create) continue;
+    if (tool.tier === "edit" && !caps.edit) continue;
+    const schema = typeof tool.schema === "function" ? tool.schema(caps) : tool.schema;
+    const command = tool.command ?? tool.name;
+    const timeout = tool.timeout;
+    const format = tool.formatResponse ?? mcpJson;
+    server.registerTool(tool.name, { description: tool.description, inputSchema: schema }, async (params) => {
+      try {
+        if (tool.validate) tool.validate(params);
+        const result = await sendCommand(command, params, timeout);
+        return format(result);
+      } catch (e) {
+        return mcpError(`${tool.name} error`, e);
+      }
+    });
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  registerTools
+});
+//# sourceMappingURL=registry.cjs.map

package/dist/tools/registry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/registry.ts","../../src/tools/types.ts"],"sourcesContent":["import type { McpServer, SendCommandFn, Capabilities, ToolDef } from \"./types\";\nimport { mcpJson, mcpError } from \"./types\";\n\n/**\n * Batch-register declarative ToolDefs on the MCP server.\n *\n * 1. Filters by tier:  read → always,  create → caps.create,  edit → caps.edit\n * 2. Resolves dynamic schemas (endpoint tools pass caps-dependent functions)\n * 3. Generates a uniform handler: validate? → sendCommand → formatResponse ?? mcpJson\n */\nexport function registerTools(\n  server: McpServer,\n  sendCommand: SendCommandFn,\n  caps: Capabilities,\n  tools: ToolDef[],\n): void {\n  for (const tool of tools) {\n    // Tier gate\n    if (tool.tier === \"create\" && !caps.create) continue;\n    if (tool.tier === \"edit\" && !caps.edit) continue;\n\n    const schema = typeof tool.schema === \"function\" ? tool.schema(caps) : tool.schema;\n    const command = tool.command ?? tool.name;\n    const timeout = tool.timeout;\n    const format = tool.formatResponse ?? mcpJson;\n\n    server.registerTool(tool.name, { description: tool.description, inputSchema: schema }, async (params: any) => {\n      try {\n        if (tool.validate) tool.validate(params);\n        const result = await sendCommand(command, params, timeout);\n        return format(result);\n      } catch (e) {\n        return mcpError(`${tool.name} error`, e);\n      }\n    });\n  }\n}\n","import type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { z } from \"zod\";\n\n/** Function signature for sending commands to Figma via WebSocket */\nexport type SendCommandFn = (command: string, params?: unknown, timeoutMs?: number) => Promise<unknown>;\n\n/** Re-export McpServer type for tool files */\nexport type { McpServer };\n\n// ─── Tool Registry Types ────────────────────────────────────────\n\n/** Access tier for a tool */\nexport type ToolTier = \"read\" | \"create\" | \"edit\";\n\n/** Which tiers are enabled for this MCP session */\nexport interface Capabilities { create: boolean; edit: boolean }\n\n/** Declarative tool definition — replaces imperative registerMcpTools() */\nexport interface ToolDef {\n  name: string;\n  description: string;\n  schema: Record<string, z.ZodTypeAny>\n        | ((caps: Capabilities) => Record<string, z.ZodTypeAny>);\n  tier: ToolTier;\n  /** Figma command name. Defaults to name. */\n  command?: string;\n  /** sendCommand timeout in ms (default: 30 000) */\n  timeout?: number;\n  /** Pre-send validation (e.g. per-method item parsing for endpoints) */\n  validate?: (params: any) => void;\n  /** Custom response formatter. Default: mcpJson */\n  formatResponse?: (result: unknown) => any;\n}\n\n/** Standard batch result from Figma handlers */\nexport interface BatchResult<T = unknown> {\n  results: Array<T | \"ok\" | { error: string }>;\n  warnings?: string[];\n  /** Set when some items were deferred (e.g. font loading cap exceeded) */\n  deferred?: string;\n}\n\n/** Max response size in characters (~12K tokens). Prevents LLM client-side truncation that corrupts JSON. */\nconst MAX_RESPONSE_CHARS = 50_000;\n\n/** Format a successful MCP response (JSON). Returns a clean error if response exceeds safe size. */\nexport function mcpJson(data: unknown) {\n  const text = JSON.stringify(data);\n  if (text.length <= MAX_RESPONSE_CHARS) {\n    return { content: [{ type: \"text\" as const, text }] };\n  }\n  return {\n    content: [{\n      type: \"text\" as const,\n      text: JSON.stringify({\n        _error: \"response_too_large\",\n        _sizeKB: Math.round(text.length / 1024),\n        warning: \"Response exceeds safe size. Use 'depth', 'fields', 'limit', or 'summaryOnly' parameters to reduce response size.\",\n      }),\n    }],\n  };\n}\n\n/** Format an error MCP response */\nexport function mcpError(prefix: string, error: unknown) {\n  const msg = error instanceof Error ? error.message : String(error);\n  return { content: [{ type: \"text\" as const, text: `${prefix}: ${msg}` }] };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;AC2CA,IAAM,qBAAqB;AAGpB,SAAS,QAAQ,MAAe;AACrC,QAAM,OAAO,KAAK,UAAU,IAAI;AAChC,MAAI,KAAK,UAAU,oBAAoB;AACrC,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACA,SAAO;AAAA,IACL,SAAS,CAAC;AAAA,MACR,MAAM;AAAA,MACN,MAAM,KAAK,UAAU;AAAA,QACnB,QAAQ;AAAA,QACR,SAAS,KAAK,MAAM,KAAK,SAAS,IAAI;AAAA,QACtC,SAAS;AAAA,MACX,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AACF;AAGO,SAAS,SAAS,QAAgB,OAAgB;AACvD,QAAM,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACjE,SAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,GAAG,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE;AAC3E;;;ADzDO,SAAS,cACd,QACA,aACA,MACA,OACM;AACN,aAAW,QAAQ,OAAO;AAExB,QAAI,KAAK,SAAS,YAAY,CAAC,KAAK,OAAQ;AAC5C,QAAI,KAAK,SAAS,UAAU,CAAC,KAAK,KAAM;AAExC,UAAM,SAAS,OAAO,KAAK,WAAW,aAAa,KAAK,OAAO,IAAI,IAAI,KAAK;AAC5E,UAAM,UAAU,KAAK,WAAW,KAAK;AACrC,UAAM,UAAU,KAAK;AACrB,UAAM,SAAS,KAAK,kBAAkB;AAEtC,WAAO,aAAa,KAAK,MAAM,EAAE,aAAa,KAAK,aAAa,aAAa,OAAO,GAAG,OAAO,WAAgB;AAC5G,UAAI;AACF,YAAI,KAAK,SAAU,MAAK,SAAS,MAAM;AACvC,cAAM,SAAS,MAAM,YAAY,SAAS,QAAQ,OAAO;AACzD,eAAO,OAAO,MAAM;AAAA,MACtB,SAAS,GAAG;AACV,eAAO,SAAS,GAAG,KAAK,IAAI,UAAU,CAAC;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}

package/dist/tools/registry.d.cts

@@ -0,0 +1,14 @@
+import { SendCommandFn, Capabilities, ToolDef } from './types.cjs';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import 'zod';
+
+/**
+ * Batch-register declarative ToolDefs on the MCP server.
+ *
+ * 1. Filters by tier:  read → always,  create → caps.create,  edit → caps.edit
+ * 2. Resolves dynamic schemas (endpoint tools pass caps-dependent functions)
+ * 3. Generates a uniform handler: validate? → sendCommand → formatResponse ?? mcpJson
+ */
+declare function registerTools(server: McpServer, sendCommand: SendCommandFn, caps: Capabilities, tools: ToolDef[]): void;
+
+export { registerTools };

package/dist/tools/registry.d.ts

@@ -0,0 +1,14 @@
+import { SendCommandFn, Capabilities, ToolDef } from './types.js';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import 'zod';
+
+/**
+ * Batch-register declarative ToolDefs on the MCP server.
+ *
+ * 1. Filters by tier:  read → always,  create → caps.create,  edit → caps.edit
+ * 2. Resolves dynamic schemas (endpoint tools pass caps-dependent functions)
+ * 3. Generates a uniform handler: validate? → sendCommand → formatResponse ?? mcpJson
+ */
+declare function registerTools(server: McpServer, sendCommand: SendCommandFn, caps: Capabilities, tools: ToolDef[]): void;
+
+export { registerTools };

package/dist/tools/registry.js

@@ -0,0 +1,47 @@
+// src/tools/types.ts
+var MAX_RESPONSE_CHARS = 5e4;
+function mcpJson(data) {
+  const text = JSON.stringify(data);
+  if (text.length <= MAX_RESPONSE_CHARS) {
+    return { content: [{ type: "text", text }] };
+  }
+  return {
+    content: [{
+      type: "text",
+      text: JSON.stringify({
+        _error: "response_too_large",
+        _sizeKB: Math.round(text.length / 1024),
+        warning: "Response exceeds safe size. Use 'depth', 'fields', 'limit', or 'summaryOnly' parameters to reduce response size."
+      })
+    }]
+  };
+}
+function mcpError(prefix, error) {
+  const msg = error instanceof Error ? error.message : String(error);
+  return { content: [{ type: "text", text: `${prefix}: ${msg}` }] };
+}
+
+// src/tools/registry.ts
+function registerTools(server, sendCommand, caps, tools) {
+  for (const tool of tools) {
+    if (tool.tier === "create" && !caps.create) continue;
+    if (tool.tier === "edit" && !caps.edit) continue;
+    const schema = typeof tool.schema === "function" ? tool.schema(caps) : tool.schema;
+    const command = tool.command ?? tool.name;
+    const timeout = tool.timeout;
+    const format = tool.formatResponse ?? mcpJson;
+    server.registerTool(tool.name, { description: tool.description, inputSchema: schema }, async (params) => {
+      try {
+        if (tool.validate) tool.validate(params);
+        const result = await sendCommand(command, params, timeout);
+        return format(result);
+      } catch (e) {
+        return mcpError(`${tool.name} error`, e);
+      }
+    });
+  }
+}
+export {
+  registerTools
+};
+//# sourceMappingURL=registry.js.map

package/dist/tools/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/tools/types.ts","../../src/tools/registry.ts"],"sourcesContent":["import type { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport type { z } from \"zod\";\n\n/** Function signature for sending commands to Figma via WebSocket */\nexport type SendCommandFn = (command: string, params?: unknown, timeoutMs?: number) => Promise<unknown>;\n\n/** Re-export McpServer type for tool files */\nexport type { McpServer };\n\n// ─── Tool Registry Types ────────────────────────────────────────\n\n/** Access tier for a tool */\nexport type ToolTier = \"read\" | \"create\" | \"edit\";\n\n/** Which tiers are enabled for this MCP session */\nexport interface Capabilities { create: boolean; edit: boolean }\n\n/** Declarative tool definition — replaces imperative registerMcpTools() */\nexport interface ToolDef {\n  name: string;\n  description: string;\n  schema: Record<string, z.ZodTypeAny>\n        | ((caps: Capabilities) => Record<string, z.ZodTypeAny>);\n  tier: ToolTier;\n  /** Figma command name. Defaults to name. */\n  command?: string;\n  /** sendCommand timeout in ms (default: 30 000) */\n  timeout?: number;\n  /** Pre-send validation (e.g. per-method item parsing for endpoints) */\n  validate?: (params: any) => void;\n  /** Custom response formatter. Default: mcpJson */\n  formatResponse?: (result: unknown) => any;\n}\n\n/** Standard batch result from Figma handlers */\nexport interface BatchResult<T = unknown> {\n  results: Array<T | \"ok\" | { error: string }>;\n  warnings?: string[];\n  /** Set when some items were deferred (e.g. font loading cap exceeded) */\n  deferred?: string;\n}\n\n/** Max response size in characters (~12K tokens). Prevents LLM client-side truncation that corrupts JSON. */\nconst MAX_RESPONSE_CHARS = 50_000;\n\n/** Format a successful MCP response (JSON). Returns a clean error if response exceeds safe size. */\nexport function mcpJson(data: unknown) {\n  const text = JSON.stringify(data);\n  if (text.length <= MAX_RESPONSE_CHARS) {\n    return { content: [{ type: \"text\" as const, text }] };\n  }\n  return {\n    content: [{\n      type: \"text\" as const,\n      text: JSON.stringify({\n        _error: \"response_too_large\",\n        _sizeKB: Math.round(text.length / 1024),\n        warning: \"Response exceeds safe size. Use 'depth', 'fields', 'limit', or 'summaryOnly' parameters to reduce response size.\",\n      }),\n    }],\n  };\n}\n\n/** Format an error MCP response */\nexport function mcpError(prefix: string, error: unknown) {\n  const msg = error instanceof Error ? error.message : String(error);\n  return { content: [{ type: \"text\" as const, text: `${prefix}: ${msg}` }] };\n}\n","import type { McpServer, SendCommandFn, Capabilities, ToolDef } from \"./types\";\nimport { mcpJson, mcpError } from \"./types\";\n\n/**\n * Batch-register declarative ToolDefs on the MCP server.\n *\n * 1. Filters by tier:  read → always,  create → caps.create,  edit → caps.edit\n * 2. Resolves dynamic schemas (endpoint tools pass caps-dependent functions)\n * 3. Generates a uniform handler: validate? → sendCommand → formatResponse ?? mcpJson\n */\nexport function registerTools(\n  server: McpServer,\n  sendCommand: SendCommandFn,\n  caps: Capabilities,\n  tools: ToolDef[],\n): void {\n  for (const tool of tools) {\n    // Tier gate\n    if (tool.tier === \"create\" && !caps.create) continue;\n    if (tool.tier === \"edit\" && !caps.edit) continue;\n\n    const schema = typeof tool.schema === \"function\" ? tool.schema(caps) : tool.schema;\n    const command = tool.command ?? tool.name;\n    const timeout = tool.timeout;\n    const format = tool.formatResponse ?? mcpJson;\n\n    server.registerTool(tool.name, { description: tool.description, inputSchema: schema }, async (params: any) => {\n      try {\n        if (tool.validate) tool.validate(params);\n        const result = await sendCommand(command, params, timeout);\n        return format(result);\n      } catch (e) {\n        return mcpError(`${tool.name} error`, e);\n      }\n    });\n  }\n}\n"],"mappings":";AA2CA,IAAM,qBAAqB;AAGpB,SAAS,QAAQ,MAAe;AACrC,QAAM,OAAO,KAAK,UAAU,IAAI;AAChC,MAAI,KAAK,UAAU,oBAAoB;AACrC,WAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,KAAK,CAAC,EAAE;AAAA,EACtD;AACA,SAAO;AAAA,IACL,SAAS,CAAC;AAAA,MACR,MAAM;AAAA,MACN,MAAM,KAAK,UAAU;AAAA,QACnB,QAAQ;AAAA,QACR,SAAS,KAAK,MAAM,KAAK,SAAS,IAAI;AAAA,QACtC,SAAS;AAAA,MACX,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AACF;AAGO,SAAS,SAAS,QAAgB,OAAgB;AACvD,QAAM,MAAM,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;AACjE,SAAO,EAAE,SAAS,CAAC,EAAE,MAAM,QAAiB,MAAM,GAAG,MAAM,KAAK,GAAG,GAAG,CAAC,EAAE;AAC3E;;;ACzDO,SAAS,cACd,QACA,aACA,MACA,OACM;AACN,aAAW,QAAQ,OAAO;AAExB,QAAI,KAAK,SAAS,YAAY,CAAC,KAAK,OAAQ;AAC5C,QAAI,KAAK,SAAS,UAAU,CAAC,KAAK,KAAM;AAExC,UAAM,SAAS,OAAO,KAAK,WAAW,aAAa,KAAK,OAAO,IAAI,IAAI,KAAK;AAC5E,UAAM,UAAU,KAAK,WAAW,KAAK;AACrC,UAAM,UAAU,KAAK;AACrB,UAAM,SAAS,KAAK,kBAAkB;AAEtC,WAAO,aAAa,KAAK,MAAM,EAAE,aAAa,KAAK,aAAa,aAAa,OAAO,GAAG,OAAO,WAAgB;AAC5G,UAAI;AACF,YAAI,KAAK,SAAU,MAAK,SAAS,MAAM;AACvC,cAAM,SAAS,MAAM,YAAY,SAAS,QAAQ,OAAO;AACzD,eAAO,OAAO,MAAM;AAAA,MACtB,SAAS,GAAG;AACV,eAAO,SAAS,GAAG,KAAK,IAAI,UAAU,CAAC;AAAA,MACzC;AAAA,IACF,CAAC;AAAA,EACH;AACF;","names":[]}