nova-control-mcp-server 0.0.5 → 0.0.6

package/README.md

@@ -113,21 +113,24 @@ Point your MCP client at `http://<host>:3000/mcp`. For Claude Desktop with a rem
 
 ## 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.
+The server exposes the following tools. The serial connection is opened lazily on the first tool call; call `disconnect` to free the port, or let the server exit cleanly.
+
+All movement tools accept an optional `within_ms` parameter. When provided, the robot moves smoothly to the target using a trapezoidal velocity profile (ramp-up → constant speed → ramp-down) over the given number of milliseconds. Without `within_ms`, the servos move at constant maximum speed.
 
 | 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 |
-| `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 |
-| `rotate_to` | `deg: number` | rotate body around Z-axis — s4 |
-| `lift_to` | `deg: number` | lift head on secondary axis, range 20°–150° — s5 |
+| `home` | `within_ms?` | send all servos to their home positions |
+| `move` | `shift_to?`, `roll_to?`, `pitch_to?`, `rotate_to?`, `lift_to?` (at least one required); `within_ms?` | set one or more servo positions atomically |
+| `move_to` | `within_ms: number` (required, must be > 0); `s1?`, `s2?`, `s3?`, `s4?`, `s5?` | move one or more servos smoothly to target positions using a trapezoidal ramp-up/ramp-down profile |
+| `shift_to` | `angle: number`; `within_ms?` | shift head forward (>90°) or back (<90°) — s1 |
+| `roll_to` | `angle: number`; `within_ms?` | roll head clockwise (>90°) or counter-clockwise (<90°) — s2 |
+| `pitch_to` | `angle: number`; `within_ms?` | pitch head up (>110°) or down (<110°) — s3 |
+| `rotate_to` | `angle: number`; `within_ms?` | rotate body around Z-axis — s4 |
+| `lift_to` | `angle: number`; `within_ms?` | 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`) |
+| `disconnect` | — | close the serial connection to free the port; the connection reopens automatically on the next movement command |
 
 ### Servo mapping
 
@@ -143,12 +146,13 @@ 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 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()`
+- *"Move NOVA's head to look straight up."* → `pitch_to(angle: 130)`
+- *"Rotate the body 45° to the right."* → `rotate_to(angle: 45)`
+- *"Move the head to 120° smoothly over 800 ms."* → `move_to(within_ms: 800, s1: 120)`
+- *"Shift to 100° with a fluid ramp, wait half a second, then return to home."* → `shift_to(angle: 100, within_ms: 600)` + `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")`
+- *"Free the serial port."* → `disconnect()`
 
 ## Exit behaviour
 

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

