nova-control-mcp-server 0.0.3 → 0.0.5

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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/README.md) as MCP tools, allowing any MCP-capable AI assistant (Claude Desktop, Cursor, …) to control the robot arm directly.
 
 ## Prerequisites
 
@@ -67,6 +67,49 @@ Add the same block under `mcpServers` in `~/.cursor/mcp.json`.
 |---|---|---|---|
 | `--port <path>` | `-p` | *(required)* | serial port path (e.g. `/dev/ttyACM0`, `COM3`) |
 | `--baud <rate>` | `-b` | `9600` | baud rate |
+| `--transport <mode>` | `-t` | `stdio` | transport: `stdio` or `http` |
+| `--listen <port>` | `-l` | `3000` | HTTP listen port (only used when `--transport http`) |
+
+## HTTP transport (Docker / remote)
+
+Use `--transport http` to expose the MCP server over HTTP instead of stdio. This is the recommended mode when the server runs in a Docker container or on a remote machine.
+
+The server listens on the given port and accepts MCP requests at `POST /mcp`.
+
+```bash
+nova-control-mcp-server --port /dev/ttyACM0 --transport http --listen 3000
+```
+
+### Docker example
+
+```dockerfile
+FROM node:22-slim
+RUN npm install -g nova-control-mcp-server
+EXPOSE 3000
+CMD ["nova-control-mcp-server", "--port", "/dev/ttyACM0", \
+     "--transport", "http", "--listen", "3000"]
+```
+
+Run the container with the serial device passed through:
+
+```bash
+docker run --device /dev/ttyACM0 -p 3000:3000 nova-mcp
+```
+
+### Connecting an MCP client to the HTTP transport
+
+Point your MCP client at `http://<host>:3000/mcp`. For Claude Desktop with a remote server, use the `url` transport type:
+
+```json
+{
+  "mcpServers": {
+    "nova-control": {
+      "type": "http",
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
 
 ## Tools
 
@@ -76,6 +119,7 @@ The server exposes the following tools. The serial connection is opened lazily o
 |---|---|---|
 | `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 |
+| `move_to` | `within_ms: number` (required), `s1?`, `s2?`, `s3?`, `s4?`, `s5?` (all optional `number`) | move one or more servos to target positions in exactly `within_ms` milliseconds, using a trapezoidal ramp-up/ramp-down profile |
 | `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 |
@@ -83,6 +127,7 @@ The server exposes the following tools. The serial connection is opened lazily o
 | `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` |
+| `run_script` | `script: string` | execute a multi-line movement script (one command per line; blank lines and `#`-comments ignored; commands: `home`, `shift-to`, `roll-to`, `pitch-to`, `rotate-to`, `lift-to`, `move`, `wait`) |
 
 ### Servo mapping
 
@@ -99,14 +144,24 @@ The server exposes the following tools. The serial connection is opened lazily o
 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)`
+- *"Rotate the body 45° to the right."* → `rotate_to(deg: 45)`
+- *"Move the head to 120° over 800 ms."* → `move_to(within_ms: 800, s1: 120)`
 - *"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()`
+- *"Run the greeting sequence from this script."* → `run_script(script: "home\nwait 500\nshift-to 110\nwait 400\nhome")`
 
 ## Exit behaviour
 
 The server exits cleanly on `SIGINT` (Ctrl+C) or `SIGTERM`, closing the serial connection before quitting.
 
+## Related packages
+
+| package | description |
+|---|---|
+| [`nova-control-browser`](../nova-control-browser/README.md) | browser ESM module — Web Serial API (Chrome / Edge 89+) |
+| [`nova-control-node`](../nova-control-node/README.md) | Node.js ESM module — `serialport` package (used internally by this server) |
+| [`nova-control-command`](../nova-control-command/README.md) | CLI — one-shot commands, interactive REPL, and script files |
+
 ## License
 
 MIT

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

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import { fileURLToPath as e } from "node:url";
 import { realpathSync as t } from "node:fs";
