arduino-mcp-server 0.2.5 → 0.2.7

package/README.md

@@ -1,17 +1,36 @@
 # Arduino MCP Server
 
-Arduino MCP server for `arduino-cli` workflows: dependency checks/install, hardware detection, compile/upload, serial monitoring, and board reference lookup.
+Arduino MCP server for `arduino-cli` workflows: dependency checks/install, hardware detection, compile/upload, serial monitoring, board reference lookup, and safety preflight checks.
 
-## Quick Start
-Install globally:
+This repository includes:
+- `server.json` for MCP Registry metadata.
+- `manifest.json` for Claude Desktop MCP bundle (`.mcpb`) packaging.
+
+## Description
+Use this server to automate Arduino setup and development tasks from an MCP client while keeping operations local to your machine.
+
+## Features
+- Arduino CLI dependency diagnosis and guided installation
+- Board/port detection with FQBN inference
+- Core installation checks and optional auto-install
+- Sketch compile/upload workflows
+- Upload-and-wait serial readiness flow
+- Stateful serial sessions (`open`, `read`, `expect`, `write`, `close`)
+- Electrical safety preflight checks
+- Board reference resource and setup prompts
+
+## Requirements
+- Node.js 20+
+- `arduino-cli` on `PATH`, or install/configure it through provided tools
+
+## Installation
+Install from npm:
 
 ```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
 {
@@ -28,38 +47,57 @@ Claude Desktop (`claude_desktop_config.json`):
 }
 ```
 
-Codex MCP config:
+## Configuration
+- `ARDUINO_CLI_PATH`: Arduino CLI command/path (default: `arduino-cli`)
+- `ARDUINO_SKETCH_ROOT`: optional absolute root restricting sketch compile/upload paths
 
-```json
-{
-  "mcpServers": {
-    "arduino": {
-      "command": "npx",
-      "args": ["-y", "arduino-mcp-server"],
-      "env": {
-        "ARDUINO_CLI_PATH": "arduino-cli",
-        "ARDUINO_SKETCH_ROOT": "D:/Projects/arduino-sketches"
-      }
-    }
-  }
-}
+## Usage Examples
+Example 1: Bootstrap missing Arduino CLI
+
+User prompt:
+```text
+Check if Arduino CLI is installed and install it automatically if missing.
 ```
 
-## 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
+Expected tool sequence:
+1. `arduino_cli_doctor`
+2. `install_arduino_cli` (when missing)
+3. `arduino_cli_doctor` (re-check)
 
-## Requirements
-- Node.js 20+
-- `arduino-cli` available on `PATH` (or let the server install it via tools)
+Example 2: Compile and upload a sketch
 
-## Configuration
-- `ARDUINO_CLI_PATH`: Arduino CLI command/path (default: `arduino-cli`)
-- `ARDUINO_SKETCH_ROOT`: optional absolute root for sketch operations
+User prompt:
+```text
+Compile D:/Projects/arduino-sketches/Blink for arduino:avr:uno and upload it to COM6.
+```
+
+Expected tool sequence:
+1. `compile_sketch` with sketch path + fqbn
+2. `upload_sketch` with sketch path + fqbn + port
+
+Example 3: Open serial monitor session and wait for ready text
+
+User prompt:
+```text
+Open serial on COM6 at 115200 and wait until the device prints READY.
+```
+
+Expected tool sequence:
+1. `serial_open_session`
+2. `serial_expect`
+3. `serial_read` (optional for additional output)
+4. `serial_close_session` (when done)
+
+Example 4: Safety preflight before writing to device
+
+User prompt:
+```text
+Before sending commands over serial, run a safety preflight for an Arduino Uno with my wiring details.
+```
+
+Expected tool sequence:
+1. `safety_preflight`
+2. `serial_write` only if preflight does not block
 
 ## MCP Surface
 Tools:
@@ -69,7 +107,15 @@ Tools:
 - `ensure_core_installed`
 - `compile_sketch`
 - `upload_sketch`
+- `upload_and_wait_ready`
 - `read_serial_snapshot`
+- `safety_preflight`
+- `serial_open_session`
+- `serial_list_sessions`
+- `serial_read`
+- `serial_expect`
+- `serial_write`
+- `serial_close_session`
 - `list_connected_boards`
 - `list_supported_boards`
 - `list_serial_ports`
@@ -84,6 +130,32 @@ Prompts:
 - `arduino-cli-bootstrap-policy`
 - `arduino-setup-assistant`
 
+## MCP Bundle (MCPB)
+Build and package:
+
+```bash
+npm run build
+npm run mcpb:validate
+npm run mcpb:pack
+```
+
+Notes:
+- `manifest.json` is consumed by `mcpb`.
+- `.mcpbignore` excludes dev/reference files from bundle packaging.
+- Bundle output is written as `<name>.mcpb` in the current directory by default.
+
+## Privacy Policy
+- Policy URL: https://github.com/akshatnerella/arduino-mcp-server/blob/main/PRIVACY.md
+- Local copy: [PRIVACY.md](PRIVACY.md)
+
+Summary:
+- No built-in telemetry or analytics.
+- Operations are local unless you explicitly invoke tooling that downloads dependencies.
+- Data handling by your MCP host application is governed by that host's policies.
+
+## Support
+- GitHub Issues: https://github.com/akshatnerella/arduino-mcp-server/issues
+
 ## Development
 ```bash
 git clone https://github.com/akshatnerella/arduino-mcp-server
@@ -99,4 +171,4 @@ npm run dev
 - PRs must include exactly one bump label: `patch`, `minor`, or `major`.
 
 ## License
-MIT, see [LICENSE](LICENSE).
+MIT, see [LICENSE](LICENSE).

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.5",
+  "version": "0.2.7",
   "description": "Arduino CLI wrapper MCP server",
   "type": "module",
   "main": "build/index.js",
@@ -20,7 +20,9 @@
     "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",