Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -230,6 +230,8 @@ And one that serves a machine to lab software:
- [`examples/sila`](examples/sila) — one field of each kind (switch, level, discrete, select, analog volts, text, command in presented
units, action) served as SiLA 2 features by a Python gateway, from a Nano or on the host with the endpoints simulated.
The rules any such consumer follows are in [`docs/consumers.md`](docs/consumers.md).
- [`examples/mcp`](examples/mcp) — the same machine served to AI assistants over MCP (Claude Code and others), from the same
description: a tool to read and a tool to command each role, with the bounds in the tool's schema.

And one on a second bus:

Expand Down
11 changes: 8 additions & 3 deletions docs/consumers.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ industrial controller. The machine is built once and knows none of them; each co
whose roles it understands.

[`examples/sila`](../examples/sila) is the worked example: a Python gateway that turns any machine built from its eight role
kinds into a SiLA 2 server.
kinds into a SiLA 2 server. [`examples/mcp`](../examples/mcp) serves the same machine to AI assistants over MCP: the same
description, another protocol's words.

## What the machine provides

Expand All @@ -29,7 +30,10 @@ These hold for any consumer; the SiLA gateway is how each looks in practice.
1. **One table: kind to the protocol's words.** The consumer's knowledge of machines is a table with one row per role kind. A
row is about a kind, never about a machine: "a `light`'s `level` is bounded by its `max` parameter", not "the lamp goes to
200". Everything machine-specific (role names, limits, allowed values, labels, scales, units, text lengths) is read from the
description at connect. In `examples/sila` the table is `KINDS` in `gateway.py`.
description at connect. What a kind says about a role (the fields it reports and commands, what bounds them, the values,
labels, scale and unit, how a raw integer is presented) is read through `python/onemachine` (`role_facts`), the same for
every consumer; the table holds only the protocol's words. In `examples/sila` the table is `KINDS` in `gateway.py`, in
`examples/mcp` it is `KINDS` in `server.py`.

2. **The protocol's self-description is generated, never written by hand.** The SiLA gateway writes each feature definition
(FDL) from the description at start. Change a limit or a label in the firmware and, after a reconnect, the consumer serves
Expand Down Expand Up @@ -70,7 +74,8 @@ place instead of carrying its own copy.

## Adding a consumer

1. Map each kind you need to the protocol's words: type, constraints, unit, readable or commandable. Write it as the table.
1. Map each kind you need to the protocol's words: type, constraints, unit, readable or commandable. Write it as the table,
and read the kind's facts from `role_facts` in `python/onemachine` instead of copying them.
2. Generate the protocol's self-description from the machine description; check it against the protocol's own schema where one
exists (SiLA: the FDL schema from `sila_base`).
3. Refuse everything outside the table, by name.
Expand Down
106 changes: 106 additions & 0 deletions examples/mcp/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# mcp

The machine of [`examples/sila`](../sila) served to AI assistants over MCP. Claude Code, or any other MCP client, can read and
command every role of the Nano by name, without knowing OneMachine, the pins or the board. Nothing on the board changes: this is
the same firmware as in `examples/sila` (wiring and flashing are described there), and the same machine description feeds both
examples. One machine, two consumers.

[MCP](https://modelcontextprotocol.io) (the Model Context Protocol) is the way an AI assistant is given tools. A server lists its
tools, each with a name, a description and a JSON Schema for its arguments; the assistant reads them, decides which to call, and the
server returns the result. `server.py` reads the machine's description over the serial link, generates the tools from it and serves
them on standard input and output, so the client starts it as a program. It knows only the kinds in its table: a role of any other
kind is refused at start, naming the role.

## Run

```
pip install -r requirements.txt # mcp and pyserial; Python 3.10 or newer
python3 server.py --port /dev/ttyUSB0 # the Nano's port
```

Opening the port resets a Nano: all outputs start off at each start.

Without the board, the same machine on this computer (from this directory):

```
g++ -std=c++17 -I../../../HAPI/include -I../../include ../sila/host/main.cpp -o ../sila/host/machine
python3 server.py --sim ../sila/host/machine
```

`python3 server.py --sim ../sila/host/machine --list` prints what a client is told (the instructions and every tool with its schema)
and stops. `--trace FILE` writes every request and response on the link.

## Add it to Claude Code

```
claude mcp add machine -- python3 /path/to/examples/mcp/server.py --port /dev/ttyUSB0
```

Then ask in plain words: "What can this machine do?", "Turn on the LED.", "Set the lamp to half its maximum."

## What the tools are

For each role, `<role>_get` reads it. A commandable role also has `<role>_set` with one argument, or `<role>_fire` for an action.
`status` reads every role in one call. The schema is built from the role's kind and its description:

| role (kind) | tools | argument and its schema | what `_get` returns |
|---|---|---|---|
| `led` (`switch`) | `led_get`, `led_set` | `on`: boolean | `{"on": true}` |
| `lamp` (`light`) | `lamp_get`, `lamp_set` | `level`: integer, 0 to `max` (200) | `{"level": 100, "clamped": false}` |
| `step` (`discrete`) | `step_get`, `step_set` | `value`: integer, one of the `value` lines (0, 10, 50, 100) | `{"value": 50}` |
| `mode` (`select`) | `mode_get`, `mode_set` | `value`: string, one of the labels (off, low, high) | `{"value": "high"}` |
| `vin` (`analog`) | `vin_get` | none: read only | `{"value": 2.49, "unit": "V"}` |
| `note` (`text`) | `note_get`, `note_set` | `text`: string, at most 16 printable ASCII characters | `{"text": "hello"}` |
| `duty` (`scaled`) | `duty_get`, `duty_set` | `value`: number, 0 to 100 (`max` times the `scale` line) | `{"value": 12.4, "unit": "%"}` |
| `ping` (`action`) | `ping_get`, `ping_fire` | none | `{"fired": 3}` |

How they behave:

- **A set returns the value the device holds.** The command is sent once, then the report is read after the device has applied it:
`duty_set 12.36` returns 12.4, the device's own resolution. The report is the truth.
- **A value outside the schema is refused, and nothing is sent.** The result is a tool error that names the parameter and the bound
(`level: 250 is above the maximum 200`). The server checks every argument itself, whether or not the client checks the schema.
- **The assistant is told to ask, not to substitute.** The server's instructions say that a value outside a tool's bounds is
refused, and that the assistant should tell the user instead of sending a different value.
- **Nothing is held or resent.** A `_fire` sends its flag in exactly one frame. Whatever the device does when commands stop is the
device's own behaviour. One lock on the link serialises the calls.
- **Every argument is checked, even the ones a schema cannot express:** `text` must be printable ASCII, a `light` must be a whole
number, a boolean is not a number.

The rules any such consumer follows are in [`docs/consumers.md`](../../docs/consumers.md). What a kind says about a role (the
fields it reports and commands, the bound, the values, the scale) is read through `python/onemachine`; this file holds the MCP words.

## An expected session

Claude Code on a Nano, a fresh session with only this server's tools (the answers are shortened; each tool call and its result are the server's own):

```
> What can this machine do?
This machine (OneMachine `ba36fc2d`) exposes several controllable roles:
led (switch) – on/off · lamp (light) – level 0–200 · step (discrete) – one of 0, 10, 50, 100 · mode (select) – off, low, high ·
vin (analog, read-only) – voltage reading in V · note (text) – up to 16 ASCII characters · duty (scaled) – 0–100%, 0.1 resolution ·
ping (action) – fires once, counts how many times it's run since boot
> Turn on the LED.
led_set {"on": true} -> {"on":true}
> Set the lamp to half its maximum.
lamp_set {"level": 100} -> {"level":100,"clamped":false}
> Set the mode to the highest setting.
mode_set {"value": "high"} -> {"value":"high"}
> Write 'hi Rui' on the note.
note_set {"text": "hi Rui"} -> {"text":"hi Rui"}
> What voltage is on vin?
vin_get {} -> {"value":0.21994134897360704,"unit":"V"} (A0 is floating: noise between 0 and 5 V)
> Set the lamp to 300.
That's out of bounds — lamp only accepts 0 to 200. I won't send a different value; let me know what level within that range you'd like.
```

Four commands reached the board, one frame each; the last request sent nothing. A client that sends the value anyway gets the tool
error, and the board never sees it; a client that bypasses the server and sends it to the board gets the kind's own behaviour (a
light is clamped to its `max`).

## What it does not cover

No network transport and no authentication (the client starts the server and talks to it on standard input and output), no tuned
roles (their limits can change at run time, which a tool schema cannot say), no timeout or safe fall (a value that was set stays
set), no MCP resources or prompts beyond the server's instructions, and no reconnect: if the board is unplugged, the tools return
errors until the server is restarted.
2 changes: 2 additions & 0 deletions examples/mcp/requirements.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
mcp==2.3.0
pyserial==3.5
Loading
Loading