@vulcan-energy/mcp-helper 0.1.8 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -34,7 +34,11 @@ This creates `vulcan-mcp-config.json` in your workspace root with:
34
34
  }
35
35
  ```
36
36
 
37
- The `license_token` is valid for ~30 days. The helper verifies it locally on startup and on every MCP request. If expired or invalid, you'll get an error message instructing you to refresh it in Vulcan.
37
+ The `license_token` is valid for **seven days**. The helper verifies it locally on startup and on every MCP request, so it works offline for the whole window; it does not phone home. When it expires, generate a new config from Vulcan → Profile → Integrations. The helper warns on startup once fewer than two days remain.
38
+
39
+ Because verification is local and offline, access can outlive a plan change by up to seven days — that is the deliberate price of working without a network.
40
+
41
+ The token names the capabilities it grants. MCP and Analyst are separate entitlements: a token issued for Analyst alone will not start this helper, and you will get `This Vulcan access config does not include MCP` rather than a signature error.
38
42
 
39
43
  Treat `vulcan-mcp-config.json` as a secret: do not commit it or share its token.
40
44
 
@@ -282,8 +286,11 @@ Common errors and what they mean:
282
286
  - **`Your Vulcan MCP token is missing`** - Token not in config. Generate config from Vulcan
283
287
  - **`Workspace directory not found: <path>`** - Workspace path in config is incorrect
284
288
  - **`Workspace missing required directory: input/batch_parameters`** - Not a valid Vulcan workspace or not in FSA mode
285
- - **`Your Vulcan MCP token has expired`** - Token expired (~30 days). Refresh in Vulcan → Integrations → MCP
286
- - **`Your Vulcan MCP token is invalid`** - Token signature invalid. Refresh in Vulcan
289
+ - **`Your Vulcan access config has expired`** - Seven-day window elapsed. Generate a new config in Vulcan → Profile → Integrations
290
+ - **`This Vulcan access config does not include MCP`** - Authentic config without the `mcp` capability. MCP needs a Vulcan Pro seat; an Analyst-only config will not start the helper
291
+ - **`This Vulcan access config was issued for a newer version of the Vulcan tools`** - Update with `npm install -g @vulcan-energy/mcp-helper@latest`
292
+ - **`This system clock is too far behind the access config issue time`** - Correct the system clock, then restart
293
+ - **`Your Vulcan access config is invalid or was signed with an unknown key`** - Signature not recognised. Generate a new config in Vulcan
287
294
  - **`WASM initialization failed`** - WASM files missing or corrupted. Reinstall package
288
295
  - **`Port argument is missing`** - Invalid `--port` usage. Use `--port <number>`
289
296
  - **`Invalid port: <value>`** - Port must be 1-65535
@@ -309,3 +316,38 @@ Should return:
309
316
  - **Port in use**: Use `--port` to specify a different port
310
317
  - **WASM errors**: Reinstall package: `npm install -g @vulcan-energy/mcp-helper`
311
318
 
319
+
320
+ ## Pinned HEM targets
321
+
322
+ A CSV saved by the current app pins its HEM target in Metadata
323
+ (`TargetBundleId`). `vulcan_merge_csv_to_json`, `vulcan_create_batch_config` and
324
+ `vulcan_run_batch` run such sources through that exact target with no extra
325
+ arguments. Install Google Chrome separately: this helper packages the browser
326
+ adapter and application workers, not a browser.
327
+
328
+ The first use of a target downloads it from `usevulcan.app` into
329
+ `~/.cache/vulcan/hem-targets` (about 12 MB for Rust, 75 MB for Python). Its
330
+ manifest must match the SHA-256 pinned in this helper release, and every model
331
+ artifact must match the manifest's size and SHA-256; nothing unverified is
332
+ cached or executed. A target newer than this helper fails with an instruction to
333
+ update `@vulcan-energy/mcp-helper`. `target_manifest` (an absolute path, or a
334
+ path relative to the workspace) plus `target_manifest_sha256` remain an optional
335
+ offline override for a trusted local bundle; supplying only one fails. Missing
336
+ inputs never substitute the helper's installed legacy Rust engine.
337
+
338
+ Merge uses the target's own schema and defaults. `vulcan_create_batch_config`
339
+ captures the application's exact `__hem` snapshot from the source CSVs and
340
+ selected JSON snippets, and refuses a batch that mixes targets. `weather_file` is
341
+ required only for unpinned models; omit it to use a pinned target's reference
342
+ weather, or name an EPW to capture it as the app does. Run uses the saved
343
+ snapshot. Target runs return `started` and continue in a background process;
344
+ `vulcan_get_batch_status` reports download and calculation progress, completion
345
+ and runtime errors, including browser startup failures after the initial
346
+ acquisition acknowledgement. Only one target operation can own a workspace at a
347
+ time. After a forcibly killed process, inspect `.hem-target-active` and its PID
348
+ before removing a stale lock.
349
+
350
+ The adapter uses the same preparation and workers as the app. Synthetic automated
351
+ checks and an a9 preparation-only Chrome probe cover this transport; full MCP
352
+ calculation qualification is separate from those checks. Existing unpinned Rust
353
+ operations retain their installed-WASM path.