@vulcan-energy/mcp-helper 0.1.1

package/README.md

@@ -0,0 +1,154 @@
+# Vulcan MCP Server
+
+A Model Context Protocol (MCP) server that exposes Vulcan's core functionality for integration with Cursor and other MCP clients.
+
+## Overview
+
+This MCP server provides access to Vulcan's parameter management, batch configuration, and simulation capabilities via stdio **or** Streamable HTTP (JSON-RPC over HTTP).
+
+## Prerequisites
+
+- Node.js (v18 or later)
+- A Vulcan workspace with FSA (File System Access) mode enabled
+- A valid `vulcan-mcp-config.json` file (generated from Vulcan → Integrations → MCP)
+
+## Installation
+
+### Local Development
+
+```bash
+cd vulcan-mcp-server
+npm install
+```
+
+### Production Distribution
+
+The server will be distributed via Vulcan website (behind authentication) for end users.
+
+## Configuration
+
+The server requires a config file at `{workspace}/vulcan-mcp-config.json`:
+
+```json
+{
+  "workspace": "/absolute/path/to/workspace",
+  "user_id": "supabase-user-id"
+}
+```
+
+Generate this file from Vulcan → Integrations → MCP after:
+1. Logging into Vulcan
+2. Selecting a workspace in FSA (Folder) mode
+
+## Usage
+
+### Command Line
+
+#### Stdio mode (original)
+
+```bash
+node index.js --config /path/to/vulcan-mcp-config.json
+```
+
+#### HTTP mode (recommended for Cursor)
+
+**Using npm (easiest):**
+```bash
+cd vulcan-mcp-server
+npm start
+```
+
+**Or manually:**
+```bash
+# default port 4000 (override with --http-port or MCP_HTTP_PORT)
+node index.js --http-port 4000 --config ../vulcan-mcp-config.json
+```
+
+### Cursor Configuration
+
+#### HTTP transport (recommended)
+
+```json
+{
+  "mcpServers": {
+    "vulcan": {
+      "url": "http://127.0.0.1:4000/mcp"
+    }
+  }
+}
+```
+
+#### Stdio transport (legacy)
+
+```json
+{
+  "mcpServers": {
+    "vulcan": {
+      "command": "node",
+      "args": ["/absolute/path/to/vulcan-mcp-server/index.js", "--config", "/absolute/path/to/workspace/vulcan-mcp-config.json"]
+    }
+  }
+}
+```
+
+## Available Tools
+
+### `vulcan_list_parameters`
+
+List available parameter categories and their JSON snippets.
+
+**Arguments:**
+- `category` (optional): Filter by category name
+
+**Returns:**
+- Catalog structure with categories and parameters
+- Total counts
+
+### Metrics Tool Notes
+
+- `vulcan_calculate_metrics` supports comparator-based metrics (`sumIf`, `averageIf`, `countIf`) and compliance metrics (e.g., `dwelling_emission_rate|compliance`).
+- Cost metrics are temporarily blocked in MCP until tariff data plumbing lands—requests containing cost metrics will return an actionable error.
+- Results now include each metric’s `id`, `name`, `column`, and `function`, matching what you send from Cursor.
+
+## Development
+
+### Testing Locally
+
+1. Create a test config file:
+```json
+{
+  "workspace": "/path/to/your/workspace",
+  "user_id": "test-user-id"
+}
+```
+
+2. Test the server (stdio mode):
+```bash
+node index.js --config test-config.json
+```
+
+3. Send test requests via stdin (newline-delimited JSON-RPC):
+```json
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
+{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}
+{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"vulcan_list_parameters","arguments":{}}}
+```
+
+## Logging & Diagnostics
+
+- All WASM `console.log` output is redirected to **stderr** so MCP stdout carries only JSON-RPC. This prevents Cursor’s “model returned error” dialog that appears when stdout is polluted.
+- When debugging, tail stderr (or pipe it to a file) to see WASM initialization and metrics parsing logs.
+
+## Architecture
+
+- **Node.js**: Single runtime, cross-platform
+- **WASM**: Uses existing WASM bundle from `web/pkg/` (for validation, batch execution, metrics)
+- **File Operations**: Node.js `fs` module for workspace file access
+- **Protocol**: MCP via stdio (newline-delimited JSON-RPC) or Streamable HTTP (`POST /mcp`)
+
+## Future Enhancements
+
+- Additional tools: `vulcan_view_parameter`, `vulcan_save_parameter`, `vulcan_create_batch_config`, `vulcan_run_batch`, `vulcan_get_batch_status`, `vulcan_calculate_metrics`
+- WASM integration for validation and batch execution
+- Enhanced error handling and logging
+

