alterlab-protocolsio

Protocols.io 連携

概要

protocols.io は、バージョン管理され、引用可能な科学プロトコル（公開された各バージョンには 10.17504/protocols.io.* の DOI が付与されます）に加え、チームのワークスペース、実験実施記録、ファイルマネージャーを提供します。プログラムから利用する方法は 2 つあります。

• 公式 MCP サーバー — https://www.protocols.io/mcp（Streamable HTTP。OAuth 2.0 サインインまたは Bearer クライアントトークンを使用します）。Claude のコネクタディレクトリにも「protocols.io」として掲載されています。
• REST API — ベース URL は https://www.protocols.io/api で、バージョンが分かれています。ほとんどのエンドポイントは v3 ですが、プロトコルの取得・更新、プロトコルのステップ、実験実施記録、ファイルマネージャーの検索、組織のエクスポートには v4 を使用します。API リファレンスは https://apidoc.protocols.io/ です。

このスキルを使用する場面

• キーワード、著者、ワークスペースで protocols.io のプロトコルを検索する場合、または DOI や URI からプロトコルを特定する場合
• プロトコルのステップや材料を（Markdown、HTML、Draft.js JSON 形式で）読み取り、分析、応用、比較する場合
• 非公開プロトコルを作成し、メタデータやステップを入力して、論文で引用できるよう公開（または DOI を予約）する場合
• プロトコルのコメントやステップに関するディスカッションを読んだり投稿したりする場合
• ワークスペースの一覧表示や参加、ワークスペース内のファイル検索、ファイルのアップロード、組織のコンテンツのエクスポートを行う場合
• プロトコルの実験実施記録を作成・更新する場合

使用しない場面

シナリオ	代わりに使用
一般的な電子実験ノートに結果（記録、添付ファイル、ノートブックのバックアップ）を保存する	alterlab-labarchive（LabArchives）または alterlab-benchling（Benchling）
作成済みのプロトコルを Opentrons OT-2/Flex または Hamilton/Tecan のリキッドハンドラー用スクリプトに変換する	alterlab-opentrons または alterlab-pylabrobot
プレプリントを登録する、またはデータ／コードリポジトリ（bioRxiv、OSF、Zenodo）を選ぶ	alterlab-preprint-deposition または alterlab-open-science
論文の Methods セクションを執筆または推敲する	alterlab-scientific-writing

MCP サーバーが接続されている場合は、そちらを優先してください

セッションで protocols.io のツール（コネクタまたは MCP サーバー）を利用できる場合は、検索、取得、編集に使用してください。ユーザー自身のアカウントで動作し、OAuth を処理して、最新のデータを返します。ツールで対応できない操作、またはコネクタが接続されていない場合は、以下の REST 呼び出しを使用してください。接続するには、https://www.protocols.io/mcp をリモート MCP サーバーとして追加するか、Claude のコネクタディレクトリから「protocols.io」を追加してサインインします。いずれの場合も、プロトコルの内容を報告する際は、プロトコルの DOI と取得日を明記してください。

認証

トークン	入手先	アクセスできる内容
CLIENT_ACCESS_TOKEN	https://www.protocols.io/developers	公開コンテンツ、およびクライアントを作成したユーザーの非公開コンテンツ
OAUTH_ACCESS_TOKEN	OAuth 2.0 認可コードフロー	公開コンテンツ、および認可したユーザーの非公開コンテンツ

すべてのリクエストで Authorization: Bearer <token> として送信し、コードやノートブックには記載せず、環境変数（例：PROTOCOLS_IO_TOKEN）に保存してください。OAuth トークンの有効期間は約 1 年です。API は有効期限の 1 か月前に警告し、更新すると古いトークンのペアは無効になります。認可リンク、トークン交換、更新の呼び出しについては references/authentication.md を参照してください。

リクエストの基本

識別子。 プロトコルのエンドポイントでは、整数の id、プロトコルの uri（tree-mapping-for-leaf-collection-megantic-only-baaciaaw のようなスラッグ）、および v4 の get／steps エンドポイントでは DOI（10.17504/protocols.io.baaciaaw または protocols.io.baaciaaw）を受け付けます。特定のバージョンを指定するには /v1、最新バージョンを指定するには /latest を追加します。書き込み用エンドポイントでは、プロトコルの guid も受け付けます。

