LC-MS Worklist Builder

LC-MS ワークリストビルダー（MassLynx、SCIEX OS、MassHunter、Xcalibur）：MCP サーバー

AI エージェントが LC-MS のサンプルキュー（ワークリスト、シーケンス、バッチ）を作成し、Waters MassLynx、SCIEX OS、Agilent MassHunter Acquisition、Thermo Xcalibur 用のインポートファイルとしてエクスポートできます。エージェントはトレイ上にサンプルを配置し、ブランクや QC を挿入し、記録されたシードを使って実行順序をランダム化し、リストに誤りがないか確認し、既存のファイルを別ベンダー用に変換して、人がインポートできるファイルを書き出せます。使用するのは文書化されたインポート形式のみです。測定を開始することはなく、質量分析計との通信も行いません。

パッケージ	labmcp-ms-worklist
ソフトウェア	Waters MassLynx 4.x、SCIEX OS、Agilent MassHunter Acquisition（LC/TQ、LC/Q-TOF）、Thermo Xcalibur 2.2 以降
インターフェース	ファイル（インポートファイルを 1 つの出力フォルダーに CSV/TXT 形式で書き込みます）
プロトコル	ベンダーのサンプルリストインポート形式（出典については 形式 を参照）
ステータス	🧪 シミュレーション済み：ゴールデンファイルと往復テストで検証済みですが、まだ当方ではベンダーソフトウェアへのインポートを試していません。テストを報告する

機器なしで試す

uvx labmcp-ms-worklist --simulate --check

--simulate を指定すると、一時的な出力フォルダーが使われ、サーバーの停止時に削除されます。それ以外はすべて同じコードです。

セットアップ

「機器のアドレス」は、ワークリストファイルを書き込む出力フォルダーです（デフォルトは ./worklists で、存在しない場合は作成されます）。

uvx labmcp-ms-worklist --address "D:\Worklists" --check        # Windows acquisition PC or a shared drive
uvx labmcp-ms-worklist --address ~/lcms/worklists --check        # macOS / Linux, then copy the files over

• サーバーが読み書きするのはこのフォルダー内のみです。..、別の場所を指す絶対パス、フォルダー外を指すシンボリックリンクは拒否します。エージェントが overwrite=true を指定しない限り、既存ファイルを上書きすることはありません。
• 既存のファイルを編集または変換する場合や、ベンダーテンプレートを使う場合は、まずこのフォルダーにコピーしてください。
• ベンダーの説明書に、ご利用の環境での動作として記載されている場合に限り、--address に測定ソフトウェアが監視するフォルダーを指定してください。それ以外の場合は、ファイルを手動でインポートしてください（手順は以下を参照）。

MCP クライアントへの追加

Claude Code

claude mcp add ms-worklist -- uvx labmcp-ms-worklist --address ~/lcms/worklists

Claude Desktop / Cursor / Windsurf

{
  "mcpServers": {
    "ms-worklist": { "command": "uvx", "args": ["labmcp-ms-worklist", "--address", "/path/to/worklists"] }
  }
}

--read-only を指定すると、情報を確認するツール（list_formats、validate_worklist、import_worklist、get_worklist、list_worklists）のみが有効になります。

ツール