package/dist/bin/vulcan-mcp-helper.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for vulcan-mcp-helper
+ *
+ * Thin wrapper that parses --config and --port arguments,
+ * then imports and calls startServer() from src/server.ts
+ */
+export {};
+//# sourceMappingURL=vulcan-mcp-helper.d.ts.map

package/dist/bin/vulcan-mcp-helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vulcan-mcp-helper.d.ts","sourceRoot":"","sources":["../../bin/vulcan-mcp-helper.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}

package/dist/bin/vulcan-mcp-helper.js

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for vulcan-mcp-helper
+ *
+ * Thin wrapper that parses --config and --port arguments,
+ * then imports and calls startServer() from src/server.ts
+ */
+import { startServer } from '../src/server.js';
+function parseArgs() {
+    const args = process.argv.slice(2);
+    const result = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--config' && i + 1 < args.length) {
+            result.configPath = args[i + 1];
+            i++; // Skip next arg
+        }
+        else if (args[i] === '--port' && i + 1 < args.length) {
+            const port = parseInt(args[i + 1], 10);
+            if (isNaN(port) || port < 1 || port > 65535) {
+                console.error(`Invalid port: ${args[i + 1]}`);
+                process.exit(1);
+            }
+            result.port = port;
+            i++; // Skip next arg
+        }
+        else if (args[i] === '--help' || args[i] === '-h') {
+            console.log(`
+Usage: vulcan-mcp-helper [--config <path>] [--port <port>]
+
+Options:
+  --config <path>  Path to vulcan-mcp-config.json (default: ./vulcan-mcp-config.json)
+  --port <port>     Port to listen on (default: 5000)
+  --help, -h        Show this help message
+
+Examples:
+  vulcan-mcp-helper
+  vulcan-mcp-helper --config /path/to/vulcan-mcp-config.json
+  vulcan-mcp-helper --port 5000
+  vulcan-mcp-helper --config ./config.json --port 5000
+`);
+            process.exit(0);
+        }
+    }
+    return result;
+}
+async function main() {
+    try {
+        const { configPath, port } = parseArgs();
+        await startServer(configPath, port);
+    }
+    catch (error) {
+        const err = error;
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=vulcan-mcp-helper.js.map

package/dist/bin/vulcan-mcp-helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vulcan-mcp-helper.js","sourceRoot":"","sources":["../../bin/vulcan-mcp-helper.ts"],"names":[],"mappings":";AAEA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,SAAS,SAAS;IAChB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,MAAM,MAAM,GAA2C,EAAE,CAAC;IAE1D,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAClD,MAAM,CAAC,UAAU,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAChC,CAAC,EAAE,CAAC,CAAC,gBAAgB;QACvB,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YACvD,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACvC,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;gBAC5C,OAAO,CAAC,KAAK,CAAC,iBAAiB,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;gBAC9C,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAClB,CAAC;YACD,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;YACnB,CAAC,EAAE,CAAC,CAAC,gBAAgB;QACvB,CAAC;aAAM,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACpD,OAAO,CAAC,GAAG,CAAC;;;;;;;;;;;;;CAajB,CAAC,CAAC;YACG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC;QACH,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,SAAS,EAAE,CAAC;QACzC,MAAM,WAAW,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,KAAc,CAAC;QAC3B,OAAO,CAAC,KAAK,CAAC,UAAU,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;QACvC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;AACH,CAAC;AAED,IAAI,EAAE,CAAC"}

package/dist/src/engine/filesystem.d.ts

@@ -0,0 +1,30 @@
+/**
+ * File system access helpers for workspace operations
+ * These are thin wrappers around Node.js fs operations
+ * that work with FSA (real filesystem) workspaces only
+ */
+/**
+ * Check if a path exists
+ */
+export declare function pathExists(filePath: string): Promise<boolean>;
+/**
+ * Read a file as text
+ */
+export declare function readFileText(filePath: string): Promise<string>;
+/**
+ * Write a file (creates parent directories if needed)
+ */
+export declare function writeFileText(filePath: string, content: string): Promise<void>;
+/**
+ * List directory contents
+ */
+export declare function listDirectory(dirPath: string): Promise<string[]>;
+/**
+ * Check if a path is a directory
+ */
+export declare function isDirectory(dirPath: string): Promise<boolean>;
+/**
+ * Resolve a path relative to a workspace root
+ */
+export declare function resolveWorkspacePath(workspaceRoot: string, relativePath: string): string;
+//# sourceMappingURL=filesystem.d.ts.map

package/dist/src/engine/filesystem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.d.ts","sourceRoot":"","sources":["../../../src/engine/filesystem.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AAEH;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEpE;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAIpF;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAEtE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAKxF"}

package/dist/src/engine/filesystem.js

@@ -0,0 +1,61 @@
+import fs from 'fs/promises';
+import path from 'path';
+/**
+ * File system access helpers for workspace operations
+ * These are thin wrappers around Node.js fs operations
+ * that work with FSA (real filesystem) workspaces only
+ */
+/**
+ * Check if a path exists
+ */
+export async function pathExists(filePath) {
+    try {
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read a file as text
+ */
+export async function readFileText(filePath) {
+    return await fs.readFile(filePath, 'utf-8');
+}
+/**
+ * Write a file (creates parent directories if needed)
+ */
+export async function writeFileText(filePath, content) {
+    const dir = path.dirname(filePath);
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(filePath, content, 'utf-8');
+}
+/**
+ * List directory contents
+ */
+export async function listDirectory(dirPath) {
+    return await fs.readdir(dirPath);
+}
+/**
+ * Check if a path is a directory
+ */
+export async function isDirectory(dirPath) {
+    try {
+        const stat = await fs.stat(dirPath);
+        return stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a path relative to a workspace root
+ */
+export function resolveWorkspacePath(workspaceRoot, relativePath) {
+    if (path.isAbsolute(relativePath)) {
+        return relativePath;
+    }
+    return path.resolve(workspaceRoot, relativePath);
+}
+//# sourceMappingURL=filesystem.js.map

package/dist/src/engine/filesystem.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"filesystem.js","sourceRoot":"","sources":["../../../src/engine/filesystem.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,aAAa,CAAC;AAC7B,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB;;;;GAIG;AAEH;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,QAAgB;IAC/C,IAAI,CAAC;QACH,MAAM,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC1B,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,QAAgB;IACjD,OAAO,MAAM,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,QAAgB,EAAE,OAAe;IACnE,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACnC,MAAM,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,MAAM,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AACjD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,OAAO,MAAM,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,OAAe;IAC/C,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACpC,OAAO,IAAI,CAAC,WAAW,EAAE,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,aAAqB,EAAE,YAAoB;IAC9E,IAAI,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC,EAAE,CAAC;QAClC,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;AACnD,CAAC"}

package/dist/src/engine/wasm.d.ts

@@ -0,0 +1,23 @@
+/**
+ * WASM module type (from wasm-pack generated bindings)
+ * We use a loose type here since the exact shape depends on the generated bindings
+ */
+interface WasmModule {
+    initSync?: (options: {
+        module: Buffer | Uint8Array;
+    }) => void;
+    setup_panic_hook?: () => void;
+    [key: string]: any;
+}
+export declare function initWasm(): Promise<WasmModule>;
+/**
+ * Get initialized WASM module (throws if not initialized)
+ */
+export declare function getWasmModule(): WasmModule;
+/**
+ * Set the current workspace for file system bridge functions
+ * This should be called before each WASM operation that uses file I/O
+ */
+export declare function setWorkspace(workspace: string): void;
+export {};
+//# sourceMappingURL=wasm.d.ts.map

package/dist/src/engine/wasm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wasm.d.ts","sourceRoot":"","sources":["../../../src/engine/wasm.ts"],"names":[],"mappings":"AAQA;;;GAGG;AACH,UAAU,UAAU;IAClB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE;QAAE,MAAM,EAAE,MAAM,GAAG,UAAU,CAAA;KAAE,KAAK,IAAI,CAAC;IAC9D,gBAAgB,CAAC,EAAE,MAAM,IAAI,CAAC;IAC9B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AA6KD,wBAAsB,QAAQ,IAAI,OAAO,CAAC,UAAU,CAAC,CAqLpD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI,UAAU,CAK1C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAEpD"}