@ompo-design/mcp-server 0.1.0 → 0.1.2

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,183 @@
+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';
+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');
+}
+function runDoctor() {
+    const projectRoot = resolve(process.cwd());
+    const configPath = join(projectRoot, '.mcp.json');
+    const desktopPath = claudeDesktopConfigPath();
+    const claudeCodePath = claudeCodeUserConfigPath();
+    const editsRoot = findProjectRoot(projectRoot);
+    console.log('Ompo MCP doctor');
+    console.log('');
+    console.log(`Project folder: ${projectRoot}`);
+    console.log(`Node: ${process.version}`);
+    console.log(`npx: ${resolveExecutable('npx')}`);
+    console.log('');
+    for (const [label, path] of [
+        ['Project 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 (editsRoot) {
+        console.log(`Edits: found ${join(editsRoot, '.ompo/edits/')}`);
+    }
+    else {
+        console.log('Edits: none yet (use 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 (creates .ompo/edits/)');
+    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.js

@@ -1,7 +1,23 @@
 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)))];
+}
 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);

package/dist/index.js

@@ -3,6 +3,7 @@ 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 { runCli } from './cli.js';
 import { findProjectRoot, listEdits, readEditBundle, recordEditApplied, recordEditPull } from './edit-store.js';
 const server = new McpServer({
     name: 'ompo-mcp-server',
@@ -81,6 +82,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.2",
   "description": "MCP server for applying Ompo visual edits to a codebase",
   "type": "module",
   "license": "MIT",