design.md

Design guide

简体中文 · User guide · Home

Laboratories expose different kinds of control. One facility accepts a complete experimental workflow; another exposes individual instrument functions. SCP-Lab gives callers a shared way to discover that control, request work, and interpret the returned evidence. The aim is to reuse integrations while preserving the experimental meaning of each operation.

Five levels of exposed control

An access level describes the choices available through a capability. Every level can have adjustable parameters. The level follows the published interface, so one instrument can offer capabilities at several levels.

Level	Access	Caller controls	Example
L1	Established workflow	Inputs and conditions of a fixed workflow	Select a synthesis recipe and reaction temperature
L2	Configurable workflow	Selection and arrangement of exposed workflow steps	Arrange addition, reaction, and measurement stages
L3	Single-device function	Inputs and settings of a function with a predefined internal sequence	Request a liquid transfer or plate read
L4	Internal device operations	Selection, ordering, or repetition of operations inside a device function	Arrange aspiration and dispensing operations
L5	Actuator action	Exposed motion or actuation commands	Specify a pose, rail position, or gripper action

For example, a plate reader can expose a fixed shake-and-read function at L3 and a caller-configurable shake–read–shake–read procedure at L4. Reusing a capability also requires matching its input schema, compatible samples and containers, operating conditions, and completion criteria.

The bundled device functions are primarily L3. The multi-device example sequences calls in the client; a published L2 capability would accept and execute a configurable workflow as its own service. Classify a capability by the control exposed to its caller, rather than the internal commands generated by its implementation.

Capability, state, and execution record

These objects answer different questions:

Object	Question	Key contents
Capability in a DeviceDescriptor	What can I request?	Input/result schemas, units, defaults, access level, and completion criteria
DeviceState	What is the instance's current condition?	Availability, occupancy, and optional observations with source and time
ExecutionRecord	What happened to this request?	Submitted and effective arguments, versions, status, progress, result, and evidence

For a temperature hold, the capability describes the accepted range and units. A request supplies the target and duration. State may report a measured temperature if the backend provides that observation. The execution record identifies the settings used and the evidence supporting completion.

This separation lets applications share discovery and lifecycle handling while retaining device-specific parameters and results. The protocol reference defines the exact fields.

From request to the next experimental step

Discover instance → inspect capability → submit explicit request
                                               ↓
                                      accepted (run_id)
                                               ↓
                                    poll status and progress
                                               ↓
                              inspect outcome and completion evidence
                                               ↓
                           caller checks conditions for the next step

Acceptance provides a task identifier. Completion evidence explains the reported outcome: schema acceptance, a mock trace, a simulator run log, or physical observations. Device release is recorded separately because an operation may finish while equipment still requires attention.

To coordinate dependent work, the calling application checks the sample, container, location, and shared resources before starting the next operation. For example, a plate read depends on preparation completing, the correct plate arriving, and the reader becoming available. Task and sample references connect that result to the experiment that produced it.

MCP compatibility

SCP-Lab defines capability descriptions, device state, and execution records as data structures independent of the access interface. Its MCP-compatible interface exposes capability queries, task submission, and status and result queries as tools that existing clients can call, preserving the SCP-Lab definitions of parameters, state, and completion evidence.

This repository provides local stdio access. See the application integration guide for client configuration and the protocol reference for tool responses and runtime behavior.

Apply the design

• Call a capability, then connect an application.
• Configure or develop a backend to expose a device interface.
• Use the protocol reference for field-level behavior and the device catalog to select a runnable example.