@yugabytedb/meko-mcp 1.0.3

package/README.md

@@ -0,0 +1,505 @@
+# Meko Setup Installer
+
+A zero-dependency Node.js CLI that configures [Meko MCP Server](https://mekodata.netlify.app/) for Claude Code, Claude Desktop, and Cursor in one command. It registers MCP server settings, configures hook/runtime environment where supported, installs skills support, and validates the setup.
+
+Reduces manual setup to a single command.
+
+## Quick Start
+
+The installer is path-agnostic — the three forms below are equivalent. Pick the one that matches how you obtained the code:
+
+| Source | Command |
+|---|---|
+| npm (no repo clone needed) | `npx @yugabytedb/meko-mcp [options]` |
+| Repo clone, from repo root | `node installer/bin/create-meko-setup.mjs [options]` |
+| Repo clone, from `installer/` | `node bin/create-meko-setup.mjs [options]` |
+
+Claude Desktop install (issue [#7](https://github.com/amiramm/meko-mcp-server/issues/7)) still requires a repo clone — the `.skill` packaging script isn't bundled. All other clients work from the npm tarball without a checkout.
+
+**Interactive (recommended for first-time users):**
+
+```bash
+npx @yugabytedb/meko-mcp
+```
+
+The installer walks you through connection type, URL, API key, and skills installation with guided prompts.
+
+**Local one-liner (docker-compose stack already running):**
+
+```bash
+npx @yugabytedb/meko-mcp --local --yes
+```
+
+**Cursor project install (local):**
+
+```bash
+npx @yugabytedb/meko-mcp --client cursor --local --scope project --yes
+```
+
+**Claude Desktop install (local, from a repo clone):**
+
+Claude Desktop supports two install paths — pick one per machine:
+
+**Option A — Desktop Extension (`.mcpb`), one-click.** Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/amiramm/meko-mcp-server/releases) and drag it onto **Claude Desktop > Settings > Extensions > Install from file**. You'll be prompted for your Meko MCP URL and API key in the Settings UI, and that's it. Best for non-technical users. See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle. Prerequisite: Node 18+ on PATH (the bundle launches `npx mcp-remote` under the hood).
+
+**Option B — `create-meko-setup` installer.** Use this when you want a scripted / repeatable install, or when you need the `.skill` bundle built at the same time:
+
+```bash
+node installer/bin/create-meko-setup.mjs --client claude-desktop --local --yes
+```
+
+Builds a `.skill` bundle at `skills/meko-mcp-tools-desktop.skill`. Drag it onto Claude Desktop (or import via Settings > Extensions) once and restart the app. The installer also merges `mcpServers.meko` into `claude_desktop_config.json`. If it detects that Meko was previously installed via the `.mcpb` path (Option A), it flags the entry and prompts before overwriting so you don't end up with two conflicting configs.
+
+**Install on multiple clients at once:**
+
+```bash
+# Target two clients in one run:
+npx @yugabytedb/meko-mcp --client claude-code,claude-desktop --local --yes
+
+# Target every supported client (claude-code, claude-desktop, cursor):
+npx @yugabytedb/meko-mcp --client all --local --yes
+```
+
+Each client is installed sequentially. A failure on one does not abort the others — the command exits with status 2 on partial success, 1 on total failure.
+
+**CI / non-interactive (Cloud Meko):**
+
+```bash
+npx @yugabytedb/meko-mcp \
+  --url https://your-mcp.mekodev.com/mcp \
+  --api-key "$MEKO_API_KEY" \
+  --yes
+```
+
+## What It Does
+
+The installer performs up to 5 steps (some are skippable via flags):
+
+| Step | Action | Command / File Modified |
+|------|--------|------------------------|
+| 1 | Register MCP server | `claude mcp add meko <url> --transport http --scope user` (with `-H "API_KEY: <key>"` for cloud) |
+| 2 | Set hook environment vars | Writes `MEKO_MCP_URL` and `MEKO_API_KEY` into `~/.claude/settings.json` under the `env` key |
+| 3 | Register plugin marketplace | `claude plugin marketplace add yugabyte/meko-mcp-server --sparse skills --scope user` |
+| 4 | Install skills plugin | `claude plugin install meko-agent-skills --scope user` |
+| 5 | Validate setup | Config check via `claude mcp list`, MCP `initialize` handshake, `tools/list` verification |
+
+**Files modified (depends on `--client`):**
+
+- **Claude Code**
+  - `~/.claude/settings.json` -- env vars (`MEKO_MCP_URL`, `MEKO_API_KEY`) that lifecycle hooks read at runtime.
+  - Claude Code internal config (`~/.claude.json`) -- MCP registration and plugin state (managed by `claude` CLI).
+- **Claude Desktop**
+  - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+  - Linux: `~/.config/Claude/claude_desktop_config.json`
+  - Windows: `%USERPROFILE%/AppData/Roaming/Claude/claude_desktop_config.json`
+- **Cursor**
+  - MCP config: `~/.cursor/mcp.json` or `.cursor/mcp.json`
+  - Hooks config: `~/.cursor/hooks.json` or `.cursor/hooks.json` (native mode)
+  - Skills path: `~/.cursor/skills` or `.cursor/skills`
+
+## CLI Reference
+
+```
+Usage:
+  create-meko-setup [options]
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--client <list>` | Target client(s): one or more of `claude-code`, `claude-desktop`, `cursor`. Comma-separated, or `all` | `claude-code` |
+| `--url <url>` | MCP server URL (from app.mekodev.com > Datapacks > Connect) | _(interactive prompt)_ |
+| `--api-key <key>` | API key for Cloud Meko authentication | _(interactive prompt or `$MEKO_API_KEY` env)_ |
+| `--local` | Use local Meko at `http://localhost:8000/mcp` (no API key needed) | `false` |
+| `--scope <scope>` | Config scope: `user` or `project` (`claude-desktop` uses user scope config) | `user` |
+| `--name <name>` | MCP server name in config | `meko` |
+| `--cursor-hook-mode <mode>` | Cursor hook strategy: `native`, `claude-compat`, `hybrid` | `hybrid` |
+| `--skip-skills` | Skip plugin marketplace and skills installation (steps 3-4) | `false` |
+| `--skip-validation` | Skip post-install validation (step 5) | `false` |
+| `--dry-run` | Show what would be done without making changes | `false` |
+| `--uninstall` | Remove Meko MCP server, skills, env vars, and marketplace entry | `false` |
+| `--verbose` | Show detailed output (API keys are always redacted) | `false` |
+| `--yes` | Accept all defaults, run non-interactively | `false` |
+| `-h`, `--help` | Show help message | |
+| `-v`, `--version` | Show version | |
+
+Migrate subcommand flags (see [Migrate Existing Data](#migrate-existing-data) below for details):
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--migrate` | Start a detached migration of existing Claude Code + Cursor conversations and `CLAUDE.md` memories into Meko. | `false` |
+| `--with-migrate` | With `--yes`, kick off `--migrate` at the end of a successful install without prompting. CI-friendly. | `false` |
+| `--migrate-status` | Print the status of the latest (or `--run-id`-specified) migration run. | `false` |
+| `--migrate-stop` | Stop the running migration (SIGTERM, then SIGKILL after 2s). | `false` |
+| `--no-extract` | Skip `memory_add(messages=...)` (the Mem0 extractor call). Replay via `conversation_create` + `conversation_add_message` only; standalone `memory_add(text=...)` for CLAUDE.md / memory files still runs. | `false` |
+| `--rate <n>` | Max concurrent MCP calls during migration. | `4` |
+| `--force` | Ignore a live lockfile or re-ingest already-processed items. | `false` |
+| `--run-id <id>` | Target a specific run-id for `--migrate-status`. | _(latest run)_ |
+
+## Migrate Existing Data
+
+After installing Meko, `--migrate` seeds your new datapack with the conversations and memories already on your machine so the first session isn't an empty slate.
+
+### What the migrator reads
+
+| Source | Location | Becomes |
+|---|---|---|
+| Claude Code transcripts | `~/.claude/projects/<slug>/<uuid>.jsonl` | One Meko conversation (one Langfuse trace) per session; one paired user↔assistant turn per message pair. |
+| Cursor transcripts | `~/.cursor/projects/<name>/agent-transcripts/<uuid>/*.jsonl` | Same — one conversation per session, one paired turn per user↔assistant round. |
+| User-scope CLAUDE.md | `~/.claude/CLAUDE.md` | One memory per top-level `# ` section (agent = `claude-code:user`). |
+| Project-scope CLAUDE.md | `<projectCwd>/.claude/CLAUDE.md` | One memory per top-level `# ` section (agent = `claude-code:<slug>`). |
+| Indexed project memories | `~/.claude/projects/<slug>/memory/*.md` | One memory per file; YAML frontmatter (`name`, `description`, `type`) is preserved in metadata. |
+
+Project `cwd` is derived by reading the `cwd` field from a real session file in each slug directory — never by reverse-slugging the directory name, which loses `.` and `-` in component names.
+
+### What the migrator writes (MCP calls)
+
+Per migrated Claude Code / Cursor session:
+
+1. **`conversation_create`** — once per session. Captures `cwd`, `gitBranch`, `startedAt`, and source agent (`claude-code` or `cursor`) in metadata. Returns the `conversation_id` used for subsequent calls.
+2. **`conversation_add_message`** — once per paired user↔assistant turn. Carries `input`, `output`, and `reasoning` (thinking blocks + tool-use/tool-result summaries), plus a deterministic `seed` for server-side dedup. Fire-and-forget; Meko batches to Langfuse.
+3. **`memory_add(messages=[{role,content},...])`** — once per paired turn. This invokes Meko's server-side Mem0 extractor (the same pipeline the demo chatbot uses at `chatbot.py:177-178`) so the migrator seeds structured memories, not just raw transcripts. Skipped entirely under `--no-extract`.
+
+Per CLAUDE.md / memory directory discovered:
+
+4. **`conversation_create`** — one umbrella "memory-migration" conversation per agent (reused for all MD items under that agent, to satisfy Meko's `memory_add` requirement that memories be associated with a conversation).
+5. **`memory_add(text=...)`** — once per CLAUDE.md section or `memory/*.md` file. Uses the `text=` form (not `messages=`) because the file is already curated memory; no LLM extraction needed.
+
+So a real run exercises **both** the Langfuse observability surface (1 + 2) and the Mem0 memory surface (3 + 5). `--dry-run` prints the exact breakdown before you commit:
+
+```
+Dry run:
+  Claude Code sessions: 94
+  Cursor sessions:      10
+  Paired user↔asst turns: 887
+  Memory items (MD):    14
+  Planned MCP calls:
+    conversation_create:      105   ← one per session + one umbrella per memory agent
+    conversation_add_message: 887   ← one per paired turn (Langfuse)
+    memory_add (messages=):   887   ← one per paired turn (Mem0 extractor)
+    memory_add (text=):       14    ← one per CLAUDE.md section / memory file
+    total:                    1893
+```
+
+### Why the migrator drives memory extraction
+
+The Meko MCP server does **not** currently auto-extract memories on `conversation_add_message` (that call only writes to Langfuse). See [yugabyte/meko#120](https://github.com/yugabyte/meko/issues/120) — auto-extraction on the live write path was deferred because of LLM cost, but batch extraction for *previously-existing* conversations was explicitly endorsed. Until #120 lands, the migrator closes that gap itself by calling `memory_add(messages=...)` once per paired turn.
+
+`--no-extract` skips step 3 above, turning migration into conversation-only replay. Use it when you're re-running for any reason other than seeding memories, when extraction cost is a concern, or if / when #120 lands (the migrator will be updated to default to `--no-extract` then).
+
+### Scope
+
+- `--scope user` (default) — every Claude Code and Cursor project on the machine, plus `~/.claude/CLAUDE.md`, plus every per-project `.claude/CLAUDE.md` and indexed `memory/*.md` directory.
+- `--scope project` — only sessions whose `cwd` equals `process.cwd()`, plus that one project's `.claude/CLAUDE.md` and memory directory.
+
+### Running
+
+```bash
+# Plan-only (no HTTP, no fork). Works without --url / --api-key — prints
+# session counts, paired-turn counts, and per-tool planned-call totals so
+# you can estimate LLM extraction cost before firing a real run.
+create-meko-setup --migrate --dry-run --scope user
+
+# Start a real migration; returns immediately with a run-id.
+create-meko-setup --migrate --scope user --url https://... --api-key "$MEKO_API_KEY"
+
+# Install + migrate in one command (CI-friendly).
+create-meko-setup --url https://... --api-key "$MEKO_API_KEY" --yes --with-migrate
+
+# Watch progress (or pass --run-id <id>).
+create-meko-setup --migrate-status
+
+# Stop a long-running migration (SIGTERM, then SIGKILL after 2s).
+create-meko-setup --migrate-stop
+
+# Conversation replay only; do not invoke the Mem0 extractor.
+create-meko-setup --migrate --scope user --no-extract
+```
+
+### Behavior around install
+
+- **Interactive install** (no `--yes`): after a successful install, the installer dry-runs the enumerator, prints how much local data would be migrated, and asks `Y/n`. Declining prints a reminder to run `--migrate` later.
+- **`--yes` without `--with-migrate`**: install succeeds silently and prints a one-line tip pointing at `create-meko-setup --migrate`. No migration is started.
+- **`--yes --with-migrate`**: install succeeds, then the detached migration is started automatically. Progress via `--migrate-status`.
+
+### Idempotency, resume, and state
+
+- Per-run logs: `~/.meko/migrate/<run-id>/log.ndjson` (one JSON object per line). `tail -f | jq .` is a reasonable debug loop.
+- Per-run progress snapshot: `~/.meko/migrate/<run-id>/progress.json` (what `--migrate-status` reads).
+- Durable state: `~/.meko/migrate/state.json` tracks per-session checkpoints (`conversationId`, `messagesSent`, `lastUuid`, `status`) and per-memory content hashes. A re-run skips sessions marked `done` and memories whose body hash is unchanged. A partial session resumes from `lastUuid + 1`.
+- Server-side dedup: `conversation_add_message` gets a deterministic `seed = sha256(agentId + ":" + sessionUuid + ":" + messageUuid)` so partial-run overlap doesn't create duplicate messages.
+- `--force` wipes resume state and re-issues every MCP call (useful for testing or after a server-side wipe).
+
+### What does NOT get migrated (v1)
+
+- Slash-command skills, hooks, and `.claude/settings.json` — those remain in Claude Code's own config; Meko has no equivalent tool.
+- Knowledge-base documents — would need an S3 upload path and `knowledgebase_trigger_index_creation` wiring.
+- Transcripts from other coding agents (Aider, Continue.dev, Windsurf, Codex CLI). Claude Code + Cursor only.
+- `user_id` is left null on every call (the server fills it from the API key). Multi-user routing is a follow-up.
+
+## Client Compatibility Matrix
+
+| Capability | Claude Code | Claude Desktop | Cursor |
+|---|---|---|---|
+| One-command install | Yes | Yes | Yes |
+| MCP server registration | via `claude mcp add` | via `claude_desktop_config.json` merge using `mcp-remote` stdio bridge | via `.cursor/mcp.json` merge |
+| Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | `.bak` on Cursor config |
+| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (hybrid hook mode) |
+| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) |
+| Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` |
+| Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up |
+| `agent_id` used by skill | `claude_code` | `claude_desktop` | `claude_code` |
+| Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only |
+| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — |
+
+## Cloud vs Local
+
+| | Cloud Meko | Local Meko |
+|---|-----------|-----------|
+| **URL** | Provided by app.mekodev.com > Datapacks > Connect | `http://localhost:8000/mcp` |
+| **Authentication** | Requires `--api-key` or `$MEKO_API_KEY` env var | None |
+| **MCP registration** | Includes `-H "API_KEY: <key>"` header | No auth header |
+| **Hook env vars** | Both `MEKO_MCP_URL` and `MEKO_API_KEY` written to settings | Only `MEKO_MCP_URL` written |
+| **Infrastructure** | Hosted, no local setup needed | Requires `docker compose up -d` running the Meko stack |
+| **Use case** | Production, team collaboration | Development, testing |
+| **Flag** | `--url <url> --api-key <key>` | `--local` |
+
+The installer auto-detects cloud vs local based on the URL: any URL containing `localhost` or `127.0.0.1` is treated as local (no API key required). All other URLs are cloud and require authentication.
+
+## Security
+
+**Where credentials are stored:**
+
+- **API key header** -- stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`). Readable only by the current user.
+- **`MEKO_API_KEY` env var** -- written to `~/.claude/settings.json` so lifecycle hooks can authenticate with the MCP server. This file has standard user-only filesystem permissions.
+
+**How credentials are protected:**
+
+- The `--verbose` flag never prints the actual API key. It always appears as `<set>` or `<not set>`.
+- `--dry-run` mode redacts the key in displayed commands (shown as `<set>`).
+- The API key is never logged to stdout or stderr during normal operation.
+- Interactive mode uses masked input (echoes `*` characters) when prompting for the API key.
+- The `MEKO_API_KEY` env var fallback means the key does not need to appear in shell history -- set it in your shell profile or CI secrets.
+
+**Backups:**
+
+Before modifying `~/.claude/settings.json`, the installer creates a `.bak` copy at `~/.claude/settings.json.bak`. The merge is additive: existing keys are preserved unless explicitly overridden.
+
+## Troubleshooting
+
+### Claude Code CLI not found
+
+```
+Claude Code CLI not found.
+Install it first: https://docs.anthropic.com/en/docs/claude-code/getting-started
+```
+
+The `claude` binary is not installed or not on your PATH. After installing, verify:
+
+```bash
+which claude
+claude --version
+```
+
+### Connection refused
+
+```
+Connection refused. Is the MCP server running?
+For local Meko, ensure `docker compose up -d` has started the stack.
+```
+
+For local setups, confirm the stack is running and the MCP endpoint is accessible:
+
+```bash
+curl -s http://localhost:8000/mcp -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}'
+```
+
+### Authentication failure (401 / 403)
+
+```
+Server returned 401. Verify your API key is correct and has not expired.
+```
+
+- Confirm the API key at app.mekodev.com > Datapacks > Connect.
+- If using `$MEKO_API_KEY` env var, ensure it is exported in the current shell.
+- Re-run the installer interactively to re-enter the key.
+
+### Plugin marketplace already registered
+
+This is non-fatal. The installer logs a warning and continues. If you need to force a re-registration, uninstall first (`--uninstall`) then install again.
+
+### Skills plugin already installed
+
+Same as above -- non-fatal. The existing plugin is kept. Use `--uninstall` followed by a fresh install if you need to update.
+
+### Invalid JSON in settings.json
+
+```
+Invalid JSON in ~/.claude/settings.json: ...
+Fix the file manually or delete it and re-run the installer.
+```
+
+The settings file has been corrupted or hand-edited incorrectly. Restore from the `.bak` backup:
+
+```bash
+cp ~/.claude/settings.json.bak ~/.claude/settings.json
+```
+
+### Missing core tools
+
+```
+Missing core tools: memory_search, conversation_create. Found 0 tool(s) total.
+```
+
+The MCP server responded but does not expose the expected tools (`memory_search`, `conversation_create`, `db_summarize_database`). This usually means a server version mismatch. Update the MCP server or check which datapack is connected.
+
+### DNS lookup failed
+
+```
+DNS lookup failed for host. Check the URL is correct.
+```
+
+Verify the MCP URL is spelled correctly and your network can resolve it.
+
+### Request timed out
+
+```
+Request timed out after 10s. Is the server running and reachable?
+```
+
+The server did not respond within 10 seconds. Check network connectivity, firewall rules, or server health.
+
+### Claude Desktop doesn't see the new MCP server
+
+After the installer writes `claude_desktop_config.json`, **quit and relaunch** Claude Desktop — it only reads the config on startup. If Desktop shows *"Some MCP servers could not be loaded"* or the server still doesn't appear:
+
+1. **Check the `meko` entry is the stdio shape.** Claude Desktop rejects the HTTP `{ "url": ... }` shape with a silent warning. The installer writes the stdio form that wraps the URL with the `mcp-remote` bridge:
+   ```json
+   "meko": {
+     "command": "npx",
+     "args": ["-y", "mcp-remote", "<url>", "--transport", "http-only"]
+   }
+   ```
+   If you see a `"url"` field at the top level instead, re-run the installer to rewrite it.
+2. Validate the config is well-formed JSON: `python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json`
+3. Verify `npx` is on PATH (the bridge is launched via `npx -y mcp-remote`): `which npx`
+4. Check the Desktop logs at `~/Library/Logs/Claude/mcp.log` (macOS) or `%APPDATA%\Claude\logs\` (Windows) for load errors.
+5. Restore the `.bak` backup if needed: `cp ~/Library/Application\ Support/Claude/claude_desktop_config.json.bak ~/Library/Application\ Support/Claude/claude_desktop_config.json`
+
+### Claude Desktop skill bundle didn't build
+
+The installer runs `skills/scripts/package-desktop-skill.sh` via `bash`. If packaging fails:
+
+- Run the script directly to see the error: `bash skills/scripts/package-desktop-skill.sh`
+- Verify `zip` is on your PATH (`which zip`)
+- The output file `skills/meko-mcp-tools-desktop.skill` is gitignored — safe to regenerate
+
+### Claude Desktop capture doesn't happen automatically
+
+Expected: Claude Desktop has no SessionStart / PreCompact / SessionEnd hook API, so automatic transcript capture is not yet implemented. The skill tells the agent to proactively call `memory_add` and `conversation_create`, but this relies on agent behavior. See [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) for the planned automatic-capture work.
+
+## Uninstalling
+
+Remove Meko configuration for the selected client:
+
+```bash
+node installer/bin/create-meko-setup.mjs --client cursor --scope project --uninstall
+```
+
+This reverses installer-managed changes for the selected client:
+
+1. Removes MCP registration/config entries
+2. Removes installer-managed hook/runtime config
+3. Removes installer-managed skills wiring where applicable
+
+Each step is safe if the component was already removed -- the uninstaller logs a warning and continues.
+
+Use `--verbose` for detailed output during uninstall:
+
+```bash
+node installer/bin/create-meko-setup.mjs --uninstall --verbose
+```
+
+## Manual Test Plan
+
+| # | Scenario | Steps | Expected Result |
+|---|----------|-------|-----------------|
+| M1 | Fresh local install | `node installer/bin/create-meko-setup.mjs --local --yes` with docker stack running | All 5 steps pass, validation shows 3 green checks |
+| M2 | Fresh cloud install | Run interactively, provide Cloud Meko URL + API key | MCP registered with API_KEY header, env vars set, validation passes |
+| M3 | Existing config | Run installer when `meko` MCP is already registered | Prompts to overwrite; answering No keeps existing config |
+| M4 | No claude CLI | Run on a machine without `claude` in PATH | Exits with error message and install link |
+| M5 | Server unreachable | Install with `--skip-validation`, then re-run without it | Install succeeds; validation warns about connectivity |
+| M6 | Uninstall | Run `--uninstall` after a successful install | MCP removed, env vars removed, plugin removed, marketplace entry removed |
+| M7 | Dry run | `--local --dry-run --verbose` | Shows all planned commands with redacted keys, no files changed on disk |
+| M8 | Cloud hooks capture | After cloud install, start a new Claude Code session | SessionStart hook creates conversation via cloud MCP (check watermark in `~/.claude/meko-capture/`) |
+| M9 | API key redaction | Run with `--verbose` using a cloud URL and API key | API key appears only as `<set>`, never as the actual value |
+| M10 | Idempotent re-install | Run installer twice with `--local --yes` | Second run detects existing config, overwrites cleanly, all checks pass |
+| M11 | Invoke from repo root | `cd <repo> && node installer/bin/create-meko-setup.mjs --client cursor --local --scope user --dry-run --yes` | Dry-run succeeds; no path-resolution errors |
+| M12 | Invoke from `installer/` | `cd <repo>/installer && node bin/create-meko-setup.mjs --client cursor --local --scope user --dry-run --yes` | Dry-run succeeds (note: `--scope project` gives different `.cursor/...` paths because project scope uses cwd — pick a fixed cwd or `--scope user` to compare byte-for-byte) |
+| M13 | Clone-free via npm pack | `cd installer && npm pack` → `npm install -g ./yugabytedb-meko-mcp-*.tgz` → from a directory with **no repo clone**, run `create-meko-setup --client cursor --local --scope project --dry-run` | Succeeds; asset paths resolve under the globally-installed `node_modules/@yugabytedb/meko-mcp/assets/...` |
+
+## Development
+
+### Prerequisites
+
+- Node.js >= 18.0.0 (required for `util.parseArgs` and `node:test`)
+- No `npm install` needed -- zero external dependencies
+
+### Project Structure
+
+```
+installer/
+  package.json               # @yugabytedb/meko-mcp
+  bin/
+    create-meko-setup.mjs    # CLI entry point (arg parsing, orchestration)
+  lib/
+    installer.mjs            # Shared multi-client orchestration
+    clients/                 # Per-client adapters (claude-code/desktop/cursor)
+    claude-code.mjs          # Backward-compatible Claude wrapper
+    config.mjs               # Safe JSON read/merge/write + path helpers
+    detect.mjs               # Claude CLI and existing config detection
+    logger.mjs               # ANSI-colored console output (respects NO_COLOR)
+    prompt.mjs               # Interactive readline prompts (choice, text, secret, yes/no)
+    validate.mjs             # Post-install validation (config, connectivity, tools)
+  test/
+    config.test.mjs          # Unit tests for JSON merge/read/write
+    clients.test.mjs         # Unit tests for cursor adapter behavior
+    validate.test.mjs        # Unit tests for validation logic
+    installer.test.mjs       # Integration tests for full install flow
+    fixtures/                # Mock settings files for tests
+```
+
+### Running Tests
+
+```bash
+cd installer
+
+# All tests
+node --test test/
+
+# Unit tests only
+npm run test:unit
+
+# Integration tests (opt-in; can mutate local config)
+npm run test:integration
+
+# Cloud round-trip tests (opt-in; regression coverage for MEKO-20).
+# Requires credentials in the shell:
+export MEKO_TEST_CLOUD_URL=https://<your-mcp>.mekodev.com/mcp
+export MEKO_TEST_API_KEY=<your-cloud-api-key>
+npm run test:integration:cloud
+```
+
+The cloud round-trip tests point the installer at a throw-away `$HOME` via
+`spawnSync`, so the developer's real `~/.claude/settings.json` is never
+modified. They skip cleanly when either env var is unset.
+
+### Design Principles
+
+- **Zero external dependencies** -- Node.js built-ins only (`fs`, `path`, `readline`, `child_process`, `url`, `http`, `https`, `os`, `node:test`, `node:assert`), matching the pattern of `capture.js`.
+- **Non-destructive** -- Creates `.bak` backups before modifying settings.
+- **Additive merges** -- New env vars are added without overwriting existing unrelated keys.
+- **Graceful failures** -- Non-critical errors (plugin already exists) warn and continue; only missing prerequisites cause hard failures.
+- **API key safety** -- Never logged, always redacted in output.
+- **NO_COLOR support** -- Respects the `NO_COLOR` env var to suppress ANSI color codes.