@vulcan-energy/mcp-helper 0.2.5 → 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/README.md +56 -53
- package/dist/bin/vulcan-mcp-helper.js +48 -102
- package/dist/hem-target-runtime/browser-adapter.mjs +73 -41
- package/dist/hem-target-runtime/host.mjs +217 -17896
- package/dist/hem-target-runtime/preparation.mjs +18497 -0
- package/dist/hem-target-runtime/wasm-loader.mjs +1 -0
- package/dist/server.d.ts +26 -6
- package/dist/server.js +36 -92
- package/package.json +18 -12
- package/schemas/core-input.schema.json +8020 -0
- package/schemas/input_fhs.schema.json +4728 -0
- package/wasm/wasm_version.json +9 -9
- package/wasm/wasm_wrapper.js +6 -6
- package/wasm/wasm_wrapper_bg.wasm +0 -0
- package/dist/hem-target-runtime/csv-target.mjs +0 -126
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
|
|
|
@@ -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,9 +313,9 @@ 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
|
|