@ompo-design/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,67 @@
+# @ompo-design/mcp-server
+
+Local MCP server for applying Ompo visual edits to a codebase.
+
+## Setup
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ompo": {
+      "command": "npx",
+      "args": ["-y", "@ompo-design/mcp-server"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+Add to `.mcp.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "ompo": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@ompo-design/mcp-server"]
+    }
+  }
+}
+```
+
+Restart your IDE session after adding the config. In Claude Code, run `/mcp` to confirm `ompo` is connected with 4 tools.
+
+## Workflow
+
+1. Edit your localhost site in Ompo
+2. Click **Send** and copy the prompt
+3. Paste the prompt into Cursor or Claude Code
+4. The agent calls:
+   - `get_edit({ id: "ed_8K42P" })`
+   - `apply_edit({ id: "ed_8K42P" })`
+5. The agent applies only the listed property changes to source files
+
+Ompo writes edit bundles to `.ompo/edits/` in your project. Open that project in your IDE so the MCP server can find them.
+
+## Tools
+
+- `list_edits` — list saved edit bundles in `.ompo/edits/`
+- `get_edit` — load a bundle by id
+- `explain_edit` — short summary of an edit
+- `apply_edit` — structured apply plan for the agent
+
+## Development
+
+```bash
+npm install
+npm run build
+npm start
+```
+
+For local testing before publish, point your MCP config at `node /absolute/path/to/mcp-server/dist/index.js`.

package/dist/apply-plan.d.ts

@@ -0,0 +1,29 @@
+import type { OmpoEditBundle, OmpoOperation } from './types.js';
+export type ApplySuggestion = {
+    property: string;
+    value: string;
+    strategy: 'inline-style' | 'css-rule' | 'component-markup' | 'text-content' | 'dom-structure';
+    notes?: string;
+};
+export type ApplyPlanFile = {
+    selector: string;
+    suggestions: ApplySuggestion[];
+};
+export type DomStructurePlan = {
+    kind: 'dom.insert' | 'dom.move' | 'dom.delete' | 'dom.flexWrap';
+    summary: string;
+    steps: string[];
+    payload: Record<string, unknown>;
+};
+export type ApplyPlan = {
+    editId: string;
+    scope: OmpoEditBundle['scope'];
+    sourceUrl: string;
+    files: ApplyPlanFile[];
+    domStructurePlans: DomStructurePlan[];
+    domChanges: OmpoOperation[];
+    warnings: string[];
+    instructions: string[];
+};
+export declare function buildApplyPlan(bundle: OmpoEditBundle): ApplyPlan;
+export declare function explainEdit(bundle: OmpoEditBundle): string;

package/dist/apply-plan.js

@@ -0,0 +1,172 @@
+function styleSuggestions(operation) {
+    return Object.entries(operation.changed).map(([property, value]) => ({
+        property,
+        value: String(value),
+        strategy: 'inline-style',
+        notes: 'Map this changed property to the matching source stylesheet, class, or component prop. Do not modify unrelated styles.'
+    }));
+}
+function buildDomStructurePlan(operation) {
+    switch (operation.kind) {
+        case 'dom.flexWrap':
+            return {
+                kind: 'dom.flexWrap',
+                summary: `Wrap ${operation.children.length} element(s) in a new flex ${operation.flexDirection} container`,
+                steps: [
+                    `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.`,
+                    'Do not change unrelated siblings or parent styling.'
+                ],
+                payload: {
+                    wrapperSelector: operation.wrapperSelector,
+                    parentSelector: operation.parentSelector,
+                    insertIndex: operation.index,
+                    flexDirection: operation.flexDirection,
+                    children: operation.children,
+                    wrapperStyles: operation.wrapperStyles
+                }
+            };
+        case 'dom.insert':
+            return {
+                kind: 'dom.insert',
+                summary: 'Insert new element into the page',
+                steps: [
+                    `Locate parent "${operation.parentSelector}" in source.`,
+                    `Insert the provided HTML at child index ${operation.index}.`,
+                    'Sanitize and adapt the HTML to the project’s component conventions before writing.'
+                ],
+                payload: {
+                    parentSelector: operation.parentSelector,
+                    insertIndex: operation.index,
+                    html: operation.html,
+                    selector: operation.selector
+                }
+            };
+        case 'dom.move':
+            return {
+                kind: 'dom.move',
+                summary: 'Move an existing element to a new parent',
+                steps: [
+                    `Locate element "${operation.selector}" in source using selector and surrounding structure.`,
+                    `Move it from "${operation.fromParentSelector}" (index ${operation.fromIndex}) to "${operation.toParentSelector}" at index ${operation.index}.`,
+                    'Preserve the element’s content and non-Ompo styling.'
+                ],
+                payload: {
+                    selector: operation.selector,
+                    fromParentSelector: operation.fromParentSelector,
+                    fromIndex: operation.fromIndex,
+                    toParentSelector: operation.toParentSelector,
+                    insertIndex: operation.index
+                }
+            };
+        case 'dom.delete':
+            return {
+                kind: 'dom.delete',
+                summary: 'Remove an element from the page',
+                steps: [
+                    `Locate and remove element "${operation.selector}" from source.`,
+                    'Do not remove surrounding structure unless required.'
+                ],
+                payload: {
+                    selector: operation.selector
+                }
+            };
+        default:
+            return null;
+    }
+}
+export function buildApplyPlan(bundle) {
+    const files = new Map();
+    const domStructurePlans = [];
+    const domChanges = [];
+    const warnings = [];
+    if (bundle.scope.mode === 'subtree' && bundle.scope.rootSelector?.includes('nth-of-type')) {
+        warnings.push(`Subtree scope uses selector "${bundle.scope.rootSelector}". Confirm the matching component in source before applying.`);
+    }
+    for (const operation of bundle.operations) {
+        if (operation.kind === 'style') {
+            const existing = files.get(operation.selector) ?? {
+                selector: operation.selector,
+                suggestions: []
+            };
+            existing.suggestions.push(...styleSuggestions(operation));
+            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.`);
+            }
+            continue;
+        }
+        if (operation.kind === 'text') {
+            const existing = files.get(operation.selector) ?? {
+                selector: operation.selector,
+                suggestions: []
+            };
+            if (operation.textContent !== undefined) {
+                existing.suggestions.push({
+                    property: 'textContent',
+                    value: operation.textContent,
+                    strategy: 'text-content'
+                });
+            }
+            if (operation.innerHTML !== undefined) {
+                existing.suggestions.push({
+                    property: 'innerHTML',
+                    value: operation.innerHTML,
+                    strategy: 'component-markup',
+                    notes: 'Sanitize inserted markup before writing to source files.'
+                });
+            }
+            files.set(operation.selector, existing);
+            continue;
+        }
+        const domPlan = buildDomStructurePlan(operation);
+        if (domPlan)
+            domStructurePlans.push(domPlan);
+        domChanges.push(operation);
+        if (operation.kind === 'dom.flexWrap') {
+            for (const child of operation.children) {
+                if (!child.id && !child.className && child.selector.includes('nth-of-type')) {
+                    warnings.push(`Flex-wrap child "${child.selector}" lacks id/class. Use tag "${child.tagName}"${child.textSnippet ? ` and text "${child.textSnippet}"` : ''} to locate it in source.`);
+                }
+            }
+        }
+    }
+    return {
+        editId: bundle.id,
+        scope: bundle.scope,
+        sourceUrl: bundle.source.url,
+        files: Array.from(files.values()),
+        domStructurePlans,
+        domChanges,
+        warnings: Array.from(new Set(warnings)),
+        instructions: [
+            'Only apply properties and operations listed in this plan.',
+            'Leave all untouched styling and markup unchanged.',
+            '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.'
+        ]
+    };
+}
+export function explainEdit(bundle) {
+    const styleCount = bundle.operations.filter((operation) => operation.kind === 'style').length;
+    const textCount = bundle.operations.filter((operation) => operation.kind === 'text').length;
+    const flexWrapCount = bundle.operations.filter((operation) => operation.kind === 'dom.flexWrap').length;
+    const domCount = bundle.operations.length - styleCount - textCount;
+    const scopeLabel = bundle.scope.mode === 'subtree' && bundle.scope.rootLabel
+        ? `${bundle.scope.rootLabel} and its children`
+        : 'all edits in the session';
+    const lines = [
+        `Edit ${bundle.id} contains ${bundle.meta.operationCount} operations for ${scopeLabel}.`,
+        `${styleCount} style change${styleCount === 1 ? '' : 's'}`,
+        `${textCount} text change${textCount === 1 ? '' : 's'}`,
+        `${domCount} DOM change${domCount === 1 ? '' : 's'}`
+    ];
+    if (flexWrapCount > 0) {
+        lines.push(`${flexWrapCount} flex-wrap operation${flexWrapCount === 1 ? '' : 's'}`);
+    }
+    lines.push(`Source preview: ${bundle.source.url}`);
+    return lines.join('\n');
+}

package/dist/edit-store.d.ts

@@ -0,0 +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;

package/dist/edit-store.js

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { OMPo_EDITS_DIR } from './types.js';
+export function findProjectRoot(startDir = process.cwd()) {
+    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;
+    }
+}
+function readIndex(projectRoot) {
+    const indexPath = join(projectRoot, OMPo_EDITS_DIR, 'index.json');
+    return JSON.parse(readFileSync(indexPath, 'utf8'));
+}
+function writeIndex(projectRoot, index) {
+    const indexPath = join(projectRoot, OMPo_EDITS_DIR, 'index.json');
+    writeFileSync(indexPath, `${JSON.stringify(index, null, 2)}\n`, 'utf8');
+}
+export function listEdits(projectRoot) {
+    return readIndex(projectRoot).edits;
+}
+export function readEditBundle(projectRoot, editId) {
+    const bundlePath = join(projectRoot, OMPo_EDITS_DIR, `${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);
+    const entry = index.edits.find((edit) => edit.id === editId);
+    if (!entry)
+        return;
+    entry.pulls += 1;
+    entry.lastPulledAt = new Date().toISOString();
+    writeIndex(projectRoot, index);
+}
+export function recordEditApplied(projectRoot, editId) {
+    const index = readIndex(projectRoot);
+    const entry = index.edits.find((edit) => edit.id === editId);
+    if (!entry)
+        return;
+    entry.appliedAt = new Date().toISOString();
+    writeIndex(projectRoot, index);
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { buildApplyPlan, explainEdit } from './apply-plan.js';
+import { findProjectRoot, listEdits, readEditBundle, recordEditApplied, recordEditPull } from './edit-store.js';
+const server = new McpServer({
+    name: 'ompo-mcp-server',
+    version: '0.1.0'
+});
+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.');
+    }
+    return projectRoot;
+}
+server.tool('list_edits', 'List Ompo edit bundles saved in the current project', {}, async () => {
+    const projectRoot = requireProjectRoot();
+    const edits = listEdits(projectRoot);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ projectRoot, edits }, null, 2)
+            }
+        ]
+    };
+});
+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);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(bundle, null, 2)
+            }
+        ]
+    };
+});
+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);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: explainEdit(bundle)
+            }
+        ]
+    };
+});
+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.', {
+    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);
+    const plan = buildApplyPlan(bundle);
+    if (markApplied) {
+        recordEditApplied(projectRoot, id);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(plan, null, 2)
+            }
+        ]
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+});

