From a5a666a94749c0e7d1d198485c8917e4b179d136 Mon Sep 17 00:00:00 2001 From: Michael Dailey Date: Mon, 20 Apr 2026 16:12:17 -0500 Subject: [PATCH 1/2] docs(mcp): add npx alternative and fix Claude Code setup instructions - Add `npx -y @salesforce/cli` as the command alternative for clients where `sf` is not on PATH (Claude Desktop, VS Code extensions, Cursor) - Fix Claude Code config: replace wrong `.claude/mcp.json` path with correct `.mcp.json` at project root - Fix Claude Code command: replace invalid `/mcp add` slash command with correct `claude mcp add` terminal command - Expand Claude Code section to distinguish terminal vs config-file setup - Add GitHub Copilot section to provar-mcp-public-docs.md (was missing) - Use `${workspaceFolder}` in VS Code-based configs for GitHub Copilot - Update SF_NOT_FOUND troubleshooting to recommend npx as primary fix Co-Authored-By: Claude Sonnet 4.6 --- docs/mcp-pilot-guide.md | 36 +++++++++-- docs/mcp.md | 109 +++++++++++++++++++++++++++------ docs/provar-mcp-public-docs.md | 72 +++++++++++++++++++--- 3 files changed, 184 insertions(+), 33 deletions(-) diff --git a/docs/mcp-pilot-guide.md b/docs/mcp-pilot-guide.md index 81a187e..1870d96 100644 --- a/docs/mcp-pilot-guide.md +++ b/docs/mcp-pilot-guide.md @@ -80,7 +80,19 @@ Restart Claude Desktop after saving the file. The Provar tools will appear in th #### Claude Code (VS Code / CLI) -Add to your project's `.claude/mcp.json`: +Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both work whether you're in the terminal, the VS Code extension, or the Claude Code Desktop app. + +**Via terminal (recommended for first-time setup):** + +```sh +# User-scoped — works across all projects +claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project + +# Project-scoped, shared — writes .mcp.json at project root; commit to source control +claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project +``` + +**Via config file** — create `.mcp.json` at your project root: ```json { @@ -93,10 +105,23 @@ Add to your project's `.claude/mcp.json`: } ``` -Or add directly from the Claude Code session: +**`sf` not found?** GUI environments often start with a restricted PATH. Use `npx` instead: +```sh +claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project ``` -/mcp add provar sf provar mcp start --allowed-paths /path/to/project + +Or in the config file: + +```json +{ + "mcpServers": { + "provar": { + "command": "npx", + "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + } + } +} ``` #### GitHub Copilot (VS Code) @@ -349,14 +374,15 @@ NitroX is Provar's Hybrid Model for locators — it maps Salesforce component-ba **Goal:** Demonstrate the full Phase 2 AI-assisted test generation loop: org metadata → corpus retrieval → LLM synthesis → generate + validate. **Setup:** + 1. Run `sf provar auth login` and complete the browser login (Provar API key). -2. *(Optional but recommended)* Connect the Salesforce Hosted MCP Server alongside Provar MCP. Add `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` to your MCP client config and authenticate with OAuth. This gives the AI real field API names for your org. +2. _(Optional but recommended)_ Connect the Salesforce Hosted MCP Server alongside Provar MCP. Add `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` to your MCP client config and authenticate with OAuth. This gives the AI real field API names for your org. > "I want to generate a Provar test case for: As a sales rep I want to create an Opportunity in Salesforce with a close date, amount, and stage. Check my org's Opportunity schema first, then find similar corpus examples." **What to look for:** -- *(If SF MCP connected)* `getObjectSchema` called for `Opportunity` — AI uses real field names (e.g. `Amount`, `CloseDate`, `StageName`) in the corpus query +- _(If SF MCP connected)_ `getObjectSchema` called for `Opportunity` — AI uses real field names (e.g. `Amount`, `CloseDate`, `StageName`) in the corpus query - `provar.qualityhub.examples.retrieve` called with the enriched user story as query, returning `examples` array with `similarity_score` values and XML content - The AI using the retrieved XML as few-shot context when calling `provar.testcase.generate` - `provar.testcase.validate` confirming `quality_score >= 70` diff --git a/docs/mcp.md b/docs/mcp.md index 2f49a3a..053617a 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -147,20 +147,26 @@ sf provar mcp start -a /workspace/project-a -a /workspace/project-b ### Claude Code -The simplest approach is the `claude mcp add` CLI command: +Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both approaches work whether you're using the Claude Code terminal, the VS Code extension, or the Claude Code Desktop app. + +#### Via terminal (one-time setup) + +Run one of the following in a terminal, choosing your preferred scope: ```sh -# User-scoped — works across all your projects +# User-scoped — registers once and works across all your projects claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project -# Project-scoped, shared — creates .mcp.json in project root (commit to source control) +# Project-scoped, shared — writes .mcp.json in the current directory; commit to source control claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project -# Project-scoped, private — stored in .claude/settings.local.json (not committed) +# Project-scoped, private — stored in .claude/settings.local.json; not committed claude mcp add provar -s local -- sf provar mcp start --allowed-paths /path/to/your/provar/project ``` -You can also edit `.mcp.json` at your project root directly for the shared project config: +#### Via config file (manual / VS Code) + +Create or edit `.mcp.json` at your project root for project-scoped configuration shared with your team: ```json { @@ -173,9 +179,36 @@ You can also edit `.mcp.json` at your project root directly for the shared proje } ``` +For user-scoped (global) configuration that applies across all projects, add the same `provar` entry under `mcpServers` in `~/.claude.json`. + +#### `sf` not found? Use `npx` + +GUI environments (VS Code, Claude Code Desktop, Claude Desktop) often start with a restricted PATH that doesn't include the `sf` binary. Using `npx` as the command resolves this — it finds `@salesforce/cli` from your npm cache without requiring `sf` to be on PATH. + +**Via terminal:** + +```sh +claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project +``` + +**Via config file:** + +```json +{ + "mcpServers": { + "provar": { + "command": "npx", + "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + } + } +} +``` + +> The Provar plugin must still be installed first via `sf plugins install @provartesting/provardx-cli@beta`. The npx invocation shares the same plugin directory as the globally installed `sf` binary. + ### Claude Desktop -Add a `provar` entry to your Claude Desktop MCP configuration file. +Edit the Claude Desktop MCP configuration file. Open it via **Claude menu → Settings → Developer → Edit Config**, or navigate to it directly: - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` @@ -191,9 +224,22 @@ Add a `provar` entry to your Claude Desktop MCP configuration file. } ``` -> **Windows:** If `sf` is not found, use `sf.cmd` as the command. Claude Desktop may not inherit the full shell PATH, so `sf.cmd` (the npm-installed wrapper) is more reliable. - -Restart Claude Desktop after saving the file. The Provar tools will appear in the tool list. +Fully quit and relaunch Claude Desktop after saving (Cmd+Q on macOS, not just close the window). The Provar tools will appear in the tool list. + +> **`sf` not found?** Claude Desktop launches with a restricted PATH on macOS and Windows. If the server fails to start, use `npx` instead: +> +> ```json +> { +> "mcpServers": { +> "provar": { +> "command": "npx", +> "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] +> } +> } +> } +> ``` +> +> On Windows, you may also try `sf.cmd` as the command if npx is not available. ### GitHub Copilot (VS Code) @@ -205,15 +251,29 @@ Create or edit `.vscode/mcp.json` in your workspace root (commit this to source "provar": { "type": "stdio", "command": "sf", - "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"] } } } ``` -> **Windows:** Use `sf.cmd` instead of `sf` if VS Code cannot find the command. - -After saving, open the **GitHub Copilot Chat** panel and select **Agent** mode. The Provar tools will be listed in the available tools. +After saving, open the **GitHub Copilot Chat** panel and select **Agent** mode. The Provar tools will appear in the available tools. + +> **`sf` not found?** VS Code may not inherit your shell PATH. Use `npx` instead: +> +> ```json +> { +> "servers": { +> "provar": { +> "type": "stdio", +> "command": "npx", +> "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"] +> } +> } +> } +> ``` +> +> On Windows, you can also try `sf.cmd` as the command. ### Cursor @@ -247,7 +307,20 @@ Cursor supports project-level and global MCP configuration. After saving, restart Cursor. The Provar tools will appear under **Settings → MCP**. -> **Windows:** Use `sf.cmd` instead of `sf` if Cursor cannot locate the command. +> **`sf` not found?** Use `npx` as the command instead: +> +> ```json +> { +> "mcpServers": { +> "provar": { +> "command": "npx", +> "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] +> } +> } +> } +> ``` +> +> On Windows, you can also try `sf.cmd` if `npx` is unavailable. ### Agentforce Vibes @@ -1464,10 +1537,10 @@ Each element in `examples`: Provar MCP does not include a built-in org introspection tool. Instead, connect the **Salesforce Hosted MCP Server** (`platform/sobject-reads`) alongside Provar MCP and call `getObjectSchema` to retrieve sObject field metadata. Pass the result as additional context in your `provar.qualityhub.examples.retrieve` query. -| Endpoint | URL | -| -------- | --- | -| Production | `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` | -| Sandbox | `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads` | +| Endpoint | URL | +| ---------- | --------------------------------------------------------------------------- | +| Production | `https://api.salesforce.com/platform/mcp/v1/platform/sobject-reads` | +| Sandbox | `https://api.salesforce.com/platform/mcp/v1/sandbox/platform/sobject-reads` | The SF Hosted MCP uses per-user OAuth 2.0, respects field-level security and sharing rules automatically, and is maintained by Salesforce. See [Salesforce Hosted MCP Server docs](https://developer.salesforce.com/docs/platform/hosted-mcp-servers/guide/sobject-reads.html) for setup. diff --git a/docs/provar-mcp-public-docs.md b/docs/provar-mcp-public-docs.md index 5355e23..5e82bf1 100644 --- a/docs/provar-mcp-public-docs.md +++ b/docs/provar-mcp-public-docs.md @@ -97,7 +97,19 @@ Restart Claude Desktop after saving. The Provar tools will appear in the tool li #### Claude Code (VS Code / CLI) -Add to your project's `.claude/mcp.json`: +Claude Code can be configured via the `claude` CLI command or by editing a JSON config file. Both approaches work in the terminal, the VS Code extension, and the Claude Code Desktop app. + +**Via terminal (recommended):** + +```sh +# User-scoped — works across all your projects +claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project + +# Project-scoped, shared — creates .mcp.json at project root; commit to source control +claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project +``` + +**Via config file** — create `.mcp.json` at your project root: ```json { @@ -110,26 +122,64 @@ Add to your project's `.claude/mcp.json`: } ``` -Or add directly from a Claude Code session: +**`sf` not found?** GUI environments (VS Code, Claude Code Desktop) often launch with a restricted PATH that doesn't include `sf`. Use `npx` as the command instead: + +```sh +# Terminal +claude mcp add provar -s user -- npx -y @salesforce/cli provar mcp start --allowed-paths /path/to/your/provar/project +``` +```json +{ + "mcpServers": { + "provar": { + "command": "npx", + "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + } + } +} ``` -/mcp add provar sf provar mcp start --allowed-paths /path/to/project + +#### GitHub Copilot (VS Code) + +Create `.vscode/mcp.json` in your workspace root (commit to share with your team): + +```json +{ + "servers": { + "provar": { + "type": "stdio", + "command": "sf", + "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"] + } + } +} ``` +Open the **GitHub Copilot Chat** panel and switch to **Agent** mode. The Provar tools will appear in the tool list. + +> **`sf` not found?** Replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array. + #### Cursor -In Cursor Settings → MCP, add: +Add to `.cursor/mcp.json` in your workspace root (project-level) or `~/.cursor/mcp.json` (global): ```json { - "provar": { - "command": "sf", - "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + "mcpServers": { + "provar": { + "command": "sf", + "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + } } } ``` -> **Important:** Set `--allowed-paths` to the root of your Provar Automation project directory. This is the folder containing your `.testproject` file. The server will only read and write files within this boundary. +Restart Cursor after saving. The Provar tools will appear under **Settings → MCP**. + +> **`sf` not found?** Replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array. + +> **Important:** Set `--allowed-paths` to the root of your Provar Automation project directory (the folder containing your `.testproject` file). The server will only read and write files within this boundary. --- @@ -364,12 +414,14 @@ Open Provar Automation IDE → Help → Manage License → ensure the license is The server started successfully but the license cache is over 2 hours old. This is a warning only. If the cache exceeds 48 hours without a successful online re-validation, the next startup will fail. Restart the server while Provar Automation IDE is connected to the internet to refresh the cache. **`SF_NOT_FOUND` error from Quality Hub / Automation tools** -The `sf` CLI binary is not on the PATH that the MCP server sees (common with macOS GUI apps). Use the full binary path in your MCP config: +The `sf` CLI binary is not on the PATH that the MCP server sees (common with macOS and Windows GUI apps). Use `npx` as the command in your MCP config — it resolves `@salesforce/cli` from your npm cache without needing `sf` on PATH: ```json -{ "command": "/usr/local/bin/sf", "args": ["provar", "mcp", "start", "--allowed-paths", "..."] } +{ "command": "npx", "args": ["-y", "@salesforce/cli", "provar", "mcp", "start", "--allowed-paths", "..."] } ``` +Alternatively, use the full path to the `sf` binary (e.g. `/usr/local/bin/sf` on macOS). + **`PATH_NOT_ALLOWED` error** The path passed to a tool is outside the `--allowed-paths` root. Update `--allowed-paths` in your client config and restart the server. From 8e5610cbee206cf2cfa295f6d66cab1beaf4c013 Mon Sep 17 00:00:00 2001 From: Michael Dailey Date: Mon, 20 Apr 2026 16:19:21 -0500 Subject: [PATCH 2/2] docs(mcp): address PR review comments - Clarify -s project runs from project root (not arbitrary cwd) - Update GitHub Copilot snippet in pilot guide to use \${workspaceFolder} - Replace Windows sf.cmd note with consistent npx fallback guidance Co-Authored-By: Claude Sonnet 4.6 --- docs/mcp-pilot-guide.md | 4 ++-- docs/mcp.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/mcp-pilot-guide.md b/docs/mcp-pilot-guide.md index 1870d96..571bbd8 100644 --- a/docs/mcp-pilot-guide.md +++ b/docs/mcp-pilot-guide.md @@ -134,7 +134,7 @@ Create or edit `.vscode/mcp.json` in your workspace root: "provar": { "type": "stdio", "command": "sf", - "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"] + "args": ["provar", "mcp", "start", "--allowed-paths", "${workspaceFolder}"] } } } @@ -142,7 +142,7 @@ Create or edit `.vscode/mcp.json` in your workspace root: Open the **GitHub Copilot Chat** panel and switch to **Agent** mode. The Provar tools will appear in the tool list. -> **Windows:** Use `sf.cmd` instead of `sf` if VS Code cannot find the command. +> **`sf` not found?** Use `npx` instead: replace `"command": "sf"` with `"command": "npx"` and prepend `"-y", "@salesforce/cli"` to the `args` array. On Windows, you can also try `sf.cmd`. #### Cursor diff --git a/docs/mcp.md b/docs/mcp.md index 053617a..6756366 100644 --- a/docs/mcp.md +++ b/docs/mcp.md @@ -157,7 +157,7 @@ Run one of the following in a terminal, choosing your preferred scope: # User-scoped — registers once and works across all your projects claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project -# Project-scoped, shared — writes .mcp.json in the current directory; commit to source control +# Project-scoped, shared — run from your project root; writes .mcp.json there; commit to source control claude mcp add provar -s project -- sf provar mcp start --allowed-paths /path/to/your/provar/project # Project-scoped, private — stored in .claude/settings.local.json; not committed