labmcp-ika 0.1.0__tar.gz

labmcp_ika-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+*.jsonl
+!**/fixtures/*.jsonl
+.idea/
+.vscode/
+
+CLAUDE.md

labmcp_ika-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.5
+Name: labmcp-ika
+Version: 0.1.0
+Summary: MCP server for IKA hotplate stirrers and overhead stirrers (NAMUR commands): heat, stir, watchdog, wait for temperature.
+Project-URL: Homepage, https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/ika-stirrer
+Author: K-Dense and LabMCP contributors
+License-Expression: Apache-2.0
+Keywords: hotplate,ika,lab-instrument,magnetic-stirrer,mcp,namur,overhead-stirrer
+Requires-Python: >=3.10
+Requires-Dist: labmcp<0.2,>=0.1
+Description-Content-Type: text/markdown
+
+# IKA Hotplate & Overhead Stirrer — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-ika -->
+
+Let an AI agent heat and stir with **IKA hotplate stirrers** (C-MAG HS control, IKA Plate / RCT digital) and drive **IKA overhead stirrers** (EUROSTAR control) through IKA's documented **NAMUR** interface commands: read plate, probe and medium temperatures, speed and torque; set and start heating and stirring; wait for a temperature; and arm the hotplate's hardware watchdog so it switches itself off if the computer stops talking to it.
+
+| | |
+|---|---|
+| **Package** | `labmcp-ika` |
+| **Instruments** | Hotplate stirrers: C-MAG HS 7 control, IKA Plate (RCT digital). Overhead stirrers (`--option device=overhead`): EUROSTAR 60 control, EUROSTAR 100 control. Other IKA devices with the same NAMUR set are likely to work but are unverified |
+| **Interfaces** | RS-232 (9-pin, PC 1.1 cable), USB (virtual COM port) |
+| **Protocol** | IKA NAMUR commands, "Interfaces and outputs" section of the operating instructions: [IKA Plate (RCT digital)](https://shop.textalk.se/shop/ws72/72372/art12/156948912-a58526-20000015643_20014388a_A2_IKA_Plate_112018_web.pdf) (11/2018), [C-MAG HS 7 control](https://shop.textalk.se/shop/ws72/72372/art16/156948916-cc53a2-20000015641_20014381a_A2_C-MAG_HS_7_control_112018_web.pdf) (11/2018), [EUROSTAR 60/100 control](https://www.wolflabs.co.uk/documents/IKA_overhead-stirrers_Eurostar-60-100-control_manual.pdf) (20000003965c). Official downloads: [ika.com](https://www.ika.com/en/Products-LabEq/Magnetic-Stirrers-pg188/C-MAG-HS-7-control-20002694/Downloads-cpdl.html) |
+| **Status** | 🧪 **simulated**: tested against a wire-level NAMUR simulator, not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-ika --simulate --check
+uvx labmcp-ika --simulate --option device=overhead --check   # EUROSTAR simulator
+```
+
+## Connect your stirrer
+
+1. **Cable:** USB A–B (the stirrer appears as a virtual COM port; on Windows install IKA's USB driver, linked in the manual) or the 9-pin RS-232 PC 1.1 cable. No setting on the device is needed. The interface is fixed at **9600 baud, 7 data bits, even parity, 1 stop bit, no flow control**, and every command ends with a blank + CR LF.
+2. **Find the port:** `uvx labmcp ports`
+3. **Test the connection:**
+   ```bash
+   uvx labmcp-ika --address /dev/ttyACM0 --check                          # Linux, hotplate
+   uvx labmcp-ika --address /dev/tty.usbmodem14101 --check                # macOS
+   uvx labmcp-ika --address COM5 --check                                  # Windows
+   uvx labmcp-ika --address COM6 --option device=overhead --check         # EUROSTAR
+   ```
+   `--check` prints the name the device reports (`IN_NAME`).
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add ika -- uvx labmcp-ika --address /dev/ttyACM0 --limit max_temperature_c=120
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "ika": {
+      "command": "uvx",
+      "args": ["labmcp-ika", "--address", "/dev/ttyACM0", "--limit", "max_temperature_c=120"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow monitoring only (the stop tools stay available). For other clients: `uvx labmcp config ika-stirrer --address /dev/ttyACM0 --client vscode`.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `disable_watchdog` | 🎛 control | Cancel watchdog mode 2 (OUT_WD2@0) and stop the background refresh. Watchdog mode 1 has no cancel command; this tool reports an error for it. |
+| `enable_watchdog` | 🎛 control | Arm the hotplate's communication watchdog (OUT_WD1@m / OUT_WD2@m). The server then re-sends the watchdog command in the background; if the computer, this server or the cable fails, the hotplate switches heating and stirring off (mode 1) or falls back to the given safety values (mode 2) after `timeout_s`. Note: stopping or reconnecting the server also stops the refresh, so the watchdog trips unless you enable it again. Mode 1 cannot be cancelled over the interface. |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_status` | 👁 read | Read temperatures, stirring speed and setpoints. On hotplates: plate and external-probe temperature, temperature setpoint and the device's safety-circuit temperature. On overhead stirrers: PT1000 probe temperature, torque and the speed/torque limits set on the device. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `set_speed` | ⚠️ hazard | Set the stirring speed setpoint (OUT_SP_4). Does not start the motor; if it is already running, the speed changes immediately. Refused above `max_speed_rpm` (and, on overhead stirrers, above the speed limit set on the device). |
+| `set_temperature` | ⚠️ hazard | Set the hotplate temperature setpoint (OUT_SP_1). With an external probe connected this is the target temperature of the medium. Does not start heating; if heating is already on, the plate starts moving to the new setpoint immediately. Refused above `max_temperature_c` or above the device's own safety-circuit temperature. |
+| `start_heating` | ⚠️ hazard | Switch the hotplate heater on (START_1). It heats towards the current setpoint, which is checked against `max_temperature_c` first. Make sure the vessel and its contents can take the setpoint temperature and that nothing flammable is near the plate. |
+| `start_stirring` | ⚠️ hazard | Start the stirring motor (START_4) at the current speed setpoint, which is checked against `max_speed_rpm` first. Make sure the stir bar or impeller is in place and the vessel is secured (a decoupled stir bar or an unclamped vessel can splash). |
+| `stop_all` | 🛑 safety | Emergency stop: switch the heater off (hotplates) and stop the motor. Every stop command is sent even if one of them fails. Also ends a running `wait_for_temperature`. |
+| `stop_heating` | 🛑 safety | Switch the hotplate heater off (STOP_1). Stirring continues. The plate stays hot for a long time after switching off. |
+| `stop_stirring` | 🛑 safety | Stop the stirring motor (STOP_4). Heating (if on) continues. |
+| `wait_for_temperature` | 👁 read | Poll a temperature until it is within `tolerance_c` of the target for `stable_for_s` seconds, or until `timeout_s` passes. Does not change anything on the device (start heating first). Returns whether the target was reached plus a short temperature trace. A stop command ends the wait early. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_temperature_c` | 150 °C | Highest hotplate setpoint an agent may set (also checked before `start_heating`, and for the watchdog fallback temperature) |
+| `max_speed_rpm` | 1000 rpm | Highest stirring speed an agent may set (also checked before `start_stirring`) |
+| `max_wait_s` | 3600 s | Longest `wait_for_temperature` |
+
+Override at launch, e.g. `--limit max_temperature_c=250 --limit max_speed_rpm=1500`. On top of these, the hotplate refuses setpoints above its own safety-circuit temperature (set with the screwdriver dial on the device, read with `IN_SP_3`), and overhead stirrers refuse speeds above the speed limit set in the device menu (`IN_SP_6`); the server checks both before sending.
+
+## Example prompts
+
+- "Heat the round-bottom flask to 65 °C using the external probe, stir at 400 rpm, and tell me when it has been stable for a minute."
+- "Arm the watchdog with 60 s, then start heating to 80 °C. I'm leaving it running overnight."
+- "Log the medium temperature every 30 s while it cools down and tell me when it is below 30 °C."
+- "Ramp the EUROSTAR up to 300 rpm and report the torque; the mixture is getting viscous."
+- "Something smells wrong, stop everything now."
+
+## Notes
+
+- **Two device types.** The default is `--option device=hotplate`. Overhead stirrers need `--option device=overhead`; they have no heater, report their PT1000 probe on `IN_PV_3` and torque on `IN_PV_5`. Tools that don't apply to the configured type return a clear error and send nothing.
+- **No state query for the heater.** The NAMUR set has no "is the heater on?" command, so `get_status` reports the last start/stop *this server* sent (`heating_commanded`, `stirring_commanded`) and `None` when unknown. The front-panel buttons can change it without the server knowing.
+- **Setpoints are read back** after `set_temperature` / `set_speed` (`IN_SP_1` / `IN_SP_4`), and a `warning` is returned if the device reports a different value.
+- **Watchdog** (hotplates, `OUT_WD1@m` / `OUT_WD2@m`, 20–1500 s): `enable_watchdog` arms it and the server re-sends the command in the background every quarter of the watchdog time. If the server or the computer dies or the cable is pulled, the hotplate switches heating and stirring off (mode 1) or falls back to the safety temperature and speed (mode 2). **Stopping or reconnecting the server also stops the refresh**, so the watchdog trips. Mode 1 has no documented cancel command; mode 2 is cancelled with `OUT_WD2@0`. The manual's watchdog error codes differ between sections (ER 2 vs Err. 1/Err. 2); a trip is visible on the display, not over the interface.
+- **Unverified reply layout.** The IKA manuals document the commands but not the exact reply line. The driver takes the first number on the line (devices are reported to append the channel, e.g. `25.3 2`), so both forms work. The value reported by `IN_PV_1` when no external probe is plugged in is not documented; ignore `external_temperature_c` if you have no probe.
+- The IKA manuals print the terminator as "Blank CR LF (hex 0x20 0x0d 0x20 0x0A)"; the extra 0x20 contradicts the text ("Blank CR LF") and is treated as a typo, so the server sends `0x20 0x0D 0x0A`.
+- Not implemented: `SET_MODE_n` (changes the power-on operating mode A/B/D, a persistent setting) and `RESET`; overhead-stirrer torque/speed-limit writes (`OUT_SP_5/6/8`) and direction change (`OUT_MODE_n`).
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_ika-0.1.0/README.md

@@ -0,0 +1,109 @@
+# IKA Hotplate & Overhead Stirrer — MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-ika -->
+
+Let an AI agent heat and stir with **IKA hotplate stirrers** (C-MAG HS control, IKA Plate / RCT digital) and drive **IKA overhead stirrers** (EUROSTAR control) through IKA's documented **NAMUR** interface commands: read plate, probe and medium temperatures, speed and torque; set and start heating and stirring; wait for a temperature; and arm the hotplate's hardware watchdog so it switches itself off if the computer stops talking to it.
+
+| | |
+|---|---|
+| **Package** | `labmcp-ika` |
+| **Instruments** | Hotplate stirrers: C-MAG HS 7 control, IKA Plate (RCT digital). Overhead stirrers (`--option device=overhead`): EUROSTAR 60 control, EUROSTAR 100 control. Other IKA devices with the same NAMUR set are likely to work but are unverified |
+| **Interfaces** | RS-232 (9-pin, PC 1.1 cable), USB (virtual COM port) |
+| **Protocol** | IKA NAMUR commands, "Interfaces and outputs" section of the operating instructions: [IKA Plate (RCT digital)](https://shop.textalk.se/shop/ws72/72372/art12/156948912-a58526-20000015643_20014388a_A2_IKA_Plate_112018_web.pdf) (11/2018), [C-MAG HS 7 control](https://shop.textalk.se/shop/ws72/72372/art16/156948916-cc53a2-20000015641_20014381a_A2_C-MAG_HS_7_control_112018_web.pdf) (11/2018), [EUROSTAR 60/100 control](https://www.wolflabs.co.uk/documents/IKA_overhead-stirrers_Eurostar-60-100-control_manual.pdf) (20000003965c). Official downloads: [ika.com](https://www.ika.com/en/Products-LabEq/Magnetic-Stirrers-pg188/C-MAG-HS-7-control-20002694/Downloads-cpdl.html) |
+| **Status** | 🧪 **simulated**: tested against a wire-level NAMUR simulator, not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-ika --simulate --check
+uvx labmcp-ika --simulate --option device=overhead --check   # EUROSTAR simulator
+```
+
+## Connect your stirrer
+
+1. **Cable:** USB A–B (the stirrer appears as a virtual COM port; on Windows install IKA's USB driver, linked in the manual) or the 9-pin RS-232 PC 1.1 cable. No setting on the device is needed. The interface is fixed at **9600 baud, 7 data bits, even parity, 1 stop bit, no flow control**, and every command ends with a blank + CR LF.
+2. **Find the port:** `uvx labmcp ports`
+3. **Test the connection:**
+   ```bash
+   uvx labmcp-ika --address /dev/ttyACM0 --check                          # Linux, hotplate
+   uvx labmcp-ika --address /dev/tty.usbmodem14101 --check                # macOS
+   uvx labmcp-ika --address COM5 --check                                  # Windows
+   uvx labmcp-ika --address COM6 --option device=overhead --check         # EUROSTAR
+   ```
+   `--check` prints the name the device reports (`IN_NAME`).
+
+## Add to your MCP client
+
+**Claude Code**
+```bash
+claude mcp add ika -- uvx labmcp-ika --address /dev/ttyACM0 --limit max_temperature_c=120
+```
+
+**Claude Desktop / Cursor / Windsurf** (`claude_desktop_config.json`, `.cursor/mcp.json`, …)
+```json
+{
+  "mcpServers": {
+    "ika": {
+      "command": "uvx",
+      "args": ["labmcp-ika", "--address", "/dev/ttyACM0", "--limit", "max_temperature_c=120"]
+    }
+  }
+}
+```
+
+Add `--read-only` to allow monitoring only (the stop tools stay available). For other clients: `uvx labmcp config ika-stirrer --address /dev/ttyACM0 --client vscode`.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `disable_watchdog` | 🎛 control | Cancel watchdog mode 2 (OUT_WD2@0) and stop the background refresh. Watchdog mode 1 has no cancel command; this tool reports an error for it. |
+| `enable_watchdog` | 🎛 control | Arm the hotplate's communication watchdog (OUT_WD1@m / OUT_WD2@m). The server then re-sends the watchdog command in the background; if the computer, this server or the cable fails, the hotplate switches heating and stirring off (mode 1) or falls back to the given safety values (mode 2) after `timeout_s`. Note: stopping or reconnecting the server also stops the refresh, so the watchdog trips unless you enable it again. Mode 1 cannot be cancelled over the interface. |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_status` | 👁 read | Read temperatures, stirring speed and setpoints. On hotplates: plate and external-probe temperature, temperature setpoint and the device's safety-circuit temperature. On overhead stirrers: PT1000 probe temperature, torque and the speed/torque limits set on the device. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `set_speed` | ⚠️ hazard | Set the stirring speed setpoint (OUT_SP_4). Does not start the motor; if it is already running, the speed changes immediately. Refused above `max_speed_rpm` (and, on overhead stirrers, above the speed limit set on the device). |
+| `set_temperature` | ⚠️ hazard | Set the hotplate temperature setpoint (OUT_SP_1). With an external probe connected this is the target temperature of the medium. Does not start heating; if heating is already on, the plate starts moving to the new setpoint immediately. Refused above `max_temperature_c` or above the device's own safety-circuit temperature. |
+| `start_heating` | ⚠️ hazard | Switch the hotplate heater on (START_1). It heats towards the current setpoint, which is checked against `max_temperature_c` first. Make sure the vessel and its contents can take the setpoint temperature and that nothing flammable is near the plate. |
+| `start_stirring` | ⚠️ hazard | Start the stirring motor (START_4) at the current speed setpoint, which is checked against `max_speed_rpm` first. Make sure the stir bar or impeller is in place and the vessel is secured (a decoupled stir bar or an unclamped vessel can splash). |
+| `stop_all` | 🛑 safety | Emergency stop: switch the heater off (hotplates) and stop the motor. Every stop command is sent even if one of them fails. Also ends a running `wait_for_temperature`. |
+| `stop_heating` | 🛑 safety | Switch the hotplate heater off (STOP_1). Stirring continues. The plate stays hot for a long time after switching off. |
+| `stop_stirring` | 🛑 safety | Stop the stirring motor (STOP_4). Heating (if on) continues. |
+| `wait_for_temperature` | 👁 read | Poll a temperature until it is within `tolerance_c` of the target for `stable_for_s` seconds, or until `timeout_s` passes. Does not change anything on the device (start heating first). Returns whether the target was reached plus a short temperature trace. A stop command ends the wait early. |
+<!-- TOOLS:END -->
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_temperature_c` | 150 °C | Highest hotplate setpoint an agent may set (also checked before `start_heating`, and for the watchdog fallback temperature) |
+| `max_speed_rpm` | 1000 rpm | Highest stirring speed an agent may set (also checked before `start_stirring`) |
+| `max_wait_s` | 3600 s | Longest `wait_for_temperature` |
+
+Override at launch, e.g. `--limit max_temperature_c=250 --limit max_speed_rpm=1500`. On top of these, the hotplate refuses setpoints above its own safety-circuit temperature (set with the screwdriver dial on the device, read with `IN_SP_3`), and overhead stirrers refuse speeds above the speed limit set in the device menu (`IN_SP_6`); the server checks both before sending.
+
+## Example prompts
+
+- "Heat the round-bottom flask to 65 °C using the external probe, stir at 400 rpm, and tell me when it has been stable for a minute."
+- "Arm the watchdog with 60 s, then start heating to 80 °C. I'm leaving it running overnight."
+- "Log the medium temperature every 30 s while it cools down and tell me when it is below 30 °C."
+- "Ramp the EUROSTAR up to 300 rpm and report the torque; the mixture is getting viscous."
+- "Something smells wrong, stop everything now."
+
+## Notes
+
+- **Two device types.** The default is `--option device=hotplate`. Overhead stirrers need `--option device=overhead`; they have no heater, report their PT1000 probe on `IN_PV_3` and torque on `IN_PV_5`. Tools that don't apply to the configured type return a clear error and send nothing.
+- **No state query for the heater.** The NAMUR set has no "is the heater on?" command, so `get_status` reports the last start/stop *this server* sent (`heating_commanded`, `stirring_commanded`) and `None` when unknown. The front-panel buttons can change it without the server knowing.
+- **Setpoints are read back** after `set_temperature` / `set_speed` (`IN_SP_1` / `IN_SP_4`), and a `warning` is returned if the device reports a different value.
+- **Watchdog** (hotplates, `OUT_WD1@m` / `OUT_WD2@m`, 20–1500 s): `enable_watchdog` arms it and the server re-sends the command in the background every quarter of the watchdog time. If the server or the computer dies or the cable is pulled, the hotplate switches heating and stirring off (mode 1) or falls back to the safety temperature and speed (mode 2). **Stopping or reconnecting the server also stops the refresh**, so the watchdog trips. Mode 1 has no documented cancel command; mode 2 is cancelled with `OUT_WD2@0`. The manual's watchdog error codes differ between sections (ER 2 vs Err. 1/Err. 2); a trip is visible on the display, not over the interface.
+- **Unverified reply layout.** The IKA manuals document the commands but not the exact reply line. The driver takes the first number on the line (devices are reported to append the channel, e.g. `25.3 2`), so both forms work. The value reported by `IN_PV_1` when no external probe is plugged in is not documented; ignore `external_temperature_c` if you have no probe.
+- The IKA manuals print the terminator as "Blank CR LF (hex 0x20 0x0d 0x20 0x0A)"; the extra 0x20 contradicts the text ("Blank CR LF") and is treated as a typo, so the server sends `0x20 0x0D 0x0A`.
+- Not implemented: `SET_MODE_n` (changes the power-on operating mode A/B/D, a persistent setting) and `RESET`; overhead-stirrer torque/speed-limit writes (`OUT_SP_5/6/8`) and direction change (`OUT_MODE_n`).
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_ika-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "labmcp-ika"
+version = "0.1.0"
+description = "MCP server for IKA hotplate stirrers and overhead stirrers (NAMUR commands): heat, stir, watchdog, wait for temperature."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "K-Dense and LabMCP contributors" }]
+keywords = ["mcp", "lab-instrument", "ika", "hotplate", "magnetic-stirrer", "overhead-stirrer", "namur"]
+dependencies = ["labmcp>=0.1,<0.2"]
+
+[project.scripts]
+labmcp-ika = "labmcp_ika.server:main"
+
+[project.urls]
+Homepage = "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/ika-stirrer"
+
+[tool.labmcp]
+name = "IKA Hotplate & Overhead Stirrer"
+domain = "chemistry"
+category = "Heating & stirring"
+vendor = "IKA"
+models = ["C-MAG HS 7 control", "IKA Plate (RCT digital)", "EUROSTAR 60 control", "EUROSTAR 100 control"]
+interfaces = ["RS-232", "USB (virtual COM)"]
+protocol = "IKA NAMUR command set"
+summary = "Read plate/probe temperature and speed, set and start heating and stirring, hardware watchdog, wait for temperature, stop all."
+status = "simulated"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labmcp_ika"]

labmcp_ika-0.1.0/server.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.K-Dense-AI/labmcp-ika",
+  "title": "IKA Hotplate & Overhead Stirrer",
+  "description": "MCP server for IKA hotplate stirrers and overhead stirrers (NAMUR commands): heat, stir, watchdog, w",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/K-Dense-AI/lab-instrument-mcps",
+    "source": "github",
+    "subfolder": "servers/chemistry/ika-stirrer"
+  },
+  "websiteUrl": "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/ika-stirrer",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "labmcp-ika",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "LABMCP_ADDRESS",
+          "description": "Instrument address, e.g. serial:///dev/ttyUSB0 or tcp://192.168.1.50:5025",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_SIMULATE",
+          "description": "Set to 1 to use the built-in simulator (no hardware)",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_READ_ONLY",
+          "description": "Set to 1 to disable all state-changing tools",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_LIMITS",
+          "description": "Safety limit overrides, e.g. max_temperature_c=80",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

labmcp_ika-0.1.0/src/labmcp_ika/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for IKA hotplate stirrers and overhead stirrers (NAMUR commands)."""

labmcp_ika-0.1.0/src/labmcp_ika/driver.py

@@ -0,0 +1,310 @@
+"""IKA NAMUR driver for hotplate stirrers and overhead stirrers.
+
+Commands, serial settings and terminators were verified in the "Interfaces and outputs"
+section of these IKA operating instructions:
+
+* IKA Plate (RCT digital), 11/2018 (print code 20014388),
+  https://shop.textalk.se/shop/ws72/72372/art12/156948912-a58526-20000015643_20014388a_A2_IKA_Plate_112018_web.pdf
+* C-MAG HS 7 control, 11/2018 (print code 20014381a),
+  https://shop.textalk.se/shop/ws72/72372/art16/156948916-cc53a2-20000015641_20014381a_A2_C-MAG_HS_7_control_112018_web.pdf
+* EUROSTAR 60 control / EUROSTAR 100 control (20000003965c, 03/2018),
+  https://www.wolflabs.co.uk/documents/IKA_overhead-stirrers_Eurostar-60-100-control_manual.pdf
+
+Wire format (identical in all three manuals): 9600 baud, 7 data bits, even parity, 1 stop
+bit, no flow control. Commands are upper case, command and parameter are separated by a
+space, and every command and every response ends with "blank CR LF" (0x20 0x0D 0x0A).
+The device only transmits when asked: ``IN_*`` commands return one line, ``START_*``,
+``STOP_*`` and ``OUT_SP_n`` return nothing, and the ``@`` variants (``OUT_SP_12@n``,
+``OUT_SP_42@n``, ``OUT_WDx@m``) echo the value. The manuals do not document the exact
+layout of the reply line, so numeric replies are parsed as "first number on the line"
+(real devices are reported to append the channel number, e.g. ``25.3 2``).
+
+Channel numbers: 1 = external temperature sensor, 2 = hotplate, 3 = PT1000 probe
+(overhead stirrers), 4 = stirring speed, 5 = viscosity trend (hotplate) / torque (overhead).
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import threading
+
+from labmcp import InstrumentError, InstrumentProtocolError, Transport
+
+log = logging.getLogger("labmcp.ika")
+
+HOTPLATE = "hotplate"
+OVERHEAD = "overhead"
+DEVICE_TYPES = (HOTPLATE, OVERHEAD)
+
+#: Watchdog time range documented for OUT_WD1@m / OUT_WD2@m.
+WATCHDOG_MIN_S = 20
+WATCHDOG_MAX_S = 1500
+
+_NUMBER_RE = re.compile(r"^\s*([-+]?(?:\d+(?:\.\d*)?|\.\d+))(?:\s+\S+)*\s*$")
+
+
+class IKAStirrer:
+    """An IKA hotplate stirrer (``device_type="hotplate"``) or overhead stirrer (``"overhead"``)."""
+
+    def __init__(self, transport: Transport, device_type: str = HOTPLATE) -> None:
+        if device_type not in DEVICE_TYPES:
+            raise ValueError(f"device_type must be one of {DEVICE_TYPES}, got {device_type!r}")
+        self.t = transport
+        self.device_type = device_type
+        # The NAMUR set has no "is the heater on?" query, so remember what we commanded.
+        self.heating_commanded: bool | None = None
+        self.stirring_commanded: bool | None = None
+        #: Set by stop commands so a running wait_for_temperature loop ends early.
+        self.abort = threading.Event()
+        self._wd_mode: int | None = None
+        self._wd_time_s: int | None = None
+        self._wd_stop = threading.Event()
+        self._wd_thread: threading.Thread | None = None
+        self.watchdog_last_error: str | None = None
+
+    # ------------------------------------------------------------ low level
+
+    def query(self, cmd: str, timeout: float | None = None) -> str:
+        """Send an ``IN_*`` command and return the reply line (stripped)."""
+        with self.t.lock:
+            # The device never sends unsolicited data; anything waiting is stale.
+            self.t.flush_input()
+            reply = self.t.query(cmd, timeout).strip()
+        if not reply:
+            raise InstrumentProtocolError(f"IKA device sent an empty reply to {cmd!r}.")
+        return reply
+
+    def send(self, cmd: str) -> None:
+        """Send a command that has no reply (``OUT_SP_n x``, ``START_n``, ``STOP_n``)."""
+        self.t.write(cmd)
+
+    def query_number(self, cmd: str) -> float:
+        reply = self.query(cmd)
+        m = _NUMBER_RE.match(reply)
+        if not m:
+            raise InstrumentProtocolError(
+                f"IKA device replied {reply!r} to {cmd!r}; expected a number. Check that the "
+                f"server's device type ({self.device_type}) matches the instrument."
+            )
+        return float(m.group(1))
+
+    def _echo(self, cmd: str, expected: float) -> float:
+        """Send an ``@`` command and check the echoed value."""
+        value = self.query_number(cmd)
+        if abs(value - expected) > 0.5:
+            raise InstrumentProtocolError(
+                f"IKA device echoed {value:g} to {cmd!r}; expected {expected:g}. The value may be "
+                "outside the range the device accepts."
+            )
+        return value
+
+    def _require(self, device_type: str, what: str) -> None:
+        if self.device_type != device_type:
+            raise InstrumentProtocolError(
+                f"{what} is only available on IKA {device_type} devices, but this server is "
+                f"configured for a {self.device_type} (start it with --option device={device_type} "
+                "if that is wrong)."
+            )
+
+    @staticmethod
+    def _fmt(value: float) -> str:
+        return f"{round(value, 1):g}"
+
+    # ------------------------------------------------------------ identity
+
+    def identify(self) -> dict[str, str]:
+        info = {"manufacturer": "IKA", "device_type": self.device_type}
+        try:
+            info["model"] = self.query("IN_NAME")
+        except InstrumentError as exc:
+            info["model"] = f"unknown ({exc})"
+        return info
+
+    # ------------------------------------------------------------ stirring (both types)
+
+    def speed_rpm(self) -> float:
+        return self.query_number("IN_PV_4")
+
+    def speed_setpoint_rpm(self) -> float:
+        return self.query_number("IN_SP_4")
+
+    def set_speed(self, rpm: float) -> None:
+        self.send(f"OUT_SP_4 {int(round(rpm))}")
+
+    def start_motor(self) -> None:
+        self.abort.clear()
+        self.send("START_4")
+        self.stirring_commanded = True
+
+    def stop_motor(self) -> None:
+        self.abort.set()
+        self.send("STOP_4")
+        self.stirring_commanded = False
+
+    # ------------------------------------------------------------ hotplate
+
+    def external_temperature_c(self) -> float:
+        """``IN_PV_1``: external temperature sensor (e.g. PT 1000 / ETS-D in the medium)."""
+        self._require(HOTPLATE, "The external sensor reading IN_PV_1")
+        return self.query_number("IN_PV_1")
+
+    def hotplate_temperature_c(self) -> float:
+        """``IN_PV_2``: hotplate sensor."""
+        self._require(HOTPLATE, "Hotplate temperature")
+        return self.query_number("IN_PV_2")
+
+    def viscosity_trend(self) -> float:
+        """``IN_PV_5``: viscosity trend value (hotplates; relative, no unit)."""
+        self._require(HOTPLATE, "The viscosity trend")
+        return self.query_number("IN_PV_5")
+
+    def temperature_setpoint_c(self) -> float:
+        self._require(HOTPLATE, "The temperature setpoint")
+        return self.query_number("IN_SP_1")
+
+    def safety_temperature_c(self) -> float:
+        """``IN_SP_3``: the safety-circuit temperature set on the device (screwdriver dial)."""
+        self._require(HOTPLATE, "The safety temperature")
+        return self.query_number("IN_SP_3")
+
+    def set_temperature(self, celsius: float) -> None:
+        self._require(HOTPLATE, "Setting a temperature")
+        self.send(f"OUT_SP_1 {self._fmt(celsius)}")
+
+    def start_heater(self) -> None:
+        self._require(HOTPLATE, "Heating")
+        self.abort.clear()
+        self.send("START_1")
+        self.heating_commanded = True
+
+    def stop_heater(self) -> None:
+        self._require(HOTPLATE, "Heating")
+        self.abort.set()
+        self.send("STOP_1")
+        self.heating_commanded = False
+
+    # ------------------------------------------------------------ overhead stirrer
+
+    def probe_temperature_c(self) -> float:
+        """``IN_PV_3``: PT1000 probe of an overhead stirrer."""
+        self._require(OVERHEAD, "The PT1000 probe reading IN_PV_3")
+        return self.query_number("IN_PV_3")
+
+    def torque(self) -> float:
+        """``IN_PV_5``: current torque value (overhead stirrers, Ncm as on the display)."""
+        self._require(OVERHEAD, "Torque")
+        return self.query_number("IN_PV_5")
+
+    def torque_limit(self) -> float:
+        self._require(OVERHEAD, "The torque limit")
+        return self.query_number("IN_SP_5")
+
+    def speed_limit_rpm(self) -> float:
+        self._require(OVERHEAD, "The speed limit")
+        return self.query_number("IN_SP_6")
+
+    def safety_speed_rpm(self) -> float:
+        self._require(OVERHEAD, "The safety speed")
+        return self.query_number("IN_SP_8")
+
+    # ------------------------------------------------------------ stop
+
+    def stop_all(self) -> list[str]:
+        """Stop heating (hotplates) and stirring. Sends every stop even if one fails."""
+        self.abort.set()
+        errors: list[str] = []
+        stops = [self.stop_heater, self.stop_motor] if self.device_type == HOTPLATE else [self.stop_motor]
+        for stop in stops:
+            try:
+                stop()
+            except InstrumentError as exc:
+                errors.append(str(exc))
+        return errors
+
+    # ------------------------------------------------------------ watchdog (hotplates)
+
+    def set_watchdog_safety_values(self, temperature_c: float, speed_rpm: float) -> None:
+        """``OUT_SP_12@n`` / ``OUT_SP_42@n``: values watchdog mode 2 falls back to."""
+        self._require(HOTPLATE, "The watchdog")
+        self._echo(f"OUT_SP_12@{self._fmt(temperature_c)}", temperature_c)
+        self._echo(f"OUT_SP_42@{int(round(speed_rpm))}", round(speed_rpm))
+
+    def enable_watchdog(self, mode: int, timeout_s: int, keepalive_interval_s: float | None = None) -> None:
+        """Arm watchdog mode 1 (heater and motor off) or 2 (fall back to the WD safety values)
+        and keep it alive from a background thread by re-sending ``OUT_WDx@m``.
+
+        If this process dies, the cable is pulled or :meth:`close` is called, the device
+        is no longer refreshed and trips after ``timeout_s`` seconds.
+        """
+        self._require(HOTPLATE, "The watchdog")
+        if mode not in (1, 2):
+            raise ValueError("watchdog mode must be 1 or 2")
+        if not WATCHDOG_MIN_S <= timeout_s <= WATCHDOG_MAX_S:
+            raise ValueError(f"watchdog time must be {WATCHDOG_MIN_S}-{WATCHDOG_MAX_S} s")
+        if self._wd_mode is not None and self._wd_mode != mode:
+            raise InstrumentProtocolError(
+                f"Watchdog mode {self._wd_mode} is already active; the manual documents no way to "
+                "switch modes without it tripping."
+            )
+        self._stop_keepalive()
+        self._echo(f"OUT_WD{mode}@{timeout_s}", timeout_s)
+        self._wd_mode, self._wd_time_s = mode, timeout_s
+        self.watchdog_last_error = None
+        interval = keepalive_interval_s if keepalive_interval_s is not None else max(1.0, timeout_s / 4)
+        self._wd_stop.clear()
+        self._wd_thread = threading.Thread(
+            target=self._keepalive, args=(interval,), name="ika-watchdog", daemon=True
+        )
+        self._wd_thread.start()
+
+    def _keepalive(self, interval: float) -> None:
+        while not self._wd_stop.wait(interval):
+            self.watchdog_tick()
+
+    def watchdog_tick(self) -> None:
+        """Re-send the watchdog command once (called by the keep-alive thread)."""
+        mode, time_s = self._wd_mode, self._wd_time_s
+        if mode is None or time_s is None:
+            return
+        try:
+            self._echo(f"OUT_WD{mode}@{time_s}", time_s)
+            self.watchdog_last_error = None
+        except InstrumentError as exc:  # keep trying; the device trips if we never get through
+            self.watchdog_last_error = str(exc)
+            log.warning("IKA watchdog refresh failed: %s", exc)
+
+    def disable_watchdog(self) -> None:
+        """Cancel watchdog mode 2 with ``OUT_WD2@0``. Mode 1 has no documented cancel command."""
+        self._require(HOTPLATE, "The watchdog")
+        if self._wd_mode is None:
+            return
+        if self._wd_mode == 1:
+            raise InstrumentProtocolError(
+                "Watchdog mode 1 cannot be cancelled over the interface (the IKA manual documents "
+                "no command for it). It stays armed while this server runs; stopping the server "
+                "makes it trip, switching heating and stirring off."
+            )
+        self._stop_keepalive()
+        self.query_number("OUT_WD2@0")
+        self._wd_mode = self._wd_time_s = None
+
+    def watchdog_state(self) -> dict[str, object]:
+        return {
+            "mode": self._wd_mode,
+            "timeout_s": self._wd_time_s,
+            "keepalive_running": bool(self._wd_thread and self._wd_thread.is_alive()),
+            "last_error": self.watchdog_last_error,
+        }
+
+    def _stop_keepalive(self) -> None:
+        self._wd_stop.set()
+        thread, self._wd_thread = self._wd_thread, None
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(timeout=5)
+
+    def close(self) -> None:
+        # Deliberately does NOT cancel the watchdog: if it is armed, the device switches
+        # itself off after the watchdog time, which is the fail-safe we want.
+        self._stop_keepalive()
+        self.t.close()