@yugabytedb/meko-mcp 1.2.0 → 2.1.0

package/lib/clients/cursor.mjs

@@ -16,8 +16,11 @@ import {
   writeJsonFile,
 } from "../config.mjs";
 import {
+  MEKO_MCP_USER_AGENT,
   getInstallerVersion,
+  installStableTree,
   isDanglingSymlink,
+  isPackagedInstall,
   markerIsStale,
   readInstallerMarker,
   resolveHooksRoot,
@@ -31,7 +34,6 @@ const SKILLS = [{ name: "meko-mcp-tools" }];
 
 const HOOKS = [
   { event: "sessionStart", script: "cursor-session-start.sh", timeout: 15000 },
-  { event: "beforeSubmitPrompt", script: "before-submit-prompt.sh", matcher: "UserPromptSubmit", timeout: 2000 },
   { event: "preCompact", script: "pre-compact.sh" },
   { event: "sessionEnd", script: "session-end.sh", timeout: 30000 },
 ];
@@ -40,6 +42,9 @@ const HOOKS = [
  * @returns {object}
  */
 export function createCursorAdapter(customPaths = {}) {
+  const resolveHooksRootPath = customPaths.resolveHooksRoot ?? resolveHooksRoot;
+  const resolveSkillSourcePath = customPaths.resolveSkillSource ?? resolveSkillSource;
+  const packagedInstallDetector = customPaths.isPackagedInstall ?? isPackagedInstall;
   const paths = {
     getMcpPath: customPaths.getMcpPath ?? getCursorMcpPath,
     getHooksPath: customPaths.getHooksPath ?? getCursorHooksPath,
@@ -70,8 +75,13 @@ export function createCursorAdapter(customPaths = {}) {
     detectExisting(name, { scope, projectRoot }) {
       const path = paths.getMcpPath(scope, projectRoot);
       const cfg = readJsonFile(path);
-      const found = Boolean(cfg?.mcpServers?.[name]);
-      return { found, status: found ? "Configured" : "" };
+      const entry = cfg?.mcpServers?.[name];
+      const found = Boolean(entry);
+      return {
+        found,
+        status: found ? "Configured" : "",
+        ...(typeof entry?.url === "string" ? { url: entry.url } : {}),
+      };
     },
     removeRegistration(name, { scope, projectRoot }) {
       const mcpPath = paths.getMcpPath(scope, projectRoot);
@@ -85,6 +95,7 @@ export function createCursorAdapter(customPaths = {}) {
       if (dryRun) {
         log.dim(`  Would update ${mcpPath}:`);
         log.dim(`    mcpServers.${name}.url = ${url}`);
+        log.dim(`    mcpServers.${name}.headers.User-Agent = ${MEKO_MCP_USER_AGENT}`);
         if (apiKey) {
           log.dim("    mcpServers.<name>.headers.Authorization = <set>");
         }
@@ -95,16 +106,18 @@ export function createCursorAdapter(customPaths = {}) {
       if (!cfg.mcpServers || typeof cfg.mcpServers !== "object") {
         cfg.mcpServers = {};
       }
-      const server = { url };
+      const server = { url, headers: { "User-Agent": MEKO_MCP_USER_AGENT } };
       if (apiKey) {
-        server.headers = { Authorization: `Bearer ${apiKey}` };
+        server.headers.Authorization = `Bearer ${apiKey}`;
       }
       cfg.mcpServers[name] = server;
       writeJsonFile(mcpPath, cfg);
     },
     setHookEnvironment({ url, apiKey, dryRun, log, scope, projectRoot, cursorHookMode }) {
       const mode = cursorHookMode || "native";
+      const installedHooksRoot = getCursorHooksInstallRoot(paths, scope, projectRoot);
       if (dryRun) {
+        log.dim(`  Would copy Cursor hook scripts to ${installedHooksRoot}`);
         if (mode === "native") {
           log.dim(`  Would configure Cursor hooks at ${paths.getHooksPath(scope, projectRoot)}`);
         }
@@ -114,11 +127,27 @@ export function createCursorAdapter(customPaths = {}) {
         return;
       }
 
+      installStableTree(resolveHooksRootPath(), installedHooksRoot);
+
       if (mode === "native") {
-        installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths });
+        installNativeCursorHooks({
+          scope,
+          projectRoot,
+          url,
+          apiKey,
+          paths,
+          handlersRoot: installedHooksRoot,
+        });
       }
       if (mode === "claude-compat") {
-        installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths });
+        installClaudeCompatHooks({
+          scope,
+          projectRoot,
+          url,
+          apiKey,
+          paths,
+          handlersRoot: installedHooksRoot,
+        });
       }
     },
     installSkills({ dryRun, log, scope, projectRoot }) {
@@ -132,7 +161,7 @@ export function createCursorAdapter(customPaths = {}) {
 
       mkdirSync(skillDir, { recursive: true });
       for (const skill of SKILLS) {
-        const source = resolveSkillSource(skill.name);
+        const source = resolveSkillSourcePath(skill.name);
         const destination = join(skillDir, skill.name);
 
         if (existsSync(destination)) {
@@ -172,7 +201,9 @@ export function createCursorAdapter(customPaths = {}) {
           removePath(destination);
         }
 
-        const strategy = symlinkOrCopy(source, destination);
+        const strategy = symlinkOrCopy(source, destination, {
+          preferCopy: packagedInstallDetector(),
+        });
         // Only stamp a marker when we materialized a real copy. Writing into
         // a symlinked source dir would mutate the shipped asset tree, which
         // is confusing at best and a permission error at worst. Symlinks
@@ -217,10 +248,20 @@ export function createCursorAdapter(customPaths = {}) {
     async validateConfig({ serverName, scope, projectRoot }) {
       const mcpPath = paths.getMcpPath(scope, projectRoot);
       const cfg = readJsonFile(mcpPath);
-      if (cfg?.mcpServers?.[serverName]) {
-        return { ok: true, message: `Server "${serverName}" is registered in ${mcpPath}.` };
+      const entry = cfg?.mcpServers?.[serverName];
+      if (!entry) {
+        return { ok: false, message: `Server "${serverName}" not found in ${mcpPath}.` };
+      }
+      const hasUserAgent = Object.keys(entry.headers ?? {}).some(
+        (key) => key.toLowerCase() === "user-agent",
+      );
+      if (!hasUserAgent) {
+        return {
+          ok: false,
+          message: `Server "${serverName}" in ${mcpPath} is missing the User-Agent header required by the Cloud WAF.`,
+        };
       }
-      return { ok: false, message: `Server "${serverName}" not found in ${mcpPath}.` };
+      return { ok: true, message: `Server "${serverName}" is registered in ${mcpPath}.` };
     },
   };
 }
@@ -245,7 +286,22 @@ function ensureEnvBlock(cfg, url, apiKey) {
   }
 }
 
-function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
+function getCursorHooksInstallRoot(paths, scope, projectRoot) {
+  return join(
+    dirname(paths.getHooksPath(scope, projectRoot)),
+    "meko-hooks",
+    "hooks-handlers",
+  );
+}
+
+function installNativeCursorHooks({
+  scope,
+  projectRoot,
+  url,
+  apiKey,
+  paths,
+  handlersRoot,
+}) {
   const hooksPath = paths.getHooksPath(scope, projectRoot);
   const cfg = readJsonFile(hooksPath);
   if (!cfg.version) cfg.version = 1;
@@ -253,7 +309,6 @@ function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
     cfg.hooks = {};
   }
 
-  const handlersRoot = resolveHooksRoot();
   pruneNativeCursorMekoHooks(cfg.hooks);
   for (const hook of HOOKS) {
     const scriptPath = join(handlersRoot, hook.script);
@@ -281,14 +336,20 @@ function installNativeCursorHooks({ scope, projectRoot, url, apiKey, paths }) {
 // will be pruned; the user must re-run the Cursor installer to restore
 // them. pruneMekoHookEntries emits a warning on any removal so the user
 // has a chance to notice before hooks silently disappear.
-function installClaudeCompatHooks({ scope, projectRoot, url, apiKey, paths }) {
+function installClaudeCompatHooks({
+  scope,
+  projectRoot,
+  url,
+  apiKey,
+  paths,
+  handlersRoot,
+}) {
   const settingsPath = paths.getClaudeCompatSettingsPath(scope, projectRoot);
   const cfg = readJsonFile(settingsPath);
   if (!cfg.hooks || typeof cfg.hooks !== "object") {
     cfg.hooks = {};
   }
 
-  const handlersRoot = resolveHooksRoot();
   const compatMap = {
     SessionStart: { script: "session-start.sh", timeout: 15000 },
     PreCompact: { script: "pre-compact.sh" },
@@ -354,9 +415,7 @@ function upsertClaudeCompatHook(hooksObj, event, entry) {
 }
 
 function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
-  const handlersRoot = resolveHooksRoot();
-  const scripts = ["session-start.sh", "cursor-session-start.sh", "before-submit-prompt.sh", "pre-compact.sh", "session-end.sh"]
-    .map((name) => join(handlersRoot, name));
+  const handlersRoot = getCursorHooksInstallRoot(paths, scope, projectRoot);
 
   if (mode === "native") {
     const hooksPath = paths.getHooksPath(scope, projectRoot);
@@ -366,7 +425,7 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
         if (!Array.isArray(cfg.hooks[event])) continue;
         cfg.hooks[event] = cfg.hooks[event].filter((item) => {
           if (!item?.command) return true;
-          return !scripts.some((script) => item.command.includes(script));
+          return !isMekoHookCommand(item.command);
         });
       }
       writeJsonFile(hooksPath, cfg);
@@ -389,7 +448,7 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
           if (!Array.isArray(group?.hooks)) return group;
           const filtered = group.hooks.filter((item) => {
             if (!item?.command) return true;
-            return !scripts.some((script) => item.command.includes(script));
+            return !isMekoHookCommand(item.command);
           });
           return { ...group, hooks: filtered };
         }).filter((group) => {
@@ -400,6 +459,8 @@ function uninstallCursorHooks({ scope, projectRoot, mode, paths }) {
       writeJsonFile(settingsPath, cfg);
     }
   }
+
+  removePath(dirname(handlersRoot));
 }
 
 /**

package/lib/config.mjs

@@ -143,6 +143,32 @@ export function getCodexMekoEnvFilePath() {
   return join(codexHome, "meko-env.sh");
 }
 
+/**
+ * Return the stable directory the Codex hook scripts are copied into at
+ * install time.
+ *
+ * Why a dedicated copy instead of referencing the shipped asset root
+ * directly: when the installer runs via `npx @yugabytedb/meko-mcp`, the
+ * asset root resolves to an ephemeral npm cache dir
+ * (`~/.npm/_npx/<hash>/node_modules/@yugabytedb/meko-mcp/assets/...`).
+ * npx garbage-collects those hashed dirs, so a hooks.json that pins the
+ * npx path becomes a dangling pointer on the next npx run — Codex then
+ * spawns `bash '<missing script>'`, which exits 127 ("command not found")
+ * and surfaces as a failed SessionStart hook + the misleading "could not
+ * reach Meko" fallback. Copying the scripts under $CODEX_HOME gives the
+ * hook a home-dir-stable target that outlives the npx cache.
+ *
+ * The `hooks-handlers` leaf is preserved so the command string still
+ * matches `isMekoHookCommand`'s prune regex — that lets a reinstall
+ * auto-heal any stale npx-pinned entry left by an older installer.
+ *
+ * @returns {string}
+ */
+export function getCodexHooksInstallRoot() {
+  const codexHome = process.env.CODEX_HOME || join(homedir(), ".codex");
+  return join(codexHome, "meko-hooks", "hooks-handlers");
+}
+
 /**
  * Return path to the shared agent-skills directory used by Codex
  * (and other agent runtimes that follow the convention).

package/lib/detect.mjs

@@ -110,7 +110,7 @@ export function getClaudeCodeConfigPath() {
  *   `scope`      — "user" (default) or "project". Project scope looks under `projects[projectRoot].mcpServers`.
  *   `projectRoot` — absolute path used as the key into `projects[...]` when `scope === "project"`.
  *                   Ignored for user scope. Must be supplied by the caller for project scope.
- * @returns {{ found: boolean, status: string }}
+ * @returns {{ found: boolean, status: string, url?: string }}
  *   `found`  - true if a matching MCP entry exists at the scope-appropriate location.
  *   `status` - "Configured" when found, "" otherwise. (Kept as a string for
  *              API compatibility with the prior implementation; callers use
@@ -129,5 +129,10 @@ export function detectExistingMeko(serverName = "meko", options = {}) {
   if (!entry) {
     return { found: false, status: "" };
   }
-  return { found: true, status: "Configured" };
+  const url = typeof entry.url === "string" ? entry.url : undefined;
+  return {
+    found: true,
+    status: "Configured",
+    ...(url ? { url } : {}),
+  };
 }

package/lib/installer.mjs

@@ -33,6 +33,7 @@ export async function install(options) {
     skipSkills = false,
     skipValidation = false,
     skipCanary = false,
+    installStatusline = false,
     dryRun = false,
     verbose = false,
     yes = false,
@@ -50,6 +51,7 @@ export async function install(options) {
 
   let totalSteps = 3; // register + env/hooks + validate
   if (!skipSkills) totalSteps += 1;
+  if (installStatusline && typeof adapter.installStatusline === "function") totalSteps += 1;
   if (skipValidation) totalSteps -= 1;
 
   banner(`Meko Setup for ${adapter.displayName}`);
@@ -171,6 +173,28 @@ export async function install(options) {
     currentStep++;
   }
 
+  if (installStatusline && typeof adapter.installStatusline === "function") {
+    try {
+      adapter.installStatusline({
+        scope,
+        dryRun,
+        verbose,
+        log: LOG,
+        settingsPath,
+        projectRoot,
+      });
+      stepOk(
+        currentStep,
+        totalSteps,
+        dryRun ? "Wiring datapack statusline (dry-run)." : "Datapack statusline wired.",
+      );
+    } catch (err) {
+      stepFail(currentStep, totalSteps, "Failed to wire datapack statusline.");
+      warn(`Non-critical: ${err.message}`);
+    }
+    currentStep++;
+  }
+
   if (!skipValidation) {
     if (dryRun) {
       dim("Would validate config, MCP connectivity, and tool availability.");

package/lib/mcp-transport.mjs

@@ -39,6 +39,11 @@ export function jsonRpcRequest(url, payload, apiKey, sessionId, opts = {}) {
     const headers = {
       "Content-Type": "application/json",
       Accept: "application/json, text/event-stream",
+      // Cloud Meko sits behind a WAF that 403s requests with no User-Agent
+      // (Node's http/https send none by default). This transport powers install
+      // validation and migration against cloud URLs, so it hits the same WAF as
+      // the capture hooks — send an explicit UA so those calls aren't rejected.
+      "User-Agent": "meko-installer/1.0 (+https://github.com/yugabyte/meko-mcp-server)",
     };
     if (apiKey) {
       headers["Authorization"] = `Bearer ${apiKey}`;

package/lib/prompt.mjs

@@ -50,7 +50,7 @@ function question(query) {
  *
  * @example
  *   const choice = await askChoice('Connection type:', [
- *     { label: 'Cloud Meko', description: 'Hosted at mekodev.com' },
+ *     { label: 'Cloud Meko', description: 'Hosted at mekodata.ai' },
  *     { label: 'Local Meko', description: 'docker-compose stack' },
  *   ]);
  */

package/lib/url-selection.mjs

@@ -0,0 +1,55 @@
+import { MEKO_PRODUCTION_MCP_URL } from "./clients/common.mjs";
+
+function validHttpUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const candidate = value.trim();
+  try {
+    const parsed = new URL(candidate);
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+    parsed.pathname = parsed.pathname.replace(/\/+$/, "") || "/";
+    return { value: candidate, comparisonKey: parsed.toString() };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Select the URL offered by interactive/non-interactive setup.
+ * Explicit CLI URLs are resolved before this helper is called.
+ */
+export function resolveSuggestedMcpUrl({
+  adapters,
+  clients,
+  name = "meko",
+  scope = "user",
+  projectRoot = process.cwd(),
+}) {
+  const existingUrlsByKey = new Map();
+  for (const client of clients) {
+    const adapter = adapters[client];
+    if (!adapter?.detectExisting) continue;
+    try {
+      const existing = adapter.detectExisting(name, { scope, projectRoot });
+      const url = existing?.found ? validHttpUrl(existing.url) : null;
+      if (url && !existingUrlsByKey.has(url.comparisonKey)) {
+        existingUrlsByKey.set(url.comparisonKey, url.value);
+      }
+    } catch {
+      // Existing-config discovery is advisory. Installation performs its own
+      // prerequisite and config checks later with actionable errors.
+    }
+  }
+
+  const uniqueUrls = [...existingUrlsByKey.values()];
+  if (uniqueUrls.length === 1) {
+    return { url: uniqueUrls[0], source: "existing", existingUrls: uniqueUrls };
+  }
+  if (uniqueUrls.length > 1) {
+    return { url: null, source: "conflict", existingUrls: uniqueUrls };
+  }
+  return {
+    url: MEKO_PRODUCTION_MCP_URL,
+    source: "production-default",
+    existingUrls: [],
+  };
+}

package/lib/validate.mjs

@@ -32,7 +32,6 @@ const CORE_TOOLS = [
   "memory_search",
   "memory_get_by_id",
   "conversation_create",
-  "db_summarize_database",
   "datapack_list",
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yugabytedb/meko-mcp",
-  "version": "1.2.0",
+  "version": "2.1.0",
   "description": "Single-line installer for Meko MCP Server across Claude and Cursor clients",
   "type": "module",
   "bin": {

package/scripts/bundle-assets.mjs

@@ -22,6 +22,10 @@ const PAYLOAD = [
     from: join(repoRoot, "skills", "skills", "meko-mcp-tools-desktop"),
     to: join(assetsDir, "skills", "meko-mcp-tools-desktop"),
   },
+  {
+    from: join(repoRoot, "skills", "skills", "meko-select-datapack-desktop"),
+    to: join(assetsDir, "skills", "meko-select-datapack-desktop"),
+  },
   {
     from: join(repoRoot, "skills", "hooks-handlers"),
     to: join(assetsDir, "hooks-handlers"),
@@ -30,6 +34,10 @@ const PAYLOAD = [
     from: join(repoRoot, "skills", "scripts", "package-desktop-skill.sh"),
     to: join(assetsDir, "scripts", "package-desktop-skill.sh"),
   },
+  {
+    from: join(repoRoot, "skills", "scripts", "meko-statusline.sh"),
+    to: join(assetsDir, "scripts", "meko-statusline.sh"),
+  },
 ];
 
 const cleaning = process.argv.includes("--clean");

package/assets/skills/meko-mcp-tools/references/tools-db-query-patterns.md

@@ -1,38 +0,0 @@
-# Read-Only vs Write Query Execution Patterns
-
-**WRONG:** `db_run_write_query(scope="write", query="SELECT * FROM users")` — requires write scope unnecessarily, triggers guardrail validation, returns `{"rows_affected": -1}` instead of data.
-**WRONG:** `db_run_read_only_query(scope="read", query="INSERT INTO ...")` — fails: "cannot execute INSERT in a read-only transaction."
-
-## How Each Tool Works
-
-**`db_run_read_only_query`:** `BEGIN READ ONLY` → execute → `ROLLBACK`. Returns JSON array of row objects.
-
-**`db_run_write_query`:** Guardrail validation → execute → `COMMIT`. Returns `{"rows_affected": N}`.
-
-## When to Use db_summarize_database
-
-Use instead of writing your own `information_schema` query when you need a table overview:
-
-```
-db_summarize_database(scope="read", schema="public")
--- Returns table names, column schemas, AND row counts in one call
-```
-
-## SQL Best Practices
-
-**Schema qualification:** For non-public schemas, use `analytics."monthly_revenue"` and pass `schema="analytics"` to `db_summarize_database`.
-
-**String escaping:** Queries are passed directly to `cur.execute()` — no parameter placeholders. Escape values in SQL: `WHERE name = 'O''Brien'`.
-
-**LIMIT on exploratory queries:**
-```
-db_run_read_only_query(scope="read", query="SELECT * FROM large_table LIMIT 25")
-```
-
-**Batch large writes:** Due to the 1000-row INSERT cap, split large inserts. Or use `INSERT ... SELECT` for unlimited rows from an existing table.
-
-**One statement per call:**
-```
-WRONG: "CREATE TABLE a (id INT); CREATE TABLE b (id INT);"
-RIGHT: Two separate db_run_write_query calls
-```

package/assets/skills/meko-mcp-tools/references/tools-scope-permissions.md

@@ -1,75 +0,0 @@
-# Scope Permission Hierarchy and Per-Tool Requirements
-
-**WRONG:** `db_run_write_query(scope="read", ...)` → PermissionError: requires 'write' or higher.
-**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
-
-## Scope Hierarchy
-
-```
-admin  (level 2)  -- can do everything
-  ↓
-write  (level 1)  -- can read + write, not admin-only
-  ↓
-read   (level 0)  -- can only read
-```
-
-Higher scopes include lower scopes. An unrecognized scope string always fails.
-
-## Per-Tool Requirements
-
-### read scope (11 tools)
-
-| Tool | Group |
-|------|-------|
-| `db_summarize_database` | Database |
-| `db_run_read_only_query` | Database |
-| `knowledgebase_check_index_status` | RAG |
-| `memory_search` | Memory |
-| `memory_get_by_id` | Memory |
-| `memory_get_all` | Memory |
-| `flush_pending_memory_candidates` | Memory |
-| `conversation_get` | Conversation |
-| `conversation_list` | Conversation |
-| `datapack_list` | Datapack |
-| `datapack_describe` | Datapack |
-
-### write scope (11 tools)
-
-| Tool | Group |
-|------|-------|
-| `db_run_write_query` | Database |
-| `knowledgebase_trigger_index_creation` | RAG |
-| `knowledgebase_add_source_to_index` | RAG |
-| `memory_add` | Memory |
-| `memory_update` | Memory |
-| `memory_delete_by_id` | Memory |
-| `conversation_create` | Conversation |
-| `conversation_add_message` | Conversation |
-| `conversation_update` | Conversation |
-| `datapack_create` | Datapack |
-| `datapack_update` | Datapack |
-
-### admin scope (3 tools — destructive, irreversible)
-
-| Tool | Group |
-|------|-------|
-| `memory_delete_all` | Memory |
-| `conversation_delete` | Conversation |
-| `datapack_delete` | Datapack |
-
-Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
-
-## Best Practices
-
-1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
-2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
-
-## Common Mistakes
-
-**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
-
-Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
-
-The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
-
-**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.

package/assets/skills/meko-mcp-tools/references/tools-write-guardrails.md

@@ -1,30 +0,0 @@
-# Write Query Guardrails and Blocked Operations
-
-**WRONG:** `"INSERT INTO a (...); INSERT INTO b (...)"` → "Multi-statement queries not allowed." Send one statement per call.
-**WRONG:** `"DROP SCHEMA analytics CASCADE"` → "DROP SCHEMA is not allowed."
-**WRONG:** `"\\d users"` → psql meta-commands not supported. Use `information_schema` queries via `db_run_read_only_query`.
-
-## Blocked Operations
-
-**Database/schema destruction:** `DROP DATABASE`, `DROP SCHEMA`, `ALTER DATABASE`, `CREATE DATABASE`
-**Role/privilege manipulation:** `GRANT`, `REVOKE`, `CREATE/ALTER/DROP ROLE`, `CREATE/ALTER/DROP USER`
-**Filesystem/code execution:** `COPY TO/FROM`, `LOAD`, `DO $$`, `CREATE EXTENSION`
-**Server configuration:** `ALTER SYSTEM`, `RESET ALL`
-**Dangerous functions:** `pg_sleep`, `pg_read_file`, `pg_write_file`, `lo_import`, `lo_export`, `dblink`
-**Structural rules:** One SQL statement per call (multi-statement rejected). No psql `\` commands.
-
-## Configurable Limits
-
-**Bulk INSERT row cap** (default 1000, env: `YB_MCP_MAX_INSERT_ROWS`): Counts parenthesized tuples in VALUES. Does NOT apply to `INSERT ... SELECT`. Split large inserts into batches of 1000 or fewer.
-
-**WHERE clause enforcement** (off by default):
-- `YB_MCP_REQUIRE_WHERE_ON_UPDATE=true` → rejects `UPDATE` without top-level `WHERE`
-- `YB_MCP_REQUIRE_WHERE_ON_DELETE=true` → rejects `DELETE` without top-level `WHERE`
-
-A `WHERE` inside a subquery does NOT satisfy the check.
-
-## What IS Allowed
-
-`INSERT INTO ... VALUES`, `INSERT INTO ... SELECT` (no row limit), `UPDATE ... SET ... WHERE`, `DELETE FROM ... WHERE`, `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE INDEX`, `TRUNCATE`, `CALL procedure_name(...)`.
-
-SQL comments are stripped before guardrail checks — patterns cannot be hidden in comments.

package/assets/skills/meko-mcp-tools-desktop/references/tools-scope-permissions.md

@@ -1,75 +0,0 @@
-# Scope Permission Hierarchy and Per-Tool Requirements
-
-**WRONG:** `db_run_write_query(scope="read", ...)` → PermissionError: requires 'write' or higher.
-**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
-
-## Scope Hierarchy
-
-```
-admin  (level 2)  -- can do everything
-  ↓
-write  (level 1)  -- can read + write, not admin-only
-  ↓
-read   (level 0)  -- can only read
-```
-
-Higher scopes include lower scopes. An unrecognized scope string always fails.
-
-## Per-Tool Requirements
-
-### read scope (11 tools)
-
-| Tool | Group |
-|------|-------|
-| `db_summarize_database` | Database |
-| `db_run_read_only_query` | Database |
-| `knowledgebase_check_index_status` | RAG |
-| `memory_search` | Memory |
-| `memory_get_by_id` | Memory |
-| `memory_get_all` | Memory |
-| `flush_pending_memory_candidates` | Memory |
-| `conversation_get` | Conversation |
-| `conversation_list` | Conversation |
-| `datapack_list` | Datapack |
-| `datapack_describe` | Datapack |
-
-### write scope (11 tools)
-
-| Tool | Group |
-|------|-------|
-| `db_run_write_query` | Database |
-| `knowledgebase_trigger_index_creation` | RAG |
-| `knowledgebase_add_source_to_index` | RAG |
-| `memory_add` | Memory |
-| `memory_update` | Memory |
-| `memory_delete_by_id` | Memory |
-| `conversation_create` | Conversation |
-| `conversation_add_message` | Conversation |
-| `conversation_update` | Conversation |
-| `datapack_create` | Datapack |
-| `datapack_update` | Datapack |
-
-### admin scope (3 tools — destructive, irreversible)
-
-| Tool | Group |
-|------|-------|
-| `memory_delete_all` | Memory |
-| `conversation_delete` | Conversation |
-| `datapack_delete` | Datapack |
-
-Agent and knowledge-base lifecycle tools are not MCP-exposed — see "Platform capabilities NOT exposed via MCP" in `tools-overview.md`.
-
-## Best Practices
-
-1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
-2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
-
-## Common Mistakes
-
-**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
-
-Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
-
-The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
-
-**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.