From 687e9e0c1444dc5b06b757437639a568f2ef649f Mon Sep 17 00:00:00 2001 From: Matan Eden <57892946+MatanEden1@users.noreply.github.com> Date: Sun, 17 May 2026 12:29:44 +0300 Subject: [PATCH 1/4] docs(README): standardize Cursor plugin README (AX-1462) --- README.md | 145 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 120 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 0f675c1..c850fb5 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,131 @@ -# JFrog Cursor Plugin (Experimental) +# JFrog Plugin for Cursor -JFrog Platform integration for [Cursor](https://cursor.com) — artifact management, security scanning, and supply-chain best practices powered by the JFrog MCP Server. +JFrog plugin for [Cursor](https://cursor.com): artifact management, security scanning, and supply-chain best practices — with all MCP servers installed exclusively through the **JFrog Agent Guard**. -## What's included +## Features -| Component | Path | Description | -|---|---|---| -| **MCP** | `plugins/jfrog/mcp.json` | Remote JFrog MCP server (OAuth, no API keys) | -| **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`. | +The JFrog plugin provides the following capabilities, grouped by component: + +| Component | Feature | Description | +| --- | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Skill** | JFrog Platform | Interact with Artifactory repositories, builds, permissions, users, access tokens, projects, release bundles, and platform administration via the JFrog CLI and REST/GraphQL APIs. Also covers security audits, CVE lookups, and Advanced Security exposure queries. | +| **Skill** | Package safety & download | Check whether npm, Maven, PyPI, Go, and other packages are safe, curated, or allowed, then download them through Artifactory remote caches or curation-aware package managers. | +| **Hook** | Agent Guard | Cursor manage MCPs through the JFrog Agent Guard. Through the Agent Guard you can discover, install, configure, update, and remove MCP servers from the JFrog AI Catalog approved for your project, and authenticate to remote HTTP MCPs via OAuth, API key, or bearer token. | + +--- ## Prerequisites -1. **JFrog Platform** access (Cloud or self-hosted). -2. An admin enables the **JFrog MCP Server** on the platform (Cloud/SaaS only): - - **Administration > General > Settings > MCP Server** → toggle ON. -3. Each developer configures Cursor with their JFrog Platform URL (see [Setup](#setup)). -4. **JFrog CLI** (`jf`) is used by several skills for authentication and REST API operations. It will be installed automatically if missing. Install manually via `brew install jfrog-cli` or the [official install script](https://jfrog.com/help/r/jfrog-cli/install-the-jfrog-cli). +Before installing, make sure you have: + +- **JFrog Platform access** — Your JFrog subscription must include the AI Catalog entitlement (required for the Agent Guard feature only). Contact your JFrog account team if you're unsure whether it's enabled. +- **JFrog project** — At least one MCP server allowed for your project (required for the Agent Guard feature only). +- **JFrog host URL and access token** — Your JFrog platform URL and a valid access token. +- **Cursor** — Installed with AI features enabled. +- **Node.js** (≥ 14) — with `npx` on your `PATH`. +- **JFrog CLI** (≥ 2.x, optional) — Recommended for `jf config add` authentication (see [Authentication](#authentication)). +- **JFrog credentials** — Provided in one of two ways (see [Authentication](#authentication)): + +--- + +## Installation + +### Install the Cursor plugin + +Use either the marketplace link from the [Configure Cursor](https://docs.jfrog.com/ai-ml/docs/configure-cursor) documentation or Cursor's UI: + +1. Open **Cursor**. +2. Open **Cursor Settings** and select **Plugins**. +3. Search for **JFrog** and open the **JFrog** plugin. +4. Choose **Add to Cursor**, then **Add Plugin**. + +### Verify + +Open **Cursor Settings → Plugins** and confirm the JFrog plugin is listed as **Installed** at **v0.3.2 or higher**. + +--- + +## Authentication + +The plugin reads JFrog credentials from environment variables or the JFrog CLI configuration. Pick **one** of the following. + +### Option A — JFrog CLI (`jf config add`) + +If you already have the JFrog CLI installed and configured, the plugin uses your existing authentication — no further setup is required. + +**First-time setup only** (if you have never configured the JFrog CLI on this machine): + +1. Open a terminal. +2. Run: + ```bash + jf config add + ``` +3. Follow the prompts for platform URL and access token. +4. Restart Cursor / your terminal so the environment and CLI config are picked up. + +### Option B — Environment variables + +Use this if you are **not** relying on the JFrog CLI for URL and token. For the settings check used by the Agent Guard, set **`JFROG_URL`** and **`JFROG_ACCESS_TOKEN`** together (legacy names `JF_URL` / `JF_ACCESS_TOKEN` are still read by the hook script if present). + +| Variable | Description | +| --- | --- | +| `JFROG_URL` | Your JFrog platform URL, for example `https://mycompany.jfrog.io` | +| `JFROG_ACCESS_TOKEN` | Your JFrog access token | + +--- + +## Usage + +Once configured, interact with the JFrog plugin through natural language. Examples are grouped by capability. + +### JFrog Platform skill + +| Ask the agent… | What happens | +| --- | --- | +| "List my Artifactory repositories." | Returns repositories via the JFrog CLI. | +| "Upload this build to Artifactory." | Publishes build artifacts and metadata. | +| "Run a security audit on this project." | Runs an Xray / Advanced Security audit and summarizes findings. | +| "Show me details on CVE-2021-23337." | Looks up CVE details in JFrog Advanced Security. | +| "Create a scoped access token for CI." | Creates an access token with the requested scope. | +| "Promote this release bundle to production." | Uses Lifecycle / Distribution APIs to promote the bundle. | + +### Package safety & download skill + +| Ask the agent… | What happens | +| --- | --- | +| "Is `lodash@4.17.21` safe to install?" | Checks JFrog Public Catalog signals and curation policy for the package. | +| "Is this Maven package approved for use?" | Checks curation entitlement and policy for the requested package. | +| "Download `requests` via JFrog." | Resolves the package through an Artifactory remote cache or curation-aware package manager. | + +### MCP server management (Agent Guard) + +| Ask the agent… | What happens | +| --- | --- | +| "Which MCP servers can I install?" | Returns all MCP servers approved for your current project that you can install. | +| "What MCP servers do I already have?" | Returns only the MCP servers already installed on your machine. | +| "Show me the details for the filesystem MCP server." | Returns detailed metadata, required configuration (environment variables, runtime arguments), and active tool policies for a given server. | +| "Add the GitHub MCP server." | Installs an approved MCP server and syncs its tool policies locally. Secrets are requested via a CLI command — never in chat. | +| "Update the environment variables for the Slack MCP." | Replaces the configuration for an already-installed server without removing and reinstalling it. | +| "Remove the Slack MCP server." | Removes the server and its stored credentials from your local setup. Changes apply immediately. | +| "Log in to the remote Jira MCP server using OAuth." | Authenticates with a remote HTTP-based MCP server (OAuth, API key, or bearer token). | +| "Switch my project to `backend-team`." | Re-syncs approved servers and policies for the new project. | + +### How secrets are handled + +When an MCP server requires a sensitive configuration, the agent cannot set the value directly. Instead, it returns a CLI command for you to copy and run in your terminal. Secrets such as API keys, tokens, and connection strings are never exposed in the agent chat history. + +--- + +## Troubleshooting + +See the [JFrog MCP Registry troubleshooting guide](https://docs.jfrog.com/ai-ml/docs/mcp-registry-troubleshooting). -## Setup +--- -1. Install the plugin in Cursor. -2. Set the `JFROG_PLATFORM_URL` environment variable to your JFrog instance (e.g. `mycompany.jfrog.io`). -3. Restart Cursor. An OAuth window opens in your browser — authorize access. +## Contributing -No manual tokens or API keys are required. MCP workflows use OAuth; CLI/REST-based skills authenticate automatically via `jf config` browser login. +See [`CONTRIBUTING.md`](CONTRIBUTING.md) for development workflow and pull-request expectations. -## Validation +## License -```bash -node scripts/validate-template.mjs -``` +Licensed under the [Apache License 2.0](LICENSE). From 10ed7baabe3c6ac2f7e8444cbc43729754ef1bc7 Mon Sep 17 00:00:00 2001 From: Matan Eden <57892946+MatanEden1@users.noreply.github.com> Date: Sun, 17 May 2026 16:11:51 +0300 Subject: [PATCH 2/4] docs(README): remove verification section for JFrog plugin installation --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index c850fb5..62b7298 100644 --- a/README.md +++ b/README.md @@ -39,10 +39,6 @@ Use either the marketplace link from the [Configure Cursor](https://docs.jfrog.c 3. Search for **JFrog** and open the **JFrog** plugin. 4. Choose **Add to Cursor**, then **Add Plugin**. -### Verify - -Open **Cursor Settings → Plugins** and confirm the JFrog plugin is listed as **Installed** at **v0.3.2 or higher**. - --- ## Authentication From 2518e506bc28e232b51176c89b6a4382038496fa Mon Sep 17 00:00:00 2001 From: Matan Eden <57892946+MatanEden1@users.noreply.github.com> Date: Mon, 18 May 2026 13:55:49 +0300 Subject: [PATCH 3/4] docs(README): update JFrog plugin documentation for clarity and remove optional requirements --- README.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 62b7298..4a81dd0 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,15 @@ # JFrog Plugin for Cursor -JFrog plugin for [Cursor](https://cursor.com): artifact management, security scanning, and supply-chain best practices — with all MCP servers installed exclusively through the **JFrog Agent Guard**. +JFrog plugin for [Cursor](https://cursor.com): artifact management, security scanning, and supply-chain best practices with all MCP servers installed. ## Features The JFrog plugin provides the following capabilities, grouped by component: -| Component | Feature | Description | -| --- | --- |-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **Skill** | JFrog Platform | Interact with Artifactory repositories, builds, permissions, users, access tokens, projects, release bundles, and platform administration via the JFrog CLI and REST/GraphQL APIs. Also covers security audits, CVE lookups, and Advanced Security exposure queries. | -| **Skill** | Package safety & download | Check whether npm, Maven, PyPI, Go, and other packages are safe, curated, or allowed, then download them through Artifactory remote caches or curation-aware package managers. | +| Component | Feature | Description | +| --- | --- | --- | +| **Skill** | JFrog Platform | Interact with Artifactory repositories, builds, permissions, users, access tokens, projects, release bundles, and platform administration via the JFrog CLI and REST/GraphQL APIs. Also covers security audits, CVE lookups, and Advanced Security exposure queries. | +| **Skill** | Package safety & download | Check whether npm, Maven, PyPI, Go, and other packages are safe, curated, or allowed, then download them through Artifactory remote caches or curation-aware package managers. | | **Hook** | Agent Guard | Cursor manage MCPs through the JFrog Agent Guard. Through the Agent Guard you can discover, install, configure, update, and remove MCP servers from the JFrog AI Catalog approved for your project, and authenticate to remote HTTP MCPs via OAuth, API key, or bearer token. | --- @@ -18,14 +18,12 @@ The JFrog plugin provides the following capabilities, grouped by component: Before installing, make sure you have: -- **JFrog Platform access** — Your JFrog subscription must include the AI Catalog entitlement (required for the Agent Guard feature only). Contact your JFrog account team if you're unsure whether it's enabled. -- **JFrog project** — At least one MCP server allowed for your project (required for the Agent Guard feature only). - **JFrog host URL and access token** — Your JFrog platform URL and a valid access token. - **Cursor** — Installed with AI features enabled. - **Node.js** (≥ 14) — with `npx` on your `PATH`. - **JFrog CLI** (≥ 2.x, optional) — Recommended for `jf config add` authentication (see [Authentication](#authentication)). -- **JFrog credentials** — Provided in one of two ways (see [Authentication](#authentication)): - +- **JFrog Platform access** (optional) — If you want to use the Agent Guard feature, your JFrog subscription needs to include the AI Catalog entitlement. Contact your JFrog account team if you're unsure whether it's enabled. +- **JFrog project** (optional) — If you want to use the Agent Guard feature, at least one MCP server must be allowed for your project. --- ## Installation From 65c0a7c0d51f24f59ea0d0077728ae9113f000a1 Mon Sep 17 00:00:00 2001 From: Matan Eden <57892946+MatanEden1@users.noreply.github.com> Date: Mon, 18 May 2026 18:48:21 +0300 Subject: [PATCH 4/4] docs(README): update JFrog plugin description and enhance authentication instructions --- README.md | 30 ++++++++++++------------------ 1 file changed, 12 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 4a81dd0..10fb0df 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # JFrog Plugin for Cursor -JFrog plugin for [Cursor](https://cursor.com): artifact management, security scanning, and supply-chain best practices with all MCP servers installed. +JFrog plugin for [Cursor](https://cursor.com): artifact management, security scanning, supply-chain best practices, and Agent Guard. ## Features @@ -23,7 +23,8 @@ Before installing, make sure you have: - **Node.js** (≥ 14) — with `npx` on your `PATH`. - **JFrog CLI** (≥ 2.x, optional) — Recommended for `jf config add` authentication (see [Authentication](#authentication)). - **JFrog Platform access** (optional) — If you want to use the Agent Guard feature, your JFrog subscription needs to include the AI Catalog entitlement. Contact your JFrog account team if you're unsure whether it's enabled. -- **JFrog project** (optional) — If you want to use the Agent Guard feature, at least one MCP server must be allowed for your project. +- **JFrog project** (optional) — If you want to use the Agent Guard feature. + --- ## Installation @@ -41,30 +42,23 @@ Use either the marketplace link from the [Configure Cursor](https://docs.jfrog.c ## Authentication -The plugin reads JFrog credentials from environment variables or the JFrog CLI configuration. Pick **one** of the following. +### 1. Set persistent environment variables -### Option A — JFrog CLI (`jf config add`) +| Variable | Description | +| --- | --- | +| `JFROG_URL` | Your JFrog platform URL, e.g. `https://mycompany.jfrog.io` | +| `JFROG_ACCESS_TOKEN` | Your JFrog access token | -If you already have the JFrog CLI installed and configured, the plugin uses your existing authentication — no further setup is required. +### 2. Configure the JFrog CLI -**First-time setup only** (if you have never configured the JFrog CLI on this machine): +If you have never configured the JFrog CLI on this machine: -1. Open a terminal. +1. Open your terminal. 2. Run: ```bash jf config add ``` -3. Follow the prompts for platform URL and access token. -4. Restart Cursor / your terminal so the environment and CLI config are picked up. - -### Option B — Environment variables - -Use this if you are **not** relying on the JFrog CLI for URL and token. For the settings check used by the Agent Guard, set **`JFROG_URL`** and **`JFROG_ACCESS_TOKEN`** together (legacy names `JF_URL` / `JF_ACCESS_TOKEN` are still read by the hook script if present). - -| Variable | Description | -| --- | --- | -| `JFROG_URL` | Your JFrog platform URL, for example `https://mycompany.jfrog.io` | -| `JFROG_ACCESS_TOKEN` | Your JFrog access token | +3. Follow the interactive prompts to enter the same JFrog platform URL and access token. ---