@vulcan-energy/mcp-helper 0.2.5 → 0.3.1

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
@@ -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
 
@@ -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,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 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
 
@@ -321,7 +324,7 @@ Should return:
321
324
 
322
325
  A CSV saved by the current app pins its HEM target in Metadata
323
326
  (`TargetBundleId`). A CSV with no `TargetBundleId` row, or an empty one, uses
324
- Rust HEM:FHS 1.0.0a7, as in the app. `vulcan_merge_csv_to_json`,
327
+ HEM:FHS 1.0.0a7, as in the app. `vulcan_merge_csv_to_json`,
325
328
  `vulcan_create_batch_config` and `vulcan_run_batch` run every CSV through its
326
329
  target with no extra arguments. Install Google Chrome separately: this helper packages the browser
327
330
  adapter and application workers, not a browser.
@@ -167,7 +167,7 @@ This is intended to be a **complete** list of production dependencies (including
167
167
 
168
168
  ## Licence texts of code bundled in `dist/`
169
169
 
170
- The published `dist/` files bundle papaparse (`server.js`, `bin/vulcan-mcp-helper.js`, `hem-target-runtime/host.mjs`, `hem-target-runtime/python-worker.mjs`) and polygon-clipping with the splaytree, robust-predicates and tslib helper code its build inlines (`hem-target-runtime/host.mjs`). `hem-target-runtime/host.mjs` also includes the Home Energy Model ECaaS input schema. The other packages in the table are installed by npm with their own licence files.
170
+ The published `dist/` files bundle papaparse (`server.js`, `bin/vulcan-mcp-helper.js`, `hem-target-runtime/host.mjs`, `hem-target-runtime/python-worker.mjs`) and polygon-clipping with the splaytree, robust-predicates and tslib helper code its build inlines (`hem-target-runtime/host.mjs`). `hem-target-runtime/host.mjs` also includes the Home Energy Model ECaaS input schemas. The other packages in the table are installed by npm with their own licence files.
171
171
 
172
172
  ### papaparse
173
173
 
@@ -326,7 +326,7 @@ END OF TERMS AND CONDITIONS
326
326
 
327
327
  ### Home Energy Model ECaaS input schema
328
328
 
329
- `dist/hem-target-runtime/host.mjs` includes `schemas/ecaas_input_fhs.schema.json`, the Home Energy Model ECaaS FHS input schema. The Ministry of Housing, Communities and Local Government provided it under the same MIT terms as the Home Energy Model.
329
+ `dist/hem-target-runtime/host.mjs` includes `schemas/ecaas_input_fhs.schema.json` (HEM 1.0.0a7) and `schemas/ecaas_input_fhs_1.0.0a9.schema.json` (HEM 1.0.0a9), the Home Energy Model ECaaS FHS input schemas. The Ministry of Housing, Communities and Local Government provided them under the same MIT terms as the Home Energy Model.
330
330
 
331
331
  The MIT License (MIT)
332
332