-import { parseArgs as n } from "node:util";
-import { Server as r } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport as i } from "@modelcontextprotocol/sdk/server/stdio.js";
-import { CallToolRequestSchema as a, ListToolsRequestSchema as o } from "@modelcontextprotocol/sdk/types.js";
-import { openNova as s } from "nova-control-node";
+import { createServer as n } from "node:http";
+import { parseArgs as r } from "node:util";
+import { Server as i } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport as a } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StreamableHTTPServerTransport as o } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { CallToolRequestSchema as s, ListToolsRequestSchema as c } from "@modelcontextprotocol/sdk/types.js";
+import { openNova as l, runScript as u } from "nova-control-node";
 //#region src/nova-control-mcp-server.ts
-function c() {
+function d() {
 	try {
-		let { values: e } = n({
+		let { values: e } = r({
 			args: process.argv.slice(2),
 			options: {
 				port: {
@@ -19,33 +21,45 @@ function c() {
 				baud: {
 					type: "string",
 					short: "b"
+				},
+				transport: {
+					type: "string",
+					short: "t"
+				},
+				listen: {
+					type: "string",
+					short: "l"
 				}
 			},
 			strict: !0,
 			allowPositionals: !1
 		});
-		return e.port ?? (process.stderr.write("nova-control-mcp: --port is required\n"), process.exit(1)), {
+		e.port ?? (process.stderr.write("nova-control-mcp: --port is required\n"), process.exit(1));
+		let t = e.transport ?? "stdio";
+		return t !== "stdio" && t !== "http" && (process.stderr.write(`nova-control-mcp: --transport must be 'stdio' or 'http', got '${t}'\n`), process.exit(1)), {
 			Port: e.port,
-			BaudRate: Number(e.baud ?? "9600")
+			BaudRate: Number(e.baud ?? "9600"),
+			Transport: t,
+			ListenPort: Number(e.listen ?? "3000")
 		};
 	} catch (e) {
 		process.stderr.write(`nova-control-mcp: ${e.message ?? e}\n`), process.exit(1);
 	}
 }
-var l = "", u = 9600, d;
-async function f() {
-	return d ??= await s(l, u), d;
+var f = "", p = 9600, m;
+async function h() {
+	return m ??= await l(f, p), m;
 }
-function p() {
-	d != null && (d.destroy(), d = void 0);
+function g() {
+	m != null && (m.destroy(), m = void 0);
 }
-function m(e, t = 9600) {
-	l = e, u = t;
+function _(e, t = 9600) {
+	f = e, p = t;
 }
-function h() {
-	p(), l = "", u = 9600;
+function v() {
+	g(), f = "", p = 9600;
 }
-var g = [
+var y = [
 	{
 		name: "home",
 		description: "send all servos to their home positions",
@@ -88,11 +102,11 @@ var g = [
 		description: "shift head forward (>90°) or back (<90°) — s1",
 		inputSchema: {
 			type: "object",
-			properties: { deg: {
+			properties: { angle: {
 				type: "number",
 				description: "target angle in degrees"
 			} },
-			required: ["deg"]
+			required: ["angle"]
 		}
 	},
 	{
@@ -100,11 +114,11 @@ var g = [
 		description: "roll head clockwise (>90°) or counter-clockwise (<90°) — s2",
 		inputSchema: {
 			type: "object",
-			properties: { deg: {
+			properties: { angle: {
 				type: "number",
 				description: "target angle in degrees"
 			} },
-			required: ["deg"]
+			required: ["angle"]
 		}
 	},
 	{
@@ -112,11 +126,11 @@ var g = [
 		description: "pitch head up (>110°) or down (<110°) — s3",
 		inputSchema: {
 			type: "object",
-			properties: { deg: {
+			properties: { angle: {
 				type: "number",
 				description: "target angle in degrees"
 			} },
-			required: ["deg"]
+			required: ["angle"]
 		}
 	},
 	{
@@ -124,11 +138,11 @@ var g = [
 		description: "rotate body around Z-axis — s4",
 		inputSchema: {
 			type: "object",
-			properties: { deg: {
+			properties: { angle: {
 				type: "number",
 				description: "target angle in degrees"
 			} },
-			required: ["deg"]
+			required: ["angle"]
 		}
 	},
 	{
@@ -136,11 +150,45 @@ var g = [
 		description: "lift head on secondary axis, range 20°–150° — s5",
 		inputSchema: {
 			type: "object",
-			properties: { deg: {
+			properties: { angle: {
 				type: "number",
 				description: "target angle in degrees"
 			} },
-			required: ["deg"]
+			required: ["angle"]
+		}
+	},
+	{
+		name: "move_to",
+		description: "move one or more servos smoothly to their target positions, completing the movement in the specified number of milliseconds using a trapezoidal ramp-up/ramp-down profile",
+		inputSchema: {
+			type: "object",
+			properties: {
+				within_ms: {
+					type: "number",
+					description: "total movement duration in milliseconds (must be > 0)"
+				},
+				s1: {
+					type: "number",
+					description: "head shift target angle (optional)"
+				},
+				s2: {
+					type: "number",
+					description: "head roll target angle (optional)"
+				},
+				s3: {
+					type: "number",
+					description: "head pitch target angle (optional)"
+				},
+				s4: {
+					type: "number",
+					description: "body rotate target angle (optional)"
+				},
+				s5: {
+					type: "number",
+					description: "head lift target angle (optional)"
+				}
+			},
+			required: ["within_ms"]
 		}
 	},
 	{
@@ -162,82 +210,111 @@ var g = [
 			type: "object",
 			properties: {}
 		}
+	},
+	{
+		name: "run_script",
+		description: "execute a multi-line movement script — one command per line; blank lines and lines starting with # are ignored; commands: home | shift-to <deg> | roll-to <deg> | pitch-to <deg> | rotate-to <deg> | lift-to <deg> | move [shift-to <deg>] [roll-to <deg>] [pitch-to <deg>] [rotate-to <deg>] [lift-to <deg>] | wait <ms>",
+		inputSchema: {
+			type: "object",
+			properties: { script: {
+				type: "string",
+				description: "multi-line movement script"
+			} },
+			required: ["script"]
+		}
 	}
 ];
-async function _() {
-	return await (await f()).home(), "all servos moved to home positions";
+async function b() {
+	return await (await h()).home(), "all servos moved to home positions";
 }
-async function v(e) {
+async function x(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 f();
+	let n = await h();
 	return n.State = t, await n.sendServoState(), `servos updated: ${JSON.stringify(t)}`;
 }
-async function y(e) {
-	let t = Number(e.deg), n = await f();
+async function S(e) {
+	let t = Number(e.angle), n = await h();
 	return n.State = { s1: t }, await n.sendServoState(), `s1 (shift) → ${t}°`;
 }
-async function b(e) {
-	let t = Number(e.deg), n = await f();
+async function C(e) {
+	let t = Number(e.angle), n = await h();
 	return n.State = { s2: t }, await n.sendServoState(), `s2 (roll) → ${t}°`;
 }
-async function x(e) {
-	let t = Number(e.deg), n = await f();
+async function w(e) {
+	let t = Number(e.angle), n = await h();
 	return n.State = { s3: t }, await n.sendServoState(), `s3 (pitch) → ${t}°`;
 }
-async function S(e) {
-	let t = Number(e.deg), n = await f();
+async function T(e) {
+	let t = Number(e.angle), n = await h();
 	return n.State = { s4: t }, await n.sendServoState(), `s4 (rotate) → ${t}°`;
 }
-async function C(e) {
-	let t = Number(e.deg), n = await f();
+async function E(e) {
+	let t = Number(e.angle), n = await h();
 	return n.State = { s5: t }, await n.sendServoState(), `s5 (lift) → ${t}°`;
 }
-async function w(e) {
+async function D(e) {
+	let t = Number(e.within_ms);
+	if (isNaN(t) || t <= 0) throw Error("move_to: within_ms must be a positive number");
+	let n = {};
+	if (e.s1 != null && (n.s1 = Number(e.s1)), e.s2 != null && (n.s2 = Number(e.s2)), e.s3 != null && (n.s3 = Number(e.s3)), e.s4 != null && (n.s4 = Number(e.s4)), e.s5 != null && (n.s5 = Number(e.s5)), Object.keys(n).length === 0) throw Error("move_to: at least one servo target (s1–s5) must be specified");
+	return await (await h()).moveTo(n, t), "move completed";
+}
+async function O(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 T() {
-	let e = await f();
+async function k() {
+	let e = await h();
 	return JSON.stringify(e.State);
 }
-function E() {
-	let e = new r({
+async function A(e) {
+	let t = String(e.script ?? "");
+	return await u(await h(), t), "script executed successfully";
+}
+function j() {
+	let e = new i({
 		name: "nova-control-mcp-server",
-		version: "0.0.1"
+		version: "0.0.5"
 	}, { capabilities: { tools: {} } });
-	return e.setRequestHandler(o, async () => ({ tools: g })), e.setRequestHandler(a, async (e) => {
+	return e.setRequestHandler(c, async () => ({ tools: y })), e.setRequestHandler(s, async (e) => {
 		let t = e.params.name, n = e.params.arguments ?? {};
 		try {
 			let e;
 			switch (t) {
 				case "home":
-					e = await _();
+					e = await b();
 					break;
 				case "move":
-					e = await v(n);
+					e = await x(n);
 					break;
 				case "shift_to":
-					e = await y(n);
+					e = await S(n);
 					break;
 				case "roll_to":
-					e = await b(n);
+					e = await C(n);
 					break;
 				case "pitch_to":
-					e = await x(n);
+					e = await w(n);
 					break;
 				case "rotate_to":
-					e = await S(n);
+					e = await T(n);
 					break;
 				case "lift_to":
-					e = await C(n);
+					e = await E(n);
+					break;
+				case "move_to":
+					e = await D(n);
 					break;
 				case "wait":
-					e = await w(n);
+					e = await O(n);
 					break;
 				case "get_state":
-					e = await T();
+					e = await k();
+					break;
+				case "run_script":
+					e = await A(n);
 					break;
 				default: return {
 					content: [{
@@ -262,17 +339,36 @@ function E() {
 		}
 	}), e;
 }
-async function D() {
-	let { Port: e, BaudRate: t } = c();
-	l = e, u = t;
-	let n = E(), r = new i();
-	await n.connect(r);
+async function M(e) {
+	let t = new a();
+	await e.connect(t);
 	for (let e of ["SIGINT", "SIGTERM"]) process.on(e, () => {
-		p(), process.exit(0);
+		g(), process.exit(0);
+	});
+}
+async function N(e, t) {
+	let r = new o({ sessionIdGenerator: void 0 });
+	await e.connect(r);
+	let i = n(async (e, t) => {
+		e.url === "/mcp" ? await r.handleRequest(e, t) : (t.writeHead(404, { "Content-Type": "text/plain" }), t.end("not found"));
 	});
+	await new Promise((e, n) => {
+		i.listen(t, () => {
+			process.stderr.write(`nova-control-mcp: HTTP transport listening on port ${t} — POST /mcp\n`), e();
+		}), i.once("error", n);
+	});
+	for (let e of ["SIGINT", "SIGTERM"]) process.on(e, async () => {
+		await r.close(), i.close(), g(), process.exit(0);
+	});
+}
+async function P() {
+	let { Port: e, BaudRate: t, Transport: n, ListenPort: r } = d();
+	f = e, p = t;
+	let i = j();
+	n === "http" ? await N(i, r) : await M(i);
 }
-t(process.argv[1]) === e(import.meta.url) && D().catch((e) => {
+t(process.argv[1]) === e(import.meta.url) && P().catch((e) => {
 	process.stderr.write(`nova-control-mcp: fatal: ${e.message ?? e}\n`), process.exit(1);
 });
 //#endregion
-export { h as _destroyForTests, m as _setupForTests, E as createServer };
+export { v as _destroyForTests, _ as _setupForTests, j as createServer };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nova-control-mcp-server",
   "description": "MCP server for controlling a NOVA DIY Artificial Intelligence Robot by Creoqode",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "keywords": [
     "nova",