fix rule injection

Author: yanivt-jfrog

README.md

@@ -18,7 +18,19 @@ Skills are vendored from [jfrog/jfrog-skills](https://github.com/jfrog/jfrog-ski
 
 ## JFrog MCP Gateway integration
 
-When the plugin is enabled, every Claude Code session starts with the rules in [`templates/jfrog-mcp-management.md`](templates/jfrog-mcp-management.md) injected into the model's context (via the [`additionalContext`](https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart) `SessionStart` hook output). **No instructions file is written to your repo** — the rules live only in the plugin and reach the model directly through the hook.
+When the plugin is enabled, every Claude Code session starts by asking the JFrog MCP Gateway whether the current tenant is entitled to the AI Catalog feature (`npx @jfrog/mcp-gateway --should-inject`). If the gateway returns **entitled**, the rules in [`templates/jfrog-mcp-management.md`](templates/jfrog-mcp-management.md) are injected into the model's context via the [`additionalContext`](https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart) `SessionStart` hook output. **No instructions file is written to your repo** — the rules live only in the plugin and reach the model directly through the hook.
+
+The check fails closed: anything other than a clean "entitled" response (entitlement denied, no JFrog server resolvable, network/`npx` failure, timeout) skips the injection so the plugin stays inert when the gateway can't authoritatively say "yes".
+
+You can short-circuit the check with the `JF_MCP_GATEWAY_FORCE_ENABLE` env var in the shell that launches Claude Code — this is mainly for tests, demos, and air-gapped setups:
+
+| Value | Effect |
+| --- | --- |
+| `true` | Always inject the instructions; skip the entitlement check entirely. |
+| `false` | Never inject; skip the entitlement check entirely. |
+| unset / anything else | Run `--should-inject` and respect its decision (default). |
+
+Set `JF_MCP_GATEWAY_DEBUG=1` to have the hook log its decision to stderr (visible in Claude Code's logs panel) for troubleshooting.
 
 The rules tell Claude to:
 
@@ -27,7 +39,9 @@ The rules tell Claude to:
 - Write the entry to **`.mcp.json` (project scope) by default** — creating the file if it doesn't exist — so the entry stays alongside the project and the team can share it via git. Only fall back to `~/.claude.json` (user scope) when you ask for it explicitly. Either way, secrets stay out of the file via `${ENV_VAR}` expansion (Claude Code has no native interactive secret prompt).
 - Run the gateway's `--login` automatically for OAuth-only remote MCPs.
 
-After a new MCP entry is written, you must (1) **export every `${VAR}` referenced by the entry** in the shell that will launch Claude Code so the gateway has them at server-start time (an unset variable shows as `[Contains warnings]` in `/mcp` — informational only — and any tool call needing that value will fail at runtime), (2) **quit and relaunch Claude Code** in the same directory, and (3) **approve the server** at the `Approve MCP server <name> from .mcp.json?` prompt. Claude Code only reads `mcpServers` at session start, and `.mcp.json` entries require explicit per-project approval (stored under `projects.<cwd>.enabledMcpjsonServers` in `~/.claude.json`). The "Project MCPs (.../.mcp.json)" section in `/mcp` only appears once at least one server in the file is approved. Verify with `/mcp` or `claude mcp list`.
+After a new MCP entry is written, you must (1) **export every `${VAR}` referenced by the entry** in the shell that will launch Claude Code so the gateway has them at server-start time (an unset variable shows as `[Contains warnings]` in `/mcp` — informational only — and any tool call needing that value will fail at runtime), and (2) **quit and relaunch Claude Code** in the same directory. The first time you launch in a project, Claude Code prompts you both for workspace trust and once per `.mcp.json` server (`Approve MCP server <name> from .mcp.json?`); accept each one. On subsequent launches the `mcpServers` block loads silently. Verify with `/mcp` (under "Project MCPs (.../.mcp.json)") or `claude mcp list`.
+
+Note: in Claude Code v2.1.x, per-project approve/reject decisions are persisted in **`<cwd>/.claude/settings.local.json`** (`enabledMcpjsonServers` / `disabledMcpjsonServers`), **not** in `~/.claude.json`. `claude mcp reset-project-choices` and deleting `projects.<cwd>` from `~/.claude.json` do **not** touch that file, so a previously-rejected `.mcp.json` server stays silently disabled and is never re-prompted. To re-enable it, edit `<cwd>/.claude/settings.local.json`, remove the entry from `disabledMcpjsonServers`, append it to `enabledMcpjsonServers`, and relaunch.
 
 To **enforce** the gateway as the only allowed transport in a project, add an `allowedMcpServers` policy to `.claude/settings.json`:
 

hooks/hooks.json

@@ -6,7 +6,7 @@
           {
             "type": "command",
             "command": "node ${CLAUDE_PLUGIN_ROOT}/scripts/inject-instructions.mjs",
-            "timeout": 10
+            "timeout": 30
           }
         ]
       }

