@ompo-design/mcp-server 0.1.2 → 0.1.4

package/dist/apply-plan.d.ts

@@ -8,6 +8,7 @@ export type ApplySuggestion = {
 export type ApplyPlanFile = {
     selector: string;
     suggestions: ApplySuggestion[];
+    layoutIntent?: string;
 };
 export type DomStructurePlan = {
     kind: 'dom.insert' | 'dom.move' | 'dom.delete' | 'dom.flexWrap';
@@ -24,6 +25,7 @@ export type ApplyPlan = {
     domChanges: OmpoOperation[];
     warnings: string[];
     instructions: string[];
+    ompoGlossary: Record<string, string>;
 };
 export declare function buildApplyPlan(bundle: OmpoEditBundle): ApplyPlan;
 export declare function explainEdit(bundle: OmpoEditBundle): string;

package/dist/apply-plan.js

@@ -1,10 +1,135 @@
-function styleSuggestions(operation) {
-    return Object.entries(operation.changed).map(([property, value]) => ({
+const OMPO_GLOSSARY = {
+    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.`,
+    fit: `Ompo "Fit" means size to content. Map \`widthMode: fit\` → \`width: fit-content\`, \`heightMode: fit\` → \`height: fit-content\` (or the project's equivalent).`
+};
+function formatChangedValue(property, value) {
+    const text = String(value);
+    if (text !== '')
+        return text;
+    if (property === 'width' || property === 'height') {
+        return '(remove fixed size — required for Fill)';
+    }
+    if (property === 'alignSelf' && text === '') {
+        return '(remove align-self override)';
+    }
+    return '(empty / remove)';
+}
+function styleSuggestionForProperty(property, value, changed) {
+    const parentFlex = changed.ensureParentFlex;
+    const parentFlexLabel = parentFlex === 'row' || parentFlex === 'column' ? parentFlex : 'row or column';
+    switch (property) {
+        case 'gap':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `${OMPO_GLOSSARY.gap} Apply on this selector if it is the flex/grid parent.`
+            };
+        case 'widthMode':
+            if (value === 'fill') {
+                return {
+                    property,
+                    value: 'fill',
+                    strategy: 'css-rule',
+                    notes: `${OMPO_GLOSSARY.fill} This selector has Fill width. If parent flex-direction is row, prefer flex-grow on this element; if column, prefer align-self: stretch for width.`
+                };
+            }
+            if (value === 'fit') {
+                return {
+                    property,
+                    value: 'fit',
+                    strategy: 'css-rule',
+                    notes: OMPO_GLOSSARY.fit
+                };
+            }
+            break;
+        case 'heightMode':
+            if (value === 'fill') {
+                return {
+                    property,
+                    value: 'fill',
+                    strategy: 'css-rule',
+                    notes: `${OMPO_GLOSSARY.fill} This selector has Fill height. If parent flex-direction is column, prefer flex-grow on this element; if row, prefer align-self: stretch for height.`
+                };
+            }
+            if (value === 'fit') {
+                return {
+                    property,
+                    value: 'fit',
+                    strategy: 'css-rule',
+                    notes: OMPO_GLOSSARY.fit
+                };
+            }
+            break;
+        case 'ensureParentFlex':
+            return {
+                property,
+                value: String(value),
+                strategy: 'css-rule',
+                notes: `Ompo auto-enabled flex on this element's parent so Fill sizing could work. In source, ensure the parent has display: flex and flex-direction: ${parentFlexLabel}. Apply on the parent element, not this child.`
+            };
+        case 'flexGrow':
+        case 'flexShrink':
+        case 'flexBasis':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: `Part of Ompo Fill sizing on the main flex axis. Apply together with widthMode/heightMode fill and remove fixed width/height on the filled axis.`
+            };
+        case 'alignSelf':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: value === 'stretch'
+                    ? 'Ompo Fill on the cross axis: stretch this flex child to fill the parent’s cross size. Remove any fixed width/height that blocks stretching.'
+                    : 'Map to the matching align-self rule in source.'
+            };
+        case 'minWidth':
+        case 'minHeight':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: 'Supporting constraint for Ompo Fill sizing. Often min-width: 0 or min-height: 0 so flex children can shrink.'
+            };
+        case 'maxWidth':
+        case 'maxHeight':
+            return {
+                property,
+                value: formatChangedValue(property, value),
+                strategy: 'css-rule',
+                notes: 'Supporting constraint for Ompo Fill sizing. max-width/max-height: none allows the element to grow.'
+            };
+    }
+    return {
         property,
-        value: String(value),
+        value: formatChangedValue(property, value),
         strategy: 'inline-style',
         notes: 'Map this changed property to the matching source stylesheet, class, or component prop. Do not modify unrelated styles.'
-    }));
+    };
+}
+function styleSuggestions(operation) {
+    const changed = operation.changed;
+    return Object.entries(changed).map(([property, value]) => styleSuggestionForProperty(property, value, changed));
+}
+function summarizeLayoutIntent(changed) {
+    const parts = [];
+    if (changed.gap !== undefined) {
+        parts.push(`Set container gap to ${changed.gap}`);
+    }
+    if (changed.widthMode === 'fill') {
+        parts.push('Width: Fill (expand on main or cross axis per parent flex-direction)');
+    }
+    if (changed.heightMode === 'fill') {
+        parts.push('Height: Fill (expand on main or cross axis per parent flex-direction)');
+    }
+    if (changed.ensureParentFlex) {
+        parts.push(`Parent needs display:flex with flex-direction:${changed.ensureParentFlex}`);
+    }
+    return parts.length > 0 ? parts.join('. ') : null;
 }
 function buildDomStructurePlan(operation) {
     switch (operation.kind) {
@@ -92,6 +217,12 @@ export function buildApplyPlan(bundle) {
                 suggestions: []
             };
             existing.suggestions.push(...styleSuggestions(operation));
+            const layoutIntent = summarizeLayoutIntent(operation.changed);
+            if (layoutIntent) {
+                existing.layoutIntent = existing.layoutIntent
+                    ? `${existing.layoutIntent} ${layoutIntent}`
+                    : layoutIntent;
+            }
             files.set(operation.selector, existing);
             if (operation.selector.includes('nth-of-type')) {
                 warnings.push(`Selector "${operation.selector}" may be unstable across builds. Prefer matching by component structure or stable attributes.`);
@@ -144,10 +275,14 @@ 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.',
+            'Gap belongs on the flex/grid parent. Fill belongs on the child inside a flex parent.',
             'For dom.flexWrap: create a new wrapper, move matched children, then apply wrapperStyles.',
             'Use child anchors (tag, id, class, textSnippet) to find elements in source when selectors are unstable.',
             'Prefer the smallest possible diff for each file.'
-        ]
+        ],
+        ompoGlossary: OMPO_GLOSSARY
     };
 }
 export function explainEdit(bundle) {

package/dist/cli.js

@@ -2,7 +2,8 @@ import { execSync } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
-import { findProjectRoot } from './edit-store.js';
+import { editsStoreReady } from './edit-store.js';
+import { getOmpoEditsStorePath } from './edits-path.js';
 const PACKAGE_NAME = '@ompo-design/mcp-server';
 const SERVER_NAME = 'ompo';
 function resolveExecutable(name) {
@@ -120,21 +121,23 @@ function runGlobalSetup() {
     console.log('  3. Open any Code project and run /mcp');
     console.log('  4. Approve ompo if prompted');
     console.log('  5. In Ompo, click Send on an edit before using the tools');
+    console.log(`     Edits are stored in ${getOmpoEditsStorePath()}`);
 }
 function runDoctor() {
     const projectRoot = resolve(process.cwd());
     const configPath = join(projectRoot, '.mcp.json');
     const desktopPath = claudeDesktopConfigPath();
     const claudeCodePath = claudeCodeUserConfigPath();
-    const editsRoot = findProjectRoot(projectRoot);
+    const storePath = getOmpoEditsStorePath();
     console.log('Ompo MCP doctor');
     console.log('');
-    console.log(`Project folder: ${projectRoot}`);
+    console.log(`Current folder: ${projectRoot}`);
     console.log(`Node: ${process.version}`);
     console.log(`npx: ${resolveExecutable('npx')}`);
+    console.log(`Edits store: ${storePath}`);
     console.log('');
     for (const [label, path] of [
-        ['Project config', configPath],
+        ['Project MCP config', configPath],
         ['Claude Desktop', desktopPath],
         ['Claude Code user', claudeCodePath]
     ]) {
@@ -153,11 +156,11 @@ function runDoctor() {
         }
     }
     console.log('');
-    if (editsRoot) {
-        console.log(`Edits: found ${join(editsRoot, '.ompo/edits/')}`);
+    if (editsStoreReady()) {
+        console.log('Edits: ready (Send from Ompo to add more)');
     }
     else {
-        console.log('Edits: none yet (use Send in Ompo first)');
+        console.log('Edits: none yet (click Send in Ompo first)');
     }
     console.log('');
     console.log('Global install: npx @ompo-design/mcp-server setup-global');
@@ -168,7 +171,7 @@ function printProjectNextSteps(projectRoot) {
     console.log(`  1. cd ${projectRoot}`);
     console.log('  2. Start Claude Code in this folder');
     console.log('  3. Run /mcp and approve ompo if prompted');
-    console.log('  4. In Ompo, click Send on an edit (creates .ompo/edits/)');
+    console.log('  4. In Ompo, click Send on an edit');
     console.log('');
     console.log('For all projects, run: npx @ompo-design/mcp-server setup-global');
 }

package/dist/edit-store.d.ts

@@ -1,6 +1,6 @@
 import type { EditIndex, OmpoEditBundle } from './types.js';
-export declare function findProjectRoot(startDir?: string): string | null;
-export declare function listEdits(projectRoot: string): EditIndex['edits'];
-export declare function readEditBundle(projectRoot: string, editId: string): OmpoEditBundle;
-export declare function recordEditPull(projectRoot: string, editId: string): void;
-export declare function recordEditApplied(projectRoot: string, editId: string): void;
+export declare function editsStoreReady(): boolean;
+export declare function listEdits(): EditIndex['edits'];
+export declare function readEditBundle(editId: string): OmpoEditBundle;
+export declare function recordEditPull(editId: string): void;
+export declare function recordEditApplied(editId: string): void;

package/dist/edit-store.js

@@ -1,67 +1,44 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
-import { dirname, join, resolve } from 'path';
-import { OMPo_EDITS_DIR } from './types.js';
-function projectRootCandidates(startDir = process.cwd()) {
-    const candidates = [
-        process.env.OMPO_PROJECT_ROOT,
-        process.env.CLAUDE_PROJECT_DIR,
-        startDir
-    ].filter((value) => Boolean(value?.trim()));
-    return [...new Set(candidates.map((value) => resolve(value)))];
+import { join } from 'path';
+import { getOmpoEditsStorePath } from './edits-path.js';
+function editsDirectory() {
+    return getOmpoEditsStorePath();
 }
-export function findProjectRoot(startDir = process.cwd()) {
-    for (const candidate of projectRootCandidates(startDir)) {
-        const found = findProjectRootFrom(candidate);
-        if (found)
-            return found;
-    }
-    return null;
-}
-function findProjectRootFrom(startDir) {
-    let current = resolve(startDir);
-    while (true) {
-        const editsDirectory = join(current, OMPo_EDITS_DIR);
-        if (existsSync(join(editsDirectory, 'index.json'))) {
-            return current;
-        }
-        const parent = dirname(current);
-        if (parent === current)
-            return null;
-        current = parent;
-    }
+export function editsStoreReady() {
+    return existsSync(join(editsDirectory(), 'index.json'));
 }
-function readIndex(projectRoot) {
-    const indexPath = join(projectRoot, OMPo_EDITS_DIR, 'index.json');
+function readIndex() {
+    const indexPath = join(editsDirectory(), 'index.json');
     return JSON.parse(readFileSync(indexPath, 'utf8'));
 }
-function writeIndex(projectRoot, index) {
-    const indexPath = join(projectRoot, OMPo_EDITS_DIR, 'index.json');
+function writeIndex(index) {
+    const indexPath = join(editsDirectory(), 'index.json');
     writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
 }
-export function listEdits(projectRoot) {
-    return readIndex(projectRoot).edits;
+export function listEdits() {
+    return readIndex().edits;
 }
-export function readEditBundle(projectRoot, editId) {
-    const bundlePath = join(projectRoot, OMPo_EDITS_DIR, `${editId}.json`);
+export function readEditBundle(editId) {
+    const bundlePath = join(editsDirectory(), `${editId}.json`);
     if (!existsSync(bundlePath)) {
         throw new Error(`Edit not found: ${editId}`);
     }
     return JSON.parse(readFileSync(bundlePath, 'utf8'));
 }
-export function recordEditPull(projectRoot, editId) {
-    const index = readIndex(projectRoot);
+export function recordEditPull(editId) {
+    const index = readIndex();
     const entry = index.edits.find((edit) => edit.id === editId);
     if (!entry)
         return;
     entry.pulls += 1;
     entry.lastPulledAt = new Date().toISOString();
-    writeIndex(projectRoot, index);
+    writeIndex(index);
 }
-export function recordEditApplied(projectRoot, editId) {
-    const index = readIndex(projectRoot);
+export function recordEditApplied(editId) {
+    const index = readIndex();
     const entry = index.edits.find((edit) => edit.id === editId);
     if (!entry)
         return;
     entry.appliedAt = new Date().toISOString();
-    writeIndex(projectRoot, index);
+    writeIndex(index);
 }

package/dist/edits-path.d.ts

@@ -0,0 +1 @@
+export declare function getOmpoEditsStorePath(): string;

package/dist/edits-path.js

@@ -0,0 +1,5 @@
+import { homedir } from 'os';
+import { join } from 'path';
+export function getOmpoEditsStorePath() {
+    return join(homedir(), '.ompo', 'edits');
+}

package/dist/index.js

@@ -4,26 +4,27 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod';
 import { buildApplyPlan, explainEdit } from './apply-plan.js';
 import { runCli } from './cli.js';
-import { findProjectRoot, listEdits, readEditBundle, recordEditApplied, recordEditPull } from './edit-store.js';
+import { editsStoreReady, listEdits, readEditBundle, recordEditApplied, recordEditPull } from './edit-store.js';
+import { getOmpoEditsStorePath } from './edits-path.js';
 const server = new McpServer({
     name: 'ompo-mcp-server',
-    version: '0.1.0'
+    version: '0.1.4'
 });
-function requireProjectRoot() {
-    const projectRoot = findProjectRoot();
-    if (!projectRoot) {
-        throw new Error('No Ompo edits found. Run Send in Ompo first to create .ompo/edits in your project.');
+function requireEditsStore() {
+    const storePath = getOmpoEditsStorePath();
+    if (!editsStoreReady()) {
+        throw new Error('No Ompo edits found. Click Send in Ompo first to save an edit, then try again.');
     }
-    return projectRoot;
+    return storePath;
 }
-server.tool('list_edits', 'List Ompo edit bundles saved in the current project', {}, async () => {
-    const projectRoot = requireProjectRoot();
-    const edits = listEdits(projectRoot);
+server.tool('list_edits', 'List Ompo edit bundles saved on this machine', {}, async () => {
+    const storePath = requireEditsStore();
+    const edits = listEdits();
     return {
         content: [
             {
                 type: 'text',
-                text: JSON.stringify({ projectRoot, edits }, null, 2)
+                text: JSON.stringify({ storePath, edits }, null, 2)
             }
         ]
     };
@@ -31,9 +32,9 @@ server.tool('list_edits', 'List Ompo edit bundles saved in the current project',
 server.tool('get_edit', 'Load a specific Ompo edit bundle by id', {
     id: z.string().describe('Edit id, e.g. ed_8K42P')
 }, async ({ id }) => {
-    const projectRoot = requireProjectRoot();
-    const bundle = readEditBundle(projectRoot, id);
-    recordEditPull(projectRoot, id);
+    requireEditsStore();
+    const bundle = readEditBundle(id);
+    recordEditPull(id);
     return {
         content: [
             {
@@ -46,9 +47,9 @@ server.tool('get_edit', 'Load a specific Ompo edit bundle by id', {
 server.tool('explain_edit', 'Summarize what an Ompo edit changes', {
     id: z.string().describe('Edit id, e.g. ed_8K42P')
 }, async ({ id }) => {
-    const projectRoot = requireProjectRoot();
-    const bundle = readEditBundle(projectRoot, id);
-    recordEditPull(projectRoot, id);
+    requireEditsStore();
+    const bundle = readEditBundle(id);
+    recordEditPull(id);
     return {
         content: [
             {
@@ -58,19 +59,19 @@ server.tool('explain_edit', 'Summarize what an Ompo edit changes', {
         ]
     };
 });
-server.tool('apply_edit', 'Build an apply plan for an Ompo edit. The agent should execute the plan against source files and only change listed properties.', {
+server.tool('apply_edit', 'Build an apply plan for an Ompo edit. The agent should execute the plan against source files in the open codebase and only change listed properties.', {
     id: z.string().describe('Edit id, e.g. ed_8K42P'),
     markApplied: z
         .boolean()
         .optional()
         .describe('Set true after the agent successfully applies the edit')
 }, async ({ id, markApplied }) => {
-    const projectRoot = requireProjectRoot();
-    const bundle = readEditBundle(projectRoot, id);
-    recordEditPull(projectRoot, id);
+    requireEditsStore();
+    const bundle = readEditBundle(id);
+    recordEditPull(id);
     const plan = buildApplyPlan(bundle);
     if (markApplied) {
-        recordEditApplied(projectRoot, id);
+        recordEditApplied(id);
     }
     return {
         content: [

package/package.json

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