コンテンツ形式。 v4 のプロトコル、ステップ、記録の読み取りでは、リッチテキストフィールド（説明、ガイドライン、警告、材料のテキスト、ステップのテキスト）に対して content_format=json|html|markdown を指定します。json は Draft.js 形式です。テキストを読み取る、または要約する場合は markdown を指定してください。

ページネーション。 リスト用エンドポイントでは、page_id（1 から開始）と page_size（1～100、デフォルトは 10）を指定できます。レスポンスには pagination オブジェクトが含まれます。

エラーはレスポンス本文に含まれます。 すべてのレスポンスには JSON の status_code が含まれ、0 は成功を意味します。失敗時は通常、error_message（v3）または status_text（v4）とともに HTTP 400 が返されます。トークンがない、または無効な場合は 1218、OAuth トークンの有効期限が切れている場合は 1219 です。そのため、HTTP ステータスだけでなく status_code を確認してください。

レート制限。 ユーザーごとに 1 分あたり 100 リクエストです。PDF エンドポイント（/view/<uri>.pdf）は、サインイン時は 1 分あたり 5 回、サインアウト時は 1 分あたり 3 回までです。制限を超えると HTTP 429 が返されます。

エンドポイント一覧

タスク	呼び出し	詳細
プロトコルを検索	GET /v3/protocols?filter=public&key=...	references/protocols_api.md
研究者またはワークスペースのプロトコル	GET /v3/researchers/<username>/protocols、GET /v3/workspaces/<uri>/protocols	protocols_api.md、workspaces.md
プロトコルを取得（ステップと材料を含む）	GET /v4/protocols/<id-uri-or-doi>	protocols_api.md
ステップ／材料を取得	GET /v4/protocols/<id>/steps、GET /v3/protocols/<id>/materials	protocols_api.md
プロトコルを作成	POST /v3/protocols/<new-guid>	protocols_api.md
メタデータを更新	PUT /v4/protocols/<id>（JSON）	protocols_api.md
ステップを追加、変更、削除	POST／DELETE /v4/protocols/<id>/steps	protocols_api.md
DOI を公開または予約	POST /v3/protocols/<uri>/publish（予約する場合は prepublish=1）	protocols_api.md
ブックマーク	POST／DELETE /v3/protocols/<uri>/bookmarks	protocols_api.md
PDF	GET https://www.protocols.io/view/<id-or-uri>.pdf	protocols_api.md
最近公開されたプロトコル	GET /v3/publications?latest=N または ?from=&to=	protocols_api.md
コメントとステップのディスカッション	/v3/protocols/<uri>/comments、/v3/steps/<step_id>/discussions	references/discussions.md
ワークスペースとメンバーシップ	/v3/workspaces、/v3/workspaces/<uri>/members	references/workspaces.md
ファイルマネージャーの検索、ゴミ箱、アップロード	/v4/filemanager/.../search、/v3/filemanager/trash、/v3/files	references/file_manager.md
プロフィール、実行記録、通知、組織のエクスポート	/v3/session/profile、/v3/records、/v3/researchers/notifications、/v4/organizations/<uri>/content/exports	references/additional_features.md

PDF 表示を除き、すべてのパスは https://www.protocols.io/api からの相対パスです。https://protocols.io/... は www. ホストにリダイレクトされます。api.protocols.io ホストはありません。

Python の例

この例では requests と、protocols.io のレスポンス本文に含まれるエラーを例外に変換するヘルパーを使用します。

import os
import time
import uuid

import requests

BASE = "https://www.protocols.io/api"
HEADERS = {"Authorization": f"Bearer {os.environ['PROTOCOLS_IO_TOKEN']}"}


def call(method, path, retries=3, **kwargs):
    """Send a request; back off on HTTP 429 and raise when the JSON status_code is not 0."""
    for attempt in range(retries):
        resp = requests.request(method, f"{BASE}{path}", headers=HEADERS, timeout=60, **kwargs)
        if resp.status_code == 429 and attempt < retries - 1:
            time.sleep(int(resp.headers.get("Retry-After", 30 * (attempt + 1))))
            continue
        try:
            data = resp.json()
        except ValueError:  # e.g. an HTML error page from a proxy
            resp.raise_for_status()
            raise
        if data.get("status_code", 0) != 0:
            message = data.get("error_message") or data.get("status_text")
            raise RuntimeError(f"protocols.io {data.get('status_code')}: {message} (HTTP {resp.status_code})")
        return data
    raise RuntimeError("protocols.io rate limit: retries exhausted")