ツール	種類	説明
add_samples	🎛 制御	下書きワークリストにサンプルを追加します（ワークリストのデフォルト設定と自動位置が適用されます。空試料／QC／ランダム化の計画がある場合は、同じシードを使って、長くなったリストに再適用されます）。
create_worklist	🎛 制御	サンプルリストとデフォルト設定（メソッド、注入量、トレイ位置、データファイルの命名パターン）から、メモリ上に下書きワークリストを作成します。export_worklistを実行するまで、ディスクには何も書き込まれません。max_injection_volume_ulの上限を超える注入量は拒否されます。
export_worklist	🎛 制御	下書きを検証し、ベンダーのインポートファイルを出力フォルダーに書き込みます。パス、先頭行のプレビュー、警告、インポート手順を返します。検証でエラーが見つかった場合、またはファイルがすでに存在する場合（overwrite=trueを指定した場合を除く）は拒否されます。測定は開始されません。担当者がファイルを測定ソフトウェアにインポートします。
get_command_log	👁 読み取り	装置に送信した直近の生コマンドと、受信した返信を返します（新しいものが最後）。デバッグや実行内容の記録に便利です。
get_connection_info	👁 読み取り	接続されている装置（識別情報、アドレス、シミュレーションか実機か）、サーバーが読み取り専用かどうか、適用中の安全上限を報告します。最初に呼び出してください。
get_worklist	👁 読み取り	下書きワークリストを実行順に表示し、デフォルト設定、空試料／QCの計画、ランダム化シード、および適用された操作の履歴を示します。
import_worklist	👁 読み取り	出力フォルダーにある既存のMassLynx、SCIEX OS、MassHunter、またはXcaliburのインポートファイルを解析し、検証、編集、または別のベンダー形式でのエクスポートができるよう、下書きに取り込みます。中立的な対応項目がない列は、そのまま保持されます。読み取りのみで、何も書き込みません。
insert_qc_blanks	🎛 制御	空試料とQC注入を挿入し、任意で実行順をランダム化します（シードは記録されます）。以前の計画を置き換えるため、再度呼び出しても空試料は重複しません。サンプルを追加するたびに計画が再適用され、データファイル名は新しい実行順に従います。
list_formats	👁 読み取り	対応しているインポート形式（Waters MassLynx、SCIEX OS、Agilent MassHunter、Thermo Xcalibur）について、列、必須フィールド、サンプルタイプ名、ファイル拡張子、インポート方法、ベンダーのドキュメントで検証済みの事項と仮定している事項、参照元URLを一覧表示します。位置パターンと、調査済みだが実装されていない形式も一覧表示します。
list_worklists	👁 読み取り	メモリ上の下書きワークリストと出力フォルダー内のファイルを一覧表示します。
reconnect	🛑 安全	装置との接続を閉じて、再度開きます（装置の電源を入れ直した後やケーブルを再接続した後など）。
validate_worklist	👁 読み取り	下書きを対象形式に照らしてチェックします。必須フィールド、データファイル名の重複、Windowsでファイル名に使用できない文字、トレイ／バイアルの位置形式とプレート範囲、注入量（0より大きく、max_injection_volume_ulの上限以下）、メソッドファイルの拡張子を確認します。エラーがあるとエクスポートはできませんが、警告ではエクスポートできます。

get_connection_info、get_command_log、reconnectは、すべてのLabMCPサーバーに組み込まれています。危険なツールはありません。ここに記載されている機能では、何かを移動、加熱、注入、測定することはありません。サーバーはファイルを書き込むだけです。制御ツールはメモリ上の下書きを変更するか、ファイルを書き込みます。--read-onlyを指定すると、これらのツールは非表示になります。

一般的な手順：create_worklist → add_samples（任意）→ insert_qc_blanks → validate_worklist → export_worklistの後、ベンダーソフトウェアでファイルをインポートします。

形式

以下の表では、ベンダーのドキュメントに記載されている内容（検証済み）と、サーバーが仮定している内容を分けています。list_formatsは、同じ情報をエージェントに返します。ご使用のソフトウェアバージョンでのヘッダーを確実に把握するには、ご自身のシステムから空のバッチ、シーケンス、またはワークリストをエクスポートし、出力フォルダーに置いて、template_pathとしてexport_worklistに渡してください。サーバーはそのヘッダーと区切り文字をそのまま書き込みます。

Waters MassLynx：サンプルリストワークシート（waters_masslynx）

• インポート： Sample list > File > Import Worksheet を選択し、File of Type で「Comma Delimited (*.CSV, *.TXT)」を選択します。
• 確認済み：
  • 1 行目には MassLynx の FIELD ID が記載され、大文字と小文字が区別されます。列の順序は任意で、Index 列が追加されます。出典：WKB63781。
  • 必須列は FILE_NAME、INLET_FILE、MS_FILE、SAMPLE_LOCATION、INJ_VOL です。出典：MassLynx 4.2 Getting Started Guide 715009602、Table 5-1。「Bottle」列の FIELD ID は BOTTLE ではなく SAMPLE_LOCATION です。
  • WKB63781 に添付されたサンプルファイルでは、CRLF 改行と引用符なしのフィールドが使われています。また、TYPE の値は Blank／Standard／QC／Analyte、メソッド名には拡張子が付いていません。
• マッピング： FILE_NAME = データファイル、FILE_TEXT = サンプル名、MS_FILE、MS_TUNE_FILE、INLET_FILE、SAMPLE_LOCATION、TYPE、ID、INJ_VOL、Index。extra を使って、サンプルごとにほかの FIELD ID（例：CONC_A や QUAN_REF）を追加できます。
• 仮定：
  • solvent と double_blank は Blank として記述されます。
  • 拡張子のチェックには、MS_FILE に .exp、チューンファイルに .ipr を使用します。拡張子が指定されている場合にのみ適用されます。
  • ファイルは BOM なしの UTF-8 です。ASCII 以外のテキストにはフラグが付けられます。
  • waters_plate_well の位置パターン（1:A,1）は一般的な慣例です。カンマは CSV の引用符で囲まれます。

