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.
Files changed (26) hide show
  1. mcp_server_sila-0.0.3/PKG-INFO +574 -0
  2. mcp_server_sila-0.0.3/README.md +548 -0
  3. mcp_server_sila-0.0.3/pyproject.toml +242 -0
  4. mcp_server_sila-0.0.3/pyproject.toml.orig +247 -0
  5. mcp_server_sila-0.0.3/src/mcp_server_sila/__init__.py +6 -0
  6. mcp_server_sila-0.0.3/src/mcp_server_sila/__main__.py +8 -0
  7. mcp_server_sila-0.0.3/src/mcp_server_sila/binary.py +236 -0
  8. mcp_server_sila-0.0.3/src/mcp_server_sila/cli.py +144 -0
  9. mcp_server_sila-0.0.3/src/mcp_server_sila/client_api.py +520 -0
  10. mcp_server_sila-0.0.3/src/mcp_server_sila/config.py +614 -0
  11. mcp_server_sila-0.0.3/src/mcp_server_sila/discovery_watcher.py +234 -0
  12. mcp_server_sila-0.0.3/src/mcp_server_sila/execution.py +366 -0
  13. mcp_server_sila-0.0.3/src/mcp_server_sila/logging_setup.py +19 -0
  14. mcp_server_sila-0.0.3/src/mcp_server_sila/policy.py +242 -0
  15. mcp_server_sila-0.0.3/src/mcp_server_sila/pool.py +502 -0
  16. mcp_server_sila-0.0.3/src/mcp_server_sila/promote.py +675 -0
  17. mcp_server_sila-0.0.3/src/mcp_server_sila/py.typed +0 -0
  18. mcp_server_sila-0.0.3/src/mcp_server_sila/schema.py +227 -0
  19. mcp_server_sila-0.0.3/src/mcp_server_sila/security.py +193 -0
  20. mcp_server_sila-0.0.3/src/mcp_server_sila/server.py +511 -0
  21. mcp_server_sila-0.0.3/src/mcp_server_sila/tools/__init__.py +79 -0
  22. mcp_server_sila-0.0.3/src/mcp_server_sila/tools/confirm.py +322 -0
  23. mcp_server_sila-0.0.3/src/mcp_server_sila/tools/core.py +504 -0
  24. mcp_server_sila-0.0.3/src/mcp_server_sila/tools/dynamic.py +100 -0
  25. mcp_server_sila-0.0.3/src/mcp_server_sila/tools/exec_tools.py +120 -0
  26. 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).