scripts/inject-instructions.mjs

@@ -4,16 +4,73 @@
 // https://www.apache.org/licenses/LICENSE-2.0
 
 import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
 import path from "node:path";
 import process from "node:process";
 
+const debug = (msg) => {
+  if (process.env.JF_MCP_GATEWAY_DEBUG) {
+    process.stderr.write(`[jfrog-plugin] ${msg}\n`);
+  }
+};
+
 const root = process.env.CLAUDE_PLUGIN_ROOT;
 if (!root) {
   process.exit(0);
 }
 
-const templatePath = path.join(root, "templates", "jfrog-mcp-management.md");
+function shouldInject() {
+  const force = process.env.JF_MCP_GATEWAY_FORCE_ENABLE;
+  if (force === "true") {
+    debug("JF_MCP_GATEWAY_FORCE_ENABLE=true -> injecting (skip entitlement)");
+    return true;
+  }
+  if (force === "false") {
+    debug("JF_MCP_GATEWAY_FORCE_ENABLE=false -> skipping (skip entitlement)");
+    return false;
+  }
 
+  const registry =
+    process.env.JFROG_MCP_GATEWAY_REPO ||
+    "https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/";
+
+  debug(`spawning gateway --should-inject (registry=${registry})`);
+  const result = spawnSync(
+    "npx",
+    [
+      "--yes",
+      "--registry",
+      registry,
+      "@jfrog/mcp-gateway",
+      "--should-inject",
+    ],
+    {
+      encoding: "utf8",
+      timeout: 25_000,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+    },
+  );
+
+  if (result.error) {
+    debug(`spawn error: ${result.error.message} -> skipping`);
+    return false;
+  }
+  if (result.status === 0) {
+    debug("gateway: entitled -> injecting");
+    return true;
+  }
+  debug(
+    `gateway exit ${result.status} (3 = not entitled, other = error) -> skipping`,
+  );
+  return false;
+}
+
+if (!shouldInject()) {
+  process.exit(0);
+}
+
+const templatePath = path.join(root, "templates", "jfrog-mcp-management.md");
 let template;
 try {
   template = readFileSync(templatePath, "utf8");

templates/jfrog-mcp-management.md

@@ -92,14 +92,12 @@ Split Step 2 inputs by `isRequired`:
 
 For each input in Step 4:
 
-- **Secrets** (`isSecret=true`, tokens, keys, passwords): use
-  `${VAR_NAME}` in the config; tell the user to export it via
-  `read -rs VAR_NAME && export VAR_NAME && echo exported` and to add
-  the equivalent `export` to `~/.zshrc` for persistence. Values pick
-  up on next launch (Step 4a). NEVER take secrets in chat, echo
-  them back, or write raw values into config.
-- **Non-secrets** (URLs, regions): literal in `env` or `${VAR_NAME}`
-  — ask if unclear.
+- **Secrets** (`isSecret=true`): use `${VAR_NAME}` in the config; tell
+  the user to export it via `read -rs VAR_NAME && export VAR_NAME &&
+  echo exported` (and add to `~/.zshrc` for persistence). Picked up on
+  next launch (Step 4a). NEVER take secrets in chat, echo them back,
+  or write raw values into config.
+- **Non-secrets**: literal in `env` or `${VAR_NAME}` — ask if unclear.
 
 ### Step 4: Write the config entry
 
@@ -140,25 +138,30 @@ Notes:
 - For `Bearer`-prefixed headers, either include the prefix in the env
   var or hard-code it: `"Bearer ${TOKEN}"`.
 
-### Step 4a: Activate the entry (mandatory)
+### Step 4a: Pre-approve and activate (mandatory)
 
-Writing the file is NOT enough. After Step 4, ALWAYS tell the user:
+First, try to pre-approve the entry so the per-server prompt is
+skipped: edit `<cwd>/.claude/settings.local.json` (create as `{}` if
+missing), remove `<spec.packageName>` from `disabledMcpjsonServers`,
+append it to `enabledMcpjsonServers`. If that write fails for any
+reason (permissions, missing dir), continue anyway — the user will
+just see the prompt on relaunch (step 3).
 
-1. Export every `${VAR}` from the new entry in the launching shell —
-   the gateway needs them at server-start. Unset vars show as
-   `[Contains warnings]` in `/mcp` (informational, does NOT hide the
-   section) and any tool call needing them will fail at runtime.
-2. `/exit` and re-run the same `claude` command in the same directory.
-3. Approve at the "Approve MCP server `<name>` from .mcp.json?"
-   prompt — saved to `projects.<cwd>.enabledMcpjsonServers`. The
-   "Project MCPs (...)" section in `/mcp` only appears once at least
-   one server in the file is approved.
-4. Verify with `/mcp` or `claude mcp list` — must show `✓ connected`.
+Then tell the user:
 
-If the prompt is skipped or a reject is cached, run
-`claude mcp reset-project-choices` and relaunch. Last resort: edit
-`projects.<cwd>.enabledMcpjsonServers` directly. NEVER call the
-install "done" without `✓ connected`.
+1. Export every `${VAR}` from the new entry in the launching shell.
+   Unset vars show as `[Contains warnings]` in `/mcp` (informational)
+   and tool calls needing them will fail at runtime.
+2. `/exit` and relaunch the same `claude` in the same directory.
+3. On the FIRST launch, Claude Code prompts for workspace trust —
+   accept. If pre-approval succeeded, the per-server prompt is
+   skipped; otherwise approve "Approve MCP server `<name>`?".
+4. Verify with `/mcp` ("Project MCPs (...)", `✓ connected`) or
+   `claude mcp list`. NEVER call it done without `✓ connected`.
+
+Rejections persist in the same `enabledMcpjsonServers` /
+`disabledMcpjsonServers` arrays — `reset-project-choices` does NOT
+clear them. Fix: move the entry to `enabledMcpjsonServers`, relaunch.
 
 ### Step 5: Authenticate OAuth MCPs (auto, after Step 4)
 
@@ -228,16 +231,13 @@ Output is a JSON array; each element has `name`, `packageName`,
 
 ## Key Rules
 
-- **`npx` argument order:** `--yes`, `--registry <URL>`,
-  `@jfrog/mcp-gateway`, then gateway flags. `--yes` and `--registry`
-  MUST precede `@jfrog/mcp-gateway` or `npx` falls back to the
-  default registry (404) and may block on a no-TTY prompt.
-- **Loader mode is the default** — do NOT add `--loader`.
-- **Always `"type": "stdio"`** — never write `"type": "http"`,
-  `"type": "sse"`, or a top-level `"url"` field. Every entry is stdio
-  pointing at `npx @jfrog/mcp-gateway`, even when the catalog MCP is
-  remote-only — the gateway proxies remote transports for you.
-  Anything else bypasses the gateway and the governance it provides.
+- **`npx` arg order:** `--yes`, `--registry <URL>`,
+  `@jfrog/mcp-gateway`, then gateway flags. Both `--yes` and
+  `--registry` MUST precede the package name or `npx` falls back to
+  the default registry (404) and may block on a no-TTY prompt.
+- **Always `"type": "stdio"`** pointing at `npx @jfrog/mcp-gateway`,
+  even for remote-only catalog MCPs (the gateway proxies them).
+  `"http"`, `"sse"`, or a top-level `"url"` bypass the gateway.
 - `_JF_MCP_LOADER_ARGS` MUST contain `project=<NAME>&mcp=<PACKAGE_NAME>`.
 - Package name MUST come from the catalog (`--inspect` /
   `--list-available`). NEVER guess. NEVER install MCPs outside the
@@ -255,10 +255,7 @@ Output is a JSON array; each element has `name`, `packageName`,
   MCP did not. Treat as Failed: re-run Step 5 for OAuth MCPs, check
   the secret env var for static-token MCPs, read gateway stderr in
   Claude Code's logs for local MCPs.
-- **Project section missing from `/mcp`** — no `.mcp.json` entries
-  are approved yet. Approve on next launch, or edit
-  `projects.<cwd>.enabledMcpjsonServers`. (`[Contains warnings]` is
-  informational; it does not hide the section.)
+- **`.mcp.json` server missing from `/mcp`** — rejected. See Step 4a.
 - **Missing from `claude mcp list`** — JSON parse failure (often an
   undefined `${VAR}`), or a server-side `allowedMcpServers` policy in
   `.claude/settings.json` / managed settings filtering the entry.