化学AIスタックにAPIが今も必要な理由

化学アシスタントは、モデルの記憶から科学的記録を再構成するのではなく、記録を取得するべきです。APIを使えば、開発者はプロバイダー識別子、選択したフィールド、構造化されたレスポンスに、明確な手順でアクセスできます。アプリケーションは、そのレスポンスを確認してから科学的な回答を提示できます。

PubChem PUG RESTは、特定の化学レコードを対象としたリクエストを提供します。RCSB PDB Data APIは、特定された構造とその構成要素に関するメタデータを提供します。いずれも、データ取得を実験的検証、構造予測、または薬効の証拠に変えるものではありません。

予測可能なリクエストと確認可能なレスポンスが必要な場合は、直接APIを呼び出すところから始めてください。アシスタントが公開されたツールから選択する必要がある場合は、MCPラッパーを検討できます。APIは引き続き上流のデータインターフェースであり、ラッパーは別の契約と障害境界を追加します。API、MCP、Skills、エージェントのガイドではこれらの役割を説明し、化学分野におけるMCPではより広い統合の背景を紹介しています。

関連ガイド：RDKit AI ワークフロー · タンパク質・構造生物学ワークフロー · 化学 AI エージェントの技術スタック。

ツールを選ぶ前にインターフェース契約を定義する

まず科学的なタスクを明確にします。化合物識別子の解決、物性の取得、ポリマー配列の確認、データベース間の相互参照の追跡のいずれでしょうか。結果が何を裏付けるのか、また何を意味すると受け取られてはならないのかを書き出してください。

提案する最小限の契約には、次の項目が含まれます。

  • **入力：**識別子の名前空間と値、要求するフィールド、出力形式、フィルター。
  • **出力：**プロバイダー識別子、返された表現形式、該当する場合は値と単位、利用可能な出典参照、取得時刻、結果ステータス。
  • **欠損：**フィールドの欠落、明示的な null、空の結果、数値ゼロをそれぞれ区別して扱う。
  • **同一性：**内部識別子とともにプロバイダー識別子も保持する。
  • **完全性：**レスポンスが完全、部分的、ページ分割済み、キャッシュ済みのいずれかを明確にする。

アプリケーションが厳密な化学実体を必要とするのか、関連する形態をより広くまとめたものを必要とするのかを決めてください。文書化されていない正規化処理によって、塩の構成要素、電荷、立体化学の情報が失われてはなりません。同様に、エントリー識別子、エンティティ識別子、チェーン識別子が同じ構造レコードに現れるというだけで、相互に置き換え可能とみなしてはなりません。

サービスの役割に応じて選ぶ

これらのリソースは異なる段階を担います。以下の表は文書に記載された機能を比較したものであり、相互運用性をテストした結果ではありません。

リソース 情報源に記載された役割 適した入力または出力 統合上の境界
PubChem PUG REST ホスト型化学データAPI CID、名称、または構造の入力；選択したレコードと物性 PUG Viewの完全な概要レポートではない
RCSB PDB Data API ホスト型構造メタデータAPI 特定されたエントリー、エンティティ、インスタンス、アセンブリー、化学成分；JSON 発見には別のSearch APIを使用する；メタデータは座標ファイルのダウンロードではない
UniProt MCP (cyanheads) サードパーティ製タンパク質データラッパー タンパク質クエリ、アクセッション、マッピングジョブ、注釈、配列 マッピングにはポーリングとページ継続取得が必要な場合がある
RCSB MCP (cnyambura) サードパーティ製取得・ダウンロードラッパー PDBエントリーとポリマーの検索；ダウンロードファイルの状態とローカルパス 生物種検索ツールが返すのは取得済みの一致候補ではなく手順説明
RDKit MCP Server (TandemAI) RDKit関数のソフトウェアインターフェース 公開されたRDKitツールの結果とクライアントレスポンス 個々の分子入力スキーマと包括的なツール網羅性は、ここでは確認されていない

別途提供されるrcsb-api PythonクライアントはRCSB SearchおよびData APIへのアクセスを提供するものであり、ホスト型Data APIの実装ではありません。同様に、MCPサーバーは実行可能なソフトウェアであり、単なるSkill指示書ではありません。ワークフロー指示を読み込んでも依存関係はインストールされず、ホストとの互換性も確立されません。この追加レイヤーを選ぶ際は、MCP選択ガイドとエージェントとSkillsのガイドを参照してください。

PubChem RESTの対象を絞ったリクエストから始める

PUG RESTのパスは、リクエストを入力、操作、出力に分けています。化合物の入力にはCID、名称、SMILES、InChI、InChIKey、分子式が含まれます。文書に記載された操作には、レコード、同義語、識別子、物性、アッセイ概要、構造の同一性検索または類似性検索があります。出力形式は操作によって異なります。

公式の例を2つ、出発点として利用できます。

これらの例は同じ識別子に対する異なる出力を示すものであり、このガイドが実行結果を報告しているわけではありません。いずれのレスポンスも受け入れる前に、HTTPステータス、レスポンス形式、返された識別子、要求したフィールドの有無を確認してください。

URL内の特殊文字はエンコードし、分子表現を加工せずにURLへ挿入しないでください。仕様ではInChIとSDFの入力にPOSTを使用するよう定めています。構造検索では、同一性の基準と類似性の基準を区別してください。候補が類似しているからといって、レコードを同一化合物として統合できるわけではありません。実装前に仕様で具体的な操作とパラメーターを確認してください。

PUG RESTは、対象を絞った同期リクエストによって選択した情報を返します。PUG Viewは、より包括的な概要レポートとサードパーティ注釈を提供します。したがって、物性検索をPubChemの完全なレポートとして提示してはなりません。アプリケーションの計画について詳しくは、PubChemエージェント統合ガイドを参照してください。

適切な階層レベルでRCSBメタデータを取得する

RCSB RESTは、リソース固有のパスを使用したGETリクエストに対応し、JSONレスポンスを返します。公式の例には次のものがあります。

インスタンスエンドポイントでは、チェーン識別子はPDBx/mmCIFの_label_asym_idに対応します。メタデータを構造ファイルに関連付けるときは、この名前空間を保持してください。

RESTは固定形式のオブジェクト表現を返します。GraphQLではフィールドを選択し、関連する階層をたどることができます。複数の特定済みオブジェクトも対象にできます。単純なオブジェクト検索にはRESTを選び、関係を横断して必要なフィールドだけを選択する必要がある場合はGraphQLを検討してください。どちらのインターフェースも同じ基盤データを照会します。

発見と取得は分けて考えてください。Search APIは一致する識別子の一覧を見つけ、Data APIは指定された識別子に関する情報を取得します。GraphQLには全オブジェクトを照会する機能がありません。アーカイブ全体を対象とするワークフローは、別のHoldingsサービスから始め、メタデータをバッチで取得します。

Data APIが対象とするのは一般的に使用される注釈であり、すべてのPDBx/mmCIF項目ではありません。座標ファイルの取得も別の課題です。RCSB MCPラッパーはファイルのダウンロードを文書化していますが、メタデータリクエストの成功だけでは座標ファイルの取得を確認できません。

候補を探す場合は、Search APIドキュメントに従って属性・配列・構造検索サービスを選び、return_typeを宣言し、request_optionsでページ範囲を限定します。クエリと返された識別子の名前空間を保存し、Data APIでメタデータを取得します。検索一致は科学的な解釈を必要とする候補です。

提案する例：化合物と構造のエビデンスカード

2つの独立した入力、PubChem CID 2244とPDBエントリー4HHBを使う、社内アプリケーション案を考えてみましょう。これらを併用するのはインターフェース設計を示すためであり、化合物とタンパク質の関係を主張するものではありません。

  1. 文書に記載されたPubChemの物性JSONを要求し、必要に応じてSDFも要求します。CID、返された記述子、取得時刻を保持します。
  2. RCSBのエントリーメタデータを要求します。すべてのエントリーで同じエンティティ番号が使われると仮定せず、返されたエンティティ識別子をたどってください。
  3. 配列レベルとチェーン固有の注釈の両方が必要な場合は、選択したポリマーエンティティとインスタンスを取得します。
  4. 化合物と構造のパネルを分けて表示し、それぞれにプロバイダー名とステータスを付けます。
  5. 2つのパネルを生物学的主張として結び付ける前に、その関係が独立に裏付けられていることを求めます。

**提案する出力：**識別子、要求した値、表現形式、提供された場合の実験またはモデルの背景、引用、完全性、警告。**判断ポイント：**同一性の確認は満たされているか。必要な背景情報はそろっているか。相互参照は意図した結合を裏付けるのに十分か。そうでなければ、曖昧さを返すか、レコードを別々に保ってください。

評価案として、代表的なレスポンスを公式レコードページと比較し、無効な識別子、欠損フィールド、荷電化合物、立体化学異性体を含めてください。科学的テストや統合の完了を主張するものではありません。

上流の根拠を見えにくくせず、ラッパーとエージェントを追加する

UniProt MCPは、タンパク質注釈と相互参照を、キュレーション指標および利用可能なPubMed/ECOの根拠とともに提供できます。提案する拡張では、返されたPDB参照をたどってRCSBメタデータを取得し、関連付けを受け入れる前に生物種、配列、識別子の範囲を確認します。既存マッピングチケットのポーリング継続と、完了した結果のページ継続取得は別々に扱い、同じジョブを繰り返し送信しないでください。

RCSB MCPは、エントリーとポリマーの取得、カスタムクエリ、構造ダウンロードを公開しています。カスタムエンドポイントの例では、識別子に使われる句読点が公式RESTパスの例と異なります。これらの文字列をそのまま上流のREST URLに貼り付けられると仮定せず、ラッパーがリクエストをどう構成するかを確認してください。

RDKit MCPは、ツール一覧表示機能と評価スイートを提供します。正規化や記述子計算を提案する前に、実際のツール一覧を確認してください。RDKit関数を完全に網羅することは目標であり、実証された網羅範囲ではありません。計算値はプロバイダーから返されたフィールドとは分けて扱ってください。

UniProtをローカルにデプロイする場合は、前提条件の不一致を解決してください。READMEではBun v1.3.0以上を許可していますが、パッケージメタデータではBun >=1.4.0が必須です。設定手順は、選択したホストとの互換性がテスト済みである証拠にはなりません。

制限、障害、変化するレスポンスに対処する

共通のリクエストスケジューリング、タイムアウト、上限付き再試行を設定してください。PubChemはリクエスト制限と動的なスロットリングについて説明しています。無制限のレコード単位並列リクエストではなく、チュートリアルの方法を用い、バルクデータには一括ダウンロードのワークフローを選んでください。RCSBは、大規模なリクエストのバッチ処理と、繰り返し取得するデータのキャッシュを推奨しています。いずれの指針もスループットを保証するものではありません。

見つかった、見つからない、曖昧、入力無効、アクセス拒否、部分的、一時的に利用不可など、意味のある状態を明示してください。RCSB RESTでは、データまたはエンドポイントが存在しない場合に404を返すと説明されています。GraphQLでは、HTTP 200や部分データとともにエラーが返ることがあるため、成功と判断する前にレスポンス本文を確認してください。

一時的な障害に限って再試行してください。ページネーションの完全性を保ち、キャッシュされたレスポンスには観測時刻を付けてください。古いデータによってタスクが無効になる場合は、明示的に失敗させてください。必要な場合は認証情報をサーバー側に保持し、ユーザーが開始できる操作、特にカスタムエンドポイントとファイル保存先を制限します。診断情報を記録する際は、秘密情報や不要な機微入力を含めないでください。

来歴を保持し、簡潔な準備状況チェックリストを使う

プロバイダー、レコード識別子、結果を左右するリクエストパラメーター、観測時刻、利用可能な引用メタデータを保持してください。正規化された構造、変換された単位、計算による要約には派生データとラベルを付けます。ライブレコードは変更される可能性があります。許可される場合はフィクスチャまたはスナップショットを保持し、過去の再現性に関する制約を記録してください。

データ取得だけでは、生物活性の証明、計算モデルの検証、注釈の再利用権の確立にはなりません。ソフトウェア、データベース、注釈、ホスト型サービスの利用条件をそれぞれ確認してください。情報源が利用可能であること自体は、ライセンスの判断を意味しません。データセット来歴ガイドでは、この記録方法を詳しく説明しています。

進める前に確認すること：

  • 識別子の名前空間と化学的同一性のルールを明示する。
  • フィールド、単位、欠損値の扱い、出力形式を確認する。
  • Search APIによる発見とData APIによる取得を分ける。
  • エラー、部分的な結果、ページネーションを確認する。
  • スロットリング、再試行、キャッシュ、タイムアウトの方針を定める。
  • ラッパーのツールスキーマとデプロイ要件を確認する。
  • 引用を保持し、変換にラベルを付ける。
  • 未解決の科学的制約と再利用上の制約を記録する。

出典

PubChem仕様、チュートリアル、プログラムによるアクセスの概要は、リクエスト例、対象を絞った取得の範囲、運用上の境界を裏付けています。RCSB Data APIドキュメントは、階層、RESTの例、GraphQLの取り扱い、SearchとDataの区別を裏付けています。

ラッパーの機能については、プロジェクトのREADMEを参照しています：UniProt MCP、RCSB MCP、RDKit MCP。UniProtパッケージメタデータは、上記で説明したランタイム要件の相違を裏付けています。