docs: fix MCP setup instructions with correct Claude Code commands

mrdailey99 · claude · mrdailey99 · commit 1ded19125eb9 · 2026-04-13T16:36:28.000-05:00
- Add Quick start sections to both README and docs/mcp.md with
  numbered steps and a provardx.ping verify step
- Fix Claude Code section: replace non-existent /mcp add slash command
  and .claude/mcp.json path with correct `claude mcp add -s user|project|local`
  commands and real config file locations (.mcp.json, settings.local.json)
- Move license requirement before client configuration in docs/mcp.md
  since it is a startup blocker
- Add Windows note: use sf.cmd in Claude Desktop when sf is not found

Co-Authored-By: Claude Sonnet 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -35,28 +35,45 @@ $ sf plugins uninstall @provartesting/provardx-cli
 
 The Provar DX CLI includes a built-in **Model Context Protocol (MCP) server** that connects AI assistants (Claude Desktop, Claude Code, Cursor) directly to your Provar project. Once connected, an AI agent can inspect your project structure, generate Page Objects and test cases, validate every level of the test hierarchy with quality scores, and work with NitroX (Hybrid Model) component page objects for LWC, Screen Flow, Industry Components, Experience Cloud, and HTML5.
 
-Validation runs in two modes: **local only** (structural rules, no key required) or **Quality Hub API** (170+ rules, quality scoring — requires a `pv_k_` API key). Run `sf provar auth login` to authenticate and unlock full validation. Don't have an account? **[Request access](https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access)**.
+Validation runs in two modes: **local only** (structural rules, no key required) or **Quality Hub API** (170+ rules, quality scoring — requires a `pv_k_` API key). Don't have an account? **[Request access](https://aqqlrlhga7.execute-api.us-east-1.amazonaws.com/dev/auth/request-access)**.
+
+## Quick setup
+
+**Requires:** Provar Automation IDE installed with an activated license.
 
 ```sh
-sf provar mcp start --allowed-paths /path/to/your/provar/project
+# 1. Install the plugin (if not already installed)
+sf plugins install @provartesting/provardx-cli@beta
+
+# 2. (Optional) Authenticate for full 170+ rule validation
+sf provar auth login
 ```
 
-📖 **See [docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) for full setup and tool documentation.**
+**Claude Code** — run once to register the server:
 
