You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
| New error code or suggestion field |`docs/mcp.md` (Troubleshooting or Error Codes section) |
17
+
| Security model change (path policy, licence, transport) |`docs/mcp.md` (Security Model section), `docs/mcp-pilot-guide.md` (Security Model section) |
18
+
| New NitroX tool or schema rule |`docs/mcp.md` (NitroX section), `docs/mcp-pilot-guide.md` (Scenario 7) |
19
+
| Smoke test count change | Update `TOTAL_EXPECTED` in `scripts/mcp-smoke.cjs`|
20
+
21
+
**External / customer-facing docs** (`docs/provar-mcp-public-docs.md`, `docs/university-of-provar-mcp-course.md`) are maintained separately by the Provar team — flag changes that affect public-facing behaviour in your PR description so those can be updated manually.
22
+
23
+
---
24
+
25
+
## Test Coverage Requirements
26
+
27
+
Every PR must include tests for new or changed behaviour:
28
+
29
+
-**New MCP tool** → unit tests in `test/unit/mcp/<toolGroup>Tools.test.ts` covering: happy path, path policy rejection, missing required fields, and any tool-specific error codes
30
+
-**Modified error handling** → at least one positive test (error path fires) and one negative test (does not fire for non-matching input)
31
+
-**New validation rule** → test that the rule fires correctly and that a valid input passes
32
+
-**Smoke test** → add an entry in `scripts/mcp-smoke.cjs` for each new tool; update `TOTAL_EXPECTED`
33
+
34
+
Run before every commit:
35
+
```sh
36
+
yarn test:only # unit tests — must all pass
37
+
node scripts/mcp-smoke.cjs 2>/dev/null # smoke — must show all PASS
38
+
yarn compile # TypeScript — must be clean
39
+
```
40
+
41
+
---
42
+
43
+
## MCP Tool Authoring Standards
44
+
45
+
### Tool description quality
46
+
47
+
Every tool description must answer these questions for an AI agent reading it cold:
48
+
49
+
1.**What does it do?** (one sentence)
50
+
2.**What prerequisite tools must run first?** (e.g. `config.load` before `metadata.download`)
51
+
3.**What are the correct flags / parameters?** Include a concrete example in the `flags` field description when flags are free-form
52
+
4.**What does a failure mean?** If a known error pattern exists (e.g. `[DOWNLOAD_ERROR]` = auth failure), say so in the description or return a `details.suggestion`
53
+
54
+
### Field descriptions
55
+
56
+
- Fields that accept a **string key or password** must say "string value, NOT a file path" if there is any risk of confusion with a path
57
+
- Fields that accept a **file path** must note if the path must be within `--allowed-paths`
58
+
- Optional fields that have a dangerous default (e.g. overwriting existing files) must call that out
59
+
60
+
### Error responses
61
+
62
+
- Return `details: { suggestion: '...' }` when a known error pattern maps to a common root cause and there is an actionable fix
63
+
- Never pass `details: {}` — omit `details` entirely when there is nothing extra to say (keeps the response shape stable)
64
+
- Error codes follow `SCREAMING_SNAKE_CASE`; document new codes in `docs/mcp.md`
65
+
66
+
### Path safety
67
+
68
+
- Call `assertPathAllowed(path, config.allowedPaths)` on **every** path input before any file operation — not just the output path
69
+
- Use `path.resolve()` before `fs.existsSync` / `fs.readFileSync` / `fs.writeFileSync`
70
+
- Never construct shell commands from user input; use `spawnSync` with an args array
71
+
72
+
---
73
+
74
+
## Branch and PR Conventions
75
+
76
+
- Feature branches off `develop`: `feature/<description>`
77
+
- Bug/fix branches off `develop`: `fix/<description>`
78
+
- Release branches off `develop`: `release-v<semver>`
79
+
- PRs target `develop`; releases are merged develop → main
80
+
- Version in `package.json` follows `<major>.<minor>.<patch>-beta.<n>` on develop
81
+
- Bump the beta suffix (`beta.N → beta.N+1`) on any PR that triggers a publish
82
+
83
+
---
84
+
85
+
## Lint
86
+
87
+
The project uses ESLint with `@typescript-eslint` strict rules. Common gotchas:
88
+
89
+
-`complexity` max is **20** — extract helpers if a function grows past that
90
+
-`no-unsafe-assignment` / `no-unsafe-call` — cast through `unknown` not `any`
91
+
-`no-unnecessary-type-assertion` — TypeScript narrows after `typeof x === 'string'` checks; remove the redundant cast
92
+
-`camelcase` — `nitroX` is valid camelCase (capital X starts the next word)
93
+
94
+
CI runs lint as part of `sf-prepack` — do not skip with `--no-verify` on the final merge commit.
The Provar DX CLI is a Salesforce CLI plugin for Provar customers who want to automate the execution of tests using Provar Automation, and the reporting of test results and other quality-related metrics to Provar Quality Hub.
10
11
11
12
# Installation, Update, and Uninstall
12
13
14
+
**Requires Node.js 18–24 (LTS 22 recommended).** Node 25+ is not yet supported due to a breaking change in a transitive dependency. Check with `node --version`.
15
+
13
16
Install the plugin
14
17
15
18
```sh-session
16
-
$ sf plugins install @provartesting/provardx-cli
19
+
$ sf plugins install @provartesting/provardx-cli@beta
17
20
```
18
21
19
22
Update plugins
@@ -30,33 +33,56 @@ $ sf plugins uninstall @provartesting/provardx-cli
30
33
31
34
# MCP Server (AI-Assisted Quality)
32
35
33
-
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, and validate every level of the test hierarchy with quality scores that match the Provar Quality Hub API.
36
+
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.
37
+
38
+
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)**.
39
+
40
+
## Quick setup
41
+
42
+
**Requires:** Provar Automation IDE installed with an activated license.
34
43
35
44
```sh
36
-
sf provar mcp start --allowed-paths /path/to/your/provar/project
45
+
# 1. Install the plugin (if not already installed)
46
+
sf plugins install @provartesting/provardx-cli@beta
47
+
48
+
# 2. (Optional) Authenticate for full 170+ rule validation
49
+
sf provar auth login
37
50
```
38
51
39
-
📖 **See [docs/mcp.md](https://github.com/ProvarTesting/provardx-cli/blob/main/docs/mcp.md) for full setup and tool documentation.**
52
+
**Claude Code** — run once to register the server:
40
53
41
-
## License Validation
54
+
```sh
55
+
claude mcp add provar -s user -- sf provar mcp start --allowed-paths /path/to/your/provar/project
56
+
```
42
57
43
-
The MCP server verifies your Provar license before accepting any connections. Validation is automatic — no extra flags are required for standard usage.
58
+
**Claude Desktop** — add to your config file and restart the app:
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.
48
-
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.
49
-
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.
50
-
4.**Fail closed** — if no valid license is detected the command exits with a non-zero exit code and a clear error message.
0 commit comments