arduino-mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Akshat Nerella
+
+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,124 @@
+# arduino-mcp-server
+Arduino MCP server that wraps `arduino-cli` so AI agents can discover boards/ports, compile/upload sketches, read serial output, and query board pin references.
+
+## Features
+- MCP tools for:
+  - listing connected boards and serial ports
+  - detecting connected hardware with inferred FQBN and next commands
+  - checking `arduino-cli` availability with OS-specific install guidance (`arduino_cli_doctor`)
+  - auto-installing `arduino-cli` when missing (`install_arduino_cli`)
+  - ensuring required board cores are installed (`ensure_core_installed`)
+  - listing supported boards
+  - compiling sketches
+  - uploading sketches
+  - reading a serial snapshot (time-bounded monitor)
+  - fetching `arduino-cli board details`
+  - querying local board pin/reference metadata
+- Structured JSON responses so agents can reason over output
+- Optional sketch path sandboxing via `ARDUINO_SKETCH_ROOT`
+
+## Requirements
+- Node.js 20+
+- `arduino-cli` installed and available on `PATH` (or set `ARDUINO_CLI_PATH`)
+
+## Agent Workflow Contract
+Use this workflow in AI agents:
+1. Call `arduino_cli_doctor` first.
+2. If `installed=false`, call `install_arduino_cli` with `{"method":"auto"}`.
+3. If auto-install fails, use the returned OS-specific `installGuide`.
+4. Set `ARDUINO_CLI_PATH` if the binary is not on `PATH`.
+5. Re-run `arduino_cli_doctor` and continue only when `installed=true`.
+6. Only then call `detect_hardware`, `compile_sketch`, `upload_sketch`, etc.
+
+Do not attempt fallback hardware scans before `arduino-cli` is available.
+
+When `detect_hardware` returns unresolved/non-standard board matches, the tool now includes
+`requiresUserBoardConfirmation` and an `agentAction` question payload. Agents should ask the user
+to confirm board model/FQBN before continuing.
+
+`compile_sketch` and `upload_sketch` automatically ensure board core installation from FQBN by default
+(`autoInstallCore=true`), so agents should not need manual `arduino-cli core install` in normal flows.
+
+## Install Arduino CLI Quickly
+Official docs: https://docs.arduino.cc/arduino-cli/installation/
+
+- Windows (recommended): `winget install ArduinoSA.CLI`
+- macOS: `brew install arduino-cli`
+- Linux: `brew install arduino-cli` or official install script
+
+If needed, set `ARDUINO_CLI_PATH`:
+- PowerShell (current session): `$env:ARDUINO_CLI_PATH='C:\\path\\to\\arduino-cli.exe'`
+- Bash/Zsh (current session): `export ARDUINO_CLI_PATH=/absolute/path/to/arduino-cli`
+
+## Install
+```bash
+npm install
+npm run build
+```
+
+## Run
+```bash
+npm start
+```
+
+For local development:
+
+```bash
+npm run dev
+```
+
+## Environment variables
+- `ARDUINO_CLI_PATH`: path/command for Arduino CLI. Default: `arduino-cli`
+- `ARDUINO_SKETCH_ROOT`: optional absolute path. When set, `sketchPath` inputs must resolve under this root.
+
+## Example MCP client config (stdio)
+Use your built `build/index.js` as the command target.
+
+```json
+{
+  "mcpServers": {
+    "arduino": {
+      "command": "node",
+      "args": ["D:/Projects/arduino-mcp-server/build/index.js"],
+      "env": {
+        "ARDUINO_CLI_PATH": "arduino-cli",
+        "ARDUINO_SKETCH_ROOT": "D:/Projects/arduino-sketches"
+      }
+    }
+  }
+}
+```
+
+## Board Reference Data
+The server includes a starter board reference database at `data/board-reference.json` with common pin mappings.
+You can expand this file or replace it with data from an external source later.
+
+## MCP Capability Coverage
+- Tools: compile/upload/monitor/board discovery and reference lookup
+- Resource: `arduino://boards/reference` for board metadata
+- Prompts:
+  - `arduino-cli-bootstrap-policy` for dependency/bootstrap behavior
+  - `arduino-setup-assistant` for wiring/setup guidance
+
+## Publish To MCP Registry
+This repo includes a registry manifest at `server.json`.
+
+### Prerequisites
+1. Publish the npm package first (`identifier` and `version` in `server.json` must exist):
+   - `npm login`
+   - `npm run build`
+   - `npm publish --access public`
+2. Get a registry auth token (Bearer token) for `registry.modelcontextprotocol.io`.
+
+### Publish command
+PowerShell:
+
+```powershell
+$env:MCP_REGISTRY_TOKEN="<your_registry_token>"
+curl --request POST `
+  --url https://registry.modelcontextprotocol.io/v0.1/publish `
+  --header "Accept: application/json, application/problem+json" `
+  --header "Authorization: Bearer $env:MCP_REGISTRY_TOKEN" `
+  --header "Content-Type: application/json" `
+  --data-binary "@server.json"
+```

package/build/arduinoCli.js

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+export function resolveSketchPath(inputPath, sketchRoot) {
+    const resolved = path.resolve(inputPath);
+    if (!sketchRoot) {
+        return resolved;
+    }
+    const root = path.resolve(sketchRoot);
+    const normalizedResolved = process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    const normalizedRoot = process.platform === "win32" ? root.toLowerCase() : root;
+    if (normalizedResolved === normalizedRoot || normalizedResolved.startsWith(`${normalizedRoot}${path.sep}`)) {
+        return resolved;
+    }
+    throw new Error(`Path "${resolved}" is outside ARDUINO_SKETCH_ROOT "${root}".`);
+}
+export async function runArduinoCli(config, args, timeoutMs = 60_000) {
+    return runCommand(config.cliPath, args, timeoutMs);
+}
+export async function runCommand(command, args, timeoutMs = 60_000) {
+    const started = Date.now();
+    return await new Promise((resolve) => {
+        const child = spawn(command, args, {
+            stdio: ["ignore", "pipe", "pipe"]
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            const durationMs = Date.now() - started;
+            resolve({
+                ok: false,
+                command,
+                args,
+                code: null,
+                stdout,
+                stderr: `${stderr}\n${err.message}`.trim(),
+                timedOut: false,
+                durationMs
+            });
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+        }, timeoutMs);
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const durationMs = Date.now() - started;
+            resolve({
+                ok: code === 0 && !timedOut,
+                command,
+                args,
+                code,
+                stdout,
+                stderr,
+                timedOut,
+                durationMs
+            });
+        });
+    });
+}
+export function tryParseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}

package/build/boardReference.js

@@ -0,0 +1,26 @@
+import boardReferenceData from "../data/board-reference.json" with { type: "json" };
+const store = boardReferenceData;
+export function listBoardReferences() {
+    return store.boards;
+}
+export function findBoardReference(query) {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) {
+        return [];
+    }
+    return store.boards.filter((board) => {
+        if (board.id.toLowerCase().includes(normalized)) {
+            return true;
+        }
+        if (board.displayName.toLowerCase().includes(normalized)) {
+            return true;
+        }
+        if (board.aliases.some((alias) => alias.toLowerCase().includes(normalized))) {
+            return true;
+        }
+        if (board.fqbnCandidates.some((fqbn) => fqbn.toLowerCase().includes(normalized))) {
+            return true;
+        }
+        return false;
+    });
+}