@ikas/code-components-mcp 1.4.0-beta.43 → 1.4.0-beta.45

package/dist/index.js

@@ -1838,7 +1838,7 @@ const server = new McpServer({
     version: "0.1.0",
 }, {
     instructions: "Examples and section templates from this server are API reference only — reuse imports, function calls, and data-access patterns; create your own JSX structure, CSS class names, and visual design.\n\n" +
-        "Live-editor actions (require `ikas-component dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content; it also accepts DYNAMIC bindings per prop, not just static values); `get_available_values` → list the dynamic values (variables / per-item COMPONENT_LIST loop fields) bindable to a prop — bind one by passing its `ref` as an `update_page_sections` update `{ prop_id, ref, list_path? }` instead of a static `value`; `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish). For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
+        "Live-editor actions (require `ikas-component dev` running with the editor connected): `list_editor_pages` → page ids; `list_imported_sections` → imported component ids; `import_section` → import a built component; `add_section_to_page` → place one section (`add_sections_to_page` places MANY at once and can set their props in the same call — fastest way to build a page); `list_page_sections` → the sections placed on a page (LEAN roster: per-placement `elementId`, `componentId`, `propCount`, which props are filled — NO schema/values, so it never truncates); `get_component_props` → a component's prop blueprint (types, ENUM valid `options`, COMPONENT_LIST `allowedComponentIds`) for any section OR child id; `get_section_values` → one section's current prop values (for read-modify-write); `get_page_by_type` → a theme page id by pageType (e.g. CATEGORY), to build PAGE links to entities (`create_page` adds that page if it does not exist yet, so you never guess a slug); `update_section_prop` → change a single prop value of a placed section (`update_page_sections` fills MANY sections/props of a page in ONE call — strongly prefer it to cut round-trips when filling content); `upload_image` → upload one image (file or URL) and get an image id (`upload_images` uploads many in one call — prefer it for several); `search_products` / `list_categories` / `list_brands` / `list_blogs` / `list_blog_categories` → find real entity ids for PRODUCT/CATEGORY/BRAND/BLOG/BLOG_CATEGORY prop values; `publish_theme` → publish the theme LIVE and get back the preview URL to review (guarded — needs `confirm:true`, and `confirm_production:true` for the main theme; only call it when the user explicitly asks to publish). For the full end-to-end process (placing a section and filling its content, with per-prop value shapes and COMPONENT_LIST rules), call `get_editor_workflow` first.\n\n" +
         "To CHANGE/EDIT a prop value (text, color, boolean, number, etc.) of a section that is already on a page, this IS supported: call `list_page_sections(page_id)` to get the placement `elementId` and the prop names/ids, then `update_section_prop(page_id, element_id, prop_name|prop_id, value)`. Do not assume prop editing is unavailable.\n\n" +
         "TWO DISTINCT JOBS — do not confuse them, and do not jump to writing code for the second one:\n" +
         "(A) DEFINING props / authoring a component = changing which props a component HAS. This edits the component source/config (types.ts via `ikas-component config add-prop`/`add-component`, JSX in index.tsx, etc.) and requires a rebuild. Use this ONLY when the needed prop does not exist yet, or the user explicitly asks to build/modify the component's code or prop schema.\n" +
@@ -2157,6 +2157,12 @@ server.tool("get_framework_guide", "Get a framework guide on a specific topic (e
         global: "global-css",
         "css-variables": "global-css",
         "custom-properties": "global-css",
+        "translation": "translations",
+        "localization": "translations",
+        "localize": "translations",
+        "locale": "translations",
+        "i18n": "translations",
+        "çeviri": "translations",
     };
     const resolvedTopic = topicAliases[topicLower] || topicLower;
     // Topics that involve MobX store reads get a reminder about root reactivity
@@ -3812,7 +3818,7 @@ server.tool("upload_image", "Upload an image to the connected editor's project a
     return callEditorAction(project_root, args);
 });
 // Tool: update_page_sections
-server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [...] }`. Each update is EITHER a STATIC value `{ prop_name|prop_id, value }` (values use the same per-type shapes as update_section_prop / get_editor_workflow) OR a DYNAMIC binding `{ prop_id, ref, list_path? }` — `ref` is a value's ref from get_available_values, binding the prop to a variable/loop field instead of a static value (pass the same `list_path` to bind a prop of a component inside a COMPONENT_LIST). So one call can set static content AND dynamic bindings across the whole page. All-or-nothing: every value is validated and every binding resolved (and built-but-unimported child code components auto-imported) before anything is written — one bad item rejects the whole update. Prefer this over many update_section_prop calls.", {
+server.tool("update_page_sections", "Fill MANY placed sections of a page in a SINGLE call — the fastest way to populate a whole page (one round-trip for the entire page instead of one call per section/prop). Takes `sections`, each `{ element_id, updates: [{ prop_name|prop_id, value }] }`; values use the same per-type shapes as update_section_prop / get_editor_workflow. All-or-nothing across the whole page: every value is resolved and deeply validated (and built-but-unimported child code components auto-imported) before anything is written — one invalid value rejects the entire page update. Prefer this over many update_section_prop(s) calls.", {
     project_root: z.string().describe("Absolute path to the code-component project."),
     page_id: z.string().describe("Target page id (from list_editor_pages)."),
     sections: z
@@ -3822,20 +3828,9 @@ server.tool("update_page_sections", "Fill MANY placed sections of a page in a SI
             .array(z.object({
             prop_id: z.string().optional().describe("Blueprint prop id (provide this or prop_name)."),
             prop_name: z.string().optional().describe("Blueprint prop name (alternative to prop_id)."),
-            value: z
-                .any()
-                .optional()
-                .describe("STATIC value (same shape update_section_prop expects). Omit when binding via `ref`."),
-            ref: z
-                .string()
-                .optional()
-                .describe("DYNAMIC binding: a value ref from get_available_values. Use instead of `value`."),
-            list_path: z
-                .array(z.object({ prop_id: z.string(), index: z.number() }))
-                .optional()
-                .describe("With `ref`: path into a COMPONENT_LIST to bind a nested child's prop."),
+            value: z.any().describe("Prop value, same shape update_section_prop expects for that type."),
         }))
-            .describe("Non-empty array of prop updates (static values and/or dynamic bindings) for this section."),
+            .describe("Non-empty array of prop updates for this section."),
     }))
         .describe("Non-empty array of sections to fill, each with its elementId and prop updates."),
     port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
@@ -3845,9 +3840,7 @@ server.tool("update_page_sections", "Fill MANY placed sections of a page in a SI
         updates: (s.updates || []).map(u => ({
             ...(u.prop_id ? { propId: u.prop_id } : {}),
             ...(u.prop_name ? { propName: u.prop_name } : {}),
-            ...(u.value !== undefined ? { value: u.value } : {}),
-            ...(u.ref ? { ref: u.ref } : {}),
-            ...(u.list_path ? { listPath: u.list_path.map(p => ({ propId: p.prop_id, index: p.index })) } : {}),
+            value: u.value,
         })),
     }));
     const args = [
@@ -4010,30 +4003,6 @@ server.tool("publish_theme", "Publish the current theme LIVE — the same action
     ];
     return callEditorAction(project_root, args);
 });
-// Tool: get_available_values
-server.tool("get_available_values", "List the DYNAMIC values that can be bound to a prop instead of a static value — store/global/parent/section variables, or (for a component placed inside a COMPONENT_LIST) the per-item LOOP variables (e.g. each product's title/image when the list repeats over products). Pass `prop_id` to filter to that prop's compatible type. For a prop of a component inside a COMPONENT_LIST, pass `list_path` = the path of `{ prop_id, index }` steps from the section down to that child (e.g. `[{ \"prop_id\": \"<listPropId>\", \"index\": 0 }]`). Returns each value's `ref`, `displayName`, `typeId`, `groupType`. To BIND a prop to one, pass its `ref` as an update in `update_page_sections` (`{ prop_id, ref, list_path? }` instead of `{ value }`). Read-only. Requires `ikas-component dev` connected.", {
-    project_root: z.string().describe("Absolute path to the code-component project."),
-    page_id: z.string().describe("Target page id (from list_editor_pages)."),
-    element_id: z.string().describe("Placed-section elementId (from list_page_sections)."),
-    prop_id: z.string().optional().describe("Target prop id — filters values to that prop's compatible type."),
-    list_path: z
-        .array(z.object({ prop_id: z.string(), index: z.number() }))
-        .optional()
-        .describe("Path into a COMPONENT_LIST to target a nested child's prop: ordered { prop_id, index } steps."),
-    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
-}, async ({ project_root, page_id, element_id, prop_id, list_path, port }) => {
-    const args = [
-        "get-available-values",
-        "--page-id",
-        page_id,
-        "--element-id",
-        element_id,
-        ...(prop_id ? ["--prop-id", prop_id] : []),
-        ...(list_path ? ["--list-path", JSON.stringify(list_path.map(s => ({ propId: s.prop_id, index: s.index })))] : []),
-        ...(port ? ["--port", String(port)] : []),
-    ];
-    return callEditorAction(project_root, args);
-});
 // Tool: get_editor_workflow
 const EDITOR_WORKFLOW_GUIDE = [
     "# Editor workflow: placing sections and filling their content on a page",
@@ -4074,11 +4043,6 @@ const EDITOR_WORKFLOW_GUIDE = [
     "- Child ids are opaque — take them from get_section_template / list_imported_sections; never invent them.",
     "- Auto-import: a referenced child that is BUILT but not yet imported is imported automatically (returned under autoImported). A child that is not built at all errors — build it first.",
     "",
-    "## Dynamic values (bind a variable / loop field instead of a static value)",
-    "- A prop can hold a DYNAMIC binding instead of a literal: a store/global/parent/section variable, or — for a component placed inside a COMPONENT_LIST — a per-ITEM loop field (e.g. each product's title/image when the list repeats over products).",
-    "- Discover what's bindable: get_available_values(element_id, prop_id?, list_path?) → a list of values each with a stable `ref` (+ displayName, typeId, groupType). For a component inside a COMPONENT_LIST, pass list_path = ordered { prop_id, index } steps from the section down to that child.",
-    "- Bind it: in update_page_sections, make that prop's update `{ prop_id, ref, list_path? }` (the `ref` from get_available_values) INSTEAD of `{ value }`. Same call can mix static values and dynamic bindings; pass the SAME list_path you used for get_available_values. Binding replaces any static value on that prop.",
-    "",
     "## Reading prop schemas (avoid guessing)",
     "- get_component_props(componentId) → a component's props with types, required, default, ENUM `options` (the valid values to set), and COMPONENT_LIST `allowedComponentIds` (valid children). Works for any section OR child id. Use it BEFORE filling — to know prop names, enum values, and which children a slot allows — instead of guessing or reading ikas.config.json.",
     "- For a COMPONENT_LIST: get_component_props(parent) → its allowedComponentIds → get_component_props(child) → the child's props/enums. Then build the components array.",
@@ -4091,6 +4055,137 @@ const EDITOR_WORKFLOW_GUIDE = [
 server.tool("get_editor_workflow", "Read this FIRST when the user wants to place a section on a page or fill/edit a section's content (text, image, link, slides, component lists) in the live editor. Returns the complete step-by-step workflow for the live-editor tools (list_editor_pages, list_imported_sections, import_section, add_section_to_page, list_page_sections, update_section_prop, upload_image), the per-prop-type value shapes, the COMPONENT_LIST read-modify-write rules, and how validation/auto-import behave. Use it to avoid the common mistake of writing component code to set a value a section already supports.", {}, async () => {
     return { content: [{ type: "text", text: EDITOR_WORKFLOW_GUIDE }] };
 });
+// Tool: list_theme_globals
+server.tool("list_theme_globals", "List the theme's global settings from the connected editor: global variables (Theme Settings) and design tokens (colors, typography, breakpoints, keyframes, color schemes). Call this BEFORE generating sections/components so you reuse the theme's existing variables and tokens (read them in component code via `getThemeSetting`/`getThemeColors`/... from `@ikas/bp-storefront`). Includes items created manually in the editor UI. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z.string().describe("Absolute path to the code-component project (where `node_modules/.bin/ikas-component` lives)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, port }) => {
+    const args = ["list-theme-globals", ...(port ? ["--port", String(port)] : [])];
+    return callEditorAction(project_root, args);
+});
+// Tool: create_theme_global
+server.tool("create_theme_global", "Create a theme global setting in the connected editor. `kind` selects what to create:\n" +
+    "- globalVariable: requires display_name + type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW); value optional. Value shapes — TEXT/COLOR: string; RICH_TEXT: HTML string; NUMBER: number; BOOLEAN: boolean; IMAGE: { url } object; BORDER: { width: { value, unit }, style, color }; SHADOW: { x, y, blur, spread, color, position: \"outside\"|\"inside\" }.\n" +
+    "- color: requires name + value (hex, e.g. \"#ff0000\").\n" +
+    "- typography: requires name + at least one of font_family/font_size/font_weight/line_height/letter_spacing.\n" +
+    "- breakpoint: requires name + width (px).\n" +
+    "- keyframe: requires name + points (array of { point, styles? }) where each style is { property, value } using a CSS property name (opacity, transform, filter, background, color, …); keyframe_type defaults to \"keyframe\". Use the keyframe's `ref` as a CSS animation-name and set timing (duration/iteration) where you apply it.\n" +
+    "- colorScheme: requires name + colors (array of { key, value }) — `key` is the color slot name (e.g. Background, Text, Primary); slots are created automatically if missing.\n" +
+    "Read created items back with `list_theme_globals`. Requires `ikas-component dev` running with the editor connected.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    kind: z
+        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme"])
+        .describe("What to create."),
+    name: z.string().optional().describe("Name (design tokens)."),
+    display_name: z.string().optional().describe("Human label (globalVariable)."),
+    type: z.string().optional().describe("globalVariable value type."),
+    value: z.any().optional().describe("globalVariable default value (shape depends on type — see tool description), or color hex string."),
+    font_family: z.string().optional(),
+    font_size: z.string().optional(),
+    font_weight: z.string().optional(),
+    line_height: z.string().optional(),
+    letter_spacing: z.string().optional(),
+    width: z.number().optional().describe("breakpoint width in px."),
+    keyframe_type: z.enum(["keyframe", "transition"]).optional(),
+    points: z.any().optional().describe("keyframe points array."),
+    colors: z.any().optional().describe("colorScheme colors: array of { key, value } (key = color slot name)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async (input) => {
+    const p = input.port ? ["--port", String(input.port)] : [];
+    let args;
+    switch (input.kind) {
+        case "globalVariable":
+            args = [
+                "create-global-variable",
+                "--display-name",
+                String(input.display_name ?? ""),
+                "--type",
+                String(input.type ?? ""),
+                ...(input.value !== undefined ? ["--value", JSON.stringify(input.value)] : []),
+                ...p,
+            ];
+            break;
+        case "color":
+            args = ["create-color", "--name", String(input.name ?? ""), "--value", String(input.value ?? ""), ...p];
+            break;
+        case "typography":
+            args = [
+                "create-text-style",
+                "--name",
+                String(input.name ?? ""),
+                ...(input.font_family ? ["--font-family", input.font_family] : []),
+                ...(input.font_size ? ["--font-size", input.font_size] : []),
+                ...(input.font_weight ? ["--font-weight", input.font_weight] : []),
+                ...(input.line_height ? ["--line-height", input.line_height] : []),
+                ...(input.letter_spacing ? ["--letter-spacing", input.letter_spacing] : []),
+                ...p,
+            ];
+            break;
+        case "breakpoint":
+            args = ["create-breakpoint", "--name", String(input.name ?? ""), "--width", String(input.width ?? ""), ...p];
+            break;
+        case "keyframe":
+            args = [
+                "create-keyframe",
+                "--name",
+                String(input.name ?? ""),
+                ...(input.keyframe_type ? ["--type", input.keyframe_type] : []),
+                "--points",
+                JSON.stringify(input.points ?? []),
+                ...p,
+            ];
+            break;
+        case "colorScheme":
+            args = [
+                "create-color-scheme",
+                "--name",
+                String(input.name ?? ""),
+                "--colors",
+                JSON.stringify(input.colors ?? []),
+                ...p,
+            ];
+            break;
+        default:
+            return { content: [{ type: "text", text: `Error: unknown kind "${input.kind}"` }] };
+    }
+    return callEditorAction(input.project_root, args);
+});
+// Tool: update_theme_global
+server.tool("update_theme_global", "Update an existing global variable in the connected editor (e.g. fix its value or change its type). Identify it by `name` (the runtime key from `list_theme_globals`). Only the fields you pass are changed. Value shapes follow `create_theme_global`.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    name: z.string().describe("The variable's runtime key (from `list_theme_globals`)."),
+    display_name: z.string().optional().describe("New label."),
+    type: z.string().optional().describe("New value type (TEXT|RICH_TEXT|IMAGE|COLOR|NUMBER|BOOLEAN|BORDER|SHADOW)."),
+    value: z.any().optional().describe("New value (shape depends on type)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, name, display_name, type, value, port }) => {
+    const args = [
+        "update-global-variable",
+        "--name",
+        name,
+        ...(display_name !== undefined ? ["--display-name", display_name] : []),
+        ...(type !== undefined ? ["--type", type] : []),
+        ...(value !== undefined ? ["--value", JSON.stringify(value)] : []),
+        ...(port ? ["--port", String(port)] : []),
+    ];
+    return callEditorAction(project_root, args);
+});
+// Tool: delete_theme_global
+server.tool("delete_theme_global", "Delete a theme global setting from the connected editor. For `kind: globalVariable` pass `name` (the runtime key); for design-token kinds (color | typography | breakpoint | keyframe | colorScheme) pass the token `id`. Get names/ids from `list_theme_globals`.", {
+    project_root: z.string().describe("Absolute path to the code-component project."),
+    kind: z
+        .enum(["globalVariable", "color", "typography", "breakpoint", "keyframe", "colorScheme"])
+        .describe("What to delete."),
+    name: z.string().optional().describe("globalVariable runtime key (from `list_theme_globals`)."),
+    id: z.string().optional().describe("design-token id (from `list_theme_globals`)."),
+    port: z.number().optional().describe("Dev server WebSocket port (default 5201)."),
+}, async ({ project_root, kind, name, id, port }) => {
+    const p = port ? ["--port", String(port)] : [];
+    const args = kind === "globalVariable"
+        ? ["delete-global-variable", "--name", String(name ?? ""), ...p]
+        : ["delete-design-token", "--token-type", kind, "--id", String(id ?? ""), ...p];
+    return callEditorAction(project_root, args);
+});
 // --- Start server ---
 async function main() {
     const transport = new StdioServerTransport();