diff --git a/plugins/jfrog/templates/jfrog-mcp-management.md b/plugins/jfrog/templates/jfrog-mcp-management.md index 7792187..69add41 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 Agent Guard (`npx @jfrog/agent-guard`). If an MCP's documentation suggests any -other installation command, ignore it and use the gateway workflow +other installation command, ignore it and use the agent guard workflow below instead. @@ -11,9 +11,19 @@ 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`)**: +- **Live execution is MANDATORY — context reuse is FORBIDDEN.** Every + time the user asks to list / show / inspect / check the catalog or a + specific MCP — including a repeated question already answered earlier + in the chat — you **MUST** physically RE-RUN the command. NEVER reuse, + copy, or re-display output from previous turns or context history; the + catalog, headers, and required inputs change between prompts. (Applies + to these catalog/registry fetches only — `--list-available` and + `--inspect`; NOT `--login`, which would re-open the OAuth browser, and + NOT reading local config for *installed* state.) + - **`` is always mandatory.** Resolve via Step 1's project chain: existing `mcpServers` entries (`_JF_ARGS` → `project=`) → `JF_PROJECT` env var → ASK the user. If none @@ -24,11 +34,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 +87,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,7 +103,7 @@ 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 ` @@ -121,8 +131,9 @@ not call `--inspect` — go to "Listing MCPs > Available to install" instead, show the catalog, have them pick, then come back to Step 2 with the chosen name. -Once you have a name, run a SINGLE command — no Fetch/WebFetch, no -custom curl/Python, no direct JFrog API calls: +Once you have a name, you must fetch its live details. + +Run EXACTLY this command — no Fetch/WebFetch, no custom curl/Python, no direct JFrog API calls: ``` npx --yes \ @@ -191,7 +202,7 @@ Add the entry under `mcpServers` in the target config (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 { @@ -218,7 +229,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 @@ -322,8 +333,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 @@ -349,12 +360,12 @@ Output is a JSON array; each element has `name`, `packageName`, ## Key Rules - **`npx` arg order:** `--yes`, `--registry `, - `@jfrog/agent-guard`, 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/agent-guard`, - even for remote-only catalog MCPs (the gateway proxies them). - `"http"`, `"sse"`, or a top-level `"url"` bypass the gateway. + 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=`. @@ -367,7 +378,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. @@ -375,25 +386,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 - started, upstream MCP did not. The top-level `ready` label is - misleading here. NEVER report success when there are 0 tools. + 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.