mcp-node-red 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,4 +1,54 @@
-# 1.0.0 (2025-10-08)
+# Changelog
+
+## [1.1.0](https://github.com/fx/mcp-node-red/compare/mcp-node-red-v1.0.1...mcp-node-red-v1.1.0) (2026-02-17)
+
+
+### Features
+
+* add delete_flow tool and API coverage spec ([#1](https://github.com/fx/mcp-node-red/issues/1)) ([4bccdf3](https://github.com/fx/mcp-node-red/commit/4bccdf33724bdb92b2eb60b17408942bb2eb8b29))
+* add dotenv support for .env and .env.local files ([#10](https://github.com/fx/mcp-node-red/issues/10)) ([cb23353](https://github.com/fx/mcp-node-red/commit/cb233535ca6e86c23e46617e8f9ffcdbd04fb7f0))
+* add flow state tools (get_flow_state, set_flow_state) ([#2](https://github.com/fx/mcp-node-red/issues/2)) ([cf4b108](https://github.com/fx/mcp-node-red/commit/cf4b1082bc2483ff9ebcb0f3b016a29aec35cb7a))
+* add MCP server for Node-RED workflow management ([4330d3a](https://github.com/fx/mcp-node-red/commit/4330d3a84f4341b000e12859d02da0604d0cf4bf))
+* add semantic-release for automated releases ([654965d](https://github.com/fx/mcp-node-red/commit/654965d940b859d784d753172f7f6f57a08bc18c))
+* **context:** add get_context and delete_context tools ([#3](https://github.com/fx/mcp-node-red/issues/3)) ([9da4888](https://github.com/fx/mcp-node-red/commit/9da4888f2a469d4b8f96c9794a8840a75aeb2bf9))
+* initial commit from template ([5ef23d6](https://github.com/fx/mcp-node-red/commit/5ef23d6ea3b7584c9116a1de1263e4f937e3b2c4))
+* **nodes:** add node module management tools ([#4](https://github.com/fx/mcp-node-red/issues/4)) ([bbd3376](https://github.com/fx/mcp-node-red/commit/bbd3376a115c938e9f28a63cbb29b777557e8ec7))
+* **runtime:** add get_settings and get_diagnostics tools ([#5](https://github.com/fx/mcp-node-red/issues/5)) ([e58b564](https://github.com/fx/mcp-node-red/commit/e58b5641af52aa817f6828268d537f3c682040b7))
+* **tools:** add trigger_inject and set_debug_state tools ([#6](https://github.com/fx/mcp-node-red/issues/6)) ([8b2f51a](https://github.com/fx/mcp-node-red/commit/8b2f51a409553875c6c0fe3b38f75ade81998147))
+
+
+### Bug Fixes
+
+* clean up release pipeline and npm package contents ([5869433](https://github.com/fx/mcp-node-red/commit/58694339c1d624b8c7fb2e9ce9a2fdb92472e5cf))
+* correct Node-RED API response handling for v4.1.5 ([#11](https://github.com/fx/mcp-node-red/issues/11)) ([eff418b](https://github.com/fx/mcp-node-red/commit/eff418bed18b5da754b1011e6a40a25b7d9bc950))
+* ensure dist/index.js is executable in npm package ([9d95bca](https://github.com/fx/mcp-node-red/commit/9d95bca133b17a98c81834470e45f19b20be1555))
+
+
+### Documentation
+
+* improve installation with claude mcp commands and collapse sections ([5edf6ff](https://github.com/fx/mcp-node-red/commit/5edf6ff55c0526f941b53f0e8cefb2bccfb930c4))
+* reorganize README and move dev docs to docs/ ([29d8575](https://github.com/fx/mcp-node-red/commit/29d857568368fdd1f55457bba448906076981ba3))
+* update all documentation for 17 MCP tools ([#7](https://github.com/fx/mcp-node-red/issues/7)) ([67e5c2c](https://github.com/fx/mcp-node-red/commit/67e5c2ce345c77892c793320c5617b4645c68d24))
+
+
+### Miscellaneous
+
+* add husky pre-commit hooks with lint-staged ([cbdc6f1](https://github.com/fx/mcp-node-red/commit/cbdc6f15db4dbfb5ff72f0fcd7c8e12b5a9f3064))
+* format code ([c09882f](https://github.com/fx/mcp-node-red/commit/c09882f98dce5486c8301aa62f78bc37975d0026))
+* format package.json ([424b6a9](https://github.com/fx/mcp-node-red/commit/424b6a91d2971bcc2fd0e599bd2d96b056862305))
+* **release:** 1.0.0 [skip ci] ([7d8cf9d](https://github.com/fx/mcp-node-red/commit/7d8cf9dcf2b9dc8671ad28d60a15e812a2ad3214))
+* **release:** 1.0.1 [skip ci] ([8ab070f](https://github.com/fx/mcp-node-red/commit/8ab070f2c6ac71ad799b718e4c4e07041d7ddb5c))
+* rename to mcp-node-red and add CI/CD workflows ([80ca66a](https://github.com/fx/mcp-node-red/commit/80ca66a1d818f428e1a8f5df905ad388bd34d406))
+* switch from semantic-release to release-please ([#8](https://github.com/fx/mcp-node-red/issues/8)) ([6bd24b2](https://github.com/fx/mcp-node-red/commit/6bd24b2ae3236d550daf414131fdddba4fd0df16))
+
+## [1.0.1](https://github.com/fx/mcp-node-red/compare/v1.0.0...v1.0.1) (2025-10-08)
+
+
+### Bug Fixes
+
+* ensure dist/index.js is executable in npm package ([9d95bca](https://github.com/fx/mcp-node-red/commit/9d95bca133b17a98c81834470e45f19b20be1555))
+
+## 1.0.0 (2025-10-08)
 
 
 ### Features

package/README.md

@@ -1,28 +1,70 @@
 # Node-RED MCP Server
 
-MCP server for Node-RED workflow management using stdio transport. Provides tools to get, update, and validate individual Node-RED flows through the Admin API v2.
+MCP server for Node-RED workflow management. Provides AI assistants with 17 tools to manage flows, node modules, context stores, and runtime settings through the Node-RED Admin API v2.
 
-## Features
+## Installation
 
-- **get_flows**: Retrieve all flows from Node-RED instance
-- **create_flow**: Create new flow using POST /flow
-- **update_flow**: Update specific flow by ID using PUT /flow/:id
-- **validate_flow**: Validate flow configuration without deploying
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-## Installation
+**Standalone Node-RED:**
+```bash
+claude mcp add node-red -e NODE_RED_URL=http://localhost:1880 -e NODE_RED_TOKEN=your-api-token -- npx mcp-node-red
+```
 
+**Home Assistant Add-on (Basic Auth):**
 ```bash
-npm install
-npm run build
+claude mcp add node-red -e NODE_RED_URL=http://username:password@homeassistant.local:1880 -- npx mcp-node-red
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/claude/claude_desktop_config.json` (Linux):
+
+```json
+{
+  "mcpServers": {
+    "node-red": {
+      "command": "npx",
+      "args": ["mcp-node-red"],
+      "env": {
+        "NODE_RED_URL": "http://localhost:1880",
+        "NODE_RED_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
 ```
 
+Restart Claude Desktop to load the server.
+
+</details>
+
 ## Configuration
 
-Set environment variables:
+### Environment Variables
+
+- `NODE_RED_URL` (required): Your Node-RED instance URL
+- `NODE_RED_TOKEN` (optional): API token for authentication
+
+### Environment Files
+
+The server loads environment variables from `.env` and `.env.local` files in the working directory:
 
+- `.env` -- Base defaults (tracked in version control if desired)
+- `.env.local` -- Local overrides (gitignored, never committed)
+
+Precedence (highest to lowest):
+1. Real environment variables (e.g., set via shell or MCP config)
+2. `.env.local`
+3. `.env`
+
+Copy `.env.example` as a starting template:
 ```bash
-export NODE_RED_URL=http://localhost:1880
-export NODE_RED_TOKEN=your-api-token  # Optional
+cp .env.example .env
 ```
 
 ### Node-RED Setup
@@ -41,289 +83,122 @@ adminAuth: {
 }
 ```
 
-2. Generate API token (if auth enabled):
+2. Generate API token:
 ```bash
 curl -X POST http://localhost:1880/auth/token \
   -H "Content-Type: application/json" \
   -d '{"client_id":"node-red-admin","grant_type":"password","scope":"*","username":"admin","password":"your-password"}'
 ```
 
-#### Home Assistant Add-on (hassio-addons/addon-node-red)
+#### Home Assistant Add-on
 
-When running Node-RED via Home Assistant add-on, authentication uses Home Assistant credentials with Basic Auth:
+The Home Assistant Node-RED add-on uses Basic Auth with your Home Assistant credentials:
 
 ```bash
-# Test connection with HA credentials
+# Test connection
 curl http://USERNAME:PASSWORD@homeassistant.local:1880/flows
 ```
 
 **Configuration**:
-```bash
-# Use basic auth in URL
-export NODE_RED_URL=http://admin:your-ha-password@192.168.0.232:1880
-# No NODE_RED_TOKEN needed for HA add-on
-```
-
-**Note**: Home Assistant add-on does not use `/auth/token` endpoint. API authentication is handled via HTTP Basic Auth using your Home Assistant credentials.
-
-## Clients
-
-<details>
-<summary>Claude Code</summary>
-
-Create `.mcp.json` in your project (copy from `.mcp.json.example`):
-
 ```json
 {
   "mcpServers": {
     "node-red": {
-      "command": "node",
-      "args": ["/path/to/mcp-node-red/dist/index.js"],
+      "command": "npx",
+      "args": ["mcp-node-red"],
       "env": {
-        "NODE_RED_URL": "http://localhost:1880",
-        "NODE_RED_TOKEN": "your-api-token"
+        "NODE_RED_URL": "http://admin:your-ha-password@homeassistant.local:1880"
       }
     }
   }
 }
 ```
 
-Load the config:
-```bash
-claude --mcp-config .mcp.json
-```
+Note: No `NODE_RED_TOKEN` needed - credentials are in the URL.
 
-</details>
+## Features
 
-<details>
-<summary>Claude Desktop</summary>
+### Flow Management
+- **get_flows**: Retrieve all flows from your Node-RED instance
+- **create_flow**: Create new flows via POST /flow
+- **update_flow**: Update individual flows safely via PUT /flow/:id
+- **validate_flow**: Validate flow configuration without deploying
+- **delete_flow**: Delete a flow and all its nodes by ID
 
-Add to `~/.config/claude-code/claude_desktop_config.json`:
+### Runtime Control
+- **get_flow_state**: Get runtime state of flows (started/stopped)
+- **set_flow_state**: Start or stop all flows in the runtime
 
-```json
-{
-  "mcpServers": {
-    "node-red": {
-      "command": "node",
-      "args": ["/path/to/mcp-node-red/dist/index.js"],
-      "env": {
-        "NODE_RED_URL": "http://localhost:1880",
-        "NODE_RED_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
+### Node Module Management
+- **get_nodes**: List all installed node modules with versions and status
+- **install_node**: Install a node module from the npm registry
+- **set_node_module_state**: Enable or disable an installed node module
+- **remove_node_module**: Uninstall a node module from Node-RED
 
-Or using npx:
+### Context Store
+- **get_context**: Read context data at global, flow, or node scope
+- **delete_context**: Delete context values at any scope
 
-```json
-{
-  "mcpServers": {
-    "node-red": {
-      "command": "npx",
-      "args": ["-y", "mcp-node-red"],
-      "env": {
-        "NODE_RED_URL": "http://localhost:1880",
-        "NODE_RED_TOKEN": "your-api-token"
-      }
-    }
-  }
-}
-```
+### Runtime Info
+- **get_settings**: Get Node-RED runtime settings including version
+- **get_diagnostics**: Get system diagnostics (Node.js, OS, memory)
 
-Restart Claude Desktop to apply changes.
-
-</details>
+### Node Interaction
+- **trigger_inject**: Trigger an inject node (same as clicking the button)
+- **set_debug_state**: Enable or disable a debug node's output
 
 ## Usage
 
-### Get Flows
+Once configured, ask your AI assistant natural language questions:
 
 ```
 Get all flows from my Node-RED instance
 ```
 
-Returns current flows with revision number for optimistic locking.
-
-### Create Flow
-
 ```
-Create a new flow with label "My New Flow"
+Create a new flow with label "Temperature Monitor"
 ```
 
-Creates a new flow using POST /flow endpoint. Flow ID can be provided or will be auto-generated.
-
-**Flow format**:
-```json
-{
-  "id": "optional-id",
-  "label": "My Flow",
-  "nodes": [],
-  "configs": []
-}
 ```
-
-### Update Flow
+Update flow "flow1" to change its label to "New Name"
+```
 
 ```
-Update flow "flow1" with label "New Name"
+Delete the flow with ID "flow1"
 ```
 
-Updates specific flow using PUT /flow/:id endpoint. Only affects the specified flow, leaving all other flows untouched.
-
-**Flow format**:
-```json
-{
-  "id": "flow1",
-  "label": "My Flow",
-  "nodes": [],
-  "configs": []
-}
 ```
-
-### Validate Flow
+What node modules are installed?
+```
 
 ```
-Validate this flow configuration:
-{
-  "id": "test",
-  "label": "Test Flow",
-  "nodes": []
-}
+Install the node-red-contrib-mqtt module
 ```
 
-Checks for:
-- Required fields (id, label)
-- Valid node references
-- Structural integrity
-
-## API Reference
-
-### get_flows
-
-Get all flows from Node-RED.
-
-**Input**: None
-
-**Output**:
-```json
-{
-  "rev": "abc123",
-  "flows": [...]
-}
 ```
-
-### create_flow
-
-Create a new flow using POST /flow.
-
-**Input**:
-- `flow` (string): JSON string containing flow data with format: `{id, label, nodes: [], configs: []}`
-
-**Output**:
-```json
-{
-  "id": "flow1"
-}
+Trigger the inject node to test my flow
 ```
 
-**Important**: Flow ID is optional - Node-RED will auto-generate if not provided. Returns 200 or 204 with the flow ID.
-
-### update_flow
-
-Update specific flow by ID using PUT /flow/:id.
-
-**Input**:
-- `flowId` (string): Flow ID to update
-- `updates` (string): JSON string containing flow data with format: `{id, label, nodes: [], configs: []}`
-
-**Output**:
-```json
-{
-  "id": "flow1"
-}
 ```
-
-**Important**: This endpoint updates ONLY the specified flow. All other flows remain completely untouched. No risk of destroying unrelated workflows.
-
-### validate_flow
-
-Validate flow configuration.
-
-**Input**:
-- `flow` (string): JSON string containing flow data with format: `{id, label, nodes: [], configs: []}`
-
-**Output**:
-```json
-{
-  "valid": true,
-  "errors": ["error1", "error2"]
-}
+Show me the global context data
 ```
 
-## Development
-
-```bash
-# Build
-npm run build
-
-# Watch mode
-npm run dev
-
-# Test
-npm test
-
-# Coverage
-npm run test:coverage
-
-# Lint
-npm run lint
-npm run lint:fix
-
-# Format
-npm run format
+```
+Get the Node-RED runtime settings and version
 ```
 
-## Node-RED Admin API v2
-
-The server uses Admin API v2 endpoints:
-
-### GET /flows
-- Returns all flows: `{rev: "...", flows: [...]}`
-- Headers: `Node-RED-API-Version: v2`, `Authorization`
-
-### POST /flow
-- Creates a new flow
-- Request: `{id, label, nodes: [], configs: []}`
-- Response: 200 or 204 with `{id: "..."}` in body
-- Flow ID is optional - auto-generated if not provided
-
-### PUT /flow/:id
-- Updates a single flow by ID
-- Request: `{id, label, nodes: [], configs: []}`
-- Response: 204 with `{id: "..."}` in body
-- Only affects the specified flow, all other flows remain untouched
-
-## Error Handling
+## Safety Features
 
-All tools return errors in content:
+- **Individual flow updates**: Uses PUT /flow/:id to update only the specified flow
+- **No accidental deletions**: Other flows remain completely untouched
+- **Validation**: All flow configurations are validated before sending to Node-RED
+- **Read-only by default**: Only modifies flows when explicitly requested
+- **Module management guards**: Core modules cannot be removed; enable/disable is reversible
+- **Scoped context operations**: Context reads and deletes are scoped to specific keys
 
-```json
-{
-  "content": [{
-    "type": "text",
-    "text": "Error: ..."
-  }],
-  "isError": true
-}
-```
+## Development
 
-Common errors:
-- Invalid JSON in request
-- Flow not found
-- Validation failures
-- Network/API errors
+See [docs/development.md](docs/development.md) for development setup, testing, and contribution guidelines.
 
 ## License
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { Config, NodeRedFlowsResponse, UpdateFlowRequest } from './schemas.js';
+import type { Config, FlowState, NodeModule, NodeRedDiagnostics, NodeRedFlowsResponse, NodeRedSettings, UpdateFlowRequest } from './schemas.js';
 export declare class NodeRedClient {
     private readonly baseUrl;
     private readonly token?;
@@ -12,9 +12,22 @@ export declare class NodeRedClient {
     updateFlow(flowId: string, flowData: UpdateFlowRequest): Promise<{
         id: string;
     }>;
+    deleteFlow(flowId: string): Promise<void>;
+    getFlowState(): Promise<FlowState>;
+    setFlowState(state: 'start' | 'stop'): Promise<FlowState>;
+    getSettings(): Promise<NodeRedSettings>;
+    getDiagnostics(): Promise<NodeRedDiagnostics>;
+    getContext(scope: 'global' | 'flow' | 'node', id?: string, key?: string, store?: string): Promise<unknown>;
+    deleteContext(scope: 'global' | 'flow' | 'node', id?: string, key?: string, store?: string): Promise<void>;
+    triggerInject(nodeId: string): Promise<void>;
+    setDebugNodeState(nodeId: string, enabled: boolean): Promise<void>;
     validateFlow(flowData: UpdateFlowRequest): Promise<{
         valid: boolean;
         errors?: string[];
     }>;
+    getNodes(): Promise<NodeModule[]>;
+    installNode(module: string): Promise<NodeModule>;
+    setNodeModuleState(module: string, enabled: boolean): Promise<NodeModule>;
+    removeNodeModule(module: string): Promise<void>;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGpF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,MAAM,EAAE,MAAM;IAc1B,OAAO,CAAC,UAAU;IAeZ,QAAQ,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAezC,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBhE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAiBhF,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CAyChG"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,MAAM,EACN,SAAS,EACT,UAAU,EACV,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EAClB,MAAM,cAAc,CAAC;AAStB,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAS;gBAExB,MAAM,EAAE,MAAM;IAc1B,OAAO,CAAC,UAAU;IAeZ,QAAQ,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAezC,UAAU,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAmBhE,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IAmBhF,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYzC,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAelC,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC;IAgBzD,WAAW,IAAI,OAAO,CAAC,eAAe,CAAC;IAevC,cAAc,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAe7C,UAAU,CACd,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EACjC,EAAE,CAAC,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAyBb,aAAa,CACjB,KAAK,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,EACjC,EAAE,CAAC,EAAE,MAAM,EACX,GAAG,CAAC,EAAE,MAAM,EACZ,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC;IAsBV,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAclE,YAAY,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IA0CzF,QAAQ,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;IAiBjC,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBhD,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;IAgBzE,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAWtD"}