arduino-mcp-server 0.2.6 → 0.2.8

package/README.md

@@ -1,18 +1,37 @@
-# Arduino MCP Server
+# arduino-mcp-server
 
-Arduino MCP server for `arduino-cli` workflows: dependency checks/install, hardware detection, compile/upload, serial monitoring, and board reference lookup.
+[![npm version](https://img.shields.io/npm/v/arduino-mcp-server)](https://www.npmjs.com/package/arduino-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js 20+](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
+
+**Give your AI assistant full control over Arduino — compile, upload, monitor serial, and verify wiring safety, all through natural language.**
+
+Part of the [HardwareMCP](https://github.com/hardware-mcp) ecosystem — open-source MCP servers that bridge AI to physical hardware.
+
+---
+
+## What this does
+
+AI assistants can control Jira, GitHub, and databases. They can't talk to a microcontroller — until now.
+
+`arduino-mcp-server` wraps `arduino-cli` into an MCP server so your AI can:
+
+- **Detect** connected boards and ports automatically
+- **Compile and upload** sketches without touching the terminal
+- **Monitor serial output** with stateful sessions (open, read, expect, write, close)
+- **Run electrical safety checks** before sending commands to hardware
+- **Manage dependencies** — cores, libraries, and CLI installation
+
+---
 
 ## Quick Start
-Install globally:
 
+**Install:**
 ```bash
 npm install -g arduino-mcp-server
 ```
 
-Add to your AI agent MCP config.
-
-Claude Desktop (`claude_desktop_config.json`):
-
+**Add to Claude Desktop** (`claude_desktop_config.json`):
 ```json
 {
   "mcpServers": {
@@ -21,72 +40,81 @@ Claude Desktop (`claude_desktop_config.json`):
       "args": ["-y", "arduino-mcp-server"],
       "env": {
         "ARDUINO_CLI_PATH": "arduino-cli",
-        "ARDUINO_SKETCH_ROOT": "D:/Projects/arduino-sketches"
+        "ARDUINO_SKETCH_ROOT": "/path/to/your/sketches"
       }
     }
   }
 }
 ```
 
-Codex MCP config:
+Requires [arduino-cli](https://arduino.github.io/arduino-cli/) on your PATH, or let the server install it for you.
 
-```json
-{
-  "mcpServers": {
-    "arduino": {
-      "command": "npx",
-      "args": ["-y", "arduino-mcp-server"],
-      "env": {
-        "ARDUINO_CLI_PATH": "arduino-cli",
-        "ARDUINO_SKETCH_ROOT": "D:/Projects/arduino-sketches"
-      }
-    }
-  }
-}
-```
+---
+
+## What you can say
+
+**Bootstrap from scratch:**
+> "Check if Arduino CLI is installed and set everything up for an Arduino Uno."
+
+**Compile and upload:**
+> "Compile my Blink sketch and upload it to the Uno on COM6."
+
+**Serial monitoring:**
+> "Open serial on COM6 at 115200 and wait until the device prints READY."
+
+**Safety-first workflows:**
+> "Run a safety preflight for an Arduino Uno with 5V on pin 13 at 25mA before I send commands."
+
+---
+
+## Tools
+
+| Tool | What it does |
+|------|-------------|
+| `arduino_cli_doctor` | Check Arduino CLI installation and version |
+| `install_arduino_cli` | Guide through arduino-cli installation |
+| `detect_hardware` | Detect connected boards and infer FQBNs |
+| `list_connected_boards` | List all connected Arduino boards |
+| `list_serial_ports` | List available serial ports |
+| `ensure_core_installed` | Check/install board cores |
+| `compile_sketch` | Compile a sketch for a target board |
+| `upload_sketch` | Upload compiled sketch to a board |
+| `upload_and_wait_ready` | Upload and wait for device ready signal |
+| `serial_open_session` | Open a stateful serial session |
+| `serial_read` | Read buffered serial data |
+| `serial_expect` | Wait for a pattern in serial output |
+| `serial_write` | Send data over serial |
+| `serial_close_session` | Close a serial session |
+| `serial_list_sessions` | List active serial sessions |
+| `read_serial_snapshot` | Quick one-shot serial read |
+| `safety_preflight` | Electrical safety check before hardware ops |
+| `get_board_details` | Get pin/capability details for a board |
+| `list_supported_boards` | List all boards arduino-cli supports |
+| `list_board_reference` | Browse board pin reference |
+| `search_board_reference` | Search board reference by keyword |
 
-## Features
-- `arduino_cli_doctor` and `install_arduino_cli` for dependency bootstrap
-- `detect_hardware` with board/FQBN inference and user-confirmation guidance
-- `ensure_core_installed` with automatic core setup from FQBN
-- `compile_sketch` and `upload_sketch` with optional auto core install
-- Serial monitoring and board/port listing tools
-- Local board reference resource and setup prompts
+**Resources:**
+- `arduino://boards/reference` — structured board pin/capability reference
 
-## Requirements
-- Node.js 20+
-- `arduino-cli` available on `PATH` (or let the server install it via tools)
+**Prompts:**
+- `arduino-cli-bootstrap-policy` — policy for arduino-cli setup behavior
+- `arduino-setup-assistant` — guided Arduino environment setup
+
+---
 
 ## Configuration
-- `ARDUINO_CLI_PATH`: Arduino CLI command/path (default: `arduino-cli`)
-- `ARDUINO_SKETCH_ROOT`: optional absolute root for sketch operations
-
-## MCP Surface
-Tools:
-- `arduino_cli_doctor`
-- `install_arduino_cli`
-- `detect_hardware`
-- `ensure_core_installed`
-- `compile_sketch`
-- `upload_sketch`
-- `read_serial_snapshot`
-- `list_connected_boards`
-- `list_supported_boards`
-- `list_serial_ports`
-- `get_board_details`
-- `list_board_reference`
-- `search_board_reference`
-
-Resources:
-- `arduino://boards/reference`
-
-Prompts:
-- `arduino-cli-bootstrap-policy`
-- `arduino-setup-assistant`
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ARDUINO_CLI_PATH` | `arduino-cli` | Path to arduino-cli binary |
+| `ARDUINO_SKETCH_ROOT` | *(none)* | Restrict sketch paths to this directory |
+
+---
 
 ## Development
+
 ```bash
-git clone https://github.com/akshatnerella/arduino-mcp-server
+git clone https://github.com/hardware-mcp/arduino-mcp-server
 cd arduino-mcp-server
 npm install
 npm run typecheck
@@ -94,9 +122,18 @@ npm run build
 npm run dev
 ```
 
-## Release
-- PRs into `main` must come from `release/*` branches.
-- PRs must include exactly one bump label: `patch`, `minor`, or `major`.
+---
+
+## Part of HardwareMCP
+
+This server is part of the [HardwareMCP](https://github.com/hardware-mcp) ecosystem — a collection of MCP servers that give AI assistants real control over physical hardware.
+
+---
 
 ## License
-MIT, see [LICENSE](LICENSE).
+
+MIT — see [LICENSE](LICENSE).
+
+## Support
+
+[Open an issue](https://github.com/hardware-mcp/arduino-mcp-server/issues)

package/build/index.js

@@ -9,9 +9,11 @@ import { resolveSketchPath, runArduinoCli, runCommand, tryParseJson } from "./ar
 import { PortOperationCoordinator } from "./portCoordinator.js";
 import { SerialSessionManager } from "./serialSessions.js";
 import { runSafetyPreflight } from "./safety.js";
+const cliPathFromEnv = process.env.ARDUINO_CLI_PATH?.trim();
+const sketchRootFromEnv = process.env.ARDUINO_SKETCH_ROOT?.trim();
 const arduinoConfig = {
-    cliPath: process.env.ARDUINO_CLI_PATH ?? "arduino-cli",
-    sketchRoot: process.env.ARDUINO_SKETCH_ROOT
+    cliPath: cliPathFromEnv && cliPathFromEnv.length > 0 ? cliPathFromEnv : "arduino-cli",
+    sketchRoot: sketchRootFromEnv && sketchRootFromEnv.length > 0 ? sketchRootFromEnv : undefined
 };
 const portCoordinator = new PortOperationCoordinator();
 const serialSessionManager = new SerialSessionManager(portCoordinator);
@@ -679,8 +681,7 @@ server.registerTool("install_arduino_cli", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: true
     }
@@ -820,8 +821,7 @@ server.registerTool("ensure_core_installed", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
     }
@@ -1062,8 +1062,7 @@ server.registerTool("compile_sketch", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
     }
@@ -1174,8 +1173,7 @@ server.registerTool("upload_sketch", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
     }
@@ -1357,8 +1355,7 @@ server.registerTool("upload_and_wait_ready", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: false,
         openWorldHint: false
     }
@@ -1629,8 +1626,7 @@ server.registerTool("serial_open_session", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: false,
         openWorldHint: false
     }
@@ -1812,8 +1808,7 @@ server.registerTool("serial_write", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: false,
         openWorldHint: false
     }
@@ -1919,8 +1914,7 @@ server.registerTool("serial_close_session", {
     },
     outputSchema: toolOutputShape,
     annotations: {
-        readOnlyHint: false,
-        destructiveHint: false,
+        destructiveHint: true,
         idempotentHint: true,
         openWorldHint: false
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arduino-mcp-server",
-  "version": "0.2.6",
+  "version": "0.2.8",
   "description": "Arduino CLI wrapper MCP server",
   "type": "module",
   "main": "build/index.js",
@@ -20,22 +20,24 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",
     "start": "node build/index.js",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "mcpb:validate": "npx @anthropic-ai/mcpb validate .",
+    "mcpb:pack": "npx @anthropic-ai/mcpb pack ."
   },
   "keywords": [
     "mcp",
     "arduino",
     "arduino-cli"
   ],
-  "mcpName": "io.github.akshatnerella/arduino-mcp-server",
+  "mcpName": "io.github.hardware-mcp/arduino-mcp-server",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/akshatnerella/arduino-mcp-server.git"
+    "url": "git+https://github.com/hardware-mcp/arduino-mcp-server.git"
   },
   "bugs": {
-    "url": "https://github.com/akshatnerella/arduino-mcp-server/issues"
+    "url": "https://github.com/hardware-mcp/arduino-mcp-server/issues"
   },
-  "homepage": "https://github.com/akshatnerella/arduino-mcp-server#readme",
+  "homepage": "https://github.com/hardware-mcp/arduino-mcp-server#readme",
   "license": "MIT",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.17.4",