検索して引用する

found = call("GET", "/v3/protocols", params={
    "filter": "public", "key": "CRISPR", "order_field": "relevance", "page_size": 10,
})
for item in found["items"]:
    doi = (item.get("doi") or "").removeprefix("dx.doi.org/")  # list items use a dx.doi.org/ prefix
    print(item["title"], f"https://doi.org/{doi}" if doi else "(no DOI yet)")

完全一致で検索するには、検索語を key 内で二重引用符で囲んでください。

DOI でプロトコルを Markdown として読み取る

data = call("GET", "/v4/protocols/10.17504/protocols.io.baaciaaw",
            params={"content_format": "markdown"})
protocol = data.get("payload") or data.get("protocol")  # current v4 responses use "payload"
print(protocol["title"], protocol["url"])
for number, step in enumerate(protocol.get("steps", []), start=1):
    print(number, step.get("step"))

プロトコルを作成し、内容を入力して公開する

guid = uuid.uuid4().hex.upper()  # new GUID without dashes, generated client-side
created = call("POST", f"/v3/protocols/{guid}", data={"type_id": 1})  # 1 protocol, 3 collection, 4 document
uri = created["protocol"]["uri"]

call("PUT", f"/v4/protocols/{guid}", json={
    "title": "CRISPR-Cas9 knockout in HEK293T cells",
    "description": "RNP electroporation workflow with T7E1 validation.",
    "materials_text": "SpCas9 nuclease; synthetic sgRNA; Neon electroporation kit",
    "status_id": 2,  # 1 working, 2 still optimizing, 3 could not get it to work
})

# Steps are ordered by previous_guid: the first step has previous_guid None.
texts = ["Anneal and complex sgRNA with Cas9 (10 min, room temperature).",
         "Electroporate 2e5 cells per reaction.",
         "Harvest genomic DNA after 72 h and run the T7E1 assay."]
steps, previous = [], None
for text in texts:
    step_guid = uuid.uuid4().hex.upper()
    steps.append({"guid": step_guid, "previous_guid": previous, "step": text})
    previous = step_guid
call("POST", f"/v4/protocols/{guid}/steps", json={"steps": steps})

# Reserve a DOI without making it public (drop prepublish to publish openly).
call("POST", f"/v3/protocols/{uri}/publish", params={"prepublish": 1})

公開するにはタイトルと 1 人以上の著者が必要です。また、DOI が付与されたバージョンは編集できなくなるため、まずウェブエディターでプロトコルを確認してください。公開済みのプロトコルで PUT により指定できるフィールドは一部に限られます（キーワード、免責事項、倫理に関する声明、原稿の引用、参考文献、資金提供者、ステータス／警告フラグ）。内容を変更するには新しいバージョンが必要ですが、その作成方法は API に記載されていないため、ウェブエディターで作成してください。

ファイルをアップロードする

アップロードは3回の呼び出しで行います。ファイルを登録し、返されたポリシーを使ってバイトデータをS3に送信してから、確定します。

path = "results.csv"
prep = call("POST", "/v3/files", data={"filename": os.path.basename(path)})
form, meta = prep["formData"], prep["metaData"]
fields = {"key": form["key"], "acl": form["acl"], "AWSAccessKeyId": form["AWSAccessKeyId"],
          "Policy": form["Policy"], "Signature": form["Signature"], "Content-Type": form["ContentType"]}
with open(path, "rb") as fh:  # the file must be the last form field
    s3 = requests.post(f"https://{form['s3_bucket']}.s3.amazonaws.com/", data=fields,
                       files={"file": (os.path.basename(path), fh)}, timeout=300)
s3.raise_for_status()
call("PUT", f"/v3/files/{meta['file_id']}")  # verify the upload

