@ompo-design/mcp-server 0.1.0 → 0.1.3

package/README.md

@@ -1,67 +1,106 @@
 # @ompo-design/mcp-server
 
-Local MCP server for applying Ompo visual edits to a codebase.
+MCP server for applying Ompo visual edits to your codebase.
 
-## Setup
+## Important: this is not a web connector
 
-### Cursor
+**Settings → Connectors → Add custom connector** only works for **remote URLs** (hosted servers).
 
-Add to `.cursor/mcp.json` in your project:
+Ompo is a **local** MCP server. Install it via the steps below — not through the Connectors URL dialog.
 
-```json
-{
-  "mcpServers": {
-    "ompo": {
-      "command": "npx",
-      "args": ["-y", "@ompo-design/mcp-server"]
-    }
-  }
-}
+---
+
+## Claude Desktop — install for ALL projects (recommended)
+
+**Prerequisites:** [Node.js](https://nodejs.org) installed.
+
+### 1. Run one command in Terminal
+
+```bash
+npx @ompo-design/mcp-server setup-global
 ```
 
-### Claude Code
+This adds Ompo to:
+- Claude Desktop (`claude_desktop_config.json`)
+- Claude Code user config (`~/.claude.json`)
+
+Works across **every project**, not just one folder.
+
+### 2. Quit and reopen Claude Desktop
+
+Fully quit with **Cmd+Q**, then reopen.
 
-Add to `.mcp.json` in your project:
+### 3. Verify
+
+Open any **Code** project, then type:
+
+```text
+/mcp
+```
+
+**ompo** should show **4 tools**. Approve it if prompted.
+
+---
+
+## Manual install (Claude Desktop)
+
+1. Open **Claude Desktop → Settings → Developer → Edit Config**
+2. Add inside `mcpServers`:
 
 ```json
-{
-  "mcpServers": {
-    "ompo": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "@ompo-design/mcp-server"]
-    }
-  }
+"ompo": {
+  "command": "/usr/local/bin/npx",
+  "args": ["-y", "@ompo-design/mcp-server"],
+  "env": {}
 }
 ```
 
-Restart your IDE session after adding the config. In Claude Code, run `/mcp` to confirm `ompo` is connected with 4 tools.
+3. Save, quit Claude Desktop (Cmd+Q), reopen.
 
-## Workflow
+Use the full path to `npx` — the Desktop app often cannot find `npx` on its own.
 
-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.
+## Per-project install (optional)
 
-## Tools
+From a project folder:
 
-- `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
+```bash
+npx @ompo-design/mcp-server setup
+```
 
-## Development
+Creates `.mcp.json` in that project only.
+
+---
+
+## Check install
 
 ```bash
-npm install
-npm run build
-npm start
+npx @ompo-design/mcp-server doctor
 ```
 
-For local testing before publish, point your MCP config at `node /absolute/path/to/mcp-server/dist/index.js`.
+---
+
+## Using Ompo
+
+1. Edit your site in **Ompo**
+2. Click **Send** (creates `.ompo/edits/` in your project)
+3. Open that **same project** in Claude Code
+4. Paste the Send prompt — Claude calls `get_edit` and `apply_edit`
+
+---
+
+## Cursor
+
+`.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "ompo": {
+      "command": "npx",
+      "args": ["-y", "@ompo-design/mcp-server"]
+    }
+  }
+}
+```

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(argv: string[]): boolean;

package/dist/cli.js

