@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 +9 -0
- package/README.md +75 -67
- package/THIRD_PARTY_NOTICES.md +10 -1
- package/dist/bin/vulcan-mcp-helper.js +50 -116
- package/dist/hem-target-runtime/browser-adapter.mjs +83 -21
- package/dist/hem-target-runtime/host.mjs +216 -17173
- package/dist/hem-target-runtime/preparation.mjs +18497 -0
- package/dist/hem-target-runtime/python-worker.mjs +5 -3
- package/dist/hem-target-runtime/rust-worker.mjs +5 -3
- package/dist/hem-target-runtime/wasm-loader.mjs +1 -0
- package/dist/server.d.ts +26 -6
- package/dist/server.js +38 -106
- package/package.json +18 -12
- package/schemas/core-input.schema.json +8020 -0
- package/schemas/input_fhs.schema.json +4728 -0
- package/wasm/THIRD_PARTY_RUST_CRATES.md +5693 -0
- package/wasm/wasm_version.json +9 -9
- package/wasm/wasm_wrapper.js +6 -6
- package/wasm/wasm_wrapper_bg.wasm +0 -0
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
|
|
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
|
|
8
|
-
- A Vulcan workspace
|
|
9
|
-
-
|
|
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
|
-
|
|
16
|
+
The helper speaks MCP over stdio with `--stdio`; your assistant starts it. Point `--workspace` at your workspace folder.
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
**Claude Code**
|
|
14
19
|
|
|
15
20
|
```bash
|
|
16
|
-
|
|
21
|
+
claude mcp add vulcan -- npx -y @vulcan-energy/mcp-helper --stdio --workspace /path/to/workspace
|
|
17
22
|
```
|
|
18
23
|
|
|
19
|
-
|
|
24
|
+
**Codex** (`~/.codex/config.toml`)
|
|
20
25
|
|
|
21
|
-
|
|
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
|
-
|
|
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
|
-
"
|
|
33
|
-
|
|
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
|
-
|
|
45
|
+
## Vulcan Pro
|
|
38
46
|
|
|
39
|
-
|
|
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
|
-
|
|
49
|
+
Alternatively, open Vulcan → Profile → Integrations → MCP, click **Generate Config**, and save `vulcan-mcp-config.json` in the workspace root:
|
|
42
50
|
|
|
43
|
-
|
|
51
|
+
```json
|
|
52
|
+
{
|
|
53
|
+
"workspace": ".",
|
|
54
|
+
"license_token": "<license-token>"
|
|
55
|
+
}
|
|
56
|
+
```
|
|
44
57
|
|
|
45
|
-
|
|
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
|
-
|
|
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
|
-
|
|
50
|
-
vulcan-mcp-helper
|
|
51
|
-
```
|
|
62
|
+
### Local HTTP (Pro)
|
|
52
63
|
|
|
53
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
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
|
-
- `
|
|
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.
|
|
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
|
|
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**:
|
|
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
|
-
##
|
|
323
|
+
## HEM targets
|
|
321
324
|
|
|
322
325
|
A CSV saved by the current app pins its HEM target in Metadata
|
|
323
|
-
(`TargetBundleId`).
|
|
324
|
-
|
|
325
|
-
|
|
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. `
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
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.
|
|
353
|
-
|
|
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`.
|
package/THIRD_PARTY_NOTICES.md
CHANGED
|
@@ -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
|
-
|
|
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/).
|