mcp-node-red 1.0.0

package/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run lint
+
+  coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: 'npm'
+      - run: npm ci
+      - run: npm run build
+      - run: npm run test:coverage

package/.github/workflows/release.yml

@@ -0,0 +1,30 @@
+name: Release
+
+on:
+  push:
+    branches: [main]
+
+permissions:
+  contents: write
+  issues: write
+  pull-requests: write
+  id-token: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+      - run: npm run lint
+      - run: npx semantic-release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.mcp.json.example

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "node-red": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-node-red/dist/index.js"],
+      "env": {
+        "NODE_RED_URL": "http://localhost:1880"
+      }
+    }
+  }
+}

package/.releaserc.json

@@ -0,0 +1,17 @@
+{
+  "branches": ["main"],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    "@semantic-release/github",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "package-lock.json", "CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ]
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# 1.0.0 (2025-10-08)
+
+
+### Features
+
+* 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))
+* initial commit from template ([5ef23d6](https://github.com/fx/mcp-node-red/commit/5ef23d6ea3b7584c9116a1de1263e4f937e3b2c4))

package/CLAUDE.md

@@ -0,0 +1,147 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+MCP (Model Context Protocol) server that provides Node-RED workflow management capabilities via stdio transport. Exposes 4 tools for AI agents to interact with Node-RED Admin API v2: get flows, create flow, update flow, and validate flow.
+
+## Commands
+
+```bash
+# Build (required after any code changes)
+npm run build
+
+# Development with auto-rebuild
+npm run dev
+
+# Run all tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Run single test file
+npx vitest tests/client.test.ts
+
+# Lint
+npm run lint
+
+# Fix lint issues
+npm run lint:fix
+
+# Format code
+npm run format
+```
+
+## Architecture
+
+### Core Components
+
+**Server Layer** (`src/server.ts`):
+- Creates MCP server using `@modelcontextprotocol/sdk`
+- Reads config from env vars: `NODE_RED_URL` (required), `NODE_RED_TOKEN` (optional)
+- Registers 4 MCP tools with schemas (get_flows, create_flow, update_flow, validate_flow)
+- Routes tool calls to individual tool handlers
+- Catches errors and returns MCP-formatted error responses
+
+**HTTP Client** (`src/client.ts`):
+- `NodeRedClient` class wraps Node-RED Admin API v2
+- Handles two auth modes:
+  - Bearer token via `NODE_RED_TOKEN` env var
+  - Basic auth extracted from URL credentials (e.g., `http://user:pass@host:1880`)
+- Always sets `Node-RED-API-Version: v2` header
+- Uses `undici` for HTTP requests
+
+**Tools** (`src/tools/*.ts`):
+- Each tool is a standalone async function
+- Takes `NodeRedClient` instance and tool arguments
+- Returns MCP tool response format: `{ content: [{ type: 'text', text: '...' }] }`
+- `create-flow.ts` uses POST /flow to create new flows
+- `update-flow.ts` uses PUT /flow/:id to update individual flows safely
+
+**Schemas** (`src/schemas.ts`):
+- Zod schemas for validation
+- `NodeRedItemSchema` is a union of flows (type: "tab") and nodes (other types)
+- All items have `id` and `type`, flows also require `label`
+- Node references to parent flows via `z` property
+- `UpdateFlowRequestSchema` defines structure for PUT /flow/:id requests
+
+### Key Design Decisions
+
+**Stdio Transport**: Uses stdin/stdout for MCP communication, not HTTP. Server runs as child process.
+
+**API v2 with Optimistic Locking**: Uses `rev` field in responses to prevent conflicts.
+
+**Authentication Flexibility**: Supports both Bearer tokens (standalone Node-RED) and Basic auth (Home Assistant add-on).
+
+**JSON String Parameters**: MCP tool parameters receive flows as JSON strings, not objects. Tools parse and validate them.
+
+**Individual Flow Updates**: Uses PUT /flow/:id to update one flow at a time, preventing accidental destruction of other flows.
+
+## Node-RED Admin API v2
+
+**GET /flows**:
+- Returns all flows: `{rev: "...", flows: [...]}`
+
+**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
+
+## Testing
+
+Tests use vitest with mocked `undici` requests. Each component has dedicated test file:
+- `tests/client.test.ts` - HTTP client + auth modes
+- `tests/tools.test.ts` - Tool handlers
+- `tests/server.test.ts` - MCP server setup
+
+## CRITICAL: Flow Update Safety
+
+**Always use PUT /flow/:id for individual flow updates**
+
+The MCP server uses `PUT /flow/:id` which:
+- Updates ONLY the specified flow
+- Leaves all other flows completely untouched
+- No risk of destroying unrelated workflows
+- Simpler and safer than POST /flows
+
+**Flow update format**:
+```json
+{
+  "id": "flow-id",
+  "label": "Flow Name",
+  "nodes": [...],
+  "configs": [...]
+}
+```
+
+## CRITICAL: ALWAYS Use MCP Tools
+
+**NEVER bypass MCP tools to interact with Node-RED directly**
+
+- NEVER use `curl` to call Node-RED API directly
+- NEVER use Bash to make HTTP requests to Node-RED
+- ALWAYS use the MCP tools: `get_flows`, `create_flow`, `update_flow`, `validate_flow`
+
+The entire purpose of this MCP server is to provide safe, validated access to Node-RED through MCP tools. Bypassing them defeats the purpose and removes safety checks.
+
+If MCP tools appear to fail:
+1. Debug the MCP tool issue
+2. Fix the tool implementation
+3. Test the fix
+4. NEVER work around it with direct API calls
+
+## Configuration
+
+Required env var: `NODE_RED_URL`
+Optional env var: `NODE_RED_TOKEN`
+
+For Home Assistant add-on deployments, embed credentials in URL: `http://username:password@host:1880`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,330 @@
+# 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.
+
+## Features
+
+- **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
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+## Configuration
+
+Set environment variables:
+
+```bash
+export NODE_RED_URL=http://localhost:1880
+export NODE_RED_TOKEN=your-api-token  # Optional
+```
+
+### Node-RED Setup
+
+#### Standalone Node-RED
+
+1. Enable Admin API in Node-RED `settings.js`:
+```javascript
+adminAuth: {
+  type: "credentials",
+  users: [{
+    username: "admin",
+    password: "$2a$08$...",  // bcrypt hash
+    permissions: "*"
+  }]
+}
+```
+
+2. Generate API token (if auth enabled):
+```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)
+
+When running Node-RED via Home Assistant add-on, authentication uses Home Assistant credentials with Basic Auth:
+
+```bash
+# Test connection with HA credentials
+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"],
+      "env": {
+        "NODE_RED_URL": "http://localhost:1880",
+        "NODE_RED_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Load the config:
+```bash
+claude --mcp-config .mcp.json
+```
+
+</details>
+
+<details>
+<summary>Claude Desktop</summary>
+
+Add to `~/.config/claude-code/claude_desktop_config.json`:
+
+```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"
+      }
+    }
+  }
+}
+```
+
+Or using npx:
+
+```json
+{
+  "mcpServers": {
+    "node-red": {
+      "command": "npx",
+      "args": ["-y", "mcp-node-red"],
+      "env": {
+        "NODE_RED_URL": "http://localhost:1880",
+        "NODE_RED_TOKEN": "your-api-token"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop to apply changes.
+
+</details>
+
+## Usage
+
+### Get Flows
+
+```
+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"
+```
+
+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" with label "New Name"
+```
+
+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
+
+```
+Validate this flow configuration:
+{
+  "id": "test",
+  "label": "Test Flow",
+  "nodes": []
+}
+```
+
+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"
+}
+```
+
+**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"]
+}
+```
+
+## 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
+```
+
+## 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
+
+All tools return errors in content:
+
+```json
+{
+  "content": [{
+    "type": "text",
+    "text": "Error: ..."
+  }],
+  "isError": true
+}
+```
+
+Common errors:
+- Invalid JSON in request
+- Flow not found
+- Validation failures
+- Network/API errors
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,20 @@
+import type { Config, NodeRedFlowsResponse, UpdateFlowRequest } from './schemas.js';
+export declare class NodeRedClient {
+    private readonly baseUrl;
+    private readonly token?;
+    private readonly basicAuth?;
+    constructor(config: Config);
+    private getHeaders;
+    getFlows(): Promise<NodeRedFlowsResponse>;
+    createFlow(flowData: UpdateFlowRequest): Promise<{
+        id: string;
+    }>;
+    updateFlow(flowId: string, flowData: UpdateFlowRequest): Promise<{
+        id: string;
+    }>;
+    validateFlow(flowData: UpdateFlowRequest): Promise<{
+        valid: boolean;
+        errors?: string[];
+    }>;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +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"}