@vulcan-energy/mcp-helper 0.2.4 → 0.3.0

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/LICENSE CHANGED
@@ -15,6 +15,15 @@ This Software is provided "AS IS" without warranty of any kind, either express
15
15
  or implied, including but not limited to the implied warranties of
16
16
  merchantability and fitness for a particular purpose.
17
17
 
18
+ This package includes code from the Vulcan community repository
19
+ (https://github.com/vulcan-energy/vulcan-community), which is also published
20
+ under the open-source licences recorded in that repository. Home Energy Foundry
21
+ Limited distributes that code in this package under this package's licence, as
22
+ its copyright holder or under the Vulcan contributor licence agreements.
23
+
24
+ Third-party material in this package is licensed under the terms in
25
+ THIRD_PARTY_NOTICES.md.
26
+
18
27
  For licensing inquiries, contact: info@usevulcan.app
19
28
 
20
29
 
package/README.md CHANGED
@@ -1,97 +1,100 @@
1
1
  # Vulcan MCP Helper
2
2
 
3
- A Model Context Protocol (MCP) server that exposes Vulcan's core functionality for integration with Cursor and other MCP clients.
3
+ A Model Context Protocol (MCP) server that gives AI assistants (Claude Code, Codex, Claude Desktop, Cursor and other MCP clients) Vulcan's Home Energy Model (HEM) tools. Everything runs on your machine: models and results are not sent to Vulcan.
4
+
5
+ **Free** needs no account: parameters, geometry CSV validation and conversion, automatic thermal bridges, and single-model runs with headline and FHS results (the same rule as the Vulcan app's Free plan).
6
+ **[Vulcan Pro](https://usevulcan.app/join)** adds scenario batches, weather and parameter variations, model comparison and cost metrics. A Pro tool called without Pro returns a normal result with `status: "requires_pro"`, the reason, and how to unlock it, so your assistant can explain rather than retry.
4
7
 
5
8
  ## Prerequisites
6
9
 
7
- - **Node.js v18 or later** (must be installed separately - not included)
8
- - A Vulcan workspace with FSA (File System Access) mode enabled
9
- - A valid `vulcan-mcp-config.json` file (generated from Vulcan → Integrations → MCP)
10
+ - **Node.js 22.19 or later** (the geometry and thermal-bridge tools run the Vulcan Community CLI, which needs it)
11
+ - A Vulcan workspace folder (the folder you open as a workspace in the Vulcan app). Validation and thermal-bridge tools work on any geometry CSV; `vulcan_list_parameters` lists the workspace's CSVs.
12
+ - Google Chrome, for models pinned to a HEM target (the first use downloads and verifies the target)
13
+
14
+ ## Set up your assistant
10
15
 
11
- ## Installation
16
+ The helper speaks MCP over stdio with `--stdio`; your assistant starts it. Point `--workspace` at your workspace folder.
12
17
 
13
- Install globally using npm:
18
+ **Claude Code**
14
19
 
15
20
  ```bash
16
- npm install -g @vulcan-energy/mcp-helper
21
+ claude mcp add vulcan -- npx -y @vulcan-energy/mcp-helper --stdio --workspace /path/to/workspace
17
22
  ```
18
23
 
19
- ## Configuration
24
+ **Codex** (`~/.codex/config.toml`)
20
25
 
21
- ### Step 1: Download Config File
26
+ ```toml
27
+ [mcp_servers.vulcan]
28
+ command = "npx"
29
+ args = ["-y", "@vulcan-energy/mcp-helper", "--stdio", "--workspace", "/path/to/workspace"]
30
+ ```
22
31
 
23
- 1. Open Vulcan web app
24
- 2. Log in to your account
25
- 3. Select a workspace in FSA (Folder) mode
26
- 4. Go to **Integrations → MCP**
27
- 5. Click **"Generate Config"**
32
+ **Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`~/.cursor/mcp.json`)
28
33
 
29
- This creates `vulcan-mcp-config.json` in your workspace root with:
30
34
  ```json
31
35
  {
32
- "workspace": ".",
33
- "license_token": "<license-token>"
36
+ "mcpServers": {
37
+ "vulcan": {
38
+ "command": "npx",
39
+ "args": ["-y", "@vulcan-energy/mcp-helper", "--stdio", "--workspace", "/path/to/workspace"]
40
+ }
41
+ }
34
42
  }
35
43
  ```
36
44
 
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.
45
+ ## Vulcan Pro
38
46
 
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.
47
+ With Vulcan Pro, ask your assistant to **sign in to Vulcan**. It calls `vulcan_sign_in`, which gives you a link to usevulcan.app/connect and a short code. Open the link, check the code matches, and approve; the assistant calls `vulcan_sign_in` again and Pro tools unlock straight away, with no restart. The token is saved in the workspace's `vulcan-mcp-config.json`. Call `vulcan_sign_in` again to renew it. The code in progress is kept under `~/.vulcan/sign-in` (readable by you only), so it survives a restart of the assistant or helper; approve the code you were shown. If `vulcan-mcp-config.json` is a symlink, the token is written through it only when it points inside the workspace or at another `vulcan-mcp-config.json`; any other link is replaced by a regular file.
40
48
 
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.
49
+ Alternatively, open Vulcan → Profile → Integrations → MCP, click **Generate Config**, and save `vulcan-mcp-config.json` in the workspace root:
42
50
 
43
- Treat `vulcan-mcp-config.json` as a secret: do not commit it or share its token.
51
+ ```json
52
+ {
53
+ "workspace": ".",
54
+ "license_token": "<license-token>"
55
+ }
56
+ ```
44
57
 
45
- ### Step 2: Start the Server
58
+ The helper reads it from the workspace (or `--config <path>`). The token lasts **seven days** and is verified locally, offline, at startup and on every Pro call; access can therefore outlive a plan change by up to seven days. When it expires, Free tools keep working and Pro tools say how to renew. A token that is malformed, or issued for Analyst only, stops the helper with the reason instead of quietly running Free.
46
59
 
47
- From your workspace directory:
60
+ Treat `vulcan-mcp-config.json` as a secret: do not commit it or share its token. It is written readable by your user only on macOS and Linux; on Windows it takes the workspace folder's permissions, so keep the workspace private.
48
61
 
49
- ```bash
50
- vulcan-mcp-helper
51
- ```
62
+ ### Local HTTP (Pro)
52
63
 
53
- Or specify config and port:
64
+ Clients that connect by URL can use the local HTTP server instead of stdio. It needs the Pro token, sent as a Bearer credential, so that a web page cannot call the helper through your browser:
54
65
 
55
66
  ```bash
56
67
  vulcan-mcp-helper --config /path/to/vulcan-mcp-config.json --port 5000
57
68
  ```
58
69
 
59
- **CLI Options:**
60
- - `--config <path>` - Path to config file (default: `./vulcan-mcp-config.json`)
61
- - `--port <port>` - Port to listen on (default: `5000`, or `HELPER_PORT` env var)
62
- - `--help, -h` - Show help message
63
-
64
- **Expected Output:**
65
- ```
66
- [MCP Helper] Config loaded from: /path/to/vulcan-mcp-config.json
67
- [MCP Helper] Workspace: /path/to/workspace
68
- [MCP Helper] WASM initialized
69
- [MCP Helper] Server running on http://127.0.0.1:5000
70
- [MCP Helper] MCP endpoint: http://127.0.0.1:5000/mcp
71
- ```
72
-
73
- ### Step 3: Configure Cursor
74
-
75
- Add to your Cursor MCP configuration (`~/.cursor/mcp.json` or Cursor settings):
76
-
77
70
  ```json
78
71
  {
79
72
  "mcpServers": {
80
73
  "vulcan": {
81
74
  "url": "http://127.0.0.1:5000/mcp",
82
- "headers": {
83
- "Authorization": "Bearer <license_token from vulcan-mcp-config.json>"
84
- }
75
+ "headers": { "Authorization": "Bearer <license_token from vulcan-mcp-config.json>" }
85
76
  }
86
77
  }
87
78
  }
88
79
  ```
89
80
 
90
- Replace the placeholder with the token from `vulcan-mcp-config.json`, then restart Cursor to connect. Requests without that exact Bearer token are rejected.
81
+ **CLI options:** `--stdio`, `--workspace <dir>` (default `VULCAN_WORKSPACE`, else the current folder), `--config <path>`, `--port <port>` (HTTP only; default 5000 or `HELPER_PORT`), `--version`, `--help`.
91
82
 
92
83
  ## Available Tools
93
84
 
94
- The MCP helper provides 10 tools for managing parameters, batch configurations, and simulations. Tools are called via MCP protocol (automatically in Cursor) or via HTTP POST to `/mcp`.
85
+ | Tool | Free | Pro adds |
86
+ |---|---|---|
87
+ | `vulcan_list_parameters`, `vulcan_view_parameter`, `vulcan_save_parameter` | ✓ | |
88
+ | `vulcan_create_batch_config`, `vulcan_run_batch` | One base model, one FHS wrapper, no variations | Scenario batches, weather and parameter variations |
89
+ | `vulcan_get_batch_status`, `vulcan_list_batch_models`, `vulcan_list_csv_columns` | ✓ | |
90
+ | `vulcan_calculate_metrics` | One model, no cost | Model comparison, cost and tariff metrics |
91
+ | `vulcan_merge_csv_to_json` | ✓ | |
92
+ | `vulcan_validate_geometry_csv`, `vulcan_auto_thermal_bridges`, `vulcan_validate_thermal_bridges` | ✓ | |
93
+ | `vulcan_run_model` | One call: create, run locally, wait, and return the FHS rates against their targets (pass/fail), the workspace's default metrics with units, and which source file ran | Cost metrics |
94
+ | `vulcan_compare_scenarios` | | Every model of a batch side by side on the default metrics |
95
+
96
+ Every result carries `structuredContent`; failures are tool errors (`isError: true`) with the reason. The validators run the open-source Vulcan Community CLI (`@vulcan-energy/community-cli`) as a separate process; from a repository checkout, build it first with `npm run build --workspace @vulcan-energy/community-cli`.
97
+
95
98
 
96
99
  ### 1. `vulcan_list_parameters`
97
100
 
@@ -263,13 +266,13 @@ Calculate metrics (sum, average, peak, min, cost) from results.
263
266
 
264
267
  ### 10. `vulcan_merge_csv_to_json`
265
268
 
266
- Convert geometry CSV files to JSON format.
269
+ Convert a geometry CSV file to HEM input JSON for its HEM target (see
270
+ [HEM targets](#hem-targets)). The target sets the schema and the defaults.
267
271
 
268
272
  **Parameters:**
269
273
  - `csv_path` (required, string): Path to CSV file (relative to workspace or absolute)
270
274
  - `output_path` (optional, string): Output JSON path (defaults to input/batch_parameters/base_json/{csv_filename}.json)
271
- - `schema_path` (optional, string): Custom schema path (defaults to the core schema with workspace fallbacks)
272
- - `defaults_path` (optional, string): Custom defaults path (defaults to `input/batch_parameters/base_json/defaults_template.json`)
275
+ - `target_manifest`, `target_manifest_sha256` (optional, strings): offline override for a trusted local bundle
273
276
 
274
277
  **Example:**
275
278
  ```json
@@ -286,7 +289,7 @@ Common errors and what they mean:
286
289
  - **`Your Vulcan MCP token is missing`** - Token not in config. Generate config from Vulcan
287
290
  - **`Workspace directory not found: <path>`** - Workspace path in config is incorrect
288
291
  - **`Workspace missing required directory: input/batch_parameters`** - Not a valid Vulcan workspace or not in FSA mode
289
- - **`Your Vulcan access config has expired`** - Seven-day window elapsed. Generate a new config in Vulcan → Profile → Integrations
292
+ - **`Your Vulcan access config has expired`** - Seven-day window elapsed. Ask your assistant to sign in again (`vulcan_sign_in`), or generate a new config in Vulcan → Profile → Integrations
290
293
  - **`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
294
  - **`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
295
  - **`This system clock is too far behind the access config issue time`** - Correct the system clock, then restart
@@ -310,19 +313,20 @@ Should return:
310
313
 
311
314
  ## Troubleshooting
312
315
 
313
- - **Server won't start**: Check Node.js version (`node --version` must be v18+)
316
+ - **Server won't start**: Check Node.js version (`node --version` must be v20+; 22.19+ for the geometry and thermal-bridge tools)
314
317
  - **Config errors**: Ensure workspace is in FSA (Folder) mode, not OPFS
315
- - **Token expired**: Refresh token in Vulcan → Integrations → MCP
318
+ - **Token expired**: Sign in again with `vulcan_sign_in`, or refresh it in Vulcan → Integrations → MCP
316
319
  - **Port in use**: Use `--port` to specify a different port
317
320
  - **WASM errors**: Reinstall package: `npm install -g @vulcan-energy/mcp-helper`
318
321
 
319
322
 
320
- ## Pinned HEM targets
323
+ ## HEM targets
321
324
 
322
325
  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
+ (`TargetBundleId`). A CSV with no `TargetBundleId` row, or an empty one, uses
327
+ Rust HEM:FHS 1.0.0a7, as in the app. `vulcan_merge_csv_to_json`,
328
+ `vulcan_create_batch_config` and `vulcan_run_batch` run every CSV through its
329
+ target with no extra arguments. Install Google Chrome separately: this helper packages the browser
326
330
  adapter and application workers, not a browser.
327
331
 
328
332
  The first use of a target downloads it from `usevulcan.app` into
@@ -335,11 +339,13 @@ path relative to the workspace) plus `target_manifest_sha256` remain an optional
335
339
  offline override for a trusted local bundle; supplying only one fails. Missing
336
340
  inputs never substitute the helper's installed legacy Rust engine.
337
341
 
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
342
+ Merge uses the target's own schema and defaults. A `DefaultsPath` in the CSV
343
+ must hold the same defaults as the target, or the merge stops with an error.
344
+ `vulcan_create_batch_config` captures the application's exact `__hem` snapshot
345
+ from the source CSVs and selected JSON snippets, and refuses a batch that mixes
346
+ targets. `weather_file` is required only for a base model with no source CSV and
347
+ no target marker; omit it to use the target's reference weather, or name an EPW
348
+ to capture it as the app does. Run uses the saved
343
349
  snapshot. Target runs return `started` and continue in a background process;
344
350
  `vulcan_get_batch_status` reports download and calculation progress, completion
345
351
  and runtime errors, including browser startup failures after the initial
@@ -349,5 +355,7 @@ before removing a stale lock.
349
355
 
350
356
  The adapter uses the same preparation and workers as the app. Synthetic automated
351
357
  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.
358
+ calculation qualification is separate from those checks. A saved batch with no
359
+ `__hem` snapshot still runs on the installed WASM only when no base model has a
360
+ source CSV or target marker; otherwise `vulcan_run_batch` refuses it and asks
361
+ you to create the batch again with `vulcan_create_batch_config`.
@@ -9,7 +9,10 @@ It also includes and/or depends on third-party software. This file is the starti
9
9
  - Generate a full dependency license report at release time (CI or local) and update this file.
10
10
  - Suggested tooling:
11
11
  - Node: `license-checker` (or equivalent) against the exact production dependency tree
12
- - If the published tarball includes bundled assets under `wasm/`, ensure those are also covered by notices
12
+
13
+ ## Rust crates in `wasm/`
14
+
15
+ `wasm/THIRD_PARTY_RUST_CRATES.md` lists each third-party Rust crate compiled into `wasm/wasm_wrapper_bg.wasm`, with its licence text. The WASM build generates it with `cargo-about`.
13
16
 
14
17
  ## Direct npm dependencies (from `package.json`)
15
18
 
@@ -341,3 +344,9 @@ THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR I
341
344
  WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
342
345
  COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
343
346
  OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
347
+
348
+ ### Home Energy Model guidance Table 3.7 default psi values
349
+
350
+ `dist/hem-target-runtime/host.mjs` includes the default linear thermal-transmittance values from Home Energy Model guidance, Building Fabric, section 3.7.2, Table 3.7 (psi values for different types of junctions), published by the Department for Energy Security and Net Zero. Crown copyright.
351
+
352
+ Contains public sector information licensed under the Open Government Licence v3.0 (https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/).