@yugabytedb/meko-mcp 1.1.0 → 1.2.0

package/README.md

@@ -18,7 +18,7 @@ The installer is path-agnostic — the three forms below are equivalent. Pick th
 | 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.
+Claude Desktop has two install paths: a one-click `.mcpb` Desktop Extension downloaded from GitHub Releases, and the scripted installer here (run via `npx` or from a clone) — only the latter also installs the agent skill bundle. See [Claude Desktop install](#claude-desktop-install) below for the full comparison.
 
 **Interactive (recommended for first-time users):**
 
@@ -40,19 +40,57 @@ npx @yugabytedb/meko-mcp --local --yes
 npx @yugabytedb/meko-mcp --client cursor --local --scope project --yes
 ```
 
-**Claude Desktop install (local, from a repo clone):**
+**Claude Desktop install:**
 
-Claude Desktop supports two install paths — pick one per machine:
+Claude Desktop has two install paths — pick based on whether you want the agent skill (the behavioral guide that teaches the agent *when* to call Meko tools, like proactive `memory_add`):
 
-**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 A: `.mcpb` Desktop Extension | Option B: `create-meko-setup` installer |
+|---|---|---|
+| Installs MCP server | Yes | Yes |
+| Installs the agent skill (behavioral guide) | **No** | **Yes** |
+| Repo clone needed | No | No (works via `npx`); clones also work |
+| Best for | Non-technical users; quickest path to a working MCP connection | Anyone who wants the skill that teaches the agent *when* to call Meko tools |
+| Auto-capture of conversations/memories | No (see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8)) | Skill-driven only — the agent is prompted to call `memory_add` proactively, but it's not as reliable as Claude Code hooks |
+
+You can also combine both: install via `.mcpb` for the MCP wiring, then run Option B to add the skill bundle. If you re-run the Option B installer on top of an `.mcpb` install, it detects the existing entry and prompts before overwriting `mcpServers.meko`.
+
+**Option A — Desktop Extension (`.mcpb`), one-click:**
+
+1. Download `meko-<version>.mcpb` from the [GitHub Releases page](https://github.com/yugabyte/meko-mcp-server/releases) (e.g. `meko-1.1.0.mcpb`).
+2. Open **Claude Desktop > Settings > Extensions > Install from file** and select the file (or drag the file onto that pane).
+3. When prompted, paste your Meko MCP URL and API key.
+4. Quit and relaunch Claude Desktop.
+5. Verify in chat: *"Is Claude configured with an MCP Server for Meko?"*
+
+Prerequisite: Node 18+ on `PATH` (the bundle launches `npx mcp-remote` under the hood). See [`mcpb/README.md`](../mcpb/README.md) for what's in the bundle.
 
-**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:
+**Option B — `create-meko-setup` installer:**
+
+Run via `npx` (no clone needed) — pick the form that matches the table at the top of this section. From a repo clone:
 
 ```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.
+Or via npm without a clone:
+
+```bash
+npx @yugabytedb/meko-mcp --client claude-desktop --local --yes
+```
+
+This does two things:
+
+1. Merges `mcpServers.meko` into `claude_desktop_config.json` (backed up to `.bak`).
+2. Builds the `meko-mcp-tools-desktop.skill` bundle and prints its absolute path. The location depends on how you invoked the installer — under the npm package's asset root for `npx`, or under `skills/` in your clone.
+
+Then, **once per machine**:
+
+1. Open the path that the installer printed (look for the `Built Meko skill bundle: ...` log line).
+2. Drag `meko-mcp-tools-desktop.skill` onto the Claude Desktop window — or import it via **Settings > Extensions > Install from file**.
+3. Quit and relaunch Claude Desktop.
+4. Verify the skill loaded: ask *"Which Meko skills do you have available?"* — the agent should mention `meko-mcp-tools-desktop`.
+
+Re-run the installer to refresh the bundle when skill content updates; you'll need to re-drag the rebuilt `.skill` to pick up changes.
 
 **Install on multiple clients at once:**
 
@@ -112,9 +150,10 @@ The canary used to do a `memory_add` → `memory_get_by_id` → `memory_delete_b
   - MCP config: `~/.codex/config.toml` (TOML; `[mcp_servers.<name>]` block).
   - Skills path: `~/.agents/skills/meko-mcp-tools/` (the shared agent-skills convention).
   - System prompt: `~/.codex/AGENTS.md` (a Meko-managed sentinel block is upserted; user content outside the fence is preserved).
-  - **Cloud auth**: Codex's TOML stores `bearer_token_env_var = "MEKO_API_KEY"` rather than the key itself. You must export `MEKO_API_KEY` in your shell before launching Codex. The installer offers (interactively, never with `--yes`) to append the export line to your shell rc (`~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`). On macOS, when the desktop app is detected the installer also offers to run `launchctl setenv MEKO_API_KEY ...` since macOS apps launched from Finder/Dock do not inherit shell-rc env vars.
+  - **Cloud auth (MCP server)**: Codex's TOML stores `bearer_token_env_var = "MEKO_API_KEY"` rather than the key itself. You must export `MEKO_API_KEY` in your shell before launching Codex. The installer offers (interactively, never with `--yes`) to append the export line to your shell rc (`~/.zshrc` / `~/.bashrc` / `~/.config/fish/config.fish`). On macOS, when the desktop app is detected and an API key is supplied, the installer runs `launchctl setenv MEKO_API_KEY ...` so Codex.app launched from Finder/Dock can authenticate in the current login session.
   - **No project scope**: Codex has no per-project config. `--scope project --client codex` warns and degrades to user scope.
-  - **No auto-capture**: Codex does not expose user-installable session lifecycle hooks, so `session-start` / `session-end` capture is not available. Memory persistence still works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
+  - **Auto-capture hooks**: when Codex hooks are available, the installer writes Meko lifecycle hooks to `~/.codex/hooks.json` and prunes stale Meko hook entries from deleted install paths. Memory persistence still also works via the model proactively calling `memory_search` / `memory_add` (the AGENTS.md block prompts this).
+  - **API key storage** (security note): Codex's hooks.json schema rejects a top-level `env` block and provides no per-command env field. The installer writes `MEKO_MCP_URL` and (when supplied) `MEKO_API_KEY` to `~/.codex/meko-env.sh` at mode 0600 (user read/write only); each hook's `command` field sources that file before invoking bash, e.g. `. '/Users/you/.codex/meko-env.sh' && bash '/.../session-start.sh'`. The key never appears in process arguments, so `ps -ef` from another user can't lift it while a hook is running. Trust boundary is the same as `~/.aws/credentials` or `~/.netrc` — file-system permissions on the user's home directory. If your threat model precludes even that, install for the local Meko URL (no API key prompt), or skip hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` after install.
   - **Restart Codex.app** after install so it picks up the new MCP server registration.
 
 ## CLI Reference
@@ -132,7 +171,7 @@ Usage:
 | `--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` |
+| `--cursor-hook-mode <mode>` | Cursor hook strategy: `native` or `claude-compat` | `native` |
 | `--skip-skills` | Skip plugin marketplace and skills installation (steps 3-4) | `false` |
 | `--skip-validation` | Skip post-install validation (step 5) | `false` |
 | `--no-canary` | Skip the canary `datapack_list` call. Basic connectivity + tools/list still run. | `false` |
@@ -297,15 +336,15 @@ memory errs:  0                (failed memory_add calls; re-run with --force to
 | One-command install | Yes | 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 | via `codex mcp add` (CLI) or direct TOML write (App-only) |
 | Backup before config write | `.bak` on `~/.claude/settings.json` | `.bak` on `claude_desktop_config.json` | `.bak` on Cursor config | `.bak` on `~/.codex/config.toml` and `~/.codex/AGENTS.md` |
-| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (hybrid hook mode) | **No** — Codex has no user-installable hooks; AGENTS.md prompts proactive memory tool calls instead |
-| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Skill + AGENTS.md (proactive `memory_add`) |
+| Automatic conversation capture | Yes (hooks) | **No** — see [issue #8](https://github.com/amiramm/meko-mcp-server/issues/8) | Yes (native hooks) | Yes (hooks via `~/.codex/hooks.json`) |
+| Automatic memory persistence | Yes (hooks + skill) | Skill only (proactive `memory_add`) | Yes (hooks + skill) | Yes (hooks + skill + AGENTS.md) |
 | Skill install | Plugin marketplace (automatic) | `.skill` bundle auto-built, user drags into app | Copy into `.cursor/skills` | Copy into `~/.agents/skills/meko-mcp-tools/` |
 | Uninstall | Full automatic | MCP entry removed; skill must be removed manually from app | MCP + hooks + skills cleaned up | MCP entry, skill dir, and AGENTS.md block all cleaned up |
-| `agent_id` used by skill | `claude_code:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `claude_desktop` | `cursor:<repo>` per project (via Cursor hook); cross-project facts go to `meko_agent` | Whatever the agent derives by following the meko-mcp-tools skill (no hook injects an agent_id; the AGENTS.md block defers to the skill) |
+| `agent_id` used by skill | `claude_code:<repo>` per project (via SessionStart hook); cross-project facts go to `meko_agent` | `claude_desktop` | `cursor:<repo>` per project (via Cursor hook); cross-project facts go to `meko_agent` | `claude_code:<repo>` per project (capture.js still classifies non-cursor hooks as the `claude_code` client; native `codex:<repo>` derivation is a follow-up); cross-project facts go to `meko_agent` |
 | Transport | HTTP only | HTTP (or stdio via hand-edited config) | HTTP only | HTTP (Codex's `bearer_token_env_var` model) |
-| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`) |
+| Auth model | inline `Authorization: Bearer ...` header | inline header via `mcp-remote` | inline header | MCP server: env-var name reference (`MEKO_API_KEY` exported in shell or via `launchctl setenv`). Hooks: key written to `~/.codex/meko-env.sh` at mode 0600; each hook command sources the file before bash (no env block in Codex's hooks schema; see [Security](#security)). |
 | Project scope | Yes (`--scope project`) | No | Yes (`--scope project`) | No (warns and degrades to user scope) |
-| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | Auto-capture (blocked on upstream Codex exposing user-installable hooks) |
+| Deferred to a follow-up | — | `.mcpb` Desktop Extension packaging — see [issue #7](https://github.com/amiramm/meko-mcp-server/issues/7) | — | Native `codex:<repo>` agent_id classification in capture.js |
 
 ## Cloud vs Local
 
@@ -323,10 +362,19 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 
 ## Security
 
-**Where credentials are stored:**
+**Where credentials are stored** (per client; all files inherit standard user-only filesystem permissions):
 
-- **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.
+- **Claude Code**
+  - API key header — stored in `~/.claude.json` (MCP server config, managed by `claude mcp add`).
+  - `MEKO_API_KEY` env var — written to `~/.claude/settings.json` under `env` so lifecycle hooks can authenticate with the MCP server.
+- **Claude Desktop**
+  - `MEKO_API_KEY` env var — written to `claude_desktop_config.json` under `mcpServers.<name>.env`. The header itself uses `${MEKO_API_KEY}` interpolation in `args`, so the key value lives only in the `env` block.
+- **Cursor**
+  - API key header — stored in `~/.cursor/mcp.json` (or `.cursor/mcp.json` for project scope) under `mcpServers.<name>.headers.Authorization`.
+  - `MEKO_API_KEY` env var — written to `~/.cursor/hooks.json` (native hook mode) and/or `~/.claude/settings.json` (claude-compat hook mode) under `env` so lifecycle hooks can authenticate.
+- **OpenAI Codex (CLI + Desktop App)**
+  - MCP-server bearer reference — `~/.codex/config.toml` stores `bearer_token_env_var = "MEKO_API_KEY"`, **not** the key itself. The runtime env (shell rc or `launchctl setenv`) supplies the value.
+  - Hook commands — Codex's `~/.codex/hooks.json` schema rejects a top-level `env` block and provides no per-command env field, so the installer writes `MEKO_API_KEY` to `~/.codex/meko-env.sh` at **mode 0600** (user read/write only). Each Meko hook's `command` field sources that file before invoking bash, so the key never appears in process arguments — `ps -ef` from another user can't lift it while the hook runs. Same trust boundary as `~/.aws/credentials` or `~/.netrc` (file-system permissions on the user's home directory). To opt out: install for the local Meko URL (no key prompt), or skip Codex hook installation by deleting the Meko entries from `~/.codex/hooks.json` and removing `~/.codex/meko-env.sh` after install.
 
 **How credentials are protected:**
 
@@ -334,11 +382,12 @@ The installer auto-detects cloud vs local based on the URL: any URL containing `
 - `--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.
+- 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.
+- During Codex installs, the installer emits a `warn`-level log line confirming where the API key has been written.
 
 **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.
+Before modifying any config file the installer touches, it creates a `.bak` copy alongside the original (e.g. `~/.claude/settings.json.bak`, `~/.codex/config.toml.bak`, `~/.codex/AGENTS.md.bak`). The merge is additive: existing keys are preserved unless explicitly overridden.
 
 ## Upgrading
 

package/assets/hooks-handlers/before-submit-prompt.sh

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+
+# Cursor native beforeSubmitPrompt hook. It only reads local cache populated by
+# cursor-session-start.sh; it never performs Meko network calls.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+HOOK_INPUT="$(cat)"
+
+printf '%s' "$HOOK_INPUT" | MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" before-submit-prompt

package/assets/hooks-handlers/cursor-session-start.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+
+# Cursor native SessionStart hook. Cursor only documents context injection from
+# SessionStart, so this wrapper returns the Meko context synchronously.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+
+load_cursor_hook_env() {
+  if [ -n "${MEKO_MCP_URL:-}" ]; then
+    return
+  fi
+  eval "$(node -e '
+    const fs = require("fs");
+    const path = require("path");
+    function shellQuote(value) {
+      return "'"'"'" + String(value).replace(/'"'"'/g, "'"'"'\\'"'"''"'"'") + "'"'"'";
+    }
+    const candidates = [
+      path.join(process.cwd(), ".cursor", "hooks.json"),
+      path.join(process.env.HOME || "", ".cursor", "hooks.json"),
+    ];
+    for (const file of candidates) {
+      try {
+        const cfg = JSON.parse(fs.readFileSync(file, "utf8"));
+        const env = cfg && cfg.env && typeof cfg.env === "object" ? cfg.env : {};
+        const out = [];
+        for (const key of ["MEKO_MCP_URL", "MEKO_API_KEY"]) {
+          if (typeof env[key] === "string" && env[key]) {
+            out.push(`export ${key}=${shellQuote(env[key])}`);
+          }
+        }
+        if (out.length) {
+          process.stdout.write(out.join("\n"));
+          break;
+        }
+      } catch {}
+    }
+  ')"
+}
+
+load_cursor_hook_env
+MEKO_HOOK_CLIENT=cursor node "$SCRIPT_DIR/lib/capture.js" session-start