-## License Validation
+```sh
+claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
 
-The MCP server verifies your Provar license before accepting any connections. Validation is automatic — no extra flags are required for standard usage.
+**Claude Desktop** — add to your config file and restart the app:
 
-**How it works:**
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
 
-1. **Auto-detection** — the server reads `~/Provar/.licenses/*.properties` (the same files written by Provar's IDE plugins). If a valid, activated license is found the server starts immediately.
-2. **Cache** — successful validations are cached at `~/Provar/.licenses/.mcp-license-cache.json` (2 h TTL). Subsequent starts within the TTL window skip the disk scan.
-3. **Grace fallback** — if the IDE license files cannot be found or read and the cache is stale (but ≤ 48 h old), the server starts with a warning on stderr using the cached result so CI pipelines are not broken by transient local file-access issues.
-4. **Fail closed** — if no valid license is detected the command exits with a non-zero exit code and a clear error message.
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "sf",
+      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
+  }
+}
+```
 
-**`NODE_ENV=test` fast-path:**
+> **Windows (Claude Desktop):** Use `sf.cmd` instead of `sf` if the server fails to start.
 
-When `NODE_ENV=test` the validation step is skipped entirely. This is intended only for the plugin's own unit-test suite.
+📖 **[docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) — full setup, all 35+ tools, troubleshooting.**
 
 ---
 
diff --git a/docs/mcp.md b/docs/mcp.md
@@ -61,6 +61,55 @@ The Provar DX CLI ships with a built-in **Model Context Protocol (MCP) server**
 
 - **Node.js 18–24** (LTS 22 recommended). Node 25+ is not supported — a transitive dependency (`buffer-equal-constant-time`) crashes on startup. Check with `node --version`.
 - **Salesforce CLI** (`sf`) ≥ 2.x
+- **Provar Automation IDE** installed with an activated license (see [License requirement](#license-requirement) below)
+
+## Quick start
+
+```sh
+# 1. Install the plugin
+sf plugins install @provartesting/provardx-cli@beta
+
+# 2. (Optional) Authenticate for full 170+ rule validation
+sf provar auth login
+
+# 3. Connect your AI assistant — pick one client below
+```
+
+**Claude Code** (one-time, works across all your projects):
+
+```sh
+claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
+
+**Claude Desktop** — edit your config file, then restart the app:
+
+- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "provar": {
+      "command": "sf",
+      "args": ["provar", "mcp", "start", "--allowed-paths", "/path/to/your/provar/project"]
+    }
+  }
+}
+```
+
+> **Windows (Claude Desktop):** If `sf` is not found, use `sf.cmd` as the command instead.
+
+**Verify it's working** — ask your AI assistant: _"Call provardx.ping with message hello"_. You should get `{ "message": "hello" }` back.
+
+---
+
+## License requirement
+
+The MCP server requires **Provar Automation IDE** to be installed on the same machine with an activated license. At startup the server reads `~/Provar/.licenses/*.properties` and verifies that at least one license is in the `Activated` state and was last verified online within the past 48 hours.
+
+If the license check fails, the server exits with a clear error message explaining the reason (not found, stale, or expired). Open Provar Automation IDE to refresh the license online, then retry.
+
+---
 
 ## Starting the server
 
@@ -90,12 +139,22 @@ sf provar mcp start -a /workspace/project-a -a /workspace/project-b
 
 ## Client configuration
 
-### Claude Desktop
+### Claude Code
 
-Add a `provar` entry to your Claude Desktop MCP configuration file.
+The simplest approach is the `claude mcp add` CLI command:
+
+```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 in project root (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)
+claude mcp add provar -s local -- sf provar mcp start --allowed-paths /path/to/your/provar/project
+```
 
-**macOS / Linux:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+You can also edit `.mcp.json` at your project root directly for the shared project config:
 
 ```json
 {
@@ -108,11 +167,12 @@ Add a `provar` entry to your Claude Desktop MCP configuration file.
 }
 ```
 
-Restart Claude Desktop after saving the file. The Provar tools will appear in the tool list.
+### Claude Desktop
 
-### Claude Code
+Add a `provar` entry to your Claude Desktop MCP configuration file.
 
-Add the server to your project's `.claude/mcp.json` (project-scoped) or `~/.claude/mcp.json` (user-scoped):
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -125,26 +185,16 @@ Add the server to your project's `.claude/mcp.json` (project-scoped) or `~/.clau
 }
 ```
 
-Alternatively, run directly from a Claude Code session:
+> **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.
 
-```
-/mcp add provar sf provar mcp start --allowed-paths /path/to/project
-```
+Restart Claude Desktop after saving the file. The Provar tools will appear in the tool list.
 
 ### Cursor / other MCP clients
 
 Any MCP client that supports the **stdio transport** can use this server. Point `command` at `sf` (or the full path to the Salesforce CLI binary) and pass `["provar", "mcp", "start"]` as arguments, plus `--allowed-paths` as appropriate for your project layout.
 
 ---
 
-## License requirement
-
-The MCP server requires **Provar Automation IDE** to be installed on the same machine with an activated license. At startup the server reads `~/Provar/.licenses/*.properties` and verifies that at least one icense is in the `Activated` state and was last verified online within the past 48 hours.
-
-If the license check fails, the server exits with a clear error message explaining the reason (not found, stale, or expired). Open Provar Automation IDE to refresh the license online, then retry.
-
----
-
 ## Authentication — Quality Hub API
 
 The `provar.testcase.validate` tool can run in two modes depending on whether an API key is configured.
@@ -365,20 +415,20 @@ Validates an XML test case for schema correctness (validity score) and best prac
 
 **Output**
 
-| Field                            | Type           | Description                                                               |
-| -------------------------------- | -------------- | ------------------------------------------------------------------------- |
-| `is_valid`                       | boolean        | `true` if zero ERROR-level schema violations                              |
-| `validity_score`                 | number (0–100) | Schema compliance score (100 − errorCount × 20)                           |
-| `quality_score`                  | number (0–100) | Best-practices score (weighted deduction formula)                         |
-| `error_count`                    | integer        | Schema error count                                                        |
-| `warning_count`                  | integer        | Schema warning count                                                      |
-| `step_count`                     | integer        | Number of `<apiCall>` steps                                               |
-| `test_case_id`                   | string         | Value of the `id` attribute                                               |
-| `test_case_name`                 | string         | Value of the `name` attribute                                             |
-| `issues`                         | array          | Schema issues with `rule_id`, `severity`, `message`                       |
-| `best_practices_violations`      | array          | Best-practices violations with `rule_id`, `severity`, `weight`, `message` |
-| `best_practices_rules_evaluated` | integer        | How many best-practices rules were checked                                |
-| `validation_source`              | string         | `quality_hub`, `local`, or `local_fallback` — see Authentication section  |
+| Field                            | Type           | Description                                                                                            |
+| -------------------------------- | -------------- | ------------------------------------------------------------------------------------------------------ |
+| `is_valid`                       | boolean        | `true` if zero ERROR-level schema violations                                                           |
+| `validity_score`                 | number (0–100) | Schema compliance score (100 − errorCount × 20)                                                        |
+| `quality_score`                  | number (0–100) | Best-practices score (weighted deduction formula)                                                      |
+| `error_count`                    | integer        | Schema error count                                                                                     |
+| `warning_count`                  | integer        | Schema warning count                                                                                   |
+| `step_count`                     | integer        | Number of `<apiCall>` steps                                                                            |
+| `test_case_id`                   | string         | Value of the `id` attribute                                                                            |
+| `test_case_name`                 | string         | Value of the `name` attribute                                                                          |
+| `issues`                         | array          | Schema issues with `rule_id`, `severity`, `message`                                                    |
+| `best_practices_violations`      | array          | Best-practices violations with `rule_id`, `severity`, `weight`, `message`                              |
+| `best_practices_rules_evaluated` | integer        | How many best-practices rules were checked                                                             |
+| `validation_source`              | string         | `quality_hub`, `local`, or `local_fallback` — see Authentication section                               |
 | `validation_warning`             | string         | Present when `validation_source` is `local` (onboarding) or `local_fallback` (explains why API failed) |
 
 **Key schema rules:** TC_001 (missing XML declaration), TC_002 (malformed XML), TC_003 (wrong root element), TC_010/011/012 (missing/invalid id/guid), TC_031 (invalid apiCall guid), TC_034/035 (non-integer testItemId).