@@ -0,0 +1,186 @@
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
+import { homedir } from 'os';
+import { join, resolve } from 'path';
+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) {
+    try {
+        return execSync(`which ${name}`, { encoding: 'utf8' }).trim();
+    }
+    catch {
+        return name;
+    }
+}
+function ompoServerEntry() {
+    const npxPath = resolveExecutable('npx');
+    return {
+        type: 'stdio',
+        command: npxPath,
+        args: ['-y', PACKAGE_NAME],
+        env: {}
+    };
+}
+function ompoDesktopEntry() {
+    const npxPath = resolveExecutable('npx');
+    return {
+        command: npxPath,
+        args: ['-y', PACKAGE_NAME],
+        env: {}
+    };
+}
+const CLAUDE_CODE_CONFIG = {
+    mcpServers: {
+        [SERVER_NAME]: ompoServerEntry()
+    }
+};
+function readJsonFile(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJsonFile(path, data) {
+    const directory = join(path, '..');
+    if (!existsSync(directory))
+        mkdirSync(directory, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+function mergeMcpServer(config, serverName, serverEntry) {
+    const mcpServers = typeof config.mcpServers === 'object' && config.mcpServers !== null
+        ? { ...config.mcpServers }
+        : {};
+    mcpServers[serverName] = serverEntry;
+    return {
+        ...config,
+        mcpServers
+    };
+}
+function claudeDesktopConfigPath() {
+    if (process.platform === 'darwin') {
+        return join(homedir(), 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+    }
+    if (process.platform === 'win32' && process.env.APPDATA) {
+        return join(process.env.APPDATA, 'Claude', 'claude_desktop_config.json');
+    }
+    return join(homedir(), '.config', 'Claude', 'claude_desktop_config.json');
+}
+function claudeCodeUserConfigPath() {
+    return join(homedir(), '.claude.json');
+}
+export function runCli(argv) {
+    const command = argv[0];
+    if (command === 'setup') {
+        runProjectSetup();
+        return true;
+    }
+    if (command === 'setup-global') {
+        runGlobalSetup();
+        return true;
+    }
+    if (command === 'doctor') {
+        runDoctor();
+        return true;
+    }
+    if (command === 'help' || command === '--help' || command === '-h') {
+        printHelp();
+        return true;
+    }
+    return false;
+}
+function runProjectSetup() {
+    const projectRoot = resolve(process.cwd());
+    const configPath = join(projectRoot, '.mcp.json');
+    writeJsonFile(configPath, CLAUDE_CODE_CONFIG);
+    console.log(`Created ${configPath}`);
+    printProjectNextSteps(projectRoot);
+}
+function runGlobalSetup() {
+    const desktopPath = claudeDesktopConfigPath();
+    const claudeCodePath = claudeCodeUserConfigPath();
+    const npxPath = resolveExecutable('npx');
+    const desktopConfig = mergeMcpServer(readJsonFile(desktopPath), SERVER_NAME, ompoDesktopEntry());
+    const claudeCodeConfig = mergeMcpServer(readJsonFile(claudeCodePath), SERVER_NAME, ompoServerEntry());
+    writeJsonFile(desktopPath, desktopConfig);
+    writeJsonFile(claudeCodePath, claudeCodeConfig);
+    console.log('Installed Ompo MCP globally for Claude Desktop and Claude Code.');
+    console.log('');
+    console.log(`  Claude Desktop: ${desktopPath}`);
+    console.log(`  Claude Code:    ${claudeCodePath}`);
+    console.log(`  npx path:       ${npxPath}`);
+    console.log('');
+    console.log('Next steps:');
+    console.log('  1. Quit Claude Desktop completely (Cmd+Q)');
+    console.log('  2. Reopen Claude Desktop');
+    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 storePath = getOmpoEditsStorePath();
+    console.log('Ompo MCP doctor');
+    console.log('');
+    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 MCP config', configPath],
+        ['Claude Desktop', desktopPath],
+        ['Claude Code user', claudeCodePath]
+    ]) {
+        const config = readJsonFile(path);
+        const servers = typeof config.mcpServers === 'object' && config.mcpServers !== null
+            ? config.mcpServers
+            : {};
+        if (servers[SERVER_NAME]) {
+            console.log(`${label}: ompo configured (${path})`);
+        }
+        else if (existsSync(path)) {
+            console.log(`${label}: found, but ompo missing (${path})`);
+        }
+        else {
+            console.log(`${label}: missing (${path})`);
+        }
+    }
+    console.log('');
+    if (editsStoreReady()) {
+        console.log('Edits: ready (Send from Ompo to add more)');
+    }
+    else {
+        console.log('Edits: none yet (click Send in Ompo first)');
+    }
+    console.log('');
+    console.log('Global install: npx @ompo-design/mcp-server setup-global');
+}
+function printProjectNextSteps(projectRoot) {
+    console.log('');
+    console.log('Next steps:');
+    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');
+    console.log('');
+    console.log('For all projects, run: npx @ompo-design/mcp-server setup-global');
+}
+function printHelp() {
+    console.log(`Ompo MCP server (${PACKAGE_NAME})`);
+    console.log('');
+    console.log('Usage:');
+    console.log(`  npx ${PACKAGE_NAME}                 Run MCP server (used by your IDE)`);
+    console.log(`  npx ${PACKAGE_NAME} setup           Create .mcp.json in current project`);
+    console.log(`  npx ${PACKAGE_NAME} setup-global    Install for all Claude projects`);
+    console.log(`  npx ${PACKAGE_NAME} doctor          Check install status`);
+}

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,51 +1,44 @@
 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;
-    }
+import { join } from 'path';
+import { getOmpoEditsStorePath } from './edits-path.js';
+function editsDirectory() {
+    return getOmpoEditsStorePath();
+}
+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

@@ -3,26 +3,28 @@ 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';
+import { runCli } from './cli.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.3'
 });
-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)
             }
         ]
     };
@@ -30,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: [
             {
@@ -45,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: [
             {
@@ -57,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: [
@@ -81,6 +83,8 @@ server.tool('apply_edit', 'Build an apply plan for an Ompo edit. The agent shoul
     };
 });
 async function main() {
+    if (runCli(process.argv.slice(2)))
+        return;
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }

package/package.json

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