@@ -62,18 +62,25 @@ function v() {
 var y = [
 	{
 		name: "home",
-		description: "send all servos to their home positions",
+		description: "send all servos to their home positions — pass within_ms for smooth, fluid motion with automatic velocity ramp-up and ramp-down; without within_ms the robot moves at constant maximum speed",
 		inputSchema: {
 			type: "object",
-			properties: {}
+			properties: { within_ms: {
+				type: "number",
+				description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down — servos glide gradually to the target instead of jumping; omit for constant-speed movement"
+			} }
 		}
 	},
 	{
 		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",
+		description: "set one or more servo positions atomically — at least one of shift_to, roll_to, pitch_to, rotate_to, lift_to is required; pass within_ms for smooth, fluid motion with automatic velocity ramp-up and ramp-down",
 		inputSchema: {
 			type: "object",
 			properties: {
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down — servos glide gradually to their targets instead of jumping; omit for constant-speed movement"
+				},
 				shift_to: {
 					type: "number",
 					description: "shift head forward (>90°) or back (<90°) — s1"
@@ -99,61 +106,91 @@ var y = [
 	},
 	{
 		name: "shift_to",
-		description: "shift head forward (>90°) or back (<90°) — s1",
+		description: "shift head forward (>90°) or back (<90°) — s1; pass within_ms for smooth motion with trapezoidal velocity profile (ramp-up → constant speed → ramp-down)",
 		inputSchema: {
 			type: "object",
-			properties: { angle: {
-				type: "number",
-				description: "target angle in degrees"
-			} },
+			properties: {
+				angle: {
+					type: "number",
+					description: "target angle in degrees"
+				},
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down; omit for constant-speed movement"
+				}
+			},
 			required: ["angle"]
 		}
 	},
 	{
 		name: "roll_to",
-		description: "roll head clockwise (>90°) or counter-clockwise (<90°) — s2",
+		description: "roll head clockwise (>90°) or counter-clockwise (<90°) — s2; pass within_ms for smooth motion with trapezoidal velocity profile",
 		inputSchema: {
 			type: "object",
-			properties: { angle: {
-				type: "number",
-				description: "target angle in degrees"
-			} },
+			properties: {
+				angle: {
+					type: "number",
+					description: "target angle in degrees"
+				},
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down; omit for constant-speed movement"
+				}
+			},
 			required: ["angle"]
 		}
 	},
 	{
 		name: "pitch_to",
-		description: "pitch head up (>110°) or down (<110°) — s3",
+		description: "pitch head up (>110°) or down (<110°) — s3; pass within_ms for smooth motion with trapezoidal velocity profile",
 		inputSchema: {
 			type: "object",
-			properties: { angle: {
-				type: "number",
-				description: "target angle in degrees"
-			} },
+			properties: {
+				angle: {
+					type: "number",
+					description: "target angle in degrees"
+				},
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down; omit for constant-speed movement"
+				}
+			},
 			required: ["angle"]
 		}
 	},
 	{
 		name: "rotate_to",
-		description: "rotate body around Z-axis — s4",
+		description: "rotate body around Z-axis — s4; pass within_ms for smooth motion with trapezoidal velocity profile",
 		inputSchema: {
 			type: "object",
-			properties: { angle: {
-				type: "number",
-				description: "target angle in degrees"
-			} },
+			properties: {
+				angle: {
+					type: "number",
+					description: "target angle in degrees"
+				},
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down; omit for constant-speed movement"
+				}
+			},
 			required: ["angle"]
 		}
 	},
 	{
 		name: "lift_to",
-		description: "lift head on secondary axis, range 20°–150° — s5",
+		description: "lift head on secondary axis, range 20°–150° — s5; pass within_ms for smooth motion with trapezoidal velocity profile",
 		inputSchema: {
 			type: "object",
-			properties: { angle: {
-				type: "number",
-				description: "target angle in degrees"
-			} },
+			properties: {
+				angle: {
+					type: "number",
+					description: "target angle in degrees"
+				},
+				within_ms: {
+					type: "number",
+					description: "duration in milliseconds for smooth motion with trapezoidal ramp-up and ramp-down; omit for constant-speed movement"
+				}
+			},
 			required: ["angle"]
 		}
 	},
@@ -213,7 +250,7 @@ var y = [
 	},
 	{
 		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>",
+		description: "execute a multi-line movement script — one command per line; blank lines and lines starting with # are ignored; commands: home | shift-to <angle> | roll-to <angle> | pitch-to <angle> | rotate-to <angle> | lift-to <angle> | move [shift-to <angle>] [roll-to <angle>] [pitch-to <angle>] [rotate-to <angle>] [lift-to <angle>] | wait <ms>",
 		inputSchema: {
 			type: "object",
 			properties: { script: {
@@ -222,61 +259,73 @@ var y = [
 			} },
 			required: ["script"]
 		}
+	},
+	{
+		name: "disconnect",
+		description: "close the serial connection to the robot — call this when you are done to free the serial port; the connection reopens automatically on the first subsequent movement command",
+		inputSchema: {
+			type: "object",
+			properties: {}
+		}
 	}
 ];
-async function b() {
-	return await (await h()).home(), "all servos moved to home positions";
+async function b(e) {
+	let t = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).home(t), "all servos moved to home positions";
 }
 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 h();
-	return n.State = t, await n.sendServoState(), `servos updated: ${JSON.stringify(t)}`;
+	let n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).moveTo(t, n), `servos updated: ${JSON.stringify(t)}`;
 }
 async function S(e) {
-	let t = Number(e.angle), n = await h();
-	return n.State = { s1: t }, await n.sendServoState(), `s1 (shift) → ${t}°`;
+	let t = Number(e.angle), n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).shiftHeadTo(t, n), `s1 (shift) → ${t}°`;
 }
 async function C(e) {
-	let t = Number(e.angle), n = await h();
-	return n.State = { s2: t }, await n.sendServoState(), `s2 (roll) → ${t}°`;
+	let t = Number(e.angle), n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).rollHeadTo(t, n), `s2 (roll) → ${t}°`;
 }
 async function w(e) {
-	let t = Number(e.angle), n = await h();
-	return n.State = { s3: t }, await n.sendServoState(), `s3 (pitch) → ${t}°`;
+	let t = Number(e.angle), n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).pitchHeadTo(t, n), `s3 (pitch) → ${t}°`;
 }
 async function T(e) {
-	let t = Number(e.angle), n = await h();
-	return n.State = { s4: t }, await n.sendServoState(), `s4 (rotate) → ${t}°`;
+	let t = Number(e.angle), n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).rotateBodyTo(t, n), `s4 (rotate) → ${t}°`;
 }
 async function E(e) {
-	let t = Number(e.angle), n = await h();
-	return n.State = { s5: t }, await n.sendServoState(), `s5 (lift) → ${t}°`;
+	let t = Number(e.angle), n = e.within_ms == null ? void 0 : Number(e.within_ms);
+	return await (await h()).liftHeadTo(t, n), `s5 (lift) → ${t}°`;
+}
+async function D() {
+	return m == null ? "not connected" : (g(), "disconnected");
 }
