technic-hub-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- technic_hub_mcp-0.1.0/.gitignore +6 -0
- technic_hub_mcp-0.1.0/LICENSE +21 -0
- technic_hub_mcp-0.1.0/PKG-INFO +271 -0
- technic_hub_mcp-0.1.0/README.md +243 -0
- technic_hub_mcp-0.1.0/pyproject.toml +49 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/__init__.py +3 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/__main__.py +4 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/hub.py +981 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/models.py +176 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/protocol.py +835 -0
- technic_hub_mcp-0.1.0/src/technic_hub_mcp/server.py +412 -0
- technic_hub_mcp-0.1.0/tests/test_hub.py +458 -0
- technic_hub_mcp-0.1.0/tests/test_protocol.py +156 -0
- technic_hub_mcp-0.1.0/tests/test_server.py +194 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Gustavo Pabon
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,271 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: technic-hub-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server that lets AI assistants read and control a LEGO Technic Hub and its motors over Bluetooth.
|
|
5
|
+
Project-URL: Homepage, https://github.com/gustavo-pabon/mhs-pilot/tree/main/technic-hub-mcp
|
|
6
|
+
Project-URL: Source, https://github.com/gustavo-pabon/mhs-pilot
|
|
7
|
+
Project-URL: Issues, https://github.com/gustavo-pabon/mhs-pilot/issues
|
|
8
|
+
Author: Gustavo Pabon
|
|
9
|
+
License-Expression: MIT
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Keywords: ble,bluetooth,lego,lwp3,mcp,model-context-protocol,motor,powered-up,technic
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Operating System :: MacOS
|
|
15
|
+
Classifier: Operating System :: Microsoft :: Windows
|
|
16
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
17
|
+
Classifier: Programming Language :: Python :: 3
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
22
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
23
|
+
Classifier: Topic :: System :: Hardware
|
|
24
|
+
Requires-Python: >=3.10
|
|
25
|
+
Requires-Dist: bleak>=3.0
|
|
26
|
+
Requires-Dist: mcp>=2.3
|
|
27
|
+
Description-Content-Type: text/markdown
|
|
28
|
+
|
|
29
|
+
# LEGO Technic Hub MCP server
|
|
30
|
+
|
|
31
|
+
An [MCP](https://modelcontextprotocol.io) server that lets AI assistants read and control a LEGO Technic Hub (88012)
|
|
32
|
+
over Bluetooth LE: the motors and sensors on its four ports, its built-in sensors and its light. It implements LEGO's
|
|
33
|
+
[Wireless Protocol 3.0](https://lego.github.io/lego-ble-wireless-protocol-docs/) (LWP3), with tools for the hub's
|
|
34
|
+
properties, alerts and actions, the devices on its ports and their modes, and the port output commands.
|
|
35
|
+
|
|
36
|
+
## Requirements
|
|
37
|
+
|
|
38
|
+
- Python 3.10 or later.
|
|
39
|
+
- A computer with Bluetooth LE: macOS, Linux (BlueZ) or Windows 10 or later, through
|
|
40
|
+
[bleak](https://github.com/hbldh/bleak).
|
|
41
|
+
- The hub with LEGO's own firmware. Pybricks firmware replaces LWP3, so this server can't talk to a hub that runs it.
|
|
42
|
+
- The hub switched on and not connected to another app or device: it accepts one connection at a time. Press its
|
|
43
|
+
button: the light flashes white while the hub waits for a connection and turns solid blue once connected. A hub that
|
|
44
|
+
nothing connects to switches itself off after a short while.
|
|
45
|
+
|
|
46
|
+
On macOS, the app that starts the server (VS Code, Claude, Terminal…) needs Bluetooth access: **System Settings →
|
|
47
|
+
Privacy & Security → Bluetooth**.
|
|
48
|
+
|
|
49
|
+
## Installation
|
|
50
|
+
|
|
51
|
+
Install it from [PyPI](https://pypi.org/project/technic-hub-mcp/) into a virtual environment:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
python3 -m venv .venv
|
|
55
|
+
.venv/bin/pip install technic-hub-mcp
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
This installs the `technic-hub-mcp` command in `.venv/bin/`. It runs the server over stdio. With
|
|
59
|
+
[uv](https://docs.astral.sh/uv/), `uvx technic-hub-mcp` runs it without installing it first.
|
|
60
|
+
|
|
61
|
+
## Configuration
|
|
62
|
+
|
|
63
|
+
Add the command to your MCP client, using its absolute path. With uv, use `"command": "uvx"` and
|
|
64
|
+
`"args": ["technic-hub-mcp"]` instead.
|
|
65
|
+
|
|
66
|
+
VS Code (`.vscode/mcp.json`):
|
|
67
|
+
|
|
68
|
+
```json
|
|
69
|
+
{
|
|
70
|
+
"servers": {
|
|
71
|
+
"technic-hub": {
|
|
72
|
+
"type": "stdio",
|
|
73
|
+
"command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
|
|
74
|
+
}
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Claude Desktop (`claude_desktop_config.json`):
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"mcpServers": {
|
|
84
|
+
"technic-hub": {
|
|
85
|
+
"command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Options, passed in `args`:
|
|
92
|
+
|
|
93
|
+
| Option | Default | Description |
|
|
94
|
+
| --- | --- | --- |
|
|
95
|
+
| `--address ADDRESS` | First Technic Hub found | Bluetooth address of the hub (a UUID on macOS). Use it when several hubs are nearby. |
|
|
96
|
+
| `--timeout SECONDS` | `10` | How long to search for and connect to the hub. |
|
|
97
|
+
|
|
98
|
+
The server looks for a hub that advertises the LWP3 service as a Technic Hub, and connects on the first tool call. If
|
|
99
|
+
the connection drops, for example because the hub switched itself off, the next tool call reconnects once the hub is
|
|
100
|
+
on again. When the server stops, it brakes the motors and disconnects.
|
|
101
|
+
|
|
102
|
+
To try the server without an AI client, open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
npx @modelcontextprotocol/inspector .venv/bin/technic-hub-mcp
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Tools
|
|
109
|
+
|
|
110
|
+
Tools take ports as a letter, `A` to `D`, a synchronized pair such as `AB` (see `connect_virtual_port`), or a port
|
|
111
|
+
number. The hub's built-in devices only have numbers; on the hub this was tested with, they are 50 (light),
|
|
112
|
+
59 (current), 60 (voltage), 61 and 96 (temperature), 97 (accelerometer), 98 (gyro), 99 (tilt) and 100 (gesture).
|
|
113
|
+
`list_ports` shows them all.
|
|
114
|
+
|
|
115
|
+
The hub:
|
|
116
|
+
|
|
117
|
+
| Tool | Protocol message | Notes |
|
|
118
|
+
| --- | --- | --- |
|
|
119
|
+
| `get_hub_info` | Hub Properties (`0x01`) | Name, firmware and hardware versions, battery, signal, MAC addresses and the other properties, and what the hub advertised |
|
|
120
|
+
| `get_hub_alerts` | Hub Alerts (`0x03`) | Low voltage, high current, low signal strength and over-power condition |
|
|
121
|
+
| `set_hub_name(name)` | Hub Properties: Set | 1–14 printable ASCII characters. The hub keeps the name and advertises it |
|
|
122
|
+
| `reset_hub_name` | Hub Properties: Reset | Restores the default name |
|
|
123
|
+
| `set_busy_indication(enabled)` | Hub Actions `0x05`, `0x06` | Shows or clears the busy indication on the light |
|
|
124
|
+
| `set_port_vcc(enabled)` | Hub Actions `0x03`, `0x04` | Switches the supply voltage of the ports |
|
|
125
|
+
| `disconnect_hub` | Hub Actions `0x02` | The next tool call reconnects while the hub is still on |
|
|
126
|
+
| `switch_off_hub` | Hub Actions `0x01` | Destructive: the hub must then be switched on by hand |
|
|
127
|
+
|
|
128
|
+
Ports and sensors:
|
|
129
|
+
|
|
130
|
+
| Tool | Protocol messages | Returns |
|
|
131
|
+
| --- | --- | --- |
|
|
132
|
+
| `list_ports` | Hub Attached I/O (`0x04`) | Every port with a device: connector, built-in or virtual pair, device type and revisions |
|
|
133
|
+
| `get_port_info(port)` | Port Information (`0x21`, `0x43`), Port Mode Information (`0x22`, `0x44`) | The device's capabilities and, per mode: name, raw, percent and SI ranges, unit, mappings and value format |
|
|
134
|
+
| `read_port_value(port, mode)` | Port Input Format Setup (`0x41`), Port Value (`0x21`, `0x45`) | The values of one mode, by number or name such as `POS`, scaled to the mode's SI unit |
|
|
135
|
+
| `get_hub_sensors` | As above | Voltage, current, temperatures, accelerometer, gyro, tilt and gesture, each in its first mode |
|
|
136
|
+
| `get_motor_state(port)` | As above | Speed, encoder position, absolute position and load |
|
|
137
|
+
| `connect_virtual_port(first_port, second_port)` | Virtual Port Setup (`0x61`) | The new pair, such as `AB`, for synchronized motor commands |
|
|
138
|
+
| `disconnect_virtual_port(port)` | Virtual Port Setup (`0x61`) | |
|
|
139
|
+
|
|
140
|
+
Motors (Port Output Command, `0x81`). On a pair, the `second_*` parameters give the second motor its own power,
|
|
141
|
+
speed or position; without them, both motors get the same value.
|
|
142
|
+
|
|
143
|
+
| Tool | Sub-commands | Notes |
|
|
144
|
+
| --- | --- | --- |
|
|
145
|
+
| `motor_start_power(port, power, second_power)` | StartPower (WriteDirectModeData mode 0), `0x02` | Unregulated, until another command |
|
|
146
|
+
| `motor_start_speed(port, speed, ...)` | StartSpeed `0x07`, `0x08` | Regulated, until another command; speed 0 holds the position |
|
|
147
|
+
| `motor_run_for_time(port, time_ms, speed, ...)` | StartSpeedForTime `0x09`, `0x0A` | Up to 32,767 ms |
|
|
148
|
+
| `motor_run_for_degrees(port, degrees, speed, ...)` | StartSpeedForDegrees `0x0B`, `0x0C` | The sign of speed sets the direction |
|
|
149
|
+
| `motor_go_to_position(port, position, speed, ...)` | GotoAbsolutePosition `0x0D`, `0x0E` | Encoder degrees |
|
|
150
|
+
| `motor_stop(port, end_state)` | StartPower brake or float, StartSpeed 0 to hold | Replaces the current command |
|
|
151
|
+
| `motor_set_acceleration_time(port, time_ms)` | SetAccTime `0x05` | Ramp for commands with `profile` `acceleration` or `both` |
|
|
152
|
+
| `motor_set_deceleration_time(port, time_ms)` | SetDecTime `0x06` | Ramp for commands with `profile` `deceleration` or `both` |
|
|
153
|
+
| `motor_preset_encoder(port, position, second_position)` | PresetEncoder (WriteDirectModeData mode 2), `0x14` | Stops the motor |
|
|
154
|
+
|
|
155
|
+
The run, turn and go-to tools also take `max_power` (0–100 %, to limit torque), `end_state` (`brake`, `float` or
|
|
156
|
+
`hold`), `profile` and `wait`. Speeds and powers are percentages from −100 to 100.
|
|
157
|
+
|
|
158
|
+
The light and the tilt sensor:
|
|
159
|
+
|
|
160
|
+
| Tool | Command | Notes |
|
|
161
|
+
| --- | --- | --- |
|
|
162
|
+
| `set_led_color(color)` | SetRgbColorNo | `off`, `pink`, `purple`, `blue`, `light_blue`, `cyan`, `green`, `yellow`, `orange`, `red` or `white` |
|
|
163
|
+
| `set_led_rgb(red, green, blue)` | SetRgbColors | 0–255 each |
|
|
164
|
+
| `preset_tilt_impact_count(count)` | TiltImpactPreset | Sets the counter of bumps the hub has detected |
|
|
165
|
+
| `configure_tilt_impact(threshold, holdoff_ms)` | TiltConfigImpact | How hard a bump must be to count, and the minimum time between two |
|
|
166
|
+
|
|
167
|
+
## How moves end
|
|
168
|
+
|
|
169
|
+
`motor_run_for_time`, `motor_run_for_degrees` and `motor_go_to_position` wait until the motors stop, unless `wait` is
|
|
170
|
+
false, and return the outcome with each motor's encoder positions before and after:
|
|
171
|
+
|
|
172
|
+
- `completed`: the move ended as asked.
|
|
173
|
+
- `interrupted`: another command replaced it, such as `motor_stop`.
|
|
174
|
+
- `stalled`: a motor stopped turning (less than 2° in 1 s) before the end, so the server braked it. A motor that is
|
|
175
|
+
slowed but still turning is not stalled. A mechanism driven against a stop on purpose, to find its zero, ends this
|
|
176
|
+
way.
|
|
177
|
+
- `started`: `wait` was false.
|
|
178
|
+
|
|
179
|
+
The hub reports when most commands finish, but this one (firmware 1.0.00.0000) doesn't for timed runs or for the
|
|
180
|
+
degree moves of a pair. For those, the server takes the move as completed once its time is up, or once every motor is
|
|
181
|
+
within 5° of its target.
|
|
182
|
+
|
|
183
|
+
## Good to know
|
|
184
|
+
|
|
185
|
+
- Values are read on request: `read_port_value` and the other readers put the device in the mode they need, then ask
|
|
186
|
+
for its value. They scale the device's raw values to its SI unit with the ranges the device reports.
|
|
187
|
+
- After a move that ends holding its position, the hub sometimes ignores the next command without replying. If the
|
|
188
|
+
hub doesn't acknowledge a motor command within 0.5 s, the server sends it once more.
|
|
189
|
+
- For a pair, `motor_go_to_position` with `second_position` didn't do what the protocol describes on the hub this was
|
|
190
|
+
tested with: the second motor moved by the first motor's distance instead of to its own target. Position motors one
|
|
191
|
+
at a time when exact positions matter.
|
|
192
|
+
- Some hub properties may be missing from `get_hub_info`: the tested hub doesn't report its hardware network family.
|
|
193
|
+
- Tool annotations mark the reading tools as read-only and `switch_off_hub` as destructive, so clients can ask before
|
|
194
|
+
running it.
|
|
195
|
+
- Tested on a Technic Hub with firmware 1.0.00.0000 and four Technic Large Motors (88013), from macOS: every reading
|
|
196
|
+
tool; `set_led_color`, `set_led_rgb` and `set_busy_indication`; `disconnect_hub`, with the reconnection that
|
|
197
|
+
follows, and `switch_off_hub`; and all the motor tools on single motors, plus pairs with `connect_virtual_port`,
|
|
198
|
+
`disconnect_virtual_port`, `motor_run_for_degrees`, `motor_run_for_time` and `motor_go_to_position`. Not tried on a
|
|
199
|
+
hub yet: `set_hub_name`, `reset_hub_name`, `set_port_vcc`, `preset_tilt_impact_count`, `configure_tilt_impact`,
|
|
200
|
+
`motor_stop` with `hold`, and the `second_power`, `second_speed` and `second_position` values of
|
|
201
|
+
`motor_start_power`, `motor_start_speed` and `motor_preset_encoder`.
|
|
202
|
+
|
|
203
|
+
## Not covered
|
|
204
|
+
|
|
205
|
+
These parts of the protocol are left out on purpose:
|
|
206
|
+
|
|
207
|
+
- Firmware update and memory lock (`0x10`–`0x13`), and the production-only fast shutdown (Hub Actions `0x2F`): they can
|
|
208
|
+
leave the hub unusable.
|
|
209
|
+
- Raw WriteDirect (`0x50`), which carries the hardware reset and the tilt sensor's factory calibration: they can
|
|
210
|
+
de-calibrate a device.
|
|
211
|
+
- Hardware network commands (`0x08`) and setting the hardware network ID and family: they are for hubs connected to
|
|
212
|
+
each other without a computer.
|
|
213
|
+
- Value notifications and combined-mode sensor streams (`0x42`, `0x46`, `0x48`): the tools read values on request
|
|
214
|
+
instead.
|
|
215
|
+
- Queued commands: every output command runs immediately, replacing the port's current command.
|
|
216
|
+
|
|
217
|
+
## Python library
|
|
218
|
+
|
|
219
|
+
The protocol and Bluetooth layers also work without MCP:
|
|
220
|
+
|
|
221
|
+
```python
|
|
222
|
+
import asyncio
|
|
223
|
+
|
|
224
|
+
from technic_hub_mcp import protocol
|
|
225
|
+
from technic_hub_mcp.hub import TechnicHub
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
async def main() -> None:
|
|
229
|
+
hub = TechnicHub()
|
|
230
|
+
try:
|
|
231
|
+
motor = await hub.port_id("A")
|
|
232
|
+
result = await hub.move(protocol.start_speed_for_degrees(motor, 90, 30))
|
|
233
|
+
print(result.outcome, result.motors[0].end_position)
|
|
234
|
+
finally:
|
|
235
|
+
await hub.disconnect()
|
|
236
|
+
|
|
237
|
+
|
|
238
|
+
asyncio.run(main())
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
- [`protocol`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/protocol.py):
|
|
242
|
+
builds and decodes LWP3 messages. No Bluetooth.
|
|
243
|
+
- [`hub`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/hub.py):
|
|
244
|
+
`TechnicHub` finds, connects to and reconnects to the hub, matches replies to requests and follows motor commands.
|
|
245
|
+
- [`models`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/models.py):
|
|
246
|
+
the results the tools return.
|
|
247
|
+
- [`server`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/server.py):
|
|
248
|
+
the MCP tools.
|
|
249
|
+
|
|
250
|
+
## Development
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
git clone https://github.com/gustavo-pabon/mhs-pilot.git
|
|
254
|
+
cd mhs-pilot/technic-hub-mcp
|
|
255
|
+
python3 -m venv .venv
|
|
256
|
+
.venv/bin/pip install -e . --group dev # needs pip 25.1 or later
|
|
257
|
+
.venv/bin/pytest
|
|
258
|
+
.venv/bin/ruff check . && .venv/bin/ruff format --check .
|
|
259
|
+
```
|
|
260
|
+
|
|
261
|
+
The tests don't need a hub: they use a simulated one.
|
|
262
|
+
|
|
263
|
+
To release, update `__version__` in `src/technic_hub_mcp/__init__.py` through a pull request. Once it's merged, tag
|
|
264
|
+
that commit on `main` with the new version, for example `technic-hub-mcp-v0.1.1`, and push the tag. GitHub Actions
|
|
265
|
+
then tests the package on Python 3.10–3.14, builds it, and publishes it to PyPI after a maintainer approves the
|
|
266
|
+
deployment on the workflow run.
|
|
267
|
+
|
|
268
|
+
## License
|
|
269
|
+
|
|
270
|
+
[MIT](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/LICENSE). This project is not affiliated
|
|
271
|
+
with or endorsed by the LEGO Group. LEGO and Technic are trademarks of the LEGO Group.
|
|
@@ -0,0 +1,243 @@
|
|
|
1
|
+
# LEGO Technic Hub MCP server
|
|
2
|
+
|
|
3
|
+
An [MCP](https://modelcontextprotocol.io) server that lets AI assistants read and control a LEGO Technic Hub (88012)
|
|
4
|
+
over Bluetooth LE: the motors and sensors on its four ports, its built-in sensors and its light. It implements LEGO's
|
|
5
|
+
[Wireless Protocol 3.0](https://lego.github.io/lego-ble-wireless-protocol-docs/) (LWP3), with tools for the hub's
|
|
6
|
+
properties, alerts and actions, the devices on its ports and their modes, and the port output commands.
|
|
7
|
+
|
|
8
|
+
## Requirements
|
|
9
|
+
|
|
10
|
+
- Python 3.10 or later.
|
|
11
|
+
- A computer with Bluetooth LE: macOS, Linux (BlueZ) or Windows 10 or later, through
|
|
12
|
+
[bleak](https://github.com/hbldh/bleak).
|
|
13
|
+
- The hub with LEGO's own firmware. Pybricks firmware replaces LWP3, so this server can't talk to a hub that runs it.
|
|
14
|
+
- The hub switched on and not connected to another app or device: it accepts one connection at a time. Press its
|
|
15
|
+
button: the light flashes white while the hub waits for a connection and turns solid blue once connected. A hub that
|
|
16
|
+
nothing connects to switches itself off after a short while.
|
|
17
|
+
|
|
18
|
+
On macOS, the app that starts the server (VS Code, Claude, Terminal…) needs Bluetooth access: **System Settings →
|
|
19
|
+
Privacy & Security → Bluetooth**.
|
|
20
|
+
|
|
21
|
+
## Installation
|
|
22
|
+
|
|
23
|
+
Install it from [PyPI](https://pypi.org/project/technic-hub-mcp/) into a virtual environment:
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
python3 -m venv .venv
|
|
27
|
+
.venv/bin/pip install technic-hub-mcp
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
This installs the `technic-hub-mcp` command in `.venv/bin/`. It runs the server over stdio. With
|
|
31
|
+
[uv](https://docs.astral.sh/uv/), `uvx technic-hub-mcp` runs it without installing it first.
|
|
32
|
+
|
|
33
|
+
## Configuration
|
|
34
|
+
|
|
35
|
+
Add the command to your MCP client, using its absolute path. With uv, use `"command": "uvx"` and
|
|
36
|
+
`"args": ["technic-hub-mcp"]` instead.
|
|
37
|
+
|
|
38
|
+
VS Code (`.vscode/mcp.json`):
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
{
|
|
42
|
+
"servers": {
|
|
43
|
+
"technic-hub": {
|
|
44
|
+
"type": "stdio",
|
|
45
|
+
"command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Claude Desktop (`claude_desktop_config.json`):
|
|
52
|
+
|
|
53
|
+
```json
|
|
54
|
+
{
|
|
55
|
+
"mcpServers": {
|
|
56
|
+
"technic-hub": {
|
|
57
|
+
"command": "/absolute/path/to/.venv/bin/technic-hub-mcp"
|
|
58
|
+
}
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Options, passed in `args`:
|
|
64
|
+
|
|
65
|
+
| Option | Default | Description |
|
|
66
|
+
| --- | --- | --- |
|
|
67
|
+
| `--address ADDRESS` | First Technic Hub found | Bluetooth address of the hub (a UUID on macOS). Use it when several hubs are nearby. |
|
|
68
|
+
| `--timeout SECONDS` | `10` | How long to search for and connect to the hub. |
|
|
69
|
+
|
|
70
|
+
The server looks for a hub that advertises the LWP3 service as a Technic Hub, and connects on the first tool call. If
|
|
71
|
+
the connection drops, for example because the hub switched itself off, the next tool call reconnects once the hub is
|
|
72
|
+
on again. When the server stops, it brakes the motors and disconnects.
|
|
73
|
+
|
|
74
|
+
To try the server without an AI client, open it in the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
|
|
75
|
+
|
|
76
|
+
```bash
|
|
77
|
+
npx @modelcontextprotocol/inspector .venv/bin/technic-hub-mcp
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Tools
|
|
81
|
+
|
|
82
|
+
Tools take ports as a letter, `A` to `D`, a synchronized pair such as `AB` (see `connect_virtual_port`), or a port
|
|
83
|
+
number. The hub's built-in devices only have numbers; on the hub this was tested with, they are 50 (light),
|
|
84
|
+
59 (current), 60 (voltage), 61 and 96 (temperature), 97 (accelerometer), 98 (gyro), 99 (tilt) and 100 (gesture).
|
|
85
|
+
`list_ports` shows them all.
|
|
86
|
+
|
|
87
|
+
The hub:
|
|
88
|
+
|
|
89
|
+
| Tool | Protocol message | Notes |
|
|
90
|
+
| --- | --- | --- |
|
|
91
|
+
| `get_hub_info` | Hub Properties (`0x01`) | Name, firmware and hardware versions, battery, signal, MAC addresses and the other properties, and what the hub advertised |
|
|
92
|
+
| `get_hub_alerts` | Hub Alerts (`0x03`) | Low voltage, high current, low signal strength and over-power condition |
|
|
93
|
+
| `set_hub_name(name)` | Hub Properties: Set | 1–14 printable ASCII characters. The hub keeps the name and advertises it |
|
|
94
|
+
| `reset_hub_name` | Hub Properties: Reset | Restores the default name |
|
|
95
|
+
| `set_busy_indication(enabled)` | Hub Actions `0x05`, `0x06` | Shows or clears the busy indication on the light |
|
|
96
|
+
| `set_port_vcc(enabled)` | Hub Actions `0x03`, `0x04` | Switches the supply voltage of the ports |
|
|
97
|
+
| `disconnect_hub` | Hub Actions `0x02` | The next tool call reconnects while the hub is still on |
|
|
98
|
+
| `switch_off_hub` | Hub Actions `0x01` | Destructive: the hub must then be switched on by hand |
|
|
99
|
+
|
|
100
|
+
Ports and sensors:
|
|
101
|
+
|
|
102
|
+
| Tool | Protocol messages | Returns |
|
|
103
|
+
| --- | --- | --- |
|
|
104
|
+
| `list_ports` | Hub Attached I/O (`0x04`) | Every port with a device: connector, built-in or virtual pair, device type and revisions |
|
|
105
|
+
| `get_port_info(port)` | Port Information (`0x21`, `0x43`), Port Mode Information (`0x22`, `0x44`) | The device's capabilities and, per mode: name, raw, percent and SI ranges, unit, mappings and value format |
|
|
106
|
+
| `read_port_value(port, mode)` | Port Input Format Setup (`0x41`), Port Value (`0x21`, `0x45`) | The values of one mode, by number or name such as `POS`, scaled to the mode's SI unit |
|
|
107
|
+
| `get_hub_sensors` | As above | Voltage, current, temperatures, accelerometer, gyro, tilt and gesture, each in its first mode |
|
|
108
|
+
| `get_motor_state(port)` | As above | Speed, encoder position, absolute position and load |
|
|
109
|
+
| `connect_virtual_port(first_port, second_port)` | Virtual Port Setup (`0x61`) | The new pair, such as `AB`, for synchronized motor commands |
|
|
110
|
+
| `disconnect_virtual_port(port)` | Virtual Port Setup (`0x61`) | |
|
|
111
|
+
|
|
112
|
+
Motors (Port Output Command, `0x81`). On a pair, the `second_*` parameters give the second motor its own power,
|
|
113
|
+
speed or position; without them, both motors get the same value.
|
|
114
|
+
|
|
115
|
+
| Tool | Sub-commands | Notes |
|
|
116
|
+
| --- | --- | --- |
|
|
117
|
+
| `motor_start_power(port, power, second_power)` | StartPower (WriteDirectModeData mode 0), `0x02` | Unregulated, until another command |
|
|
118
|
+
| `motor_start_speed(port, speed, ...)` | StartSpeed `0x07`, `0x08` | Regulated, until another command; speed 0 holds the position |
|
|
119
|
+
| `motor_run_for_time(port, time_ms, speed, ...)` | StartSpeedForTime `0x09`, `0x0A` | Up to 32,767 ms |
|
|
120
|
+
| `motor_run_for_degrees(port, degrees, speed, ...)` | StartSpeedForDegrees `0x0B`, `0x0C` | The sign of speed sets the direction |
|
|
121
|
+
| `motor_go_to_position(port, position, speed, ...)` | GotoAbsolutePosition `0x0D`, `0x0E` | Encoder degrees |
|
|
122
|
+
| `motor_stop(port, end_state)` | StartPower brake or float, StartSpeed 0 to hold | Replaces the current command |
|
|
123
|
+
| `motor_set_acceleration_time(port, time_ms)` | SetAccTime `0x05` | Ramp for commands with `profile` `acceleration` or `both` |
|
|
124
|
+
| `motor_set_deceleration_time(port, time_ms)` | SetDecTime `0x06` | Ramp for commands with `profile` `deceleration` or `both` |
|
|
125
|
+
| `motor_preset_encoder(port, position, second_position)` | PresetEncoder (WriteDirectModeData mode 2), `0x14` | Stops the motor |
|
|
126
|
+
|
|
127
|
+
The run, turn and go-to tools also take `max_power` (0–100 %, to limit torque), `end_state` (`brake`, `float` or
|
|
128
|
+
`hold`), `profile` and `wait`. Speeds and powers are percentages from −100 to 100.
|
|
129
|
+
|
|
130
|
+
The light and the tilt sensor:
|
|
131
|
+
|
|
132
|
+
| Tool | Command | Notes |
|
|
133
|
+
| --- | --- | --- |
|
|
134
|
+
| `set_led_color(color)` | SetRgbColorNo | `off`, `pink`, `purple`, `blue`, `light_blue`, `cyan`, `green`, `yellow`, `orange`, `red` or `white` |
|
|
135
|
+
| `set_led_rgb(red, green, blue)` | SetRgbColors | 0–255 each |
|
|
136
|
+
| `preset_tilt_impact_count(count)` | TiltImpactPreset | Sets the counter of bumps the hub has detected |
|
|
137
|
+
| `configure_tilt_impact(threshold, holdoff_ms)` | TiltConfigImpact | How hard a bump must be to count, and the minimum time between two |
|
|
138
|
+
|
|
139
|
+
## How moves end
|
|
140
|
+
|
|
141
|
+
`motor_run_for_time`, `motor_run_for_degrees` and `motor_go_to_position` wait until the motors stop, unless `wait` is
|
|
142
|
+
false, and return the outcome with each motor's encoder positions before and after:
|
|
143
|
+
|
|
144
|
+
- `completed`: the move ended as asked.
|
|
145
|
+
- `interrupted`: another command replaced it, such as `motor_stop`.
|
|
146
|
+
- `stalled`: a motor stopped turning (less than 2° in 1 s) before the end, so the server braked it. A motor that is
|
|
147
|
+
slowed but still turning is not stalled. A mechanism driven against a stop on purpose, to find its zero, ends this
|
|
148
|
+
way.
|
|
149
|
+
- `started`: `wait` was false.
|
|
150
|
+
|
|
151
|
+
The hub reports when most commands finish, but this one (firmware 1.0.00.0000) doesn't for timed runs or for the
|
|
152
|
+
degree moves of a pair. For those, the server takes the move as completed once its time is up, or once every motor is
|
|
153
|
+
within 5° of its target.
|
|
154
|
+
|
|
155
|
+
## Good to know
|
|
156
|
+
|
|
157
|
+
- Values are read on request: `read_port_value` and the other readers put the device in the mode they need, then ask
|
|
158
|
+
for its value. They scale the device's raw values to its SI unit with the ranges the device reports.
|
|
159
|
+
- After a move that ends holding its position, the hub sometimes ignores the next command without replying. If the
|
|
160
|
+
hub doesn't acknowledge a motor command within 0.5 s, the server sends it once more.
|
|
161
|
+
- For a pair, `motor_go_to_position` with `second_position` didn't do what the protocol describes on the hub this was
|
|
162
|
+
tested with: the second motor moved by the first motor's distance instead of to its own target. Position motors one
|
|
163
|
+
at a time when exact positions matter.
|
|
164
|
+
- Some hub properties may be missing from `get_hub_info`: the tested hub doesn't report its hardware network family.
|
|
165
|
+
- Tool annotations mark the reading tools as read-only and `switch_off_hub` as destructive, so clients can ask before
|
|
166
|
+
running it.
|
|
167
|
+
- Tested on a Technic Hub with firmware 1.0.00.0000 and four Technic Large Motors (88013), from macOS: every reading
|
|
168
|
+
tool; `set_led_color`, `set_led_rgb` and `set_busy_indication`; `disconnect_hub`, with the reconnection that
|
|
169
|
+
follows, and `switch_off_hub`; and all the motor tools on single motors, plus pairs with `connect_virtual_port`,
|
|
170
|
+
`disconnect_virtual_port`, `motor_run_for_degrees`, `motor_run_for_time` and `motor_go_to_position`. Not tried on a
|
|
171
|
+
hub yet: `set_hub_name`, `reset_hub_name`, `set_port_vcc`, `preset_tilt_impact_count`, `configure_tilt_impact`,
|
|
172
|
+
`motor_stop` with `hold`, and the `second_power`, `second_speed` and `second_position` values of
|
|
173
|
+
`motor_start_power`, `motor_start_speed` and `motor_preset_encoder`.
|
|
174
|
+
|
|
175
|
+
## Not covered
|
|
176
|
+
|
|
177
|
+
These parts of the protocol are left out on purpose:
|
|
178
|
+
|
|
179
|
+
- Firmware update and memory lock (`0x10`–`0x13`), and the production-only fast shutdown (Hub Actions `0x2F`): they can
|
|
180
|
+
leave the hub unusable.
|
|
181
|
+
- Raw WriteDirect (`0x50`), which carries the hardware reset and the tilt sensor's factory calibration: they can
|
|
182
|
+
de-calibrate a device.
|
|
183
|
+
- Hardware network commands (`0x08`) and setting the hardware network ID and family: they are for hubs connected to
|
|
184
|
+
each other without a computer.
|
|
185
|
+
- Value notifications and combined-mode sensor streams (`0x42`, `0x46`, `0x48`): the tools read values on request
|
|
186
|
+
instead.
|
|
187
|
+
- Queued commands: every output command runs immediately, replacing the port's current command.
|
|
188
|
+
|
|
189
|
+
## Python library
|
|
190
|
+
|
|
191
|
+
The protocol and Bluetooth layers also work without MCP:
|
|
192
|
+
|
|
193
|
+
```python
|
|
194
|
+
import asyncio
|
|
195
|
+
|
|
196
|
+
from technic_hub_mcp import protocol
|
|
197
|
+
from technic_hub_mcp.hub import TechnicHub
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
async def main() -> None:
|
|
201
|
+
hub = TechnicHub()
|
|
202
|
+
try:
|
|
203
|
+
motor = await hub.port_id("A")
|
|
204
|
+
result = await hub.move(protocol.start_speed_for_degrees(motor, 90, 30))
|
|
205
|
+
print(result.outcome, result.motors[0].end_position)
|
|
206
|
+
finally:
|
|
207
|
+
await hub.disconnect()
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
asyncio.run(main())
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
- [`protocol`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/protocol.py):
|
|
214
|
+
builds and decodes LWP3 messages. No Bluetooth.
|
|
215
|
+
- [`hub`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/hub.py):
|
|
216
|
+
`TechnicHub` finds, connects to and reconnects to the hub, matches replies to requests and follows motor commands.
|
|
217
|
+
- [`models`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/models.py):
|
|
218
|
+
the results the tools return.
|
|
219
|
+
- [`server`](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/src/technic_hub_mcp/server.py):
|
|
220
|
+
the MCP tools.
|
|
221
|
+
|
|
222
|
+
## Development
|
|
223
|
+
|
|
224
|
+
```bash
|
|
225
|
+
git clone https://github.com/gustavo-pabon/mhs-pilot.git
|
|
226
|
+
cd mhs-pilot/technic-hub-mcp
|
|
227
|
+
python3 -m venv .venv
|
|
228
|
+
.venv/bin/pip install -e . --group dev # needs pip 25.1 or later
|
|
229
|
+
.venv/bin/pytest
|
|
230
|
+
.venv/bin/ruff check . && .venv/bin/ruff format --check .
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
The tests don't need a hub: they use a simulated one.
|
|
234
|
+
|
|
235
|
+
To release, update `__version__` in `src/technic_hub_mcp/__init__.py` through a pull request. Once it's merged, tag
|
|
236
|
+
that commit on `main` with the new version, for example `technic-hub-mcp-v0.1.1`, and push the tag. GitHub Actions
|
|
237
|
+
then tests the package on Python 3.10–3.14, builds it, and publishes it to PyPI after a maintainer approves the
|
|
238
|
+
deployment on the workflow run.
|
|
239
|
+
|
|
240
|
+
## License
|
|
241
|
+
|
|
242
|
+
[MIT](https://github.com/gustavo-pabon/mhs-pilot/blob/main/technic-hub-mcp/LICENSE). This project is not affiliated
|
|
243
|
+
with or endorsed by the LEGO Group. LEGO and Technic are trademarks of the LEGO Group.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "technic-hub-mcp"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "MCP server that lets AI assistants read and control a LEGO Technic Hub and its motors over Bluetooth."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
license-files = ["LICENSE"]
|
|
12
|
+
authors = [{ name = "Gustavo Pabon" }]
|
|
13
|
+
requires-python = ">=3.10"
|
|
14
|
+
dependencies = ["bleak>=3.0", "mcp>=2.3"]
|
|
15
|
+
keywords = ["mcp", "model-context-protocol", "bluetooth", "ble", "lego", "technic", "powered-up", "lwp3", "motor"]
|
|
16
|
+
classifiers = [
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
"Intended Audience :: Developers",
|
|
19
|
+
"Operating System :: MacOS",
|
|
20
|
+
"Operating System :: Microsoft :: Windows",
|
|
21
|
+
"Operating System :: POSIX :: Linux",
|
|
22
|
+
"Programming Language :: Python :: 3",
|
|
23
|
+
"Programming Language :: Python :: 3.10",
|
|
24
|
+
"Programming Language :: Python :: 3.11",
|
|
25
|
+
"Programming Language :: Python :: 3.12",
|
|
26
|
+
"Programming Language :: Python :: 3.13",
|
|
27
|
+
"Programming Language :: Python :: 3.14",
|
|
28
|
+
"Topic :: System :: Hardware",
|
|
29
|
+
]
|
|
30
|
+
|
|
31
|
+
[project.urls]
|
|
32
|
+
Homepage = "https://github.com/gustavo-pabon/mhs-pilot/tree/main/technic-hub-mcp"
|
|
33
|
+
Source = "https://github.com/gustavo-pabon/mhs-pilot"
|
|
34
|
+
Issues = "https://github.com/gustavo-pabon/mhs-pilot/issues"
|
|
35
|
+
|
|
36
|
+
[project.scripts]
|
|
37
|
+
technic-hub-mcp = "technic_hub_mcp.server:main"
|
|
38
|
+
|
|
39
|
+
[dependency-groups]
|
|
40
|
+
dev = ["pytest>=8", "ruff>=0.6"]
|
|
41
|
+
|
|
42
|
+
[tool.hatch.version]
|
|
43
|
+
path = "src/technic_hub_mcp/__init__.py"
|
|
44
|
+
|
|
45
|
+
[tool.pytest.ini_options]
|
|
46
|
+
testpaths = ["tests"]
|
|
47
|
+
|
|
48
|
+
[tool.ruff]
|
|
49
|
+
line-length = 120
|