labmcp-thermo-iapi 0.1.0__tar.gz

labmcp_thermo_iapi-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+.DS_Store
+*.jsonl
+!**/fixtures/*.jsonl
+.idea/
+.vscode/
+
+CLAUDE.md

labmcp_thermo_iapi-0.1.0/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: labmcp-thermo-iapi
+Version: 0.1.0
+Summary: MCP server adapter for Thermo Fisher Orbitrap mass spectrometers via the licensed Instrument API (IAPI): status, live scans, custom and repeating scans, acquisitions.
+Project-URL: Homepage, https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/thermo-iapi
+Author: K-Dense and LabMCP contributors
+License-Expression: Apache-2.0
+Keywords: iapi,lab-instrument,mass-spectrometry,mcp,orbitrap,proteomics,thermo-fisher
+Requires-Python: >=3.10
+Requires-Dist: labmcp<0.2,>=0.1.2
+Provides-Extra: windows
+Requires-Dist: pythonnet>=3.0.3; (sys_platform == 'win32') and extra == 'windows'
+Description-Content-Type: text/markdown
+
+# Thermo Orbitrap (Instrument API): MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-thermo-iapi -->
+
+Let an AI agent watch and steer a **Thermo Fisher Orbitrap mass spectrometer** in real time: check the instrument mode and vacuum, read the scans streaming off the instrument (filtered by MS order, with the most intense centroids), place validated custom scans and pick up their results, set a repeating scan, and start, pause or stop acquisitions to a raw file. It does this through Thermo's own **Instrument API (IAPI)**.
+
+> [!IMPORTANT]
+> **This is an adapter. It contains no Thermo software.** The IAPI is a Windows .NET API. To use it you need a **signed IAPI software licence agreement with Thermo Fisher Scientific**, with the licence applied to your instrument ([legal requirements](https://github.com/thermofisherlsms/iapi/blob/master/GettingStarted.md#legal-requirements), [licence FAQ](https://github.com/thermofisherlsms/iapi/blob/master/docs/API%20license%20agreement%20FAQs%20r1.3.pdf), [how to obtain a licence](https://github.com/thermofisherlsms/iapi/blob/master/docs/Orbitrap_IAPI_Online_licensing_guidance_material.pdf)). This package **never bundles or downloads** the IAPI assemblies: you point it at the ones you obtained. **It has never been tested on real hardware.** Everything below was developed against the official IAPI interface definitions and examples and a simulator.
+
+| | |
+|---|---|
+| **Package** | `labmcp-thermo-iapi` (install the `[windows]` extra on the instrument PC for pythonnet) |
+| **Instruments** | Orbitrap Tribrid (Fusion, Fusion Lumos, Eclipse, Ascend), Orbitrap Exploris 240/480, Q Exactive family. Not the Orbitrap Astral: Thermo states the Astral line does not support IAPI (as of fall 2025). Not the Exploris 120, which Thermo's examples say doesn't support the API. |
+| **Interfaces** | .NET API on the Windows instrument PC (through [pythonnet](https://pythonnet.github.io/)) |
+| **Protocol** | [Thermo Fisher Instrument API (IAPI)](https://github.com/thermofisherlsms/iapi): interface definitions in `lib/*.xml`, examples in `examples/` |
+| **Status** | 🧪 **simulated**: tested against a simulated Orbitrap (FakeOrbitrap), not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-thermo-iapi --simulate --check
+```
+
+The simulator is an Orbitrap Exploris 480 by default (`--option sim_model=eclipse` or `qexactive-hf` for the others). It runs a synthetic tryptic digest: MS1 survey scans in On mode, a data-dependent top-10 method during an acquisition, custom and repeating scans that come back with their access id, realistic transient and injection times, and a status log with vacuum readings every ~5 s.
+
+## Connect your instrument
+
+On the **Windows instrument PC**, with Tune installed and your IAPI licence applied:
+
+1. **Get the IAPI assemblies** that come with your licence (for a Tribrid: `API-2.0.dll`, `Spectrum-1.0.dll`, `Thermo.TNG.Factory.dll` and `Fusion.API-2.0.dll` for Tune 4.3 or `Fusion.API-1.0.dll` for Tune 4.2 and earlier). Put them in a folder, e.g. `C:\IAPI`.
+2. **Install** Python 3.10+ and the server with pythonnet:
+   ```powershell
+   pip install "labmcp-thermo-iapi[windows]"
+   ```
+3. **Test the connection** (the instrument family picks the connection recipe from the IAPI examples):
+   ```powershell
+   labmcp-thermo-iapi --option instrument=tribrid  --option assembly_dir=C:\IAPI --check   # Fusion/Lumos/Eclipse/Ascend
+   labmcp-thermo-iapi --option instrument=exploris --option assembly_dir=C:\IAPI --check   # Exploris 240/480
+   labmcp-thermo-iapi --option instrument=exactive --option assembly_dir=C:\IAPI --check   # Q Exactive family
+   ```
+
+| Family | How the server connects (from the IAPI repository) | Assemblies expected in `assembly_dir` |
+|---|---|---|
+| `tribrid` | `Factory<IFusionInstrumentAccessContainer>.Create()`, `StartOnlineAccess()`, `Get(1)` | `API-2.0.dll`, `Spectrum-1.0.dll`, `Thermo.TNG.Factory.dll`, `Fusion.API-2.0.dll` or `Fusion.API-1.0.dll` |
+| `exploris` | `HKLM\SOFTWARE\Thermo Exploris` → `DataSystem.xml` (`ApiFileName`, `ApiClassName`) | `Thermo.API.NetStd-1.0.dll`, `Thermo.API.Exploris.NetStd-1.0.dll`, `Thermo.API.Spectrum.NetStd-1.0.dll` (4.3+) or the `Thermo.API-2.0` / `Thermo.API.Exploris-1.0` / `Thermo.API.Spectrum-1.x` set |
+| `exactive` | `HKLM\SOFTWARE\Finnigan\Xcalibur\Devices\Thermo Exactive` (`ApiFileName_Clr2_32_V1`, `ApiClassName_Clr2_32_V1`) | `API-2.0.dll` (or 1.x), `Spectrum-1.0.dll`, `ESAPI-1.1.dll` (or 1.0) |
+
+The server gives a specific message if it is not running on Windows, pythonnet is missing, the folder or an assembly is missing, the IAPI service does not connect (Tune not running), or IAPI refuses a command for lack of a licence.
+
+Other options: `readbacks=Name1;Name2` (instrument values to show in `get_instrument_status`; the tool lists the names your instrument exposes), `exclusive_scans=true` (exclusive rather than cooperative `IScans` access), `runtime=coreclr`, `connect_timeout_s`, `buffer_size` (scans kept in memory, default 500).
+
+## Add to your MCP client
+
+```bash
+claude mcp add orbitrap -- labmcp-thermo-iapi --option instrument=tribrid --option assembly_dir=C:\IAPI
+```
+
+```json
+{
+  "mcpServers": {
+    "orbitrap": {
+      "command": "labmcp-thermo-iapi",
+      "args": ["--option", "instrument=exploris", "--option", "assembly_dir=C:\\IAPI"]
+    }
+  }
+}
+```
+
+Add `--read-only` to let the agent watch scans and status but not place scans or start acquisitions. The stop and cancel tools stay available. To reach the server from another computer, run it with `--transport http --host 0.0.0.0 --port 8000` on the instrument PC and protect that port.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `cancel_custom_scans` | 🛑 safety | Cancel any pending custom scan and its processing delay (IAPI CancelCustomScan). |
+| `cancel_repeating_scan` | 🛑 safety | Cancel the repeating scan set with set_repeating_scan (IAPI CancelRepetition). |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_instrument_status` | 👁 read | Report the instrument model, IAPI service/instrument connection, system mode and state (On/Standby/Off; Running/ReadyToDownload/...), whether an acquisition can be paused or resumed, the IAPI licence where the API exposes it, requested readbacks, the latest scan status log (vacuum, source) and how many scans have arrived. |
+| `get_possible_scan_parameters` | 👁 read | List the scan parameters this instrument accepts for custom and repeating scans (IScans.PossibleParameters): name, allowed range or choices, default and help. The set depends on the model, licence and Tune version. |
+| `get_recent_scans` | 👁 read | Return the most recent scans received from the instrument (oldest first), optionally only one MS order or one custom scan's access id: scan number, MS order, precursor m/z, AGC target, injection time and the most intense centroids. Scans only arrive in On mode. |
+| `pause_acquisition` | 🛑 safety | Pause the running acquisition (IAPI Pause). Fails if the instrument reports it cannot pause. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `resume_acquisition` | ⚠️ hazard | Resume a paused acquisition (IAPI Resume). Sample consumption continues. |
+| `set_repeating_scan` | ⚠️ hazard | Define or replace the scan the instrument repeats when no method or custom scan is running (IAPI CreateRepeatingScan/SetRepetitionScan). Values are validated like submit_custom_scan. Cancel with cancel_repeating_scan. |
+| `start_acquisition` | ⚠️ hazard | Start an acquisition with the instrument's current settings (IAPI StartAcquisition), recording to a raw file. This consumes sample. The instrument must be On; an acquisition must not already be running. Stop it with stop_acquisition. scan_count and until_stopped acquisitions are cancelled automatically after max_acquisition_duration_s. |
+| `stop_acquisition` | 🛑 safety | Stop the running acquisition (IAPI CancelAcquisition), by default also cancelling custom and repeating scans, and optionally switch the instrument to Standby (switch back to On in Tune). Every step is attempted even if an earlier one fails; failures are reported. |
+| `submit_custom_scan` | ⚠️ hazard | Place one custom scan to run next (IAPI CreateCustomScan/SetCustomScan); unset values fall back to the instrument's defaults. Every value is checked against PossibleParameters and the safety limits, and calls are rate-limited, before anything is sent. Fetch the result with wait_for_scan(access_id=running_number). |
+| `wait_for_scan` | 👁 read | Wait for the next scan that arrives after this call (optionally of one MS order, or the result of a custom scan by its access id) and return it. For a custom scan placed with submit_custom_scan, a result that arrived since it was placed is returned at once. Returns found=false after timeout_s if nothing matching arrived (e.g. the instrument is in Standby). |
+<!-- TOOLS:END -->
+
+`get_connection_info`, `get_command_log` and `reconnect` are built into every LabMCP server. Every IAPI control call (with the exact scan values sent) is recorded in the command log.
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_custom_scans_per_minute` | 60 scans/min | Custom scans an agent may place in any 60 s window (server-side rate limit; `reconnect` does not reset it) |
+| `max_injection_time_ms` | 1000 ms | Largest maximum injection time (`MaxIT`) in a custom or repeating scan (every element of a multi-valued `MaxIT`) |
+| `max_acquisition_duration_s` | 7200 s | Longest acquisition an agent may start: a `duration` above it is refused, and `scan_count` / `until_stopped` acquisitions are cancelled automatically when it runs out (wall-clock, pauses included) |
+
+Override at launch: `--limit max_custom_scans_per_minute=600`.
+
+On top of these limits, every custom and repeating scan value is checked against the instrument's own `IScans.PossibleParameters` before anything is sent: the parameter name must exist, numbers must lie inside the instrument's range (for example the m/z range for `FirstMass`/`LastMass`), and choice parameters such as `OrbitrapResolution` must be one of the allowed values. IAPI itself silently ignores illegal values, which is why the server checks first, and why accepted values are sent in the instrument's own spelling (`hcd` goes out as `HCD`, `2.0` for an integer parameter as `2`).
+
+`stop_acquisition` attempts every step (cancel the acquisition, the custom scans, the repeating scan, Standby) even if one fails, and reports what failed.
+
+## Example prompts
+
+- "Is the Orbitrap in On mode and what are the vacuum readings? How many scans came in during the last minute?"
+- "Show me the last 5 MS2 scans with their precursor m/z, injection times and top 10 fragments."
+- "Place a 120k SIM scan on m/z 524.26 with a 10 m/z window and tell me the most intense peaks you see."
+- "Start a 30-minute acquisition to D:\Data\HeLa_test.raw with sample name HeLa 200 ng, then check every few minutes that MS2 scans are still arriving."
+
+## Notes
+
+- **Instrument mode:** scans only arrive in **On** mode, and custom scans and acquisitions need it too. `stop_acquisition(standby=true)` switches to Standby. This server has no tool to switch back to On (do that in Tune).
+- **Custom scans:** values you leave out come from the instrument's defaults, as Thermo documents for `IScanDefinition.Values`. `running_number` comes back as the scan's `access_id` (trailer item `Access Id:`). The server numbers scans automatically if you don't. A custom scan usually finishes before the agent's next tool call, so `wait_for_scan(access_id=...)` also returns a result that arrived after the scan was placed but before the wait started. IAPI leaves the result undefined when several custom scans are placed before the instrument has processed the earlier ones; the rate limit keeps this under control.
+- **Parameter names differ by model and Tune version** (e.g. `Analyzer` on Tribrids). Use `get_possible_scan_parameters` and pass anything that has no named argument through `extra_parameters`.
+- **Scan headers:** `scan_number`, `ms_order`, `scan_mode` and `precursor_mz` come from header keys used in Thermo's examples (`Scan`, `MSOrder`, `ScanMode`, `PrecursorMass[0]`). `master_scan_number`, `agc_target` and `injection_time_ms` are read from the trailer names Thermo raw files use (`Master Scan Number:`, `AGC Target:`, `Ion Injection Time (ms):`). The IAPI repository doesn't document these, so they may be `null` on your instrument. Use `include_header_trailer=true` to see exactly what it sends.
+- **Readbacks:** IAPI has no fixed list of readback names (vacuum gauges, voltages). `get_instrument_status` shows the names from `IInstrumentValues.ValueNames` and the latest scan `StatusLog`, where the vacuum readings usually appear.
+- **Licence check:** on Exploris instruments the server reports whether an API licence is present (`IExplorisInstrumentAccess.Licenses`). Tribrid and Exactive instruments enforce the licence in the instrument service, and a refused command reports it.
+- **Verified API surface:** every IAPI member the pythonnet backend touches is listed with its source file in [`iapi_members.py`](src/labmcp_thermo_iapi/iapi_members.py) (checked against [thermofisherlsms/iapi@c246dcc](https://github.com/thermofisherlsms/iapi/tree/c246dcc8772d03c9c32e9b2fde486e97572c8fbf)). A test fails if the backend uses a name that isn't in that list.
+- **Scan data:** each scan's .NET object is copied and disposed at once, as Thermo's examples require (otherwise the instrument's shared memory stays blocked). Up to 5 000 centroids per scan are kept. `max_centroids` limits what a tool returns, and `get_recent_scans(save_path=...)` writes all kept centroids to a new CSV file (the path must end in `.csv` and must not exist yet: existing files are never overwritten).
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_thermo_iapi-0.1.0/README.md

@@ -0,0 +1,131 @@
+# Thermo Orbitrap (Instrument API): MCP Server
+
+<!-- mcp-name: io.github.K-Dense-AI/labmcp-thermo-iapi -->
+
+Let an AI agent watch and steer a **Thermo Fisher Orbitrap mass spectrometer** in real time: check the instrument mode and vacuum, read the scans streaming off the instrument (filtered by MS order, with the most intense centroids), place validated custom scans and pick up their results, set a repeating scan, and start, pause or stop acquisitions to a raw file. It does this through Thermo's own **Instrument API (IAPI)**.
+
+> [!IMPORTANT]
+> **This is an adapter. It contains no Thermo software.** The IAPI is a Windows .NET API. To use it you need a **signed IAPI software licence agreement with Thermo Fisher Scientific**, with the licence applied to your instrument ([legal requirements](https://github.com/thermofisherlsms/iapi/blob/master/GettingStarted.md#legal-requirements), [licence FAQ](https://github.com/thermofisherlsms/iapi/blob/master/docs/API%20license%20agreement%20FAQs%20r1.3.pdf), [how to obtain a licence](https://github.com/thermofisherlsms/iapi/blob/master/docs/Orbitrap_IAPI_Online_licensing_guidance_material.pdf)). This package **never bundles or downloads** the IAPI assemblies: you point it at the ones you obtained. **It has never been tested on real hardware.** Everything below was developed against the official IAPI interface definitions and examples and a simulator.
+
+| | |
+|---|---|
+| **Package** | `labmcp-thermo-iapi` (install the `[windows]` extra on the instrument PC for pythonnet) |
+| **Instruments** | Orbitrap Tribrid (Fusion, Fusion Lumos, Eclipse, Ascend), Orbitrap Exploris 240/480, Q Exactive family. Not the Orbitrap Astral: Thermo states the Astral line does not support IAPI (as of fall 2025). Not the Exploris 120, which Thermo's examples say doesn't support the API. |
+| **Interfaces** | .NET API on the Windows instrument PC (through [pythonnet](https://pythonnet.github.io/)) |
+| **Protocol** | [Thermo Fisher Instrument API (IAPI)](https://github.com/thermofisherlsms/iapi): interface definitions in `lib/*.xml`, examples in `examples/` |
+| **Status** | 🧪 **simulated**: tested against a simulated Orbitrap (FakeOrbitrap), not yet verified on hardware. [Report a hardware test](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml) |
+
+## Try it without hardware
+
+```bash
+uvx labmcp-thermo-iapi --simulate --check
+```
+
+The simulator is an Orbitrap Exploris 480 by default (`--option sim_model=eclipse` or `qexactive-hf` for the others). It runs a synthetic tryptic digest: MS1 survey scans in On mode, a data-dependent top-10 method during an acquisition, custom and repeating scans that come back with their access id, realistic transient and injection times, and a status log with vacuum readings every ~5 s.
+
+## Connect your instrument
+
+On the **Windows instrument PC**, with Tune installed and your IAPI licence applied:
+
+1. **Get the IAPI assemblies** that come with your licence (for a Tribrid: `API-2.0.dll`, `Spectrum-1.0.dll`, `Thermo.TNG.Factory.dll` and `Fusion.API-2.0.dll` for Tune 4.3 or `Fusion.API-1.0.dll` for Tune 4.2 and earlier). Put them in a folder, e.g. `C:\IAPI`.
+2. **Install** Python 3.10+ and the server with pythonnet:
+   ```powershell
+   pip install "labmcp-thermo-iapi[windows]"
+   ```
+3. **Test the connection** (the instrument family picks the connection recipe from the IAPI examples):
+   ```powershell
+   labmcp-thermo-iapi --option instrument=tribrid  --option assembly_dir=C:\IAPI --check   # Fusion/Lumos/Eclipse/Ascend
+   labmcp-thermo-iapi --option instrument=exploris --option assembly_dir=C:\IAPI --check   # Exploris 240/480
+   labmcp-thermo-iapi --option instrument=exactive --option assembly_dir=C:\IAPI --check   # Q Exactive family
+   ```
+
+| Family | How the server connects (from the IAPI repository) | Assemblies expected in `assembly_dir` |
+|---|---|---|
+| `tribrid` | `Factory<IFusionInstrumentAccessContainer>.Create()`, `StartOnlineAccess()`, `Get(1)` | `API-2.0.dll`, `Spectrum-1.0.dll`, `Thermo.TNG.Factory.dll`, `Fusion.API-2.0.dll` or `Fusion.API-1.0.dll` |
+| `exploris` | `HKLM\SOFTWARE\Thermo Exploris` → `DataSystem.xml` (`ApiFileName`, `ApiClassName`) | `Thermo.API.NetStd-1.0.dll`, `Thermo.API.Exploris.NetStd-1.0.dll`, `Thermo.API.Spectrum.NetStd-1.0.dll` (4.3+) or the `Thermo.API-2.0` / `Thermo.API.Exploris-1.0` / `Thermo.API.Spectrum-1.x` set |
+| `exactive` | `HKLM\SOFTWARE\Finnigan\Xcalibur\Devices\Thermo Exactive` (`ApiFileName_Clr2_32_V1`, `ApiClassName_Clr2_32_V1`) | `API-2.0.dll` (or 1.x), `Spectrum-1.0.dll`, `ESAPI-1.1.dll` (or 1.0) |
+
+The server gives a specific message if it is not running on Windows, pythonnet is missing, the folder or an assembly is missing, the IAPI service does not connect (Tune not running), or IAPI refuses a command for lack of a licence.
+
+Other options: `readbacks=Name1;Name2` (instrument values to show in `get_instrument_status`; the tool lists the names your instrument exposes), `exclusive_scans=true` (exclusive rather than cooperative `IScans` access), `runtime=coreclr`, `connect_timeout_s`, `buffer_size` (scans kept in memory, default 500).
+
+## Add to your MCP client
+
+```bash
+claude mcp add orbitrap -- labmcp-thermo-iapi --option instrument=tribrid --option assembly_dir=C:\IAPI
+```
+
+```json
+{
+  "mcpServers": {
+    "orbitrap": {
+      "command": "labmcp-thermo-iapi",
+      "args": ["--option", "instrument=exploris", "--option", "assembly_dir=C:\\IAPI"]
+    }
+  }
+}
+```
+
+Add `--read-only` to let the agent watch scans and status but not place scans or start acquisitions. The stop and cancel tools stay available. To reach the server from another computer, run it with `--transport http --host 0.0.0.0 --port 8000` on the instrument PC and protect that port.
+
+## Tools
+
+<!-- TOOLS:START -->
+| Tool | Kind | Description |
+|---|---|---|
+| `cancel_custom_scans` | 🛑 safety | Cancel any pending custom scan and its processing delay (IAPI CancelCustomScan). |
+| `cancel_repeating_scan` | 🛑 safety | Cancel the repeating scan set with set_repeating_scan (IAPI CancelRepetition). |
+| `get_command_log` | 👁 read | Return the most recent raw commands sent to / replies received from the instrument (newest last). Useful for debugging and for recording what was done. |
+| `get_connection_info` | 👁 read | Report which instrument is connected (identity, address, simulated or real), whether the server is read-only, and the active safety limits. Call this first. |
+| `get_instrument_status` | 👁 read | Report the instrument model, IAPI service/instrument connection, system mode and state (On/Standby/Off; Running/ReadyToDownload/...), whether an acquisition can be paused or resumed, the IAPI licence where the API exposes it, requested readbacks, the latest scan status log (vacuum, source) and how many scans have arrived. |
+| `get_possible_scan_parameters` | 👁 read | List the scan parameters this instrument accepts for custom and repeating scans (IScans.PossibleParameters): name, allowed range or choices, default and help. The set depends on the model, licence and Tune version. |
+| `get_recent_scans` | 👁 read | Return the most recent scans received from the instrument (oldest first), optionally only one MS order or one custom scan's access id: scan number, MS order, precursor m/z, AGC target, injection time and the most intense centroids. Scans only arrive in On mode. |
+| `pause_acquisition` | 🛑 safety | Pause the running acquisition (IAPI Pause). Fails if the instrument reports it cannot pause. |
+| `reconnect` | 🛑 safety | Close and re-open the connection to the instrument (e.g. after it was power cycled or a cable was re-plugged). |
+| `resume_acquisition` | ⚠️ hazard | Resume a paused acquisition (IAPI Resume). Sample consumption continues. |
+| `set_repeating_scan` | ⚠️ hazard | Define or replace the scan the instrument repeats when no method or custom scan is running (IAPI CreateRepeatingScan/SetRepetitionScan). Values are validated like submit_custom_scan. Cancel with cancel_repeating_scan. |
+| `start_acquisition` | ⚠️ hazard | Start an acquisition with the instrument's current settings (IAPI StartAcquisition), recording to a raw file. This consumes sample. The instrument must be On; an acquisition must not already be running. Stop it with stop_acquisition. scan_count and until_stopped acquisitions are cancelled automatically after max_acquisition_duration_s. |
+| `stop_acquisition` | 🛑 safety | Stop the running acquisition (IAPI CancelAcquisition), by default also cancelling custom and repeating scans, and optionally switch the instrument to Standby (switch back to On in Tune). Every step is attempted even if an earlier one fails; failures are reported. |
+| `submit_custom_scan` | ⚠️ hazard | Place one custom scan to run next (IAPI CreateCustomScan/SetCustomScan); unset values fall back to the instrument's defaults. Every value is checked against PossibleParameters and the safety limits, and calls are rate-limited, before anything is sent. Fetch the result with wait_for_scan(access_id=running_number). |
+| `wait_for_scan` | 👁 read | Wait for the next scan that arrives after this call (optionally of one MS order, or the result of a custom scan by its access id) and return it. For a custom scan placed with submit_custom_scan, a result that arrived since it was placed is returned at once. Returns found=false after timeout_s if nothing matching arrived (e.g. the instrument is in Standby). |
+<!-- TOOLS:END -->
+
+`get_connection_info`, `get_command_log` and `reconnect` are built into every LabMCP server. Every IAPI control call (with the exact scan values sent) is recorded in the command log.
+
+## Safety limits
+
+| Limit | Default | Meaning |
+|---|---|---|
+| `max_custom_scans_per_minute` | 60 scans/min | Custom scans an agent may place in any 60 s window (server-side rate limit; `reconnect` does not reset it) |
+| `max_injection_time_ms` | 1000 ms | Largest maximum injection time (`MaxIT`) in a custom or repeating scan (every element of a multi-valued `MaxIT`) |
+| `max_acquisition_duration_s` | 7200 s | Longest acquisition an agent may start: a `duration` above it is refused, and `scan_count` / `until_stopped` acquisitions are cancelled automatically when it runs out (wall-clock, pauses included) |
+
+Override at launch: `--limit max_custom_scans_per_minute=600`.
+
+On top of these limits, every custom and repeating scan value is checked against the instrument's own `IScans.PossibleParameters` before anything is sent: the parameter name must exist, numbers must lie inside the instrument's range (for example the m/z range for `FirstMass`/`LastMass`), and choice parameters such as `OrbitrapResolution` must be one of the allowed values. IAPI itself silently ignores illegal values, which is why the server checks first, and why accepted values are sent in the instrument's own spelling (`hcd` goes out as `HCD`, `2.0` for an integer parameter as `2`).
+
+`stop_acquisition` attempts every step (cancel the acquisition, the custom scans, the repeating scan, Standby) even if one fails, and reports what failed.
+
+## Example prompts
+
+- "Is the Orbitrap in On mode and what are the vacuum readings? How many scans came in during the last minute?"
+- "Show me the last 5 MS2 scans with their precursor m/z, injection times and top 10 fragments."
+- "Place a 120k SIM scan on m/z 524.26 with a 10 m/z window and tell me the most intense peaks you see."
+- "Start a 30-minute acquisition to D:\Data\HeLa_test.raw with sample name HeLa 200 ng, then check every few minutes that MS2 scans are still arriving."
+
+## Notes
+
+- **Instrument mode:** scans only arrive in **On** mode, and custom scans and acquisitions need it too. `stop_acquisition(standby=true)` switches to Standby. This server has no tool to switch back to On (do that in Tune).
+- **Custom scans:** values you leave out come from the instrument's defaults, as Thermo documents for `IScanDefinition.Values`. `running_number` comes back as the scan's `access_id` (trailer item `Access Id:`). The server numbers scans automatically if you don't. A custom scan usually finishes before the agent's next tool call, so `wait_for_scan(access_id=...)` also returns a result that arrived after the scan was placed but before the wait started. IAPI leaves the result undefined when several custom scans are placed before the instrument has processed the earlier ones; the rate limit keeps this under control.
+- **Parameter names differ by model and Tune version** (e.g. `Analyzer` on Tribrids). Use `get_possible_scan_parameters` and pass anything that has no named argument through `extra_parameters`.
+- **Scan headers:** `scan_number`, `ms_order`, `scan_mode` and `precursor_mz` come from header keys used in Thermo's examples (`Scan`, `MSOrder`, `ScanMode`, `PrecursorMass[0]`). `master_scan_number`, `agc_target` and `injection_time_ms` are read from the trailer names Thermo raw files use (`Master Scan Number:`, `AGC Target:`, `Ion Injection Time (ms):`). The IAPI repository doesn't document these, so they may be `null` on your instrument. Use `include_header_trailer=true` to see exactly what it sends.
+- **Readbacks:** IAPI has no fixed list of readback names (vacuum gauges, voltages). `get_instrument_status` shows the names from `IInstrumentValues.ValueNames` and the latest scan `StatusLog`, where the vacuum readings usually appear.
+- **Licence check:** on Exploris instruments the server reports whether an API licence is present (`IExplorisInstrumentAccess.Licenses`). Tribrid and Exactive instruments enforce the licence in the instrument service, and a refused command reports it.
+- **Verified API surface:** every IAPI member the pythonnet backend touches is listed with its source file in [`iapi_members.py`](src/labmcp_thermo_iapi/iapi_members.py) (checked against [thermofisherlsms/iapi@c246dcc](https://github.com/thermofisherlsms/iapi/tree/c246dcc8772d03c9c32e9b2fde486e97572c8fbf)). A test fails if the backend uses a name that isn't in that list.
+- **Scan data:** each scan's .NET object is copied and disposed at once, as Thermo's examples require (otherwise the instrument's shared memory stays blocked). Up to 5 000 centroids per scan are kept. `max_centroids` limits what a tool returns, and `get_recent_scans(save_path=...)` writes all kept centroids to a new CSV file (the path must end in `.csv` and must not exist yet: existing files are never overwritten).
+
+## Hardware verification
+
+| Model | Firmware | Interface | Verified by | Date |
+|---|---|---|---|---|
+| *none yet: [be the first](https://github.com/K-Dense-AI/lab-instrument-mcps/issues/new?template=hardware-verification.yml)* | | | | |

labmcp_thermo_iapi-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "labmcp-thermo-iapi"
+version = "0.1.0"
+description = "MCP server adapter for Thermo Fisher Orbitrap mass spectrometers via the licensed Instrument API (IAPI): status, live scans, custom and repeating scans, acquisitions."
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.10"
+authors = [{ name = "K-Dense and LabMCP contributors" }]
+keywords = ["mcp", "lab-instrument", "mass-spectrometry", "orbitrap", "thermo-fisher", "iapi", "proteomics"]
+dependencies = ["labmcp>=0.1.2,<0.2"]
+
+[project.optional-dependencies]
+# The IAPI is a Windows .NET API; the IAPI assemblies themselves are licensed by Thermo Fisher
+# and are NOT a dependency: users supply them with --option assembly_dir=...
+windows = ["pythonnet>=3.0.3; sys_platform == 'win32'"]
+
+[project.scripts]
+labmcp-thermo-iapi = "labmcp_thermo_iapi.server:main"
+
+[project.urls]
+Homepage = "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/thermo-iapi"
+
+[tool.labmcp]
+name = "Thermo Orbitrap (Instrument API)"
+domain = "chemistry"
+category = "Mass spectrometry"
+vendor = "Thermo Fisher Scientific"
+models = ["Orbitrap Fusion", "Orbitrap Fusion Lumos", "Orbitrap Eclipse", "Orbitrap Ascend", "Orbitrap Exploris 240", "Orbitrap Exploris 480", "Q Exactive family"]
+interfaces = [".NET API (Windows)"]
+protocol = "Thermo Fisher Instrument API (IAPI)"
+summary = "Adapter for the licensed Thermo IAPI (bring your own assemblies): instrument status, live scan buffer with MS-order filters, validated and rate-limited custom and repeating scans, acquisitions to raw files, stop/cancel."
+status = "simulated"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/labmcp_thermo_iapi"]

labmcp_thermo_iapi-0.1.0/server.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.K-Dense-AI/labmcp-thermo-iapi",
+  "title": "Thermo Orbitrap (Instrument API)",
+  "description": "MCP server adapter for Thermo Fisher Orbitrap mass spectrometers via the licensed Instrument API (IA",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/K-Dense-AI/lab-instrument-mcps",
+    "source": "github",
+    "subfolder": "servers/chemistry/thermo-iapi"
+  },
+  "websiteUrl": "https://github.com/K-Dense-AI/lab-instrument-mcps/tree/main/servers/chemistry/thermo-iapi",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "registryBaseUrl": "https://pypi.org",
+      "identifier": "labmcp-thermo-iapi",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "LABMCP_ADDRESS",
+          "description": "Instrument address, e.g. serial:///dev/ttyUSB0 or tcp://192.168.1.50:5025",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_SIMULATE",
+          "description": "Set to 1 to use the built-in simulator (no hardware)",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_READ_ONLY",
+          "description": "Set to 1 to disable all state-changing tools",
+          "isRequired": false
+        },
+        {
+          "name": "LABMCP_LIMITS",
+          "description": "Safety limit overrides, e.g. max_temperature_c=80",
+          "isRequired": false
+        }
+      ]
+    }
+  ]
+}

labmcp_thermo_iapi-0.1.0/src/labmcp_thermo_iapi/__init__.py

@@ -0,0 +1 @@
+"""LabMCP server for Thermo Orbitrap (Instrument API)."""

labmcp_thermo_iapi-0.1.0/src/labmcp_thermo_iapi/backend.py

@@ -0,0 +1,128 @@
+"""The backend interface the driver talks to, and the plain-Python records it exchanges.
+
+Two implementations exist:
+
+* :class:`labmcp_thermo_iapi.pythonnet_backend.PythonNetBackend` loads the scientist's own,
+  licensed Thermo Fisher Instrument API (IAPI) assemblies through pythonnet on the Windows
+  instrument PC.
+* :class:`labmcp_thermo_iapi.simulator.FakeOrbitrap` emits synthetic scans for ``--simulate``
+  and CI.
+
+Nothing in here imports .NET. Everything that crosses the backend boundary is a plain Python
+value, so the driver, the tools and the tests are identical for both backends.
+"""
+
+from __future__ import annotations
+
+import abc
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+AcquisitionMode = Literal["duration", "scan_count", "until_stopped"]
+
+
+@dataclass(frozen=True)
+class ParameterDescription:
+    """One entry of ``IScans.PossibleParameters`` (``IParameterDescription``).
+
+    ``selection`` follows the grammar documented on ``IParameterDescription.Selection`` in
+    lib/API-2.0.xml: ``""`` (no argument), ``"string"`` (free text), ``"num1-num2"`` (integer
+    range, inclusive), ``"num1.frac-num2.frac"`` (float range, inclusive) or
+    ``"sel1,sel2,..."`` (one of the listed values).
+    """
+
+    name: str
+    selection: str
+    default_value: str = ""
+    help: str = ""
+
+
+@dataclass
+class Centroid:
+    mz: float
+    intensity: float
+    charge: int | None = None
+
+
+@dataclass
+class ScanRecord:
+    """A scan copied out of ``MsScanEventArgs.GetScan()`` before the .NET object is disposed."""
+
+    received_at: str  # UTC ISO 8601, stamped by the backend when MsScanArrived fired
+    header: dict[str, str]
+    trailer: dict[str, str]
+    centroid_count: int
+    centroids: list[Centroid]  # sorted by decreasing intensity, capped by the backend
+    status_log: dict[str, str] = field(default_factory=dict)
+    sequence: int = 0  # assigned by the driver: arrival order since connect
+
+
+class OrbitrapBackend(abc.ABC):
+    """What the driver needs from an Orbitrap, expressed in IAPI terms.
+
+    Every method maps onto IAPI members listed in :mod:`labmcp_thermo_iapi.iapi_members`
+    (see :class:`~labmcp_thermo_iapi.pythonnet_backend.PythonNetBackend` for the mapping).
+    Control methods return what the IAPI returns: ``True`` when the command was sent to the
+    instrument, ``False`` otherwise.
+    """
+
+    #: "simulator" or "pythonnet"
+    kind: str = "abstract"
+
+    @abc.abstractmethod
+    def open(self, on_scan: Callable[[ScanRecord], None]) -> None:
+        """Connect, and call ``on_scan`` for every scan (from a background thread)."""
+
+    @abc.abstractmethod
+    def identify(self) -> dict[str, str]: ...
+
+    @abc.abstractmethod
+    def status(self) -> dict[str, Any]:
+        """Keys: service_connected, instrument_connected, instrument_name, instrument_id,
+        system_mode, system_state, can_pause, can_resume, api_license (True/False/None),
+        readbacks {name: {value, unit, status}}, readback_names [str]."""
+
+    @abc.abstractmethod
+    def possible_parameters(self) -> list[ParameterDescription]: ...
+
+    @abc.abstractmethod
+    def start_acquisition(
+        self,
+        mode: AcquisitionMode,
+        *,
+        duration_s: float | None,
+        scan_count: int | None,
+        raw_file_path: str | None,
+        sample_name: str | None,
+        comment: str | None,
+    ) -> None: ...
+
+    @abc.abstractmethod
+    def pause_acquisition(self) -> None: ...
+
+    @abc.abstractmethod
+    def resume_acquisition(self) -> None: ...
+
+    @abc.abstractmethod
+    def cancel_acquisition(self) -> None: ...
+
+    @abc.abstractmethod
+    def set_standby(self) -> None: ...
+
+    @abc.abstractmethod
+    def set_custom_scan(
+        self, values: dict[str, str], *, running_number: int, single_processing_delay_s: float
+    ) -> bool: ...
+
+    @abc.abstractmethod
+    def cancel_custom_scan(self) -> bool: ...
+
+    @abc.abstractmethod
+    def set_repeating_scan(self, values: dict[str, str], *, running_number: int) -> bool: ...
+
+    @abc.abstractmethod
+    def cancel_repeating_scan(self) -> bool: ...
+
+    @abc.abstractmethod
+    def close(self) -> None: ...