SCIEX OS：バッチのインポート（sciex_os）

• インポート： Batch workspace > Open > Import from file を選択し、その後 Save As を選択します。
• 確認済み：
  • バッチは .txt または .csv からインポートでき、列のレイアウトには SCIEX OS からエクスポートしたバッチを使用する必要があります。出典：SCIEX KB。
  • 列名は Sample Name（252 文字未満）、MS Method、Sample Type、Data File、Processing Method です。出典：SCIEX OS Feature Guide RUO-IDV-05-15796-C、Table 4-1。
  • Rack Type、Rack Position、Plate Type、Plate Position、Vial Position の各列があります。出典：SCIEX KB。
  • サンプルタイプは Unknown、Blank、Standard、QualityControl、Solvent、Double blank です。
  • 複数のサンプルで 1 つのデータファイルを共有できます。
• 仮定：
  • SCIEX は、エクスポートしたバッチの正確なヘッダーテキストを公開していません。 デフォルトのヘッダー（Sample Name,Sample ID,Sample Type,MS Method,LC Method,Rack Type,Rack Position,Plate Type,Plate Position,Vial Position,Injection Volume,Data File,Processing Method,Comment）は推測に基づくものです。独自のエクスポートファイルを template_path で指定してください。テンプレートを使用していない場合、validate_worklist と export_worklist は警告を表示します。
  • .msm、.lcm、.qmethod の拡張子については警告のみ表示されます。
  • ラック列とプレート列は、vendor_columns またはサンプルごとの extra で設定します。

Agilent MassHunter Acquisition：ワークリストの CSV インポート（agilent_masshunter）

• インポート： Worklist で右クリックし、「Add/Append Samples from... (csv, xlsx)」を選択します。旧バージョンでは「Import Worklist...」という名前です。ヘッダーがワークリストの列名と一致するため、マップファイルは不要です。
• 確認済み：
  • ヘッダー Sample Name,Barcode,Rack Code,Sample Position,Method,Data File,Sample Type,Level Name,Inj Vol (µL),Comment、P1-A1 のような位置、および Calibration と Sample のタイプは、Agilent Communityで引用されている、D:\MassHunter\Worklist_Import に付属するサンプルファイルに基づいています。
  • ファイルに µ が含まれる場合は、UTF-8 で保存します。出典：Agilent Community。
  • Inj Vol の -1 は「As method」を意味します。出典：Agilent Known Problem Report。
  • Sample Position、Method、Data File は入力必須です。出典：Study Manager Quick Start G3335-90140。
• 推定：
  • ファイルは UTF-8 BOM 付きで、改行コードは CRLF です。
  • データファイルには .d 拡張子が付きます。
  • メソッドには .m 拡張子が必要です。
  • サンプルタイプの Blank、QC、DoubleBlank はサンプルに含まれていません。solvent は Blank として記述されています。

Thermo Xcalibur：シーケンスの CSV インポート（thermo_xcalibur）

• インポート： Sequence Setup > File > Import Sequence。
• Xcalibur 2.2 Acquisition and Processing User Guide XCALI-97209 Rev. D の付録 A で確認済み：
  • .csv ファイルのみ受け付けます。
  • 最初のセルは Bracket Type=n（1 Overlapped、2 None、3 Non-Overlapped、4 Open）である必要があります。
  • 区切り文字は Windows のリスト区切り文字と一致させる必要があります。リスト区切り文字が ; の場合は delimiter=";" を使用します。
  • シーケンスの列名と、サンプルタイプ Unknown、Blank、QC、Std Bracket、Std Clear、Std Update。
• Thermo による公開情報ではありませんが、裏付けあり： 2 行目の正確なヘッダー文字列（Sample Type,File Name,Sample ID,Path,Instrument Method,Process Method,Calibration File,Position,Inj Vol,Level,Sample Wt,Sample Vol,ISTD Amt,Dil Factor,L1 Study,L2 Client,L3 Laboratory,L4 Company,L5 Phone,Comment,Sample Name）。Xcalibur のインポートを対象とするオープンソースのジェネレーターで使用されています：protti、fgcz/qg、lcms-sequencer。ネイティブのエクスポートは Bracket Type=4 のみを記述した行から始まります（Rapid-QC-MS #83）。確実な形式を確認したい場合は、Xcalibur からシーケンスを 1 つエクスポートしてテンプレートにしてください。
• 推定：
  • Sample Wt 0、Sample Vol 0、ISTD Amt 0、Dil Factor 1 をデフォルト値として記述します。
  • standard は Std Bracket として記述します。これはブラケットタイプ 4 に適しています。
  • 拡張子の検証：装置メソッドには .meth、処理メソッドには .pmd を使用します。