-async function D(e) {
+async function O(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) {
+async function k(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 k() {
+async function A() {
 	let e = await h();
 	return JSON.stringify(e.State);
 }
-async function A(e) {
+async function j(e) {
 	let t = String(e.script ?? "");
 	return await u(await h(), t), "script executed successfully";
 }
-function j() {
+function M() {
 	let e = new i({
 		name: "nova-control-mcp-server",
-		version: "0.0.5"
+		version: "0.0.6"
 	}, { capabilities: { tools: {} } });
 	return e.setRequestHandler(c, async () => ({ tools: y })), e.setRequestHandler(s, async (e) => {
 		let t = e.params.name, n = e.params.arguments ?? {};
@@ -284,7 +333,7 @@ function j() {
 			let e;
 			switch (t) {
 				case "home":
-					e = await b();
+					e = await b(n);
 					break;
 				case "move":
 					e = await x(n);
@@ -305,16 +354,19 @@ function j() {
 					e = await E(n);
 					break;
 				case "move_to":
-					e = await D(n);
+					e = await O(n);
 					break;
 				case "wait":
-					e = await O(n);
+					e = await k(n);
 					break;
 				case "get_state":
-					e = await k();
+					e = await A();
 					break;
 				case "run_script":
-					e = await A(n);
+					e = await j(n);
+					break;
+				case "disconnect":
+					e = await D();
 					break;
 				default: return {
 					content: [{
@@ -339,14 +391,14 @@ function j() {
 		}
 	}), e;
 }
-async function M(e) {
+async function N(e) {
 	let t = new a();
 	await e.connect(t);
 	for (let e of ["SIGINT", "SIGTERM"]) process.on(e, () => {
 		g(), process.exit(0);
 	});
 }
-async function N(e, t) {
+async function P(e, t) {
 	let r = new o({ sessionIdGenerator: void 0 });
 	await e.connect(r);
 	let i = n(async (e, t) => {
@@ -361,14 +413,14 @@ async function N(e, t) {
 		await r.close(), i.close(), g(), process.exit(0);
 	});
 }
-async function P() {
+async function F() {
 	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);
+	let i = M();
+	n === "http" ? await P(i, r) : await N(i);
 }
-t(process.argv[1]) === e(import.meta.url) && P().catch((e) => {
+t(process.argv[1]) === e(import.meta.url) && F().catch((e) => {
 	process.stderr.write(`nova-control-mcp: fatal: ${e.message ?? e}\n`), process.exit(1);
 });
 //#endregion
-export { v as _destroyForTests, _ as _setupForTests, j as createServer };
+export { v as _destroyForTests, _ as _setupForTests, M 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.5",
+  "version": "0.0.6",
   "type": "module",
   "keywords": [
     "nova",