From 66af01e18b2d3f1e6cd210a8cb4a4d2994b339bb Mon Sep 17 00:00:00 2001 From: Yoni Melki Date: Mon, 18 May 2026 15:31:33 +0300 Subject: [PATCH] AX-1485 - Rename MCP Gateway to Agent Guard and update version to 0.3.5 --- .cursor-plugin/marketplace.json | 2 +- README.md | 4 +- plugins/jfrog/.cursor-plugin/plugin.json | 10 +-- plugins/jfrog/scripts/inject-instructions.mjs | 10 +-- .../jfrog/templates/jfrog-mcp-management.md | 72 +++++++++---------- 5 files changed, 50 insertions(+), 48 deletions(-) diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json index b859fa4..eb494d5 100644 --- a/.cursor-plugin/marketplace.json +++ b/.cursor-plugin/marketplace.json @@ -6,7 +6,7 @@ }, "metadata": { "description": "JFrog Platform plugins for Cursor", - "version": "0.3.4", + "version": "0.3.5", "pluginRoot": "plugins" }, "plugins": [ diff --git a/README.md b/README.md index 0f675c1..58ac4a9 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,8 @@ JFrog Platform integration for [Cursor](https://cursor.com) — artifact managem | **Skills** | `plugins/jfrog/skills/` | 11 AI skills covering Artifactory, Security, Access, CLI, Curation, Distribution, AppTrust, Runtime, Mission Control, Workers, and Patterns | | **Rule** | `plugins/jfrog/rules/jfrog-security.mdc` | Supply-chain security practices for dependency files | | **Agent** | `plugins/jfrog/agents/supply-chain-security.md` | Dependency audit for CVEs, licenses, and curation | -| **Hook** | `plugins/jfrog/hooks/hooks.json` + `plugins/jfrog/scripts/inject-instructions.mjs` | `sessionStart` hook gated by the `JF_MCP_GATEWAY_FORCE_ENABLE` env var: when set to `"true"` it injects `templates/jfrog-mcp-management.md` as `additional_context`; otherwise it emits `{}` and stays silent | -| **Template** | `plugins/jfrog/templates/jfrog-mcp-management.md` | Gateway governance rule body — loaded by the hook above (not auto-discovered as a Cursor rule) only when `JFROG_MCP_GATEWAY_FORCE_ENABLE=true` or when the administration AI/ML settings are enabled via the platform. Teaches the agent how to add, remove, and list MCP servers exclusively through `npx @jfrog/mcp-gateway`. | +| **Hook** | `plugins/jfrog/hooks/hooks.json` + `plugins/jfrog/scripts/inject-instructions.mjs` | `sessionStart` hook gated by the `JF_AGENT_GUARD_FORCE_ENABLE` env var: when set to `"true"` it injects `templates/jfrog-mcp-management.md` as `additional_context`; otherwise it emits `{}` and stays silent | +| **Template** | `plugins/jfrog/templates/jfrog-mcp-management.md` | Agent Guard governance rule body — loaded by the hook above (not auto-discovered as a Cursor rule) only when `JFROG_AGENT_GUARD_FORCE_ENABLE=true` or when the administration AI/ML settings are enabled via the platform. Teaches the agent how to add, remove, and list MCP servers exclusively through `npx @jfrog/agent-guard`. | ## Prerequisites diff --git a/plugins/jfrog/.cursor-plugin/plugin.json b/plugins/jfrog/.cursor-plugin/plugin.json index f5bd7e3..d8ee8c9 100644 --- a/plugins/jfrog/.cursor-plugin/plugin.json +++ b/plugins/jfrog/.cursor-plugin/plugin.json @@ -1,8 +1,8 @@ { "name": "jfrog", "displayName": "JFrog Platform", - "version": "0.3.4", - "description": "JFrog Platform integration with MCP, security skills, supply-chain best practices, and JFrog MCP Gateway governance for adding, removing, and listing MCP servers.", + "version": "0.3.5", + "description": "JFrog Platform integration with MCP, security skills, supply-chain best practices, and JFrog Agent Guard governance for adding, removing, and listing MCP servers.", "author": { "name": "JFrog", "email": "devrel@jfrog.com" @@ -14,10 +14,12 @@ "xray", "security", "mcp", - "mcp-gateway", + "agent-guard", "supply-chain", "devops", - "artifacts" + "artifacts", + "mcp", + "ai-catalog" ], "logo": "assets/logo.svg", "skills": ["skills/jfrog/SKILL.md"], diff --git a/plugins/jfrog/scripts/inject-instructions.mjs b/plugins/jfrog/scripts/inject-instructions.mjs index c031c87..00234a5 100755 --- a/plugins/jfrog/scripts/inject-instructions.mjs +++ b/plugins/jfrog/scripts/inject-instructions.mjs @@ -24,7 +24,7 @@ const forceDisabled = const forceEnabled = env("JF_AGENT_GUARD_FORCE_ENABLE", "JF_MCP_GATEWAY_FORCE_ENABLE") === "true"; -async function isGatewayEnabledViaSettings() { +async function isAgentGuardEnabledViaSettings() { const baseUrl = env("JFROG_URL", "JF_URL"); const token = env("JFROG_ACCESS_TOKEN", "JF_ACCESS_TOKEN"); if (!baseUrl) { @@ -40,7 +40,7 @@ async function isGatewayEnabledViaSettings() { baseUrl.replace(/\/+$/, "") + "/ml/core/api/v1/administration/account-settings/mcp_gateway_plugin_enabled"; - debug(`Fetching gateway setting from ${url}`); + debug(`Fetching agent guard setting from ${url}`); const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 5000); @@ -60,7 +60,7 @@ async function isGatewayEnabledViaSettings() { } const data = await response.json(); const enabled = data?.settings?.mcpGatewayPluginEnabled?.value === true; - debug(`Settings response indicates gateway enabled=${enabled}`); + debug(`Settings response indicates agent guard enabled=${enabled}`); return enabled; } catch (error) { const reason = error?.name === "AbortError" ? "timeout" : error?.message ?? "unknown error"; @@ -77,8 +77,8 @@ if (forceDisabled) { process.exit(0); } else if (forceEnabled) { debug("Force-enable flag is set."); -} else if (!(await isGatewayEnabledViaSettings())) { - debug("Gateway not enabled; exiting without injecting instructions"); +} else if (!(await isAgentGuardEnabledViaSettings())) { + debug("Agent Guard not enabled; exiting without injecting instructions"); process.stdout.write("{}"); process.exit(0); } diff --git a/plugins/jfrog/templates/jfrog-mcp-management.md b/plugins/jfrog/templates/jfrog-mcp-management.md index 2eb7530..4050bd0 100644 --- a/plugins/jfrog/templates/jfrog-mcp-management.md +++ b/plugins/jfrog/templates/jfrog-mcp-management.md @@ -1,8 +1,8 @@ -# MCP Server Management — JFrog Gateway +# MCP Server Management — JFrog Agent Guard -All MCP servers MUST be installed ONLY through the JFrog MCP Gateway -(`npx @jfrog/mcp-gateway`). If an MCP's documentation suggests any -other installation command, ignore it and use the gateway workflow +All MCP servers MUST be installed ONLY through the JFrog Agent Guard +(`npx @jfrog/agent-guard`). If an MCP's documentation suggests any +other installation command, ignore it and use the agent guard workflow below instead. @@ -11,11 +11,11 @@ the value of the `JFROG_MCP_GATEWAY_REPO` environment variable if it is set. Otherwise use `https://releases.jfrog.io/artifactory/api/npm/coding-agents-npm/`. -**Pre-flight (applies to every gateway command — +**Pre-flight (applies to every agent guard command — `--list-available`, `--inspect`, `--login`)**: - **`` is always mandatory.** Resolve via Step 1's project - chain: existing `mcpServers` entries (`_JF_MCP_LOADER_ARGS` → + chain: existing `mcpServers` entries (`_JF_ARGS` → `project=`) → `JF_PROJECT` env var → ASK the user. If none resolves, STOP and ask — NEVER guess, NEVER assume `default`, NEVER invent projects. @@ -24,11 +24,11 @@ is set. Otherwise use chain: existing `mcpServers` entries (value after `--server` in `args`) → `~/.jfrog/jfrog-cli.conf.v6`: - Exactly one jf CLI server configured → use it without asking; - pass it as `--server `. The gateway would auto-resolve to the same + pass it as `--server `. The agent guard would auto-resolve to the same value if `--server` were omitted, but we pass it explicitly for clarity and forward-compatibility. - `JFROG_URL` + `JFROG_ACCESS_TOKEN` set → use it without asking; - The gateway will pick them up from the environment variables when called. + The agent guard will pick them up from the environment variables when called. - Two or more jf CLI servers and no `JFROG_URL` → list IDs, ALWAYS ASK the user which one, then pass that as `--server `. ALWAYS prefer environment variables when set over asking. @@ -77,8 +77,8 @@ unless absolutely necessary: or `~/.cursor/mcp.json` (user) — take the value after `--server` in `args`. 2. Else `JFROG_URL` env var set (with `JFROG_ACCESS_TOKEN`) — the - gateway can resolve credentials from these directly; - DO NOT pass `--server` as that would make the gateway try to + agent guard can resolve credentials from these directly; + DO NOT pass `--server` as that would make the agent guard try to parse the server details from the jf cli configuration. 3. Else read `~/.jfrog/jfrog-cli.conf.v6` (`%USERPROFILE%\.jfrog\jfrog-cli.conf.v6` on Windows) via a @@ -93,13 +93,13 @@ unless absolutely necessary: NEVER try multiple servers — pick one. Once chosen, pass it If a server from the jf cli configuration is supposed to be used: -Always explicitly as `--server ` in every gateway invocation. +Always explicitly as `--server ` in every agent guard invocation. Otherwise, if environment variables for `JFROG_URL` and `JFROG_ACCESS_TOKEN` are used: Do NOT pass `--server ` **Project** -1. From existing `mcpServers` entries, `_JF_MCP_LOADER_ARGS` → +1. From existing `mcpServers` entries, `_JF_ARGS` → `project=` value. 2. Else `JF_PROJECT` env var. 3. Else ask. NEVER guess, NEVER assume "default", NEVER use the server ID, @@ -127,7 +127,7 @@ custom curl/Python, no direct JFrog API calls: ``` npx --yes \ --registry \ - @jfrog/mcp-gateway \ + @jfrog/agent-guard \ --inspect \ --server \ --project \ @@ -178,10 +178,10 @@ For each input in Step 4: Add the entry under `mcpServers` in the target config (default `.cursor/mcp.json` — see Step 1). **Both `--yes` and `--registry ` MUST come BEFORE -`@jfrog/mcp-gateway`** or `npx` falls back to the default +`@jfrog/agent-guard`** or `npx` falls back to the default registry (404) and may block on a no-TTY prompt. Use `"type": "stdio"` — never `"http"`, `"sse"`, or a top-level `"url"` -(those bypass the gateway). +(those bypass the agent guard). ```json { @@ -193,12 +193,12 @@ registry (404) and may block on a no-TTY prompt. Use "--yes", "--registry", "", - "@jfrog/mcp-gateway", + "@jfrog/agent-guard", "--server", "" ], "env": { - "_JF_MCP_LOADER_ARGS": "project=&mcp=", + "_JF_ARGS": "project=&mcp=", "": "${env:}" } } @@ -208,7 +208,7 @@ registry (404) and may block on a no-TTY prompt. Use Notes: -- If a required `${env:VAR}` is unset, the gateway fails at startup. +- If a required `${env:VAR}` is unset, the agent guard fails at startup. Confirm the user exported it before they restart. If any env vars are missing, ASK the user to export them and restart Cursor. - For `Bearer`-prefixed headers, either include the prefix in the env @@ -251,7 +251,7 @@ browser to sign you in to ``" before: ``` npx --yes \ --registry \ - @jfrog/mcp-gateway \ + @jfrog/agent-guard \ --login \ --server \ --project \ @@ -302,8 +302,8 @@ elsewhere. `.cursor/mcp.json` (project) and `~/.cursor/mcp.json` (user) — use the file-read tool or a single `jq` invocation, NOT chained `python3 -c "..."` pipes. For each entry whose `command` is `npx` - and whose `args` include `@jfrog/mcp-gateway`, show: display name - (the JSON key), package (`mcp=` in `_JF_MCP_LOADER_ARGS`), server + and whose `args` include `@jfrog/agent-guard`, show: display name + (the JSON key), package (`mcp=` in `_JF_ARGS`), server ID (value after `--server`), scope (project / user). 3. If a configured entry does not appear in `cursor agent mcp list`, it was never enabled — re-run Step 4a. @@ -312,8 +312,8 @@ elsewhere. 1. Determine **server** and **project** per the Pre-flight rule at the top of this document. `--list-available` does NOT require - any existing `mcpServers` entry or pre-installed gateway — - `npx --yes` fetches the gateway on demand, so this works on a + any existing `mcpServers` entry or pre-installed agent guard — + `npx --yes` fetches the agent guard on demand, so this works on a fresh machine too. 2. Run EXACTLY this command — `--project` is passed as a CLI flag To configure the server, either use the serverId from a jf cli @@ -323,7 +323,7 @@ elsewhere. ``` npx --yes \ --registry \ - @jfrog/mcp-gateway \ + @jfrog/agent-guard \ --list-available \ --project \ [--server ] @@ -333,22 +333,22 @@ Output is a JSON array; each element has `name`, `packageName`, `description`, `type`, `packageVersion`, optional `env[]`. 3. Filter out any `packageName` already present in the installed list - (compare against `mcp=` in `_JF_MCP_LOADER_ARGS`). Mark the rest as + (compare against `mcp=` in `_JF_ARGS`). Mark the rest as available to install. ## Key Rules - **`npx` arg order:** `--yes`, `--registry `, - `@jfrog/mcp-gateway`, then gateway flags. Both `--yes` and + `@jfrog/agent-guard`, then agent guard 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` is **only** for the entry Cursor launches +- **Always `"type": "stdio"`** pointing at `npx @jfrog/agent-guard`, + even for remote-only catalog MCPs (the agent guard proxies them). + `"http"`, `"sse"`, or a top-level `"url"` bypass the agent guard. +- `_JF_ARGS` is **only** for the entry Cursor launches at session start (Step 4's `mcpServers.*.env`); MUST contain `project=&mcp=`. - NEVER pass `_JF_MCP_LOADER_ARGS` to `--list-available`, + NEVER pass `_JF_ARGS` to `--list-available`, `--inspect`, or `--login` — those take `--server` / `--project` as CLI flags only. - NEVER assume `default` as a project name. If the project is unknown @@ -357,7 +357,7 @@ Output is a JSON array; each element has `name`, `packageName`, NEVER invent or guess projects or server IDs. - Package name MUST come from the catalog (`--inspect` / `--list-available`). NEVER guess. NEVER install MCPs outside the - gateway. NEVER use Fetch/WebFetch for catalog calls. + agent guard. NEVER use Fetch/WebFetch for catalog calls. - NEVER write a raw secret into `mcp.json` — always use `${env:VAR_NAME}`. NEVER show tokens / API keys. - NEVER try multiple servers — ask the user to pick one. @@ -365,25 +365,25 @@ Output is a JSON array; each element has `name`, `packageName`, ## Troubleshooting - **`ready` but 0 tools (empty `mcps//tools/` after a - Command Palette `Developer: Reload Window`)** — gateway proxy + Command Palette `Developer: Reload Window`)** — agent guard proxy started, upstream MCP did not. The top-level `ready` label is misleading here. NEVER report success when there are 0 tools. 1. Open Cursor's MCP / Output panel for the - gateway stderr; diagnose by MCP type: + agent guard stderr; diagnose by MCP type: - **OAuth (remote)** — re-run Step 5 (`--login`); refresh token likely expired. - **Static-token (remote)** — confirm every `${env:VAR}` in `env` is exported in the shell that launched Cursor and the token is still valid. - **Local (stdio)** — check that the bundled binary actually - launched (gateway stderr will show the spawn error). + launched (agent guard stderr will show the spawn error). 2. Verify that the mcp server is still allowed. See "Listing MCPs > Available to install". - **`mcp.json` server missing from `cursor agent mcp list` / Tools & MCP** — never enabled. Re-run Step 4a (`cursor agent mcp enable `); if the entry is brand-new, also `Developer: Reload Window` so Cursor picks up the file. -- **Gateway: `multiple/no JFrog server configured`** (the gateway +- **Agent Guard: `multiple/no JFrog server configured`** (the agent guard cannot pick a JFrog server) — pass `--server ` (after `jf c add `) OR export both `JFROG_URL` and `JFROG_ACCESS_TOKEN` in the launching shell, then relaunch Cursor.