nova-control-mcp-server 0.0.1

package/LICENSE.md

@@ -0,0 +1,9 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present Andreas Rozek
+
+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,95 @@
+# nova-control-mcp-server
+
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for controlling the [NOVA DIY Artificial Intelligence Robot](https://www.creoqode.com/nova) by Creoqode. It exposes the same servo commands as [nova-control-command](../nova-control-command) as MCP tools, allowing any MCP-capable AI assistant (Claude Desktop, Cursor, …) to control the robot arm directly.
+
+## Prerequisites
+
+| requirement | details |
+|---|---|
+| Node.js | v22 or later |
+| NOVA robot | connected via USB serial port |
+| serial permissions | on Linux: `sudo usermod -aG dialout $USER` (re-login required) |
+
+## Installation
+
+```bash
+npm install
+npm run build
+```
+
+The compiled binary lands at `dist/nova-control-mcp-server.js`.
+
+## Configuration
+
+### Claude Desktop
+
+Add the server to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "nova-control": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/nova-control-mcp-server/dist/nova-control-mcp-server.js",
+        "--port", "/dev/ttyACM0",
+        "--baud", "115200"
+      ]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add the same block under `mcpServers` in `~/.cursor/mcp.json`.
+
+### Command-line options
+
+| option | short | default | description |
+|---|---|---|---|
+| `--port <path>` | `-p` | *(required)* | serial port path (e.g. `/dev/ttyACM0`, `COM3`) |
+| `--baud <rate>` | `-b` | `9600` | baud rate |
+
+## Tools
+
+The server exposes the following tools. The serial connection is opened lazily on the first tool call and kept alive for the lifetime of the server process.
+
+| tool | parameters | description |
+|---|---|---|
+| `home` | — | send all servos to their home positions |
+| `move` | `shift_to?`, `roll_to?`, `pitch_to?`, `rotate_to?`, `lift_to?` (all `number`, at least one required) | set one or more servo positions atomically |
+| `shift_to` | `deg: number` | shift head forward (>90°) or back (<90°) — s1 |
+| `roll_to` | `deg: number` | roll head clockwise (>90°) or counter-clockwise (<90°) — s2 |
+| `pitch_to` | `deg: number` | pitch head up (>110°) or down (<110°) — s3 |
+| `rotate_to` | `deg: number` | rotate body around Z-axis — s4 |
+| `lift_to` | `deg: number` | lift head on secondary axis, range 20°–150° — s5 |
+| `wait` | `ms: number` | pause for `ms` milliseconds before the next action |
+| `get_state` | — | return current servo positions as a JSON object with keys `s1`–`s5` |
+
+### Servo mapping
+
+| key | tool suffix | direction |
+|---|---|---|
+| s1 | `shift_to` | forward/back |
+| s2 | `roll_to` | clockwise/counter-clockwise |
+| s3 | `pitch_to` | up/down |
+| s4 | `rotate_to` | Z-axis rotation |
+| s5 | `lift_to` | secondary lift axis |
+
+## Usage examples
+
+Once the server is running inside Claude Desktop you can give natural-language instructions like:
+
+- *"Move NOVA's head to look straight up."* → `pitch_to(deg: 130)`
+- *"Rotate the body 45° to the left."* → `rotate_to(deg: 45)`
+- *"Shift to 100°, wait half a second, then return to home."* → `shift_to(100)` + `wait(500)` + `home()`
+- *"What is the current servo state?"* → `get_state()`
+
+## Exit behaviour
+
+The server exits cleanly on `SIGINT` (Ctrl+C) or `SIGTERM`, closing the serial connection before quitting.
+
+## License
+
+MIT

package/dist/nova-control-mcp-server.js

