NodeMCU Model Context Protocol Handler

An implementation of the Model Context Protocol (MCP) designed specifically for managing embedded NodeMCU (ESP8266) hardware. This utility exposes standardized interfaces—a conventional REST API, real-time WebSockets, and the MCP layer—enabling sophisticated control and interaction, particularly with cognitive assistants like Claude Desktop.

Core Functionality

This manager suite facilitates comprehensive lifecycle control over your fleet of ESP8266 microcontrollers: - Continuous supervision of device telemetry and operational state. - Transmission of control signals and operational commands across the network. - Remote modification of device operational settings and persistent storage. - Native adherence to the Model Context Protocol for AI-driven interactions.

System Visualization

System Architecture Overview

Data Flow Between Components

How Claude Desktop Interacts with NodeMCU Devices

Key Features

• 🔌 Device Orchestration: Provisioning, tracking, and commanding NodeMCU endpoints.
• 📊 Live Data Streams: Utilizes WebSockets for sub-second update latency.
• ⚙️ Remote Parameterization: Ability to push configuration changes dynamically.
• 🔄 Action Dispatch: Execute remote operations such as hard resets or firmware checks.
• 📡 Metric Acquisition: Collect and persist environmental readings and system health data.
• 🔐 Security Layer: Enforces access control via JSON Web Token (JWT) authentication.
• 🧠 Intelligent Interoperability: Full compatibility with Claude and other MCP-compliant systems.

Initial Setup Guide

Prerequisites

• Node.js (version 16.x or newer).
• Package manager: npm or yarn.
• For the target hardware: Arduino IDE configured for ESP8266 board support.

Installation Pathways

Automated Deployment via Smithery

Install the NodeMCU Manager directly for Claude Desktop integration using the Smithery CLI:

bash npx -y @smithery/cli install @amanasmuei/nodemcu-mcp --client claude

Standard npm Registry (When Published)

bash

Recommended for system-wide MCP service availability

npm install -g nodemcu-mcp

Local project inclusion

npm install nodemcu-mcp

From Source Code

bash

Clone the repository structure

git clone https://github.com/amanasmuei/nodemcu-mcp.git cd nodemcu-mcp

Install project dependencies

npm install

Optional: Install globally for immediate MCP service access

npm install -g .

Configuration Management

1. Initialize the configuration file from the template: bash cp .env.example .env

2. Customize settings within the newly created .env file: bash # Server Host Settings PORT=3000 HOST=localhost

# Security Token (Must be strong and unique) JWT_SECRET=your_strong_random_secret_key

# Operational Logging Verbosity (Levels: error, warn, info, debug) LOG_LEVEL=info

Execution Modes

Running the REST API Server

For development with automatic code reloading: bash npm run dev

For stable, production deployment: bash npm start

Launching the MCP Service Endpoint

To enable interaction with AI tooling: bash npm run mcp

If installed globally, use the command line executable: bash nodemcu-mcp --mode=mcp

Command Line Interface (CLI) Parameters

Usage: nodemcu-mcp [options]

Options: -m, --mode Operating scope (mcp, api, both) [string] [default: "both"] -p, --port Network port assignment [number] [default: 3000] -h, --help Display usage guide [boolean] --version Display software version [boolean]

MCP Interoperability Layer

This service leverages the official Model Context Protocol TypeScript SDK, enabling seamless tool invocation by Claude Desktop and other conforming clients.

Exposed MCP Tools

These functions are directly accessible via the MCP communication channel:

• list-devices: Retrieves a manifest of all registered NodeMCU units and their current operational state.
• get-device: Fetches comprehensive operational and state data for a singular identified NodeMCU unit.
• send-command: Transmits a specified command payload to the target device.
• update-config: Pushes a new configuration object to persist on the remote device.

Integration with Claude for Desktop

To enable Claude Desktop to utilize these device management tools:

1. Obtain and install Claude for Desktop from https://claude.ai/desktop.
2. Modify your Claude Desktop configuration file, typically located at ~/Library/Application Support/Claude/claude_desktop_config.json:

