@ompo-design/mcp-server 0.1.11 → 0.1.13

package/dist/apply-plan.d.ts

@@ -11,7 +11,7 @@ export type ApplyPlanFile = {
     layoutIntent?: string;
 };
 export type DomStructurePlan = {
-    kind: 'dom.insert' | 'dom.move' | 'dom.delete' | 'dom.flexWrap';
+    kind: 'dom.insert' | 'dom.move' | 'dom.delete' | 'dom.flexWrap' | 'dom.iconReplace';
     summary: string;
     steps: string[];
     payload: Record<string, unknown>;

package/dist/apply-plan.js

@@ -1,12 +1,19 @@
 const OMPO_GLOSSARY = {
+    layoutNone: `Ompo layout "None" means the element is a normal block container (\`display: block\`), not a flex or grid layout parent. Do not add flex-direction, grid-template-columns, or gap unless a separate edit sets \`display: flex\` or \`display: grid\` on this selector.`,
+    layoutFlex: `Ompo layout "Flex" maps to \`display: flex\` (or inline-flex) on this selector. Apply flexDirection, justifyContent, alignItems, and gap together on the same container. Row/column toggles in Ompo map to flex-direction.`,
+    layoutGrid: `Ompo layout "Grid" maps to \`display: grid\` on this selector. Apply gridTemplateColumns (often \`repeat(n, 1fr)\`), optional gridTemplateRows / gridAutoRows, gridAutoFlow (row vs column), justifyContent, alignItems, and gap together on the grid parent. Prefer grid over flex for multi-column card/bento layouts.`,
     gap: `Ompo "Gap" is the space between children inside a flex or grid container. Apply \`gap\` on the parent layout element (not on children). The parent needs \`display: flex\` or \`display: grid\`. Example: gap "16px" → CSS \`gap: 16px\` or Tailwind \`gap-4\`.`,
-    fill: `Ompo "Fill" means an element should expand to consume free space inside its parent. Fill is NOT a CSS property — read \`widthMode: fill\` / \`heightMode: fill\` together with \`ensureParentFlex\`, \`flexGrow\`, \`flexShrink\`, \`flexBasis\`, and \`alignSelf\` on the same selector. Parent must be \`display: flex\`. Main axis (direction of flex): use \`flex: 1 1 0\` (grow/shrink/basis). Cross axis: use \`align-self: stretch\` and remove fixed width/height on that axis. If \`ensureParentFlex\` is present, make the parent a flex container with that direction first.`,
+    fill: `Ompo "Fill" means an element should expand to consume free space inside its parent. Fill is NOT a CSS property — read \`widthMode: fill\` / \`heightMode: fill\` together with \`ensureParentFlex\`, \`flexGrow\`, \`flexShrink\`, \`flexBasis\`, and \`alignSelf\` on the same selector. Parent must be \`display: flex\` (Fill does not apply inside grid parents). Main axis (direction of flex): use \`flex: 1 1 0\` (grow/shrink/basis). Cross axis: use \`align-self: stretch\` and remove fixed width/height on that axis. If \`ensureParentFlex\` is present, make the parent a flex container with that direction first.`,
     fit: `Ompo "Fit" means size to content. Map \`widthMode: fit\` → \`width: fit-content\`, \`heightMode: fit\` → \`height: fit-content\` (or the project's equivalent).`,
-    imageFill: `Ompo image background fill: copy the source file from \`backgroundImageSource\` into the project (e.g. public/images/), then set \`background-image\` to a project-relative url(), with \`background-size: cover\`, \`background-position: center\`, and \`background-repeat: no-repeat\`. Do not commit file:// URLs to source.`,
+    imageFill: `Ompo image background fill: when \`backgroundImageSource\` is an https URL, download that asset into the project (e.g. public/images/) and set \`background-image\` to a project-relative url(). For legacy local paths, copy from the user's machine instead. Always use \`background-size: cover\`, \`background-position: center\`, and \`background-repeat: no-repeat\`. Do not commit file:// URLs to source.`,
     domMove: `Ompo DOM move: reorder or reparent elements in source markup/components. Use movedElement anchors (tag, id, class, textSnippet) to find nodes. destinationChildren is the authoritative sibling order after the move — match this order in JSX/HTML or reorder mapped arrays. CSS alone cannot satisfy a dom.move.`,
     insertText: `Ompo text insert: the user added a new text block (usually <p>). insertedElement carries insertKind "text", a stable data-ompo-insert-id selector, and textSnippet for the current copy. Apply as markup or a text component at parent/index; check separate text operations for edits after insert.`,
+    insertSection: `Ompo section insert: the user added a full-width page section (<div>, insertKind "section"). Default size is width 100% and height 300px with fill #AEC8F8. Append at the page root / bottom of main content unless parent/index says otherwise.`,
+    insertFrame: `Ompo frame insert: the user added a small div (insertKind "frame"). Default size is 150×80px with fill #AEC8F8. Use for nested containers, cards, or tiles inside a section.`,
     insertIcon: `Ompo icon insert: the user added an Iconify icon (span.ompo-insert-icon) or editable SVG. iconId is the Iconify name (e.g. lucide:home) when known. Prefer the project's icon library or @iconify/react with that id instead of inlining raw SVG when possible. Size, fill color, and stroke changes appear as style operations on the same stable data-ompo-insert-id or data-ompo-icon-id selector.`,
-    iconStroke: `Ompo icon/SVG stroke: iconStrokeWidth sets stroke-width on the inner SVG; iconStrokeColor sets stroke (often currentColor). Applies to inserted icons and native SVG elements selected in Ompo.`
+    replaceIcon: `Ompo icon replace: the user swapped an existing icon/SVG to a different Iconify icon. Update the project's icon component or @iconify/react usage to the new iconId — do not only patch inline SVG unless the project already inlines icons.`,
+    iconStroke: `Ompo icon/SVG stroke: iconStrokeWidth sets stroke-width on the inner SVG; iconStrokeColor sets stroke (often currentColor). Applies to inserted icons and native SVG elements selected in Ompo.`,
+    zIndex: `Ompo "Z Index" maps to CSS \`z-index\` on the selected element. Use the integer from the edit, or \`auto\` to clear an authored value. Higher values stack above lower values within the same stacking context. If stacking does not change in the browser, the element may also need a non-static \`position\` (e.g. relative) in source — Ompo may set inline z-index without changing position.`
 };
 function describeAnchor(anchor) {
     const parts = [anchor.tagName];
@@ -28,6 +35,8 @@ function buildDomInsertPlan(operation) {
     const inserted = operation.insertedElement;
     const isIcon = operation.insertKind === 'icon';
     const isText = operation.insertKind === 'text';
+    const isSection = operation.insertKind === 'section';
+    const isFrame = operation.insertKind === 'frame';
     const steps = [];
     if (operation.parent) {
         steps.push(`Locate destination parent: ${describeAnchor(operation.parent)}.`);
@@ -44,11 +53,20 @@ function buildDomInsertPlan(operation) {
     if (isText) {
         steps.push(OMPO_GLOSSARY.insertText);
     }
+    else if (isSection) {
+        steps.push(OMPO_GLOSSARY.insertSection);
+    }
+    else if (isFrame) {
+        steps.push(OMPO_GLOSSARY.insertFrame);
+    }
     else if (isIcon) {
         steps.push(OMPO_GLOSSARY.insertIcon);
         if (operation.iconId) {
             steps.push(`Iconify id: ${operation.iconId}`);
         }
+        if (operation.iconSvg) {
+            steps.push('iconSvg is included in the plan payload for inline SVG or reference.');
+        }
     }
     steps.push(`Insert at child index ${operation.index}.`);
     steps.push('Sanitize and adapt the HTML to the project’s component conventions before writing.');
@@ -56,7 +74,11 @@ function buildDomInsertPlan(operation) {
         ? `Insert Iconify icon${operation.iconId ? ` (${operation.iconId})` : ''}`
         : isText
             ? 'Insert text block'
-            : 'Insert new element into the page';
+            : isSection
+                ? 'Insert page section'
+                : isFrame
+                    ? 'Insert frame div'
+                    : 'Insert new element into the page';
     return {
         kind: 'dom.insert',
         summary,
@@ -68,11 +90,41 @@ function buildDomInsertPlan(operation) {
             selector: operation.selector,
             insertKind: operation.insertKind,
             iconId: operation.iconId,
+            iconSvg: operation.iconSvg,
             insertedElement: operation.insertedElement,
             parent: operation.parent
         }
     };
 }
+function buildIconReplacePlan(operation) {
+    const steps = [];
+    if (operation.element) {
+        steps.push(`Locate icon element: ${describeAnchor(operation.element)} (selector: "${operation.selector}").`);
+    }
+    else {
+        steps.push(`Locate icon element "${operation.selector}" in source.`);
+    }
+    steps.push(OMPO_GLOSSARY.replaceIcon);
+    steps.push(`Set Iconify id to ${operation.iconId}.`);
+    if (operation.iconSvg) {
+        steps.push('Use iconSvg from the payload when the project inlines SVG markup.');
+    }
+    if (operation.previousIconId) {
+        steps.push(`Previous icon id: ${operation.previousIconId}`);
+    }
+    return {
+        kind: 'dom.iconReplace',
+        summary: `Replace icon with ${operation.iconId}`,
+        steps,
+        payload: {
+            selector: operation.selector,
+            iconId: operation.iconId,
+            iconSvg: operation.iconSvg,
+            previousIconId: operation.previousIconId,
+            element: operation.element
+        }
+    };
+}
 function formatChildOrder(children, movedSelector) {
     return children.map((child, index) => {
         const marker = child.selector === movedSelector ? ' ← moved element' : '';
@@ -162,10 +214,120 @@ function formatChangedValue(property, value) {
     }
     return '(empty / remove)';
 }
+function layoutModeFromChanged(changed) {
+    const display = typeof changed.display === 'string' ? changed.display : null;
+    if (display === 'flex' || display === 'inline-flex')
+        return 'flex';
+    if (display === 'grid' || display === 'inline-grid')
+        return 'grid';
+    if (display === 'block' || display === 'none')
+        return 'block';
+    if (changed.gridTemplateColumns !== undefined || changed.gridAutoFlow !== undefined) {
+        return 'grid';
+    }
+    if (changed.flexDirection !== undefined)
+        return 'flex';
+    return null;
+}
+function imageFillSourceNotes(source) {
+    const trimmed = source.trim();
+    if (trimmed.startsWith('http://') || trimmed.startsWith('https://')) {
+        return `${OMPO_GLOSSARY.imageFill} Download ${trimmed}, save into the project (e.g. public/images/), and reference the copied asset in CSS.`;
+    }
+    return `${OMPO_GLOSSARY.imageFill} Read this file from the user's machine (${trimmed}), copy it into the repo, and reference the copied asset in CSS.`;
+}
 function styleSuggestionForProperty(property, value, changed) {
     const parentFlex = changed.ensureParentFlex;
     const parentFlexLabel = parentFlex === 'row' || parentFlex === 'column' ? parentFlex : 'row or column';
+    const layoutMode = layoutModeFromChanged(changed);
     switch (property) {
+        case 'display': {
+            const displayValue = String(value);
+            if (displayValue === 'grid' || displayValue === 'inline-grid') {
+                return {
+                    property,
+                    value: displayValue,
+                    strategy: 'css-rule',
+                    notes: OMPO_GLOSSARY.layoutGrid
+                };
+            }
+            if (displayValue === 'flex' || displayValue === 'inline-flex') {
+                return {
+                    property,
+                    value: displayValue,
+                    strategy: 'css-rule',
+                    notes: OMPO_GLOSSARY.layoutFlex
+                };
+            }
+            return {
+                property,
+                value: displayValue,
+                strategy: 'css-rule',
+                notes: OMPO_GLOSSARY.layoutNone
+            };
+        }
+        case 'gridTemplateColumns':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Column template for the grid parent — e.g. repeat(3, 1fr) for three equal columns. Tailwind: grid-cols-3 or arbitrary grid-template-columns.`
+            };
+        case 'gridTemplateRows':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Explicit row template. Use when Ompo authored fixed row tracks; otherwise grid-auto-rows may define implicit row sizing.`
+            };
+        case 'gridAutoRows':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Size for implicit grid rows (auto-generated tracks). Common: auto, minmax(180px, auto).`
+            };
+        case 'gridAutoColumns':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Size for implicit grid columns when grid-auto-flow creates new columns.`
+            };
+        case 'gridAutoFlow':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Ompo row/column direction toggle on grid maps to grid-auto-flow (row | column). Apply on the grid container.`
+            };
+        case 'gridColumn':
+        case 'gridRow':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.layoutGrid} Grid item placement on this child selector (span / line placement).`
+            };
+        case 'flexDirection':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: layoutMode === 'grid'
+                    ? `${OMPO_GLOSSARY.layoutGrid} flex-direction does not apply when display is grid — use gridAutoFlow instead if present in the same edit.`
+                    : `${OMPO_GLOSSARY.layoutFlex} Main axis direction for the flex container.`
+            };
+        case 'justifyContent':
+        case 'alignItems':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: layoutMode === 'grid'
+                    ? `${OMPO_GLOSSARY.layoutGrid} Alignment on the grid container (${property}). Maps from Ompo’s alignment pinner / space-between toggle.`
+                    : `${OMPO_GLOSSARY.layoutFlex} Alignment on the flex container (${property}). Maps from Ompo’s alignment pinner / space-between toggle.`
+            };
         case 'gap':
             return {
                 property,
@@ -255,7 +417,7 @@ function styleSuggestionForProperty(property, value, changed) {
                 property,
                 value: formatChangedValue(property, value),
                 strategy: 'component-markup',
-                notes: `${OMPO_GLOSSARY.imageFill} Read this file from the user's machine (${String(value)}), copy it into the repo, and reference the copied asset in CSS.`
+                notes: imageFillSourceNotes(String(value))
             };
         case 'backgroundImage':
             if (changed.backgroundImageSource) {
@@ -263,7 +425,7 @@ function styleSuggestionForProperty(property, value, changed) {
                     property,
                     value: formatChangedValue(property, value),
                     strategy: 'css-rule',
-                    notes: `${OMPO_GLOSSARY.imageFill} Apply after copying the file from backgroundImageSource.`
+                    notes: imageFillSourceNotes(String(changed.backgroundImageSource))
                 };
             }
             break;
@@ -287,6 +449,13 @@ function styleSuggestionForProperty(property, value, changed) {
                 strategy: 'inline-style',
                 notes: OMPO_GLOSSARY.iconStroke
             };
+        case 'zIndex':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.zIndex} Apply as CSS \`z-index\` on this selector.`
+            };
     }
     return {
         property,
@@ -301,6 +470,30 @@ function styleSuggestions(operation) {
 }
 function summarizeLayoutIntent(changed) {
     const parts = [];
+    const layoutMode = layoutModeFromChanged(changed);
+    if (changed.display !== undefined) {
+        if (layoutMode === 'grid') {
+            parts.push('Layout: Grid container');
+        }
+        else if (layoutMode === 'flex') {
+            parts.push('Layout: Flex container');
+        }
+        else if (layoutMode === 'block') {
+            parts.push('Layout: None (block flow, not flex/grid)');
+        }
+    }
+    if (changed.gridTemplateColumns !== undefined) {
+        parts.push(`Grid columns: ${changed.gridTemplateColumns}`);
+    }
+    if (changed.gridTemplateRows !== undefined) {
+        parts.push(`Grid rows: ${changed.gridTemplateRows}`);
+    }
+    if (changed.gridAutoFlow !== undefined) {
+        parts.push(`Grid auto-flow: ${changed.gridAutoFlow}`);
+    }
+    if (changed.flexDirection !== undefined && layoutMode !== 'grid') {
+        parts.push(`Flex direction: ${changed.flexDirection}`);
+    }
     if (changed.gap !== undefined) {
         parts.push(`Set container gap to ${changed.gap}`);
     }
@@ -313,6 +506,9 @@ function summarizeLayoutIntent(changed) {
     if (changed.ensureParentFlex) {
         parts.push(`Parent needs display:flex with flex-direction:${changed.ensureParentFlex}`);
     }
+    if (changed.zIndex !== undefined) {
+        parts.push(`Set z-index to ${changed.zIndex}`);
+    }
     return parts.length > 0 ? parts.join('. ') : null;
 }
 function buildDomStructurePlan(operation) {
@@ -325,7 +521,8 @@ function buildDomStructurePlan(operation) {
                     `Locate the parent element matching "${operation.parentSelector}" in source.`,
                     `Insert a new <div> wrapper at child index ${operation.index} inside that parent.`,
                     `Move the matched child elements into the new wrapper. Use the child anchors (tag, id, class, textSnippet) to find the correct nodes in source.`,
-                    `Apply only the wrapper styles listed in wrapperStyles to the new container.`,
+                    `Apply only the wrapper styles listed in wrapperStyles to the new container (typically display:flex and flex-direction).`,
+                    'For multi-column card layouts, prefer display:grid with grid-template-columns if wrapperStyles do not already specify layout.',
                     'Do not change unrelated siblings or parent styling.'
                 ],
                 payload: {
@@ -341,6 +538,8 @@ function buildDomStructurePlan(operation) {
             return buildDomInsertPlan(operation);
         case 'dom.move':
             return buildDomMovePlan(operation);
+        case 'dom.iconReplace':
+            return buildIconReplacePlan(operation);
         case 'dom.delete':
             return {
                 kind: 'dom.delete',
@@ -438,14 +637,19 @@ export function buildApplyPlan(bundle) {
         instructions: [
             'Only apply properties and operations listed in this plan.',
             'Leave all untouched styling and markup unchanged.',
-            'Read ompoGlossary.fill and ompoGlossary.gap before applying layout changes — Ompo terms are not literal CSS properties.',
-            'When widthMode or heightMode is "fill", apply the grouped flex properties together (flexGrow, flexBasis, alignSelf, removed width/height) — do not set a fixed px width/height on the filled axis.',
+            'Read ompoGlossary.layoutNone, layoutFlex, layoutGrid, fill, and gap before applying layout changes.',
+            'Ompo layout types: None → display:block; Flex → display:flex + flexDirection; Grid → display:grid + gridTemplateColumns (+ gridAutoFlow for row/column).',
+            'When display is grid, apply gridTemplateColumns / gridAutoFlow / gap / justifyContent / alignItems on the grid parent — do not convert grid containers to flex.',
+            'When display is block (layout None), do not add flex or grid properties unless this edit explicitly sets display:flex or display:grid.',
+            'When widthMode or heightMode is "fill", apply the grouped flex properties together (flexGrow, flexBasis, alignSelf, removed width/height) — Fill requires a flex parent, not grid.',
             'Gap belongs on the flex/grid parent. Fill belongs on the child inside a flex parent.',
             'DOM moves are in domStructurePlans and domChanges — reorder or reparent elements in source markup/components, not just CSS.',
             'Read ompoGlossary.domMove before applying dom.move operations.',
             'For dom.move: destinationChildren is the structural snapshot of the final sibling order — match it in JSX/HTML or reorder mapped arrays.',
             'For dom.flexWrap: create a new wrapper, move matched children, then apply wrapperStyles.',
             'For dom.insert with insertKind text or icon: read ompoGlossary.insertText / insertIcon; use insertedElement anchors and iconId when applying.',
+            'For dom.iconReplace: read ompoGlossary.replaceIcon; update the project icon to the new iconId. Use iconSvg from domStructurePlans when inlining SVG.',
+            'For zIndex: read ompoGlossary.zIndex; map to CSS z-index on the matching selector.',
             'Use child anchors (tag, id, class, textSnippet, insertKind, iconId) to find elements in source when selectors are unstable.',
             'Prefer the smallest possible diff for each file.'
         ],
@@ -459,6 +663,7 @@ export function explainEdit(bundle) {
     const moveCount = bundle.operations.filter((operation) => operation.kind === 'dom.move').length;
     const textInsertCount = bundle.operations.filter((operation) => operation.kind === 'dom.insert' && operation.insertKind === 'text').length;
     const iconInsertCount = bundle.operations.filter((operation) => operation.kind === 'dom.insert' && operation.insertKind === 'icon').length;
+    const iconReplaceCount = bundle.operations.filter((operation) => operation.kind === 'dom.iconReplace').length;
     const domCount = bundle.operations.length - styleCount - textCount;
     const scopeLabel = bundle.scope.mode === 'subtree' && bundle.scope.rootLabel
         ? `${bundle.scope.rootLabel} and its children`
@@ -479,7 +684,10 @@ export function explainEdit(bundle) {
         lines.push(`${textInsertCount} text insert${textInsertCount === 1 ? '' : 's'} — apply via domStructurePlans (markup at parent/index)`);
     }
     if (iconInsertCount > 0) {
-        lines.push(`${iconInsertCount} icon insert${iconInsertCount === 1 ? '' : 's'} — map iconId to project icons when possible`);
+        lines.push(`${iconInsertCount} icon insert${iconInsertCount === 1 ? '' : 's'} — apply iconId (and iconSvg when present) via domStructurePlans`);
+    }
+    if (iconReplaceCount > 0) {
+        lines.push(`${iconReplaceCount} icon replace${iconReplaceCount === 1 ? '' : 's'} — update iconId/iconSvg via domStructurePlans`);
     }
     lines.push(`Source preview: ${bundle.source.url}`);
     return lines.join('\n');

package/dist/cli.js

@@ -7,7 +7,7 @@ import { getOmpoEditsStorePath } from './edits-path.js';
 import { readOmpoMcpSession } from './session.js';
 import { readMcpTokenBalance } from './tokens.js';
 const PACKAGE_NAME = '@ompo-design/mcp-server';
-const PACKAGE_VERSION = '0.1.11';
+const PACKAGE_VERSION = '0.1.12';
 const SERVER_NAME = 'ompo';
 function resolveExecutable(name) {
     try {
@@ -187,7 +187,7 @@ async function runDoctor() {
         console.log('Edits: none yet (click Send in Ompo first)');
     }
     console.log('');
-    console.log('If tools skip token usage, quit and reopen Claude Code to reload MCP v0.1.11+');
+    console.log('If tools skip token usage, quit and reopen Claude Code to reload MCP v0.1.12+');
     console.log('Global install: npx @ompo-design/mcp-server setup-global');
 }
 function printProjectNextSteps(projectRoot) {

package/dist/edit-billing.js

@@ -64,7 +64,7 @@ export async function consumeMcpTokenForEdit(toolName, editId) {
         const balance = await readMcpTokenBalance();
         return balance ?? 0;
     }
-    const tokensRemaining = await consumeMcpToken(toolName);
+    const tokensRemaining = await consumeMcpToken(toolName, editId);
     markEditBilled(editId);
     return tokensRemaining;
 }

package/dist/iconify.d.ts

@@ -0,0 +1,11 @@
+export type IconifySearchResult = {
+    icons: string[];
+    total: number;
+    limit: number;
+    start: number;
+};
+export declare function searchIconifyIcons(query: string, options?: {
+    limit?: number;
+    start?: number;
+}): Promise<IconifySearchResult>;
+export declare function fetchIconifySvg(iconId: string): Promise<string>;

package/dist/iconify.js

@@ -0,0 +1,42 @@
+const ICONIFY_API_BASE = 'https://api.iconify.design';
+function splitIconifyId(iconId) {
+    const separator = iconId.indexOf(':');
+    if (separator <= 0)
+        return ['', ''];
+    return [iconId.slice(0, separator), iconId.slice(separator + 1)];
+}
+export async function searchIconifyIcons(query, options) {
+    const trimmed = query.trim();
+    const limit = Math.min(Math.max(options?.limit ?? 32, 1), 999);
+    const start = Math.max(options?.start ?? 0, 0);
+    if (!trimmed) {
+        return { icons: [], total: 0, limit, start };
+    }
+    const url = new URL(`${ICONIFY_API_BASE}/search`);
+    url.searchParams.set('query', trimmed);
+    url.searchParams.set('limit', String(limit));
+    url.searchParams.set('start', String(start));
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Iconify search failed with ${response.status}`);
+    }
+    const payload = (await response.json());
+    return {
+        icons: payload.icons ?? [],
+        total: payload.total ?? payload.icons?.length ?? 0,
+        limit: payload.limit ?? limit,
+        start: payload.start ?? start
+    };
+}
+export async function fetchIconifySvg(iconId) {
+    const [prefix, name] = splitIconifyId(iconId);
+    if (!prefix || !name) {
+        throw new Error(`Invalid Iconify icon id: ${iconId}`);
+    }
+    const url = `${ICONIFY_API_BASE}/${prefix}/${name}.svg`;
+    const response = await fetch(url);
+    if (!response.ok) {
+        throw new Error(`Iconify SVG fetch failed with ${response.status}`);
+    }
+    return response.text();
+}

package/dist/index.js

@@ -7,10 +7,11 @@ import { runCli } from './cli.js';
 import { consumeMcpTokenForEdit, requireMcpSessionBalance } from './edit-billing.js';
 import { editsStoreReady, listEdits, readEditBundle, recordEditApplied, recordEditPull } from './edit-store.js';
 import { getOmpoEditsStorePath } from './edits-path.js';
+import { fetchIconifySvg, searchIconifyIcons } from './iconify.js';
 import { McpTokenError } from './tokens.js';
 const server = new McpServer({
     name: 'ompo-mcp-server',
-    version: '0.1.11'
+    version: '0.1.13'
 });
 function requireEditsStore() {
     const storePath = getOmpoEditsStorePath();
@@ -129,6 +130,44 @@ server.tool('apply_edit', 'Build an apply plan for an Ompo edit. The agent shoul
         return tokenErrorResult(error);
     }
 });
+server.tool('search_icons', 'Search Iconify icons by keyword (same catalog Ompo uses in the editor)', {
+    query: z.string().describe('Search terms, e.g. "home", "menu", "arrow right"'),
+    limit: z.number().int().min(1).max(64).optional().describe('Max results (default 32)'),
+    start: z.number().int().min(0).optional().describe('Pagination offset')
+}, async ({ query, limit, start }) => {
+    try {
+        const result = await searchIconifyIcons(query, { limit, start });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2)
+                }
+            ]
+        };
+    }
+    catch (error) {
+        return tokenErrorResult(error);
+    }
+});
+server.tool('fetch_icon', 'Fetch Iconify SVG markup for an icon id (e.g. lucide:home)', {
+    iconId: z.string().describe('Iconify id in prefix:name format, e.g. lucide:home')
+}, async ({ iconId }) => {
+    try {
+        const iconSvg = await fetchIconifySvg(iconId);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ iconId, iconSvg }, null, 2)
+                }
+            ]
+        };
+    }
+    catch (error) {
+        return tokenErrorResult(error);
+    }
+});
 async function main() {
     if (runCli(process.argv.slice(2)))
         return;

package/dist/tokens.d.ts

@@ -3,4 +3,4 @@ export declare class McpTokenError extends Error {
     constructor(code: McpTokenError['code'], message: string);
 }
 export declare function readMcpTokenBalance(): Promise<number | null>;
-export declare function consumeMcpToken(toolName: string): Promise<number>;
+export declare function consumeMcpToken(toolName: string, editId?: string): Promise<number>;

package/dist/tokens.js

@@ -16,6 +16,9 @@ function mapRpcError(message) {
     if (normalized.includes('INSUFFICIENT_TOKENS')) {
         return new McpTokenError('INSUFFICIENT_TOKENS', 'You are out of MCP tokens. Add more tokens to your account before using Ompo MCP tools.');
     }
+    if (normalized.includes('COULD NOT CHOOSE THE BEST CANDIDATE FUNCTION')) {
+        return new McpTokenError('TOKEN_SERVICE_UNAVAILABLE', 'MCP token service is misconfigured on the server. Update Ompo or contact support.');
+    }
     return new McpTokenError('TOKEN_SERVICE_UNAVAILABLE', 'Could not verify MCP token balance. Check your connection and try again.');
 }
 async function createAuthedSupabase(session) {
@@ -70,14 +73,15 @@ export async function readMcpTokenBalance() {
         throw mapRpcError(error.message);
     return data?.tokens_available ?? null;
 }
-export async function consumeMcpToken(toolName) {
+export async function consumeMcpToken(toolName, editId) {
     const session = readOmpoMcpSession();
     if (!session) {
         throw new McpTokenError('NOT_SIGNED_IN', 'Sign in to Ompo and keep the app open so your MCP session stays active.');
     }
     const supabase = await createAuthedSupabase(session);
     const { data, error } = await supabase.rpc('consume_mcp_token', {
-        p_tool_name: toolName
+        p_tool_name: toolName,
+        p_edit_id: editId ?? null
     });
     if (error) {
         throw mapRpcError(error.message);

package/dist/types.d.ts

@@ -15,8 +15,9 @@ export type DomInsertOperation = {
     index: number;
     html: string;
     selector?: string;
-    insertKind?: 'text' | 'icon';
+    insertKind?: 'text' | 'icon' | 'frame' | 'section';
     iconId?: string;
+    iconSvg?: string;
     insertedElement?: ElementAnchor;
     parent?: ElementAnchor;
 };
@@ -38,13 +39,21 @@ export type DomDeleteOperation = {
     kind: 'dom.delete';
     selector: string;
 };
+export type DomIconReplaceOperation = {
+    kind: 'dom.iconReplace';
+    selector: string;
+    iconId: string;
+    iconSvg?: string;
+    previousIconId?: string;
+    element?: ElementAnchor;
+};
 export type ElementAnchor = {
     selector: string;
     tagName: string;
     id?: string;
     className?: string;
     textSnippet?: string;
-    insertKind?: 'text' | 'icon';
+    insertKind?: 'text' | 'icon' | 'frame' | 'section';
     iconId?: string;
 };
 export type DomFlexWrapOperation = {
@@ -62,7 +71,7 @@ export type TextOperation = {
     textContent?: string;
     innerHTML?: string;
 };
-export type OmpoOperation = StyleOperation | DomInsertOperation | DomMoveOperation | DomDeleteOperation | DomFlexWrapOperation | TextOperation;
+export type OmpoOperation = StyleOperation | DomInsertOperation | DomMoveOperation | DomDeleteOperation | DomIconReplaceOperation | DomFlexWrapOperation | TextOperation;
 export type OmpoEditBundle = {
     schemaVersion: number;
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ompo-design/mcp-server",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "MCP server for applying Ompo visual edits to a codebase",
   "type": "module",
   "license": "MIT",