package/dist/types.d.ts

@@ -0,0 +1,84 @@
+export declare const OMPo_EDITS_DIR = ".ompo/edits";
+export type EditScope = {
+    mode: 'session' | 'subtree';
+    rootSelector?: string;
+    rootLabel?: string;
+};
+export type StyleOperation = {
+    kind: 'style';
+    selector: string;
+    changed: Record<string, unknown>;
+};
+export type DomInsertOperation = {
+    kind: 'dom.insert';
+    parentSelector: string;
+    index: number;
+    html: string;
+    selector?: string;
+};
+export type DomMoveOperation = {
+    kind: 'dom.move';
+    selector: string;
+    fromParentSelector: string;
+    fromIndex: number;
+    toParentSelector: string;
+    index: number;
+};
+export type DomDeleteOperation = {
+    kind: 'dom.delete';
+    selector: string;
+};
+export type ElementAnchor = {
+    selector: string;
+    tagName: string;
+    id?: string;
+    className?: string;
+    textSnippet?: string;
+};
+export type DomFlexWrapOperation = {
+    kind: 'dom.flexWrap';
+    wrapperSelector: string;
+    parentSelector: string;
+    index: number;
+    flexDirection: 'row' | 'column';
+    children: ElementAnchor[];
+    wrapperStyles: Record<string, unknown>;
+};
+export type TextOperation = {
+    kind: 'text';
+    selector: string;
+    textContent?: string;
+    innerHTML?: string;
+};
+export type OmpoOperation = StyleOperation | DomInsertOperation | DomMoveOperation | DomDeleteOperation | DomFlexWrapOperation | TextOperation;
+export type OmpoEditBundle = {
+    schemaVersion: number;
+    id: string;
+    createdAt: string;
+    ompoVersion: string;
+    source: {
+        url: string;
+        pathname: string;
+    };
+    scope: EditScope;
+    operations: OmpoOperation[];
+    meta: {
+        operationCount: number;
+        styleCount: number;
+        domCount: number;
+    };
+};
+export type EditIndexEntry = {
+    id: string;
+    createdAt: string;
+    scope: EditScope;
+    sourceUrl: string;
+    operationCount: number;
+    pulls: number;
+    lastPulledAt?: string;
+    appliedAt?: string;
+};
+export type EditIndex = {
+    version: 1;
+    edits: EditIndexEntry[];
+};

package/dist/types.js

@@ -0,0 +1 @@
+export const OMPo_EDITS_DIR = '.ompo/edits';

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@ompo-design/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for applying Ompo visual edits to a codebase",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "ompo",
+    "design",
+    "cursor",
+    "claude-code"
+  ],
+  "bin": {
+    "ompo-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.3",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}