{ "mcpServers": { "nodemcu_manager": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/PROJECT/mcp_server_sdk.js" ] } } }

1. Relaunch the Claude for Desktop application.
2. The management tools for NodeMCU devices will now appear in Claude's available tool set.

Standalone MCP Server Execution

To isolate and run only the MCP interface:

bash npm run mcp

Alternatively, using the local CLI utility:

bash ./bin/cli.js --mode=mcp

RESTful API Endpoints Reference

Authentication Procedure

• POST /api/auth/login - Initiates session and yields a valid JWT string.

{ "username": "administrator", "password": "secure_password_123" }

Successful Response:

{ "message": "Authentication successful", "token": "your.jwt.token.string", "user": { "id": 1, "username": "administrator", "role": "admin" } }

• POST /api/auth/validate - Verifies the integrity and expiration of the provided JWT.

{ "token": "your.jwt.token.string" }

Device Management API

All subsequent device operations mandate the inclusion of a bearer token in the HTTP header:

Authorization: Bearer your.jwt.token.string

Retrieve All Devices

GET /api/devices

Response Body Sample:

{ "totalCount": 1, "devices": [ { "id": "nodemcu-unit-001", "deviceName": "Main Thermostat", "deviceType": "ESP8266", "operationalStatus": "connected", "networkAddress": "192.168.1.100", "softwareVersion": "1.0.0", "lastHeartbeat": "2023-05-15T14:30:45.123Z" } ] }

Query Specific Device Details

GET /api/devices/:id

Response Body Sample:

{ "id": "nodemcu-unit-001", "deviceName": "Main Thermostat", "deviceType": "ESP8266", "operationalStatus": "connected", "networkAddress": "192.168.1.100", "softwareVersion": "1.0.0", "lastHeartbeat": "2023-05-15T14:30:45.123Z", "currentConfiguration": { "reportingFrequencySec": 30, "enableDiagnosticLogging": false, "internalLEDControl": true }, "latestTelemetry": { "ambientTempC": 23.5, "relativeHumidity": 48.2, "cumulativeUptimeSec": 3600, "memoryUsageBytes": 35280, "signalStrengthDBm": -68 } }

Dispatch Command to Hardware

POST /api/devices/:id/command

Request Payload Example:

{ "action": "execute_reboot", "parameters": {} }

Response Body Example:

{ "statusMessage": "Command successfully queued for device processing", "actionExecuted": "execute_reboot", "arguments": {}, "deviceAcknowledgement": { "success": true, "note": "Device confirmed receipt and is commencing restart sequence" } }

WebSocket Communication Standard

The real-time data stream is accessible via a WebSocket connection established at the base URI: ws://your-server-address:3000/. Detailed message formats and event types are documented within the underlying source code or the provided examples.

NodeMCU Client Integration Guide

Consult the Arduino sketch located in the examples/ directory for a complete blueprint of a client implementation capable of communicating with this server.

Essential Client Steps

1. Install the following prerequisite libraries via the Arduino IDE Library Manager:
2. ESP8266WiFi
3. WebSocketsClient

4. ArduinoJson

5. Configure the sketch constants with your network and server particulars: cpp // Network Credentials const char WIFI_SSID = "YOUR_WIFI_NETWORK"; const char WIFI_PASS = "YOUR_PASSWORD";

// MCP Server Connection Details const char* MCP_HOST = "server.local.address"; const int MCP_PORT = 3000;

1. Compile and flash the configured sketch onto your NodeMCU board.

Development Lifecycle

Project Directory Layout

nodemcu-mcp/ ├── assets/ # Visual resources and branding ├── bin/ # Executable wrappers (CLI) ├── examples/ # Sample client firmware code ├── middleware/ # Express.js intermediate handlers ├── routes/ # Endpoint definitions ├── services/ # Core business logic modules ├── .env.example # Template for environment variables ├── index.js # Primary API server bootstrap file ├── mcp_server.js # MCP protocol implementation layer ├── mcp-manifest.json # MCP service description file └── package.json # Project metadata and scripts

Contribution Guidelines

We welcome external contributions! Please follow standard Git Flow procedures:

1. Fork the repository to your personal account.
2. Establish a new feature branch (git checkout -b feat/new-capability).
3. Commit atomic, descriptive changes (git commit -m 'feat: Added metric transformation hook').
4. Push your branch to your fork (git push origin feat/new-capability).
5. Submit a formal Pull Request against the main repository branch.

Licensing

This codebase is distributed under the highly permissive MIT License. Refer to the included LICENSE file for the full terms regarding commercial use, modification, and redistribution.

Key permissions granted by MIT: - Commercial utilization is permitted. - Internal and external modification is permitted. - Redistribution of source or binary forms is permitted.

The sole mandatory condition is the inclusion of the original copyright notice and license text in derived works.

Credits

• The specification framework provided by the Model Context Protocol.
• The versatile development platform offered by NodeMCU.
• The AI interface support provided by Anthropic's Claude Desktop.

WIKIPEDIA: Cloud computing represents an evolution where computational services, storage, and software are accessed over the network as a utility, rather than being hosted locally. The ISO standardizes this concept, defining core tenets that drive modern cloud adoption across enterprises. This model prioritizes resource abstraction and consumption metering over outright ownership of physical infrastructure.

== NIST Essential Characteristics (Refined) == Modern cloud deployments adhere to strict criteria established by standards bodies. Beyond the initial five characteristics, refinement emphasizes security and governance, though the following pillars remain central to the architecture:

• Self-Service Provisioning: Users procure resources independently without vendor mediation.
• Ubiquitous Connectivity: Services are reachable via standard protocols across diverse client devices.
• Shared Resource Pool: Infrastructure is multi-tenant, enabling efficient, dynamic allocation to numerous consumers.
• Scalability (Elasticity): Capacity scales automatically and rapidly to meet fluctuating demand, appearing virtually infinite to the user.
• Usage-Based Billing: Consumption of processing, storage, and bandwidth is meticulously tracked and reported transparently.

== Historical Trajectory ==

The foundational concepts trace back to 1960s time-sharing systems, which aimed to maximize mainframe utilization by allowing multiple users simultaneous access. This era focused on operational efficiency through centralized job processing. The visual 'cloud' shorthand for network topology emerged in telecommunications and was later applied to computing environments in the mid-1990s, notably by General Magic's Telescript, symbolizing the vast, interconnected space where abstract services reside. The term 'cloud computing' gained widespread industry recognition around 1996 through internal strategy discussions at corporations like Compaq, signalling a future where computing power would be delivered as a network utility.