Add AI-agent help text to mcp and uv commands (#3545)

* JGC-504 - Add AI-agent help text to mcp and uv commands

Complete GetAIDescription() coverage for the umbrella commands that landed
after JGC-473 and were still falling back to the short description in AI mode:

- mcp install / show / uninstall
- uv

Each help.go gains a GetAIDescription() following the JGC-473 template
(when-to-use / prerequisites / runnable examples / gotchas / related), with
examples validated against the commands' real flags. The four call sites in
mcp/cli.go and buildtools/cli.go now route Usage/HelpName through
corecommon.ResolveDescription so the AI text renders when JFROG_CLI_AI_HELP is
truthy or an AI agent is auto-detected.

Hidden/deprecated rt-namespace duplicates and unwired doc stubs (per issue
#3544) are intentionally left out — their canonical visible commands are
already covered, and they are excluded by the JGC-473 skip-hidden policy.

* JGC-504 - Add AI help coverage check to static analysis

Author: ehl-jf

.github/workflows/analysis.yml

@@ -52,6 +52,14 @@ jobs:
       - name: Run golangci linter
         uses: jfrog/.github/actions/golangci-lint@main
 
+      - name: Check AI help coverage
+        uses: jfrog/.github/actions/ai-help-coverage@main
+        with:
+          # Commands still missing AI-oriented help. Remove from this list once a
+          # GetAIDescription() is added and wired through ResolveDescription.
+          skip-commands: |
+            nix
+
   Go-Sec:
     name: Go-Sec
     runs-on: ubuntu-latest

buildtools/cli.go

@@ -366,8 +366,8 @@ func GetCommands() []cli.Command {
 		{
 			Name:            "uv",
 			Flags:           cliutils.GetCommandFlags(cliutils.Uv),
-			Usage:           uvcommand.GetDescription(),
-			HelpName:        corecommon.CreateUsage("uv", uvcommand.GetDescription(), uvcommand.Usage),
+			Usage:           corecommon.ResolveDescription(uvcommand.GetDescription(), uvcommand.GetAIDescription()),
+			HelpName:        corecommon.CreateUsage("uv", corecommon.ResolveDescription(uvcommand.GetDescription(), uvcommand.GetAIDescription()), uvcommand.Usage),
 			UsageText:       uvcommand.GetArguments(),
 			ArgsUsage:       common.CreateEnvVars(),
 			SkipFlagParsing: true,

docs/buildtools/uvcommand/help.go

@@ -6,6 +6,29 @@ func GetDescription() string {
 	return "Run uv command"
 }
 
+func GetAIDescription() string {
+	return `Run a uv (Python package manager) command through JFrog CLI so dependencies resolve against Artifactory and build-info can be recorded. Arguments are forwarded to the uv binary unchanged; the jf-specific flags are the build-info and server options.
+
+When to use:
+- Running 'uv pip install' / 'uv sync' / 'uv add' in a project that resolves through an Artifactory-backed index.
+- Capturing build-info for a uv-based Python build by passing --build-name and --build-number.
+
+Prerequisites:
+- uv installed and available on PATH.
+- A configured JFrog Platform server (jf c add or jf login), or pass --server-id.
+
+Common patterns:
+  $ jf uv pip install -r requirements.txt
+  $ jf uv sync --build-name=my-app --build-number=7
+  $ jf uv add requests --build-name=my-app --build-number=7 --module=api
+
+Gotchas:
+- All arguments after the uv sub-command are passed straight to uv (the command uses SkipFlagParsing); only --build-name, --build-number, --module, --project, and --server-id are interpreted by jf.
+- Build-info is collected only when --build-name and --build-number are provided; publish it afterwards with 'jf rt build-publish'.
+
+Related: jf rt build-publish, jf pip-install`
+}
+
 func GetArguments() string {
 	return `	sub-command
 		Arguments and options for the uv command.`

docs/mcp/install/help.go

@@ -6,6 +6,30 @@ func GetDescription() string {
 	return "Configure an AI agent (cursor or claude) to connect to the remote JFrog MCP server."
 }
 
+func GetAIDescription() string {
+	return `Add the remote JFrog MCP server to an AI agent's configuration so the agent can call JFrog Platform tools. Writes the MCP entry for Cursor or Claude Code; authentication is completed via OAuth in the agent itself, so no credentials are written to the agent config.
+
+When to use:
+- Onboarding Cursor or Claude Code to the JFrog Platform MCP integration.
+- Adding the MCP server at project scope (default) or user scope (--global).
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add or jf login), or pass --server-id / --url.
+- The target agent (Cursor or Claude Code) installed locally.
+
+Common patterns:
+  $ jf mcp install --agent=cursor
+  $ jf mcp install --agent=claude --global
+  $ jf mcp install --agent=cursor --dry-run
+
+Gotchas:
+- Before writing config, the command verifies the MCP server is reachable; pass --skip-check to bypass that probe.
+- After installing, complete the OAuth authorization in the agent (e.g. run /mcp in Claude Code, or approve the server in Cursor) to activate the connection.
+- Default scope is the current project; --global writes the user-level agent config instead.
+
+Related: jf mcp show, jf mcp uninstall`
+}
+
 func GetArguments() string {
 	return `	EXAMPLES
   # Configure Cursor for the current project

docs/mcp/show/help.go

@@ -6,6 +6,27 @@ func GetDescription() string {
 	return "Print the remote MCP (Model Context Protocol) server endpoint for the configured JFrog Platform."
 }
 
+func GetAIDescription() string {
+	return `Print the remote MCP (Model Context Protocol) server endpoint for the configured JFrog Platform, derived as <platform-url>/mcp. Use this to discover the URL an AI agent should connect to, or to confirm which platform the MCP integration points at.
+
+When to use:
+- Looking up the MCP endpoint to configure an agent manually (rather than via 'jf mcp install').
+- Verifying which platform / server the MCP integration resolves to before installing.
+
+Prerequisites:
+- A configured JFrog Platform server (jf c add or jf login), or pass --server-id / --url.
+
+Common patterns:
+  $ jf mcp show
+  $ jf mcp show --server-id=my-platform --format=json
+
+Gotchas:
+- The endpoint defaults to <platform-url>/mcp; override it with --mcp-url or the JFROG_CLI_MCP_URL environment variable.
+- This is the remote, platform-hosted MCP server. It is unrelated to 'jf source-mcp', which runs a local MCP server for source-code analysis.
+
+Related: jf mcp install, jf mcp uninstall`
+}
+
 func GetArguments() string {
 	return `	EXAMPLES
   # Print the MCP endpoint for the default server

docs/mcp/uninstall/help.go

@@ -6,6 +6,27 @@ func GetDescription() string {
 	return "Remove the JFrog MCP server entry previously added to an AI agent's configuration."
 }
 
+func GetAIDescription() string {
+	return `Remove the JFrog MCP server entry previously added to an AI agent's configuration (Cursor or Claude Code). Only the JFrog entry is removed; other configured MCP servers are left untouched.
+
+When to use:
+- Disconnecting an agent from the JFrog Platform MCP integration.
+- Cleaning up before re-installing against a different platform or scope.
+
+Prerequisites:
+- The agent (Cursor or Claude Code) with a JFrog MCP entry previously added by 'jf mcp install'.
+
+Common patterns:
+  $ jf mcp uninstall --agent=cursor
+  $ jf mcp uninstall --agent=claude --global
+
+Gotchas:
+- Match the scope used at install time: a --global install is removed with --global; a project install is removed from the project config.
+- If the entry was installed under a non-default name, pass --name to target it.
+
+Related: jf mcp install, jf mcp show`
+}
+
 func GetArguments() string {
 	return `	EXAMPLES
   # Remove the JFrog MCP server from Cursor (current project)

mcp/cli.go

@@ -25,8 +25,8 @@ func GetCommands() []cli.Command {
 		{
 			Name:         "show",
 			Flags:        cliutils.GetCommandFlags(cliutils.McpShow),
-			Usage:        showDocs.GetDescription(),
-			HelpName:     corecommon.CreateUsage("mcp show", showDocs.GetDescription(), showDocs.Usage),
+			Usage:        corecommon.ResolveDescription(showDocs.GetDescription(), showDocs.GetAIDescription()),
+			HelpName:     corecommon.CreateUsage("mcp show", corecommon.ResolveDescription(showDocs.GetDescription(), showDocs.GetAIDescription()), showDocs.Usage),
 			UsageText:    showDocs.GetArguments(),
 			ArgsUsage:    common.CreateEnvVars(),
 			BashComplete: corecommon.CreateBashCompletionFunc(),
@@ -35,8 +35,8 @@ func GetCommands() []cli.Command {
 		{
 			Name:         "install",
 			Flags:        cliutils.GetCommandFlags(cliutils.McpInstall),
-			Usage:        installDocs.GetDescription(),
-			HelpName:     corecommon.CreateUsage("mcp install", installDocs.GetDescription(), installDocs.Usage),
+			Usage:        corecommon.ResolveDescription(installDocs.GetDescription(), installDocs.GetAIDescription()),
+			HelpName:     corecommon.CreateUsage("mcp install", corecommon.ResolveDescription(installDocs.GetDescription(), installDocs.GetAIDescription()), installDocs.Usage),
 			UsageText:    installDocs.GetArguments(),
 			ArgsUsage:    common.CreateEnvVars(),
 			BashComplete: corecommon.CreateBashCompletionFunc("cursor", "claude"),
@@ -45,8 +45,8 @@ func GetCommands() []cli.Command {
 		{
 			Name:         "uninstall",
 			Flags:        cliutils.GetCommandFlags(cliutils.McpUninstall),
-			Usage:        uninstallDocs.GetDescription(),
-			HelpName:     corecommon.CreateUsage("mcp uninstall", uninstallDocs.GetDescription(), uninstallDocs.Usage),
+			Usage:        corecommon.ResolveDescription(uninstallDocs.GetDescription(), uninstallDocs.GetAIDescription()),
+			HelpName:     corecommon.CreateUsage("mcp uninstall", corecommon.ResolveDescription(uninstallDocs.GetDescription(), uninstallDocs.GetAIDescription()), uninstallDocs.Usage),
 			UsageText:    uninstallDocs.GetArguments(),
 			ArgsUsage:    common.CreateEnvVars(),
 			BashComplete: corecommon.CreateBashCompletionFunc("cursor", "claude"),