未実装

• MassHunter Walkup Custom Sample Import（G2725-90026）：ガイドを取得できなかった（HTTP 403）ため、その形式を検証できませんでした。
• ネイティブのワークリストおよびシーケンスファイル（MassHunter .wkl XML、Xcalibur .sld、MassLynx .spl）：未実装です。公開仕様が見つからなかったため、サーバーでは上記の CSV インポート方法を使用します。

検証

validate_worklist は export_worklist の実行時にも呼び出され、エクスポートを妨げるエラーと警告を報告します。

• 形式で必須のフィールドがありません。
• 大文字と小文字を区別せずに比較した場合、データファイル名が重複しています。SCIEX OS では同じデータファイルを共有できますが、1 つのデータファイル内でサンプル名が重複するとエラーになります。
• Windows でファイル名に使用できない文字（< > : " / \ | ? *、制御文字）、末尾のピリオドまたは空白、予約名（CON、NUL、COM1…）が含まれています。
• 位置が選択した position_pattern（vial_number、well、agilent_plate_well、waters_plate_well、tray_well）に一致しないか、plate_size（24/48/54/96/384）または max_vial の範囲外です。
• 注入量が 0 以下、数値ではない、または max_injection_volume_ul の上限を超えています。これには、extra または vendor_columns で設定された注入量の列も含まれます。
• テキストフィールドまたは extra の値に改行やその他の制御文字が含まれており、インポートファイルが正しく処理されません。
• メソッドファイルの拡張子が正しくありません。たとえば、SCIEX OS のバッチに Analyst の .dam を指定した場合や、Xcalibur のシーケンスに MassHunter の .m を指定した場合です。
• 対象形式に対応する列がないフィールド、および BOM のない形式での非 ASCII テキストです。

安全制限

制限	デフォルト	意味
max_injection_volume_ul	100 µL	ワークリストで許可される最大注入量です。サンプルの追加時とエクスポート時に適用されます。extra または vendor_columns でそのまま設定された注入量の列も対象です。import_worklist はこれを超える量について警告し、そのようなドラフトはエクスポートできません。

起動時に上書きできます。たとえば、20 µL のループの場合は --limit max_injection_volume_ul=20 を指定します。

プロンプトの例

• 「このリストにある 40 個の血漿サンプル用に Xcalibur シーケンスを作成してください。R トレイのウェル A1 から順に配置し、注入量は 2 µL、メソッドは C:\Xcalibur\methods\DIA_60min にしてください。R:H12 の位置から 10 サンプルごとにブランクを追加し、R:H11 の位置から開始時と終了時にプール QC を追加してください。サンプルをランダム化し、シードを教えてください。」
• 「ワークリストフォルダーにある old_batch.csv をインポートし、メソッド D:\MassHunter\methods\Panel.m を使って MassHunter ワークリストに変換してください。」
• 「フォルダーに blank_batch.txt（SCIEX OS からエクスポートしたもの）を置きました。このバッチのテンプレートとして使ってください。」
• 「この MassLynx サンプルリストを確認し、ファイル名の重複と不正なバイアル位置があれば、インポートする前に教えてください。」

注意事項

• ドラフトはメモリ上に保存されます。reconnect（またはサーバーの再起動）を行うと破棄されます。--simulate では一時フォルダーも削除されます。保存したいエクスポートファイルは別途保存してください。
• デフォルトでは、export_worklist はワークリストの隣に <file>.provenance.json（例：Plasma.csv.provenance.json）も書き出します。ワークリストと同様に、overwrite=true を指定しない限り上書きされません。これには操作履歴、ランダム化のシード、ランダム化前のサンプル順が含まれており、実行順を再現できます。書き出しを省略するには write_provenance=false を指定します。
• blank_every_n / qc_every_n は、サンプル数が指定した数で割り切れる場合、blank_at_end / qc_at_end によってすでに追加されていなければ、最後のサンプルの後にもコントロールを追加します。
• ドラフトを別のベンダーの形式でエクスポートするとき、新しいベンダーが対応する列について、元のベンダーからそのまま引き継いだ値（たとえば Xcalibur の Std Clear サンプルタイプ）はコピーされません。エクスポート時の注記にその旨が記載されます。
• ランダム化では、Python の random.Random(seed) を使用し、randomize_types で指定した種類（デフォルトでは種類不明のサンプル）のみを、それぞれの枠の中でシャッフルします。標準試料、ブランク、QC は位置が変わりません。
• メソッド名は、分析用 PC に存在するメソッドと一致する必要があります。サーバーでは確認できません。

検証

ソフトウェア	バージョン	形式	検証者	日付
まだありません：最初の報告者になる