@@ -0,0 +1,277 @@
+#!/usr/bin/env node
+import { fileURLToPath as e } from "node:url";
+import { parseArgs as t } from "node:util";
+import { Server as n } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport as r } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema as i, ListToolsRequestSchema as a } from "@modelcontextprotocol/sdk/types.js";
+import { openNova as o } from "nova-control-node";
+//#region src/nova-control-mcp-server.ts
+function s() {
+	try {
+		let { values: e } = t({
+			args: process.argv.slice(2),
+			options: {
+				port: {
+					type: "string",
+					short: "p"
+				},
+				baud: {
+					type: "string",
+					short: "b"
+				}
+			},
+			strict: !0,
+			allowPositionals: !1
+		});
+		return e.port ?? (process.stderr.write("nova-control-mcp: --port is required\n"), process.exit(1)), {
+			Port: e.port,
+			BaudRate: Number(e.baud ?? "9600")
+		};
+	} catch (e) {
+		process.stderr.write(`nova-control-mcp: ${e.message ?? e}\n`), process.exit(1);
+	}
+}
+var c = "", l = 9600, u;
+async function d() {
+	return u ??= await o(c, l), u;
+}
+function f() {
+	u != null && (u.destroy(), u = void 0);
+}
+function p(e, t = 9600) {
+	c = e, l = t;
+}
+function m() {
+	f(), c = "", l = 9600;
+}
+var h = [
+	{
+		name: "home",
+		description: "send all servos to their home positions",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	},
+	{
+		name: "move",
+		description: "set one or more servo positions atomically — at least one of shift_to, roll_to, pitch_to, rotate_to, lift_to is required",
+		inputSchema: {
+			type: "object",
+			properties: {
+				shift_to: {
+					type: "number",
+					description: "shift head forward (>90°) or back (<90°) — s1"
+				},
+				roll_to: {
+					type: "number",
+					description: "roll head clockwise (>90°) or counter-clockwise (<90°) — s2"
+				},
+				pitch_to: {
+					type: "number",
+					description: "pitch head up (>110°) or down (<110°) — s3"
+				},
+				rotate_to: {
+					type: "number",
+					description: "rotate body around Z-axis — s4"
+				},
+				lift_to: {
+					type: "number",
+					description: "lift head on secondary axis, range 20°–150° — s5"
+				}
+			}
+		}
+	},
+	{
+		name: "shift_to",
+		description: "shift head forward (>90°) or back (<90°) — s1",
+		inputSchema: {
+			type: "object",
+			properties: { deg: {
+				type: "number",
+				description: "target angle in degrees"
+			} },
+			required: ["deg"]
+		}
+	},
+	{
+		name: "roll_to",
+		description: "roll head clockwise (>90°) or counter-clockwise (<90°) — s2",
+		inputSchema: {
+			type: "object",
+			properties: { deg: {
+				type: "number",
+				description: "target angle in degrees"
+			} },
+			required: ["deg"]
+		}
+	},
+	{
+		name: "pitch_to",
+		description: "pitch head up (>110°) or down (<110°) — s3",
+		inputSchema: {
+			type: "object",
+			properties: { deg: {
+				type: "number",
+				description: "target angle in degrees"
+			} },
+			required: ["deg"]
+		}
+	},
+	{
+		name: "rotate_to",
+		description: "rotate body around Z-axis — s4",
+		inputSchema: {
+			type: "object",
+			properties: { deg: {
+				type: "number",
+				description: "target angle in degrees"
+			} },
+			required: ["deg"]
+		}
+	},
+	{
+		name: "lift_to",
+		description: "lift head on secondary axis, range 20°–150° — s5",
+		inputSchema: {
+			type: "object",
+			properties: { deg: {
+				type: "number",
+				description: "target angle in degrees"
+			} },
+			required: ["deg"]
+		}
+	},
+	{
+		name: "wait",
+		description: "pause for a given number of milliseconds before the next action",
+		inputSchema: {
+			type: "object",
+			properties: { ms: {
+				type: "number",
+				description: "duration in milliseconds (non-negative)"
+			} },
+			required: ["ms"]
+		}
+	},
+	{
+		name: "get_state",
+		description: "return the current servo positions as a JSON object with keys s1–s5",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
+	}
+];
+async function g() {
+	return await (await d()).home(), "all servos moved to home positions";
+}
+async function _(e) {
+	let t = {};
+	if (e.shift_to != null && (t.s1 = Number(e.shift_to)), e.roll_to != null && (t.s2 = Number(e.roll_to)), e.pitch_to != null && (t.s3 = Number(e.pitch_to)), e.rotate_to != null && (t.s4 = Number(e.rotate_to)), e.lift_to != null && (t.s5 = Number(e.lift_to)), Object.keys(t).length === 0) throw Error("move: at least one of shift_to, roll_to, pitch_to, rotate_to, lift_to is required");
+	let n = await d();
+	return n.State = t, await n.sendServoState(), `servos updated: ${JSON.stringify(t)}`;
+}
+async function v(e) {
+	let t = Number(e.deg), n = await d();
+	return n.State = { s1: t }, await n.sendServoState(), `s1 (shift) → ${t}°`;
+}
+async function y(e) {
+	let t = Number(e.deg), n = await d();
+	return n.State = { s2: t }, await n.sendServoState(), `s2 (roll) → ${t}°`;
+}
+async function b(e) {
+	let t = Number(e.deg), n = await d();
+	return n.State = { s3: t }, await n.sendServoState(), `s3 (pitch) → ${t}°`;
+}
+async function x(e) {
+	let t = Number(e.deg), n = await d();
+	return n.State = { s4: t }, await n.sendServoState(), `s4 (rotate) → ${t}°`;
+}
+async function S(e) {
+	let t = Number(e.deg), n = await d();
+	return n.State = { s5: t }, await n.sendServoState(), `s5 (lift) → ${t}°`;
+}
+async function C(e) {
+	let t = Number(e.ms);
+	if (isNaN(t) || t < 0) throw Error(`wait: invalid duration '${e.ms}' — expected a non-negative number`);
+	return await new Promise((e) => setTimeout(e, t)), `waited ${t} ms`;
+}
+async function w() {
+	let e = await d();
+	return JSON.stringify(e.State);
+}
+function T() {
+	let e = new n({
+		name: "nova-control-mcp-server",
+		version: "0.0.1"
+	}, { capabilities: { tools: {} } });
+	return e.setRequestHandler(a, async () => ({ tools: h })), e.setRequestHandler(i, async (e) => {
+		let t = e.params.name, n = e.params.arguments ?? {};
+		try {
+			let e;
+			switch (t) {
+				case "home":
+					e = await g();
+					break;
+				case "move":
+					e = await _(n);
+					break;
+				case "shift_to":
+					e = await v(n);
+					break;
+				case "roll_to":
+					e = await y(n);
+					break;
+				case "pitch_to":
+					e = await b(n);
+					break;
+				case "rotate_to":
+					e = await x(n);
+					break;
+				case "lift_to":
+					e = await S(n);
+					break;
+				case "wait":
+					e = await C(n);
+					break;
+				case "get_state":
+					e = await w();
+					break;
+				default: return {
+					content: [{
+						type: "text",
+						text: `unknown tool: ${t}`
+					}],
+					isError: !0
+				};
+			}
+			return { content: [{
+				type: "text",
+				text: e
+			}] };
+		} catch (e) {
+			return {
+				content: [{
+					type: "text",
+					text: e instanceof Error ? e.message : String(e)
+				}],
+				isError: !0
+			};
+		}
+	}), e;
+}
+async function E() {
+	let { Port: e, BaudRate: t } = s();
+	c = e, l = t;
+	let n = T(), i = new r();
+	await n.connect(i);
+	for (let e of ["SIGINT", "SIGTERM"]) process.on(e, () => {
+		f(), process.exit(0);
+	});
+}
+process.argv[1] === e(import.meta.url) && E().catch((e) => {
+	process.stderr.write(`nova-control-mcp: fatal: ${e.message ?? e}\n`), process.exit(1);
+});
+//#endregion
+export { m as _destroyForTests, p as _setupForTests, T as createServer };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "nova-control-mcp-server",
+  "description": "MCP server for controlling a NOVA DIY Artificial Intelligence Robot by Creoqode",
+  "version": "0.0.1",
+  "type": "module",
+  "keywords": [
+    "nova",
+    "creoqode",
+    "robot",
+    "mcp",
+    "mcp-server"
+  ],
+  "author": "Andreas Rozek",
+  "homepage": "https://github.com/rozek/nova-control#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rozek/nova-control.git",
+    "directory": "packages/nova-control-mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/rozek/nova-control/issues"
+  },
+  "license": "MIT",
+  "bin": {
+    "nova-control-mcp": "./dist/nova-control-mcp-server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "nova-control-node": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.0",
+    "vitest": "^4.1.0"
+  },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest",
+    "test:run": "vitest run"
+  }
+}