記載されているアップロード呼び出しには、フォルダー、ワークスペース、タグの各フィールドはありません。返された file_id をコレクションに追加する（content_type_id 15 の collection_items を使用する）か、ウェブアプリで整理してください。S3の手順では標準のS3 POSTポリシー形式に従いますが、APIドキュメントには詳細が記載されていません。まず小さなファイルで試してください。references/file_manager.md を参照してください。

一般的なワークフロー

既存のプロトコルをインポートして分析する。 検索し（GET /v3/protocols）、選択したプロトコルをMarkdownとして取得し（GET /v4/protocols/<doi>）、修正の報告がないかコメントを読み（GET /v3/protocols/<uri>/comments）、使用したDOIとバージョンを記録します。

ラボのプロトコルを作成して公開する。 作成し（POST /v3/protocols/<guid>）、メタデータを設定し（PUT /v4/protocols/<guid>）、ステップを順番に追加し（POST /v4/protocols/<guid>/steps）、ウェブエディターで共著者と確認します。論文の査読中に prepublish=1 を指定してDOIを予約し、採択後に公開します。

プロトコルの実施記録を残す。 プロトコルから実施記録を作成し（protocol_uri を指定して POST /v3/records）、ステップを完了済みにして、メモを追加します（PUT /v3/records/<guid>。references/additional_features.md を参照してください）。生データはELNまたはリポジトリに保存し、そこで記録またはプロトコルを引用してください。

チームのワークスペース。 ユーザーのワークスペースを一覧表示し（GET /v3/workspaces?filter=my_groups）、ワークスペースのプロトコルやファイルを一覧表示または検索します。公開ワークスペースへの参加を申請するには、POST /v3/workspaces/<uri>/members を使用します（references/workspaces.md を参照してください）。

機関のアーカイブ。 組織アカウントで、コンテンツ全体のエクスポートを開始し（POST https://<subdomain>.protocols.io/api/v4/organizations/<org_uri>/content/exports）、download_link が設定されるまで状態を確認します。

プロトコルの引用

実際に使用したバージョンを引用してください。Author(s). Title. protocols.io. https://doi.org/10.17504/protocols.io.<id> の形式を使用し、DOIにバージョンサフィックス（/v1、/v2、…）が含まれる場合はそのまま保持します。DOIが付与されたバージョンは編集できませんが、/latest は新しいバージョンを参照します。そのため、方法のセクションやデータ記録ではバージョンを固定してください。

トラブルシューティング

症状	考えられる原因と対処法
status_code 1218 を伴う HTTP 400	Authorization: Bearer <token> ヘッダーがないか、形式が正しくありません
status_code 1219「token is expired」	OAuthトークンを更新します（grant_type=refresh_token）。古いトークンの組み合わせは使用できなくなります
非公開プロトコルが見つからない、またはアクセス拒否 132 が返る	トークンのユーザーにはアクセス権がありません。所有ユーザーのOAuthトークンを使うか、ワークスペースへの追加を依頼してください
作成時の 1905	ワークスペースのサブスクリプション上限に達しています
ステップの POST が拒否される（「loop detected」、「multiple first steps」、「steps are not forming a complete sequence」）	previous_guid の連結を修正してください。ステップを挿入する場合は、次のステップも新しい previous_guid を指定して再送信してください
公開時の 255 / 256 / 257	すでに公開されている／タイトルがない／著者がいません
HTTP 429	1分あたり100件（またはPDFリクエストは1分あたり5件）を超えています。間隔を空け、読み取り結果をキャッシュしてください
Mac の curl がバイナリー出力を表示する	--compressed を追加してください

リファレンスファイル

• references/authentication.md — トークンの種類、OAuth認証リンク、トークンの交換と更新、MCP接続、制限
• references/protocols_api.md — 検索、取得、作成、更新、ステップ、材料、公開、ブックマーク、PDF、出版物、試薬
• references/discussions.md — プロトコルのコメント、ステップのディスカッション、実施記録のコメント、ダイレクトメッセージ
• references/workspaces.md — ワークスペース一覧、詳細、メンバーシップ、ワークスペースのプロトコル
• references/file_manager.md — ファイルマネージャーでの検索、ゴミ箱と復元、S3ファイルのアップロード
• references/additional_features.md — プロフィール、実施記録、通知、組織コンテンツのエクスポート

AlterLab Academic Skills スイートの一部です。