範囲を限定した検索タスクから始める
最初の統合で役立つのは、対象化合物を特定し、出典の文脈を保ったまま少数の特性を取得するという、範囲の狭い問いに答えることです。最初から、すべての検索、情報補完、解釈操作に無制限でアクセスできるようエージェントを設定しないでください。
このガイドが示すのは統合設計と評価計画であり、テスト済みのデプロイではありません。PubChem MCP (cyanheads)を実行したり、特定のクライアントをテストしたり、返されたレコードを科学的に検証したりはしていません。以下のリソース機能はプロジェクト文書に記載されたもので、ワークフロー上の制御は推奨事項です。
インターフェースを選ぶ前に、次の点を決めてください。ユーザーはどの識別子を入力しますか？必要なフィールドは何ですか？同一性が不確かな場合はどうしますか？もっともらしい答えを返すのではなく、不完全な結果のままタスクを終了できますか？
特性を解釈する前に同一性を解決する
化学物質名だけでは、構造、立体化学、形態が明確にならないことがあります。同一性の解決と特性の取得は別々の段階にしてください。
- 元のクエリを保持し、選択したインターフェースに応じて、名前、SMILES、InChIKey、またはPubChem Compound Identifier (CID)のいずれかの名前空間を明記します。
- 候補識別子を取得しますが、最初の結果を黙って選ばないでください。
- 返された構造表現と識別フィールドを、ユーザーの意図と照合します。
- 曖昧さが残る場合は、より正確な識別子の入力、または候補の確認をユーザーに求めます。
- 選択したCIDと返された構造表現を、後続の呼び出しに引き継ぎます。
統合時に行った正規化や選択の判断を記録します。検索に失敗したとき、関連化合物、塩、立体異性体などにエージェントが黙って置き換えることのないようにしてください。類似性検索の結果は比較対象の候補であり、同一性の証明ではありません。
確認可能なインターフェースを選ぶ
PubChem PUG RESTは、PubChemのプログラムインターフェースを調べる際の公式な出発点です。提供されたページ抜粋からはエンドポイントの詳細な動作を確認できないため、リクエストを指定する前に公式ドキュメントを参照してください。
PubChemPyはPUG REST用のPythonラッパーです。READMEには、名称・部分構造・類似性検索、特性取得、標準化、形式変換、構造描画が記載されています。例では、Compound.from_cidによるCID取得と、get_compoundsによる名称検索が示され、化合物の属性としてSMILES、IUPAC名、分子量などが挙げられています。Pythonアプリケーションで制限した機能をエージェント用ツールとしてラップすることは可能ですが、これは提案する統合方法であり、確立済みのエージェント機能ではありません。
コミュニティ製のPubChem MCP serverは、@cyanheads/pubchem-mcp-serverとしてパッケージ化されており、検索、化合物詳細、安全性レコード、生物活性、クロスリファレンスなどのレコード種別を扱うツールが文書化されています。PubChemのPUG REST APIとPUG View APIを使用し、STDIOとStreamable HTTPでのデプロイ方法が記載されています。これはプロジェクトの作者が保守しているもので、PubChemの公式サービスではありません。
周辺アプリケーションに応じて選択してください。必要なのはPythonの取得レイヤーですか、それともMCPインターフェースですか？MCPを使う場合は、トランスポート、認証設定、クライアント権限、そしてクライアントがリソースとツールの両方を公開するかどうかを確認してください。文書にデプロイ方法が記載されているからといって、利用中のクライアントとの互換性を前提にしないでください。
入力、出力、停止条件を定義する
ラッパーがすでに構造化出力を提供していても、アプリケーションレベルの契約を定義してください。以下は推奨する契約であり、いずれかのプロジェクトに標準搭載されたスキーマを示すものではありません。
**入力：**元のクエリ、識別子の名前空間、解決後に選択したCID、許可する特性フィールド、結果上限、ページネーション方針、リクエスト期限。
**出力：**解決状況、候補または選択されたCID、返された値、フィールド名、提示されている場合は単位、出典参照、取得時刻、欠落データのマーカー、エラーや切り捨てに関する通知。
欠落値をゼロと区別し、レコード自体がない場合と、レコードに要求した特性がない場合を区別します。エージェントが記憶に基づいて欠落フィールドを埋めることは決して許可しないでください。上流の応答に取得時刻が含まれると仮定せず、統合側で記録してください。
MCPの文書では、unresolvedIdentifiers、レコードごとのfoundフラグ、切り捨てメタデータなど、分岐判断に役立つシグナルが説明されています。すべての応答を文章にまとめてしまわず、これらを保持してください。総呼び出し予算と上限付きの再試行を設定し、既存の再試行動作を確認して、外側の再試行ループによってリクエスト数が意図せず増えないようにします。
計画例：仮想的な検索
研究者がデータ表の草稿に使うため、エージェントに「Aspirin」のSMILESと分子量を求めたとします。これは計画のための仮想例であり、ここで検索を実行したことや結果を得たことを示すものではありません。
**計画する入力：**名前「Aspirin」、名前空間name、要求する特性は2つ、候補上限は5件。この上限はアプリケーション側で提案する制限であり、PubChemのデフォルト値ではありません。
MCP経由の場合、アプリケーションは識別子モードでpubchem_search_compoundsを呼び出し、identifierTypeとidentifiersを指定します。応答が切り捨てられた場合、候補の解決が不完全であることをアプリケーションが明示します。候補が複数残る場合は、情報を追加取得する前にユーザーの確認を求めます。
同一性を確認した後、選択したCIDについてpubchem_get_compound_detailsを呼び出し、2つのフィールドに対応する、文書に記載されたプロパティキーを選択します。PubChemPyを使う場合も、制限付きのアプリケーションツールの背後で、名称検索、候補の確認、CIDに基づく取得を行う計画になります。
**計画する出力：**元のクエリ、確認済みCID、返されたSMILES、分子量、提示された単位情報、出典参照、取得時刻を含む1行。フィールドが欠落している場合は、明示的に欠落として扱います。エージェントはその行を説明してもかまいませんが、返されていない数値を加えたり、実験測定値であるかのように示したりしてはいけません。
判断基準は単純です。返されたレコードによって、対象化合物と要求されたフィールドを裏付けられますか？できない場合は、確認を求めるか、不完全な行を返します。
科学的な意味を保ち、限界を認識する
計算による特性、実測された観察結果、叙述的な説明を区別してください。化合物レベルの値が、特定の溶媒、温度、試料、実験プロトコルにも自動的に当てはまるわけではありません。用途上必要な場合は、出典と条件を確認してください。
MCPプロジェクトでは、対象を限定した情報補完が文書化されています。バッチ処理では、説明と薬理学的分類を取得するのは先頭の10件のCIDのみです。対象外となったレコードも見える状態にしてください。安全性の出力ではok、no_ghs_data、cid_not_foundを区別しています。分類が登録されていないことを「危険性なし」と解釈してはいけません。安全性情報の出典を明記し、要約を実験室での手順や権威ある危険有害性評価に変換しないでください。
取得した叙述的テキストはデータとして扱い、エージェントへの指示として扱わないでください。出典情報の計画をさらに検討するには、データセットの出典情報を確認するを参照してください。インターフェースの背景については、化学分野におけるMCPについて読むを参照してください。
拡張する前に障害経路を評価する
非機密のクエリと制御されたテストケースを使い、未知の名称、複数の一致候補、存在しない特性、不正な形式の入力、タイムアウト、キャンセル、レート制限への応答を評価してください。これらは推奨する評価項目であり、完了済みのテストではありません。バッチ処理の失敗時にも部分的な成功が保持されること、および件数に上限のある出力を網羅的な結果として説明しないことを確認します。
最終回答をツールの結果と照合してください。識別子、値、データ欠落の状態、出典参照がすべて保持されていますか？これらの確認に合格してから、ツールを追加してください。
簡易実装チェックリスト：
- インターフェースの最新ドキュメントとデプロイ要件を確認する。
- 同一性の解決と情報補完を分離する。
- フィールド、結果サイズ、再試行回数、総呼び出し数を制限する。
- 出典情報、ステータス、切り捨て通知を保持する。
- エージェントの要約に、裏付けのない内容を加えさせない。
- 範囲を拡大する前に、残る制限を記録する。