PDX-515: fix(mcp): read Provar IDE SfObject org-describe cache layout

[mrdailey99]

Summary

• provar_org_describe previously returned field_count: 0 for every object because it resolved only the legacy <workspace>/.metadata/<connection_name>/ directory and parsed only native JSON / CustomObject XML. The Provar IDE actually writes one <sfObject>/<fields>/<sfField> XML file per object under .metadata/.plugins/com.provar.eclipse.ui/<connection>/<env>/SfObject/, so the directory was never found (silent cache-miss) and the format could not be parsed.
• The tool now prefers the IDE SfObject layout and falls back to the legacy/native layout, so existing JSON/.object/.xml caches keep working.
• New optional environment parameter (default default) selects the test-environment subdirectory; if the requested environment has no cached metadata, the tool falls back to any environment that does, preferring default.
• Verified end-to-end against the real Provar IDE cache files on disk: the real provar__Person__c.xml yields 16 fields with provar__Email__c as the only required field; the real Account.xml stub (detailsLoaded="false") yields exists: true, field_count: 0.

Jira

https://provartesting.atlassian.net/browse/PDX-515

Changes

• src/mcp/tools/orgDescribeTools.ts
  • XML_PARSER now arrays both fields and sfField so both on-disk XML formats parse with one parser instance.
  • New readSfObjectXml helper parses the IDE format: name ← @_n (nameless fields skipped), type ← @_type (absent → unknown), nillable ← NOT(@_required === 'true'), default_value always null, display name from @_t/@_n; container <sfField> children (e.g. <referenceTos>) are not counted; stubs yield an empty field list.
  • readXmlCacheFile now detects <sfObject> vs <CustomObject>/<toolingObjectInfo> and dispatches; legacy parsing extracted into readCustomObjectXml.
  • New resolveSfObjectDir resolves the IDE layout with requested-env-first / default-preferred fallback; resolveConnectionDir prefers it before the legacy directory. assertPathAllowed is enforced on the workspace, the com.provar.eclipse.ui dir, the connection dir, and every candidate SfObject dir; connection_name and environment are validated as identifiers (no separators / ..).
  • New optional environment input param (default default); tool description and field descriptions updated per MCP authoring standards.
  • cache_age_ms reflects the SfObject directory mtime when that layout is used.
• test/unit/mcp/orgDescribeTools.test.ts — added 9 SfObject-layout tests (happy path, field_filter=required, env fallback, env default, stub handling, dir listing, IDE-preferred-over-legacy, environment traversal rejection, workspace-outside-allowedPaths rejection). All existing JSON / CustomObject / .object regression tests retained and passing.
• docs/mcp.md — documented the IDE SfObject cache layout, the new environment param (defaults to default), the cache-layout resolution order, and the SfObject XML on-disk schema + field mapping.

Test plan

• yarn compile — clean
• node_modules/.bin/nyc node_modules/.bin/mocha "test/**/*.test.ts" — 1500 passing, 1 pending
• node scripts/mcp-smoke.cjs — only environmental timeouts on unrelated provar_automation_* / provar_testrun_* tools (the smoke script spawns the globally-installed package, not this build; counts varied 4→3 across runs, confirming flakiness)
• yarn lint — clean

Customer-facing behaviour note

This changes the on-disk cache layout provar_org_describe reads (it now reads the Provar IDE SfObject cache and accepts a new environment parameter). The external/customer-facing docs (docs/provar-mcp-public-docs.md, docs/university-of-provar-mcp-course.md) are maintained separately by the Provar team and should be updated to reflect the new layout and parameter.

🤖 Generated with Claude Code

[github-actions]

Quality Orchestrator

🟢 LOW · 2 / 100 · All changed files have mapped tests.

---

🧪 Tests to Run · Running 1 of 57 tests

• unit/mcp/orgDescribeTools.test.ts

▶ Run command

npx vitest run \
  unit/mcp/orgDescribeTools.test.ts

---

_{⚡ quality-orchestrator  ·  /qo stub <file>  ·  qo analyze-local}