mcp-server-sila 0.0.3__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.
- mcp_server_sila-0.0.3/PKG-INFO +574 -0
- mcp_server_sila-0.0.3/README.md +548 -0
- mcp_server_sila-0.0.3/pyproject.toml +242 -0
- mcp_server_sila-0.0.3/pyproject.toml.orig +247 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/__init__.py +6 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/__main__.py +8 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/binary.py +236 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/cli.py +144 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/client_api.py +520 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/config.py +614 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/discovery_watcher.py +234 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/execution.py +366 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/logging_setup.py +19 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/policy.py +242 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/pool.py +502 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/promote.py +675 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/py.typed +0 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/schema.py +227 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/security.py +193 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/server.py +511 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/tools/__init__.py +79 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/tools/confirm.py +322 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/tools/core.py +504 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/tools/dynamic.py +100 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/tools/exec_tools.py +120 -0
- mcp_server_sila-0.0.3/src/mcp_server_sila/values.py +279 -0
|
@@ -0,0 +1,574 @@
|
|
|
1
|
+
Metadata-Version: 2.3
|
|
2
|
+
Name: mcp-server-sila
|
|
3
|
+
Version: 0.0.3
|
|
4
|
+
Summary: A generic, dynamic MCP server bridging the Model Context Protocol to SiLA 2 laboratory devices.
|
|
5
|
+
Keywords: mcp,model-context-protocol,sila,sila2,laboratory,automation,llm
|
|
6
|
+
Author: mark doerr
|
|
7
|
+
Author-email: mark doerr <mark.doerr@uni-greifswald.de>
|
|
8
|
+
License: MIT
|
|
9
|
+
Classifier: Development Status :: 2 - Pre-Alpha
|
|
10
|
+
Classifier: Intended Audience :: Developers
|
|
11
|
+
Classifier: Intended Audience :: Science/Research
|
|
12
|
+
Classifier: Natural Language :: English
|
|
13
|
+
Classifier: Operating System :: OS Independent
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
15
|
+
Classifier: Topic :: Scientific/Engineering
|
|
16
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
17
|
+
Requires-Dist: mcp>=2,<3
|
|
18
|
+
Requires-Dist: unitelabs-sila>=0.14,<1
|
|
19
|
+
Maintainer: mark doerr
|
|
20
|
+
Requires-Python: ==3.13.*
|
|
21
|
+
Project-URL: Bug Tracker, https://github.com/markdoerr/mcp-server-sila/issues
|
|
22
|
+
Project-URL: Changelog, https://github.com/markdoerr/mcp-server-sila/blob/main/CHANGELOG.md
|
|
23
|
+
Project-URL: documentation, https://mcp-server-sila.readthedocs.io
|
|
24
|
+
Project-URL: repository, https://github.com/markdoerr/mcp-server-sila
|
|
25
|
+
Description-Content-Type: text/markdown
|
|
26
|
+
|
|
27
|
+
<p align="center">
|
|
28
|
+
<img src="docs/_static/logo.svg" alt="mcp-server-sila โ the SiLA 2 standard connected to the Model Context Protocol" width="420">
|
|
29
|
+
</p>
|
|
30
|
+
|
|
31
|
+
# mcp-server-sila
|
|
32
|
+
|
|
33
|
+
**A generic, dynamic [Model Context Protocol](https://modelcontextprotocol.io) (MCP) โ
|
|
34
|
+
[SiLA 2](https://sila-standard.com) bridge for scientists and lab-workflow orchestrators.**
|
|
35
|
+
|
|
36
|
+
Connect SiLA 2 laboratory devices to LLM clients โ OpenCode, Claude Desktop, or a custom
|
|
37
|
+
orchestrator โ and operate real hardware in natural language. The bridge exposes each
|
|
38
|
+
device's real types, units, and constraints as MCP tools, handles SiLA 2's asynchronous
|
|
39
|
+
and stateful execution model, and gates unsafe actions behind a server-side policy engine
|
|
40
|
+
and confirmation prompts.
|
|
41
|
+
|
|
42
|
+
```mermaid
|
|
43
|
+
flowchart LR
|
|
44
|
+
subgraph client["๐งโ๐ฌ Lab agent"]
|
|
45
|
+
LLM["LLM client<br/>OpenCode ยท Claude Desktop<br/>orchestrator"]
|
|
46
|
+
end
|
|
47
|
+
|
|
48
|
+
subgraph bridge["mcp-server-sila"]
|
|
49
|
+
direction TB
|
|
50
|
+
Tools["Core tools + promoted tools<br/>resources"]
|
|
51
|
+
Policy["Policy engine<br/>confirm gate"]
|
|
52
|
+
Exec["Execution registry<br/>binary store"]
|
|
53
|
+
Disc["mDNS discovery"]
|
|
54
|
+
Tools --> Policy --> Exec
|
|
55
|
+
end
|
|
56
|
+
|
|
57
|
+
subgraph lab["Laboratory network"]
|
|
58
|
+
direction TB
|
|
59
|
+
Mover["Plate mover<br/><i>SiLA 2 server</i>"]
|
|
60
|
+
Reader["Plate reader<br/><i>SiLA 2 server</i>"]
|
|
61
|
+
Thermo["Thermometer<br/><i>SiLA 2 server</i>"]
|
|
62
|
+
end
|
|
63
|
+
|
|
64
|
+
LLM <-->|"MCP<br/>stdio ยท streamable-http"| Tools
|
|
65
|
+
Exec <-->|"SiLA 2 / gRPC<br/>TLS ยท mTLS"| Mover
|
|
66
|
+
Exec <-->|"SiLA 2 / gRPC"| Reader
|
|
67
|
+
Exec <-->|"SiLA 2 / gRPC"| Thermo
|
|
68
|
+
Disc -.->|"mDNS / DNS-SD<br/>auto-discovery"| Mover
|
|
69
|
+
Disc -.-> Reader
|
|
70
|
+
Disc -.-> Thermo
|
|
71
|
+
Mover -.->|"labware transfer<br/>(SiLA, device-to-device)"| Reader
|
|
72
|
+
|
|
73
|
+
classDef clientStyle fill:#15222B,stroke:#15222B,color:#fff
|
|
74
|
+
classDef bridgeStyle fill:#41889F,stroke:#2f6d81,color:#fff
|
|
75
|
+
classDef labStyle fill:#CDDCE2,stroke:#41889F,color:#15222B
|
|
76
|
+
class LLM clientStyle
|
|
77
|
+
class Tools,Policy,Exec,Disc bridgeStyle
|
|
78
|
+
class Mover,Reader,Thermo labStyle
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
<sub>LLM clients speak MCP to the bridge; the bridge speaks SiLA 2 to the instruments.
|
|
82
|
+
Instruments can also act on each other over SiLA โ a plate mover hands labware to a
|
|
83
|
+
plate reader, discovered through mDNS.</sub>
|
|
84
|
+
|
|
85
|
+
## Why this exists
|
|
86
|
+
|
|
87
|
+
MCP is request/response; SiLA 2 is long-lived and stateful (execution UUIDs, polling
|
|
88
|
+
subscriptions, observable properties). The bridge resolves that mismatch with
|
|
89
|
+
**server-side state + pull-style tools**:
|
|
90
|
+
|
|
91
|
+
- an observable command returns `{execution: <uuid>, status}` immediately, and the model
|
|
92
|
+
waits, polls progress, and pulls intermediate responses through separate tools;
|
|
93
|
+
- binary payloads never flood the context โ they are stored and referenced as
|
|
94
|
+
`sila://binaries/<id>` resources;
|
|
95
|
+
- connection loss and reconnection are handled for you, and every failure the model sees
|
|
96
|
+
is an actionable message, not an opaque internal error.
|
|
97
|
+
|
|
98
|
+
Because an LLM can be wrong (or prompt-injected), safety is **not** delegated to tool
|
|
99
|
+
annotations: a policy engine decides allow / confirm / deny before any SiLA call is made,
|
|
100
|
+
and destructive actions require an explicit human confirmation when the client can show
|
|
101
|
+
one.
|
|
102
|
+
|
|
103
|
+
## Feature highlights
|
|
104
|
+
|
|
105
|
+
- **Two-tier tool model.** A stable set of 12 core meta-tools is always present; typed
|
|
106
|
+
tools for a device's features are generated on demand (with real parameter names, types,
|
|
107
|
+
units, and constraints) and removed again when no longer needed.
|
|
108
|
+
- **Full async lifecycle.** Observable command tracking by execution UUID, bounded waits,
|
|
109
|
+
intermediate-response cursors, observable-property polling, and retention-based GC.
|
|
110
|
+
- **Safety first.** Read-only devices, deny globs, destructive-pattern classification,
|
|
111
|
+
per-device rate and concurrency limits, property-write gating, and a headless fallback
|
|
112
|
+
that denies destructive actions instead of assuming "yes".
|
|
113
|
+
- **TLS by default.** Four modes โ `insecure` (loopback only), `pinned` (CA from mDNS),
|
|
114
|
+
`ca` (explicit root CA), and `mtls` (client certificates). Certificate contents never
|
|
115
|
+
appear in logs or errors; only paths.
|
|
116
|
+
- **mDNS discovery.** Adopt devices as they appear, forget them when they leave (releasing
|
|
117
|
+
their stored binaries); discovered devices stay **read-only until explicitly
|
|
118
|
+
allowlisted**.
|
|
119
|
+
- **Two transports.** stdio for a local client, streamable-http with a static bearer token
|
|
120
|
+
for remote use โ and the server refuses to expose an unauthenticated off-loopback
|
|
121
|
+
endpoint.
|
|
122
|
+
- **Hybrid protocol support.** Works across MCP protocol eras, using the modern
|
|
123
|
+
`InputRequiredResult` round-trip for confirmations on 2026-07-28+ connections and
|
|
124
|
+
elicitation on earlier ones.
|
|
125
|
+
- **Operationally boring.** One PyPI package, 12-factor configuration, a Docker image, a
|
|
126
|
+
redacted `--check-config` summary, and a test suite against a real in-process SiLA 2
|
|
127
|
+
device (including TLS and error paths).
|
|
128
|
+
|
|
129
|
+
## Requirements
|
|
130
|
+
|
|
131
|
+
- Python **3.13**
|
|
132
|
+
- A SiLA 2 server on the network (any device speaking SiLA 2 over gRPC)
|
|
133
|
+
|
|
134
|
+
## Install
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
uv tool install mcp-server-sila
|
|
138
|
+
# or
|
|
139
|
+
pip install mcp-server-sila
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
Both install the `mcp-server-sila` console script; `python -m mcp_server_sila` is
|
|
143
|
+
equivalent.
|
|
144
|
+
|
|
145
|
+
### Container
|
|
146
|
+
|
|
147
|
+
```bash
|
|
148
|
+
docker build -f docker/Dockerfile -t mcp-server-sila:dev .
|
|
149
|
+
docker run --rm -e MCP_SILA_SERVER_HOST=0.0.0.0 -e MCP_SILA_AUTH_TOKEN=change-me \
|
|
150
|
+
-p 8765:8765 mcp-server-sila:dev
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
The image serves streamable-http by default. Mount certificate material at
|
|
154
|
+
`/opt/mcp-server-sila/certificates` (the compose file maps
|
|
155
|
+
`./docker/mcp-server-sila/certificates` there) and reference it by path in the
|
|
156
|
+
configuration.
|
|
157
|
+
|
|
158
|
+
## Quick start
|
|
159
|
+
|
|
160
|
+
### stdio โ local client (OpenCode, Claude Desktop, โฆ)
|
|
161
|
+
|
|
162
|
+
Point your MCP client at `mcp-server-sila --transport stdio` and configure the devices โ
|
|
163
|
+
either statically (`MCP_SILA_ENDPOINT_0_*`) or by mDNS discovery (no endpoint
|
|
164
|
+
configuration at all). With discovery enabled and an allowlist, the client only needs:
|
|
165
|
+
|
|
166
|
+
```json
|
|
167
|
+
{
|
|
168
|
+
"mcpServers": {
|
|
169
|
+
"sila": {
|
|
170
|
+
"command": "mcp-server-sila",
|
|
171
|
+
"args": ["--transport", "stdio"],
|
|
172
|
+
"env": {
|
|
173
|
+
"MCP_SILA_DISCOVERY_ENABLED": "true",
|
|
174
|
+
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Then ask things like *"Which devices are connected?"*, *"What can the pump do?"*, or
|
|
182
|
+
*"Set the setpoint to 42 and tell me when it's done."* The exact configuration for
|
|
183
|
+
OpenCode and Claude Desktop, including the remote variant, is in
|
|
184
|
+
[Connect a client](#connect-a-client).
|
|
185
|
+
|
|
186
|
+
### streamable-http โ remote / orchestrator
|
|
187
|
+
|
|
188
|
+
```bash
|
|
189
|
+
MCP_SILA_AUTH_TOKEN=change-me MCP_SILA_SERVER_HOST=0.0.0.0 \
|
|
190
|
+
mcp-server-sila --transport streamable-http --port 8765
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
The endpoint is `http://<host>:8765/mcp`; clients send
|
|
194
|
+
`Authorization: Bearer change-me`. A non-loopback host without a token is refused at
|
|
195
|
+
startup.
|
|
196
|
+
|
|
197
|
+
### Validate a configuration without serving
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
mcp-server-sila --config bridge.toml --check-config
|
|
201
|
+
# prints a redacted summary and exits 0 (errors exit 2)
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
## Connect a client
|
|
205
|
+
|
|
206
|
+
Any MCP client works. The bridge serves **stdio** (the client starts it as a child
|
|
207
|
+
process) or **streamable-http** (a URL plus a bearer token). Confirmation prompts and
|
|
208
|
+
tool-list changes are supported on both protocol eras; see the notes below.
|
|
209
|
+
|
|
210
|
+
### OpenCode
|
|
211
|
+
|
|
212
|
+
OpenCode's V2 configuration declares MCP servers under `mcp.servers` โ in
|
|
213
|
+
`opencode.jsonc` for a project or in the global config.
|
|
214
|
+
|
|
215
|
+
**local (stdio)** โ OpenCode starts the bridge itself:
|
|
216
|
+
|
|
217
|
+
```json
|
|
218
|
+
{
|
|
219
|
+
"$schema": "https://opencode.ai/config.json",
|
|
220
|
+
"mcp": {
|
|
221
|
+
"servers": {
|
|
222
|
+
"sila": {
|
|
223
|
+
"type": "local",
|
|
224
|
+
"command": ["mcp-server-sila", "--transport", "stdio"],
|
|
225
|
+
"environment": {
|
|
226
|
+
"MCP_SILA_DISCOVERY_ENABLED": "true",
|
|
227
|
+
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
|
|
228
|
+
},
|
|
229
|
+
"protocol": "auto"
|
|
230
|
+
}
|
|
231
|
+
}
|
|
232
|
+
}
|
|
233
|
+
}
|
|
234
|
+
```
|
|
235
|
+
|
|
236
|
+
The same entry can be created from the CLI:
|
|
237
|
+
|
|
238
|
+
```bash
|
|
239
|
+
opencode mcp add sila \
|
|
240
|
+
--env MCP_SILA_DISCOVERY_ENABLED=true \
|
|
241
|
+
--env MCP_SILA_DISCOVERY_ALLOWLIST="Plate Mover,Plate Reader" \
|
|
242
|
+
-- mcp-server-sila --transport stdio
|
|
243
|
+
opencode mcp list # expect: โ sila connected
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
**remote (streamable-http)** โ for a bridge running elsewhere (or in a container):
|
|
247
|
+
|
|
248
|
+
```json
|
|
249
|
+
{
|
|
250
|
+
"mcp": {
|
|
251
|
+
"servers": {
|
|
252
|
+
"sila": {
|
|
253
|
+
"type": "remote",
|
|
254
|
+
"url": "http://127.0.0.1:8765/mcp",
|
|
255
|
+
"oauth": false,
|
|
256
|
+
"headers": { "Authorization": "Bearer {env:MCP_SILA_TOKEN}" },
|
|
257
|
+
"protocol": "auto"
|
|
258
|
+
}
|
|
259
|
+
}
|
|
260
|
+
}
|
|
261
|
+
}
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
`oauth` is set to `false` because the bridge uses a static bearer token, not OAuth;
|
|
265
|
+
`{env:MCP_SILA_TOKEN}` keeps the secret out of the configuration file. `/mcps` in the TUI
|
|
266
|
+
shows the connection state, and OpenCode's default Code Mode groups the tools under
|
|
267
|
+
`tools.sila.*`.
|
|
268
|
+
|
|
269
|
+
### Claude Desktop
|
|
270
|
+
|
|
271
|
+
Claude Desktop uses `mcpServers` in `claude_desktop_config.json`:
|
|
272
|
+
|
|
273
|
+
```json
|
|
274
|
+
{
|
|
275
|
+
"mcpServers": {
|
|
276
|
+
"sila": {
|
|
277
|
+
"command": "mcp-server-sila",
|
|
278
|
+
"args": ["--transport", "stdio"],
|
|
279
|
+
"env": {
|
|
280
|
+
"MCP_SILA_DISCOVERY_ENABLED": "true",
|
|
281
|
+
"MCP_SILA_DISCOVERY_ALLOWLIST": "Plate Mover,Plate Reader"
|
|
282
|
+
}
|
|
283
|
+
}
|
|
284
|
+
}
|
|
285
|
+
}
|
|
286
|
+
```
|
|
287
|
+
|
|
288
|
+
### Protocol eras and confirmations
|
|
289
|
+
|
|
290
|
+
The bridge speaks both MCP protocol eras:
|
|
291
|
+
|
|
292
|
+
- **Modern (2026-07-28)** โ selected by OpenCode's `"protocol": "auto"` (or `"2026-07-28"`).
|
|
293
|
+
Confirmation prompts arrive as an input-required round-trip and are shown as forms.
|
|
294
|
+
- **Legacy (up to 2025-11-25)** โ OpenCode's default (`"legacy"`) and what most clients
|
|
295
|
+
use today. The bridge asks for confirmation through classic elicitation, which clients
|
|
296
|
+
that support it (including OpenCode) render as a form.
|
|
297
|
+
|
|
298
|
+
Clients that cannot show a prompt never get a silent "yes": destructive actions are
|
|
299
|
+
denied (see [Safety & security](#safety--security)).
|
|
300
|
+
|
|
301
|
+
### No endpoint configuration needed
|
|
302
|
+
|
|
303
|
+
With `MCP_SILA_DISCOVERY_ENABLED=true`, the bridge finds SiLA servers on the network by
|
|
304
|
+
itself โ nothing else to configure. Ask the agent *"Which SiLA devices are on the
|
|
305
|
+
network?"*, then *"Promote the plate mover's feature and hand the plate to the reader."*
|
|
306
|
+
See [Discovery (mDNS / Bonjour)](#discovery-mdns--bonjour) for the mechanics and
|
|
307
|
+
[examples/sila-labware-transfer](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/examples/sila-labware-transfer/README.md)
|
|
308
|
+
for a working two-server lab.
|
|
309
|
+
|
|
310
|
+
## How it works
|
|
311
|
+
|
|
312
|
+
### The tool model
|
|
313
|
+
|
|
314
|
+
1. **Core meta-tools** (always present) work on any device, addressed by alias, short
|
|
315
|
+
identifier, fully qualified identifier (FQID), or UUID prefix.
|
|
316
|
+
2. **Promoted typed tools** are generated per feature on demand. They behave like native
|
|
317
|
+
MCP tools โ typed parameters, JSON-Schema constraints, units in the description, and
|
|
318
|
+
structured output โ and disappear when demoted or when their device is lost.
|
|
319
|
+
|
|
320
|
+
| Core tool | What it does |
|
|
321
|
+
|---|---|
|
|
322
|
+
| `sila_list_devices` | All known devices with lifecycle state (`connected`/`connecting`/`lost`) |
|
|
323
|
+
| `sila_describe_device` | Identity plus the full feature tree (properties, commands, types, units) |
|
|
324
|
+
| `sila_list_features` | Lighter feature summary for a device |
|
|
325
|
+
| `sila_read_property` | Current value (observable properties: first value) |
|
|
326
|
+
| `sila_write_property` | Write a value (policy-gated; confirmation by default) |
|
|
327
|
+
| `sila_execute_command` | Execute a command: responses, or `{execution, status}` for observable ones |
|
|
328
|
+
| `sila_poll_property` | Changed values within a bounded window (capped, with a true count) |
|
|
329
|
+
| `sila_execution_info` | Status, progress, remaining time of a tracked execution |
|
|
330
|
+
| `sila_wait_execution` | Bounded wait โ final responses, error, or "still running" |
|
|
331
|
+
| `sila_execution_intermediate` | Intermediate responses since a cursor |
|
|
332
|
+
| `sila_promote_feature` | Generate typed tools for `alias/*`, `alias/Feature`, or an FQID |
|
|
333
|
+
| `sila_demote_feature` | Remove a feature's typed tools |
|
|
334
|
+
|
|
335
|
+
Element tools (`read_property`, `write_property`, `execute_command`, `poll_property`)
|
|
336
|
+
accept an optional `device` argument. When several connected devices implement the same
|
|
337
|
+
FQID and no device is given, the call is refused rather than guessing โ actuating the
|
|
338
|
+
wrong instrument is worse than an actionable error.
|
|
339
|
+
|
|
340
|
+
### Resources
|
|
341
|
+
|
|
342
|
+
| URI | Content |
|
|
343
|
+
|---|---|
|
|
344
|
+
| `sila://{device}/{feature}/{property}` | A property's current value as JSON text |
|
|
345
|
+
| `sila://binaries/{id}` | Bytes of a stored binary value (`application/octet-stream`) |
|
|
346
|
+
|
|
347
|
+
Binary values (properties or command responses) are stored in an ephemeral store with a
|
|
348
|
+
10 MB per-value and 500 MB per-device cap, returned to the model as
|
|
349
|
+
`{"$binary": size, "type": "binary", "uri": "sila://binaries/<id>"}`, and cleaned up when
|
|
350
|
+
their execution leaves the retention window, when the device leaves discovery, or after
|
|
351
|
+
one hour.
|
|
352
|
+
|
|
353
|
+
### Architecture
|
|
354
|
+
|
|
355
|
+
- **`pool`** owns one `sila.client.Client` per device, reconnects with exponential
|
|
356
|
+
backoff, and fires lifecycle events.
|
|
357
|
+
- **`discovery_watcher`** bridges mDNS discovery into pool adoption/removal.
|
|
358
|
+
- **`policy`** makes allow/confirm/deny decisions before any RPC.
|
|
359
|
+
- **`tools/confirm`** turns "confirm" into an MCP elicitation round-trip (or the headless
|
|
360
|
+
policy fallback).
|
|
361
|
+
- **`execution`** tracks observable executions by UUID with retention GC.
|
|
362
|
+
- **`binary`** is the ephemeral value store; **`values`/`schema`** translate between SiLA
|
|
363
|
+
types and JSON.
|
|
364
|
+
- **`server`** assembles the MCP server, core tools, resources, and lifespan; **`cli`**
|
|
365
|
+
runs the transport.
|
|
366
|
+
|
|
367
|
+
See [docs/architecture.md](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/architecture.md)
|
|
368
|
+
for the component table and lifecycle diagram, and the
|
|
369
|
+
[design specification](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/development/2026-11-10-mcp-server-sila-design.md)
|
|
370
|
+
for the full rationale.
|
|
371
|
+
|
|
372
|
+
## Discovery (mDNS / Bonjour)
|
|
373
|
+
|
|
374
|
+
SiLA 2 servers announce themselves with multicast DNS / DNS-based Service Discovery โ the
|
|
375
|
+
same Bonjour/Avahi mechanism printers and Chromecasts use. The bridge consumes those
|
|
376
|
+
announcements to find and configure devices, and (for configured `pinned` endpoints)
|
|
377
|
+
resolves a device's CA certificate from them.
|
|
378
|
+
|
|
379
|
+
### What a SiLA server advertises
|
|
380
|
+
|
|
381
|
+
Over IPv4 multicast (UDP 5353) a server publishes, under the service type
|
|
382
|
+
`_sila._tcp.local.`:
|
|
383
|
+
|
|
384
|
+
| Record | Content |
|
|
385
|
+
|---|---|
|
|
386
|
+
| PTR | `_sila._tcp.local.` โ `<uuid>._sila._tcp.local.` |
|
|
387
|
+
| SRV | host and port of the gRPC endpoint |
|
|
388
|
+
| TXT | `server_name`, `description`, `version`, and โ when TLS is enabled โ the CA certificate as `ca0`, `ca1`, โฆ lines |
|
|
389
|
+
| A | the IPv4 address(es) to connect to |
|
|
390
|
+
|
|
391
|
+
On shutdown the server sends an mDNS "goodbye". Most SiLA 2 SDKs advertise automatically:
|
|
392
|
+
the unitelabs-cdk (used by the copier templates) enables it by default and lets you tune
|
|
393
|
+
it in the `discovery:` section of its config.
|
|
394
|
+
|
|
395
|
+
### What the bridge does with it
|
|
396
|
+
|
|
397
|
+
1. **Browse.** The discovery watcher runs a DNS-SD browser and snapshots the service table
|
|
398
|
+
once a second (the library's change notification is private).
|
|
399
|
+
2. **Adopt.** A new service becomes a device: alias = advertised `server_name`, endpoint =
|
|
400
|
+
SRV/A address and port, TLS = CA-pinned to the TXT certificate. Adoption never blocks
|
|
401
|
+
startup โ a failing connection stays `connecting`/`lost` and is retried with backoff.
|
|
402
|
+
3. **Allowlist.** `discovery.allowlist` (UUIDs or names, case-insensitive) decides access:
|
|
403
|
+
listed โ full access (subject to the policy engine); **empty โ everything is adopted
|
|
404
|
+
read-only** and a warning is logged; not listed โ the service is ignored entirely.
|
|
405
|
+
4. **Forget.** A departed service (goodbye packet) is removed from the pool, its client is
|
|
406
|
+
closed and its stored binaries are released.
|
|
407
|
+
5. **Pin TLS for configured endpoints.** A configured endpoint with `tls = "pinned"` and no
|
|
408
|
+
known CA triggers a one-shot mDNS lookup by the endpoint's name and uses the advertised
|
|
409
|
+
certificate as the trust anchor. If nothing answers, the connection fails with a message
|
|
410
|
+
suggesting `tls = "ca"` plus a `ca_cert` path.
|
|
411
|
+
|
|
412
|
+
Enable it in the configuration file:
|
|
413
|
+
|
|
414
|
+
```toml
|
|
415
|
+
[discovery]
|
|
416
|
+
enabled = true
|
|
417
|
+
allowlist = ["Plate Mover", "Plate Reader"] # names or UUIDs
|
|
418
|
+
```
|
|
419
|
+
|
|
420
|
+
or through the environment:
|
|
421
|
+
|
|
422
|
+
```bash
|
|
423
|
+
MCP_SILA_DISCOVERY_ENABLED=true \
|
|
424
|
+
MCP_SILA_DISCOVERY_ALLOWLIST="Plate Mover,Plate Reader" \
|
|
425
|
+
mcp-server-sila --transport stdio
|
|
426
|
+
```
|
|
427
|
+
|
|
428
|
+
### Practical notes
|
|
429
|
+
|
|
430
|
+
- Discovery needs a shared multicast domain: the same LAN, `network_mode: host` in Docker,
|
|
431
|
+
or an mDNS reflector (e.g. Avahi in bridge mode). A container on Docker's default bridge
|
|
432
|
+
network does not see the lab's multicast.
|
|
433
|
+
- `avahi-browse -rt _sila._tcp` (or `dns-sd -B _sila._tcp`) lists what the network actually
|
|
434
|
+
advertises; the bridge logs `Discovered SiLA server '<name>' (<uuid>) โฆ`.
|
|
435
|
+
- A device can be configured statically and discovered at the same time: a discovered
|
|
436
|
+
service that matches a known endpoint is not adopted twice, and `ca_cert` always wins
|
|
437
|
+
over a discovered CA.
|
|
438
|
+
- A complete worked example โ two copier-generated servers (plate mover and plate reader),
|
|
439
|
+
mDNS-only bridge configuration, and a plate transfer plus read over MCP โ is in
|
|
440
|
+
[examples/sila-labware-transfer](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/examples/sila-labware-transfer/README.md).
|
|
441
|
+
|
|
442
|
+
## Configuration
|
|
443
|
+
|
|
444
|
+
The bridge is 12-factor: a TOML file (`--config PATH` or `$MCP_SILA_CONFIG`) plus
|
|
445
|
+
`MCP_SILA_*` environment variables, which win per key. CLI flags win over both.
|
|
446
|
+
A minimal file:
|
|
447
|
+
|
|
448
|
+
```toml
|
|
449
|
+
[server]
|
|
450
|
+
transport = "stdio" # stdio | streamable-http
|
|
451
|
+
host = "127.0.0.1" # streamable-http only
|
|
452
|
+
port = 8765
|
|
453
|
+
log_level = "INFO"
|
|
454
|
+
|
|
455
|
+
[[endpoint]]
|
|
456
|
+
name = "pump1" # alias used in tool names and references
|
|
457
|
+
address = "192.168.1.40"
|
|
458
|
+
port = 50065
|
|
459
|
+
tls = "pinned" # insecure | pinned | ca | mtls
|
|
460
|
+
# ca_cert = "/srv/certs/lab-ca.pem" # tls = ca | mtls
|
|
461
|
+
# client_cert = "/srv/certs/mcp.pem" # tls = mtls
|
|
462
|
+
# client_key = "/srv/certs/mcp.key"
|
|
463
|
+
```
|
|
464
|
+
|
|
465
|
+
The full key reference, defaults, environment-variable mapping, and validation rules live
|
|
466
|
+
in [docs/configuration.md](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/configuration.md).
|
|
467
|
+
The important defaults:
|
|
468
|
+
|
|
469
|
+
| Setting | Default |
|
|
470
|
+
|---|---|
|
|
471
|
+
| Transport / port | `stdio` ยท `8765` (streamable-http path `/mcp`) |
|
|
472
|
+
| Discovery | disabled; discovered devices read-only until allowlisted |
|
|
473
|
+
| Confirmation | destructive commands and property writes |
|
|
474
|
+
| Rate limits | 10 commands/min and 4 concurrent executions per device |
|
|
475
|
+
| Promotion | enabled, max 200 tools, none auto-promoted |
|
|
476
|
+
| Execution retention | 600 s; `sila_wait_execution` capped at 300 s |
|
|
477
|
+
|
|
478
|
+
## Safety & security
|
|
479
|
+
|
|
480
|
+
The short version; details in
|
|
481
|
+
[docs/security.md](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/security.md).
|
|
482
|
+
|
|
483
|
+
- **Policy engine is the enforcement point.** Every write and command is checked first:
|
|
484
|
+
read-only devices and deny globs reject immediately; destructive commands and property
|
|
485
|
+
writes require confirmation; rate and concurrency limits bound the traffic.
|
|
486
|
+
- **Confirmation degrades to policy, never to "always yes".** Interactive clients get an
|
|
487
|
+
elicitation form (`proceed`/`reason`). Clients that cannot answer (unattended
|
|
488
|
+
orchestrators) get: destructive โ **denied**, non-destructive โ allowed โ and under
|
|
489
|
+
`confirm_all_commands` everything is denied.
|
|
490
|
+
- **Discovered devices are read-only until allowlisted.** mDNS adoption alone never grants
|
|
491
|
+
write or execute access.
|
|
492
|
+
- **TLS modes:**
|
|
493
|
+
|
|
494
|
+
| Mode | Trust anchor | When |
|
|
495
|
+
|---|---|---|
|
|
496
|
+
| `insecure` | none (loopback only โ validated) | local development |
|
|
497
|
+
| `pinned` | the CA in the device's mDNS TXT record (one-shot lookup for configured endpoints) | self-signed lab devices |
|
|
498
|
+
| `ca` | an explicit `ca_cert` path | lab PKI |
|
|
499
|
+
| `mtls` | any of the above plus `client_cert`/`client_key` | devices requiring client auth |
|
|
500
|
+
|
|
501
|
+
`ca_cert` always wins over a discovered CA; PEM contents are never logged or returned.
|
|
502
|
+
- **Bearer token for streamable-http.** Compared in constant time; required whenever the
|
|
503
|
+
host is not loopback; set via config or `MCP_SILA_AUTH_TOKEN` only (never a CLI
|
|
504
|
+
argument).
|
|
505
|
+
- **Untrusted metadata.** Device descriptions are truncated into tool descriptions, the
|
|
506
|
+
server instructions say metadata is data (not instructions), and values are capped
|
|
507
|
+
(4 KB text, 100-element lists, binaries by reference).
|
|
508
|
+
- **Annotations are hints, not security.** `readOnlyHint`/`destructiveHint` inform clients;
|
|
509
|
+
enforcement never depends on them.
|
|
510
|
+
|
|
511
|
+
## CLI reference
|
|
512
|
+
|
|
513
|
+
```
|
|
514
|
+
mcp-server-sila [--config PATH] [--transport {stdio,streamable-http}]
|
|
515
|
+
[--host HOST] [--port PORT] [--log-level LEVEL]
|
|
516
|
+
[--check-config]
|
|
517
|
+
```
|
|
518
|
+
|
|
519
|
+
- `--config PATH` โ TOML file (default `$MCP_SILA_CONFIG`).
|
|
520
|
+
- `--transport`, `--host`, `--port`, `--log-level` โ override the configuration.
|
|
521
|
+
- `--check-config` โ validate, print a redacted summary, exit 0 (or 2 with the aggregated
|
|
522
|
+
error).
|
|
523
|
+
|
|
524
|
+
Exit codes: `0` success, `2` configuration/auth errors.
|
|
525
|
+
|
|
526
|
+
## Development
|
|
527
|
+
|
|
528
|
+
```bash
|
|
529
|
+
uv sync # create the environment (Python 3.13)
|
|
530
|
+
uv run pytest # full suite (in-process SiLA 2 test device)
|
|
531
|
+
uv run ruff check --fix . # lint + import order
|
|
532
|
+
uv run ruff format . # formatting (line length 120)
|
|
533
|
+
uv run zuban check # static types (src/ and tests/)
|
|
534
|
+
uv run --group docs python -m sphinx -b html docs /tmp/docs-build
|
|
535
|
+
uv build # wheel + sdist
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
The suite covers the bridge end-to-end through an in-memory MCP client against a real
|
|
539
|
+
in-process SiLA 2 server: device discovery and reconnection, command execution and error
|
|
540
|
+
mapping, confirmations in both protocol eras, policy decisions, TLS with ephemeral
|
|
541
|
+
certificates, bearer-token auth, binary round-trips, and GC.
|
|
542
|
+
|
|
543
|
+
Project layout: `src/mcp_server_sila/` (package), `tests/` (mirrors it, plus
|
|
544
|
+
`tests/fixtures/sila_device.py`), `docs/` (user documentation; the design and plan live in
|
|
545
|
+
`docs/development/`), `docker/` (image + entrypoint).
|
|
546
|
+
|
|
547
|
+
## Documentation
|
|
548
|
+
|
|
549
|
+
**Rendered documentation:** <https://opensourcelab.gitlab.io/sila/mcp-server-sila/>
|
|
550
|
+
|
|
551
|
+
- [User guide](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/index.md)
|
|
552
|
+
- [Installation](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/installation.md)
|
|
553
|
+
- [Connecting a client](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/connecting.md)
|
|
554
|
+
- [Your first workflow](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/quickstart.md)
|
|
555
|
+
- [Device discovery (mDNS)](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/mdns.md)
|
|
556
|
+
- [Sequences & orchestration](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/guide/x-orchestration.md)
|
|
557
|
+
- [Developer guide](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/index.md)
|
|
558
|
+
- [Tool catalogue](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/tools.md)
|
|
559
|
+
- [Configuration reference](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/configuration.md)
|
|
560
|
+
- [Security model](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/security.md)
|
|
561
|
+
- [Architecture](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/developer/architecture.md)
|
|
562
|
+
- [Design specification](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/docs/development/2026-11-10-mcp-server-sila-design.md)
|
|
563
|
+
|
|
564
|
+
## Status
|
|
565
|
+
|
|
566
|
+
**0.x โ pre-1.0.** All core capabilities are implemented and tested: the core tool set,
|
|
567
|
+
typed tool promotion, policy and confirmation gates, TLS modes, mDNS discovery,
|
|
568
|
+
binary resources, and both transports. Planned for later releases: push-based resource
|
|
569
|
+
subscriptions, full OAuth for streamable-http, and re-adopting in-flight executions after
|
|
570
|
+
a bridge restart.
|
|
571
|
+
|
|
572
|
+
## License
|
|
573
|
+
|
|
574
|
+
MIT โ see [LICENSE](https://gitlab.com/opensourcelab/sila/mcp-server-sila/-/blob/main/LICENSE).
|