interpro-mcp-server

---

概要

InterPro と、統合されているメンバーデータベース（Pfam、PROSITE、SMART、CDD、PANTHER など）から、タンパク質ファミリー、ドメイン、リピート、機能部位を、認証情報不要の EMBL-EBI InterPro API を介して取得します。エントリーを検索して完全なメタデータを読み取り、UniProt タンパク質または PDB エントリーの鎖を残基座標付きのアノテーションにマッピングし、Pfam、CDD、PIRSF のクランをたどり、特定のシグネチャを持つタンパク質を検索して、未加工のタンパク質配列をスキャンできます。認証情報の設定は不要で、STDIO、Streamable HTTP、または上記の公開ホスト型エンドポイント経由で動作します。新しい InterProScan ジョブを開始するには、運用担当者が設定した連絡先メールアドレスが必要です（設定を参照）。

ツール

ツール	説明
interpro_search_entries	GO アノテーションによる InterPro エントリの検索、またはテキスト、エントリタイプ、統合先アクセッションによる InterPro エントリおよびメンバーシグネチャの検索
interpro_get_entry	1 件のエントリの説明、階層、メンバーシグネチャ、GO 用語、文献、相互参照、クランへの所属、カバレッジカウンターを読み取ります
interpro_get_protein_domains	UniProt タンパク質のドメイン、ファミリー、リピート、機能部位を配列座標に対応付けます。任意で 1 つの残基を指定できます
interpro_get_clan	Pfam、CDD、PIRSF のセットを読み取り、そのメンバーをページごとに取得します。任意で関係グラフを含められます
interpro_find_proteins_by_domain	あるエントリを持つ UniProt タンパク質を検索します。デフォルトではレビュー済みヒトタンパク質が対象で、任意で 1 つのプロテオーム内に絞り込めます
interpro_get_structure_domains	1 件の PDB エントリのタンパク質鎖にシグネチャをマッピングし、鎖、著者、UniProt の各番号体系で示します
interpro_scan_sequence	生のタンパク質配列からドメイン、ファミリー、部位の一致を検索します。UniParc 配列では事前計算結果を使用し、それ以外は InterProScan ジョブを実行します
interpro_get_scan_result	interpro_scan_sequence で開始した InterProScan ジョブのステータスと一致結果を読み取ります
interpro_list_reference	データベースのスラッグ、エントリタイプ、アクセッションのパターン、一般的な分類群 ID、現在の InterPro リリースを確認します

機能リファレンス

interpro_search_entries _tool

• sourceDatabase（デフォルトは interpro）に加え、任意で query（1～300 文字）、entryType、goTerm（GO:0003677 形式）、goCategory（P、F、C）、integratedInto（IPR アクセッション。メンバーデータベースのみ）を指定できます。フィルターは必須ではなく、すべて省略するとデータベースを閲覧します
• goTerm と goCategory には sourceDatabase: "interpro" が必要です。1 回の呼び出しにつき GO フィルターは 1 つだけ選択してください。両方を組み合わせると、用語が指定された場合に上流がカテゴリを無視するため、ネットワークアクセス前に失敗します。メンバーシグネチャを検索する場合は、GO フィルターで InterPro を検索した後、interpro_get_entry で member_databases を読み取るか、一致する InterPro アクセッションを integratedInto に指定してメンバーデータベースを検索してください
• カーソルによるページ分割に対応します。limit は正の整数で、上限は 100（デフォルトは 20）です。これを超えるリクエストは通知とともに上限値に切り詰められます。entries、page（total、returned、limit、hasMore、nextCursor）、適用された query を返します。page.limit は実際に適用されたページサイズです

---

interpro_get_entry _tool

• accession は必須です。省略された場合、sourceDatabase は標準的なアクセッションのプレフィックスから推定されます。セットアクセッション（CL…）は entry_not_found として失敗し、interpro_get_clan を案内します
• 任意の sections では、description、hierarchy、member_databases、go_terms、literature、cross_references、wikipedia、counters、overlaps_with から選択できます。コアメタデータと上流由来の未知のフィールドは保持されます。sections を省略すると、詳細情報全体を返します
• 任意の正の整数 overlapLimit で overlaps_with レコード全体をページ分割できます。overlapOffset を指定するには overlapLimit が必要です。開始値は 0 で、overlapsPage.nextOffset を使用して次のページに進みます。ページ分割には、重複情報を保持する必要があります。選択した項目と省略した項目が通知されます。重複データが存在しない場合や null の場合は、空のリストとは区別されます
• includeThumbnail: true を指定しない限り、Wikipedia のサムネイルは省略され、省略された内容を通知します
• entry.descriptionText は、元の entry.description（HTML とアノテーションフラグを含む）を変更せずに保持しながら、段落、リスト、表の区切りを含む読みやすいテキストを追加します。説明が除外されている場合、または読み取り可能なテキストが提供されていない場合は省略されます
• 取り下げられたレコードは、削除日と短縮名を含む entry_withdrawn として失敗します

---

interpro_get_protein_domains _tool

• UniProt の正規の6文字または10文字の accession（アイソフォームのサフィックスなし）。任意の residuePosition（1始まり、両端を含む）を指定すると、その位置を含むフラグメントを持つ一致をすべて保持し、一致した各レコードのフラグメントはすべてそのまま返します。includeExtraFeatures を指定すると、ディスオーダーや膜貫通領域などの予測された特徴が追加されます
• includeResidueAnnotations: true を指定すると、プロバイダーの機能ルール注釈である residueAnnotations が追加されます。残基フィルターを指定すると、位置を含むフラグメントがあるルール全体が保持され、説明、残基文字、位置、出典情報もそのまま残ります
• 大きなマップは、100,000バイトの応答上限内で、レコード全体を単位とするセグメントに分割して返されます。順序は、一致、要求された追加特徴、要求された残基ルールです。coverage.nextCursor をたどり、hasMore が false になるまで続けてください。最初のセグメントにはタンパク質のメタデータが含まれます。空のセグメントから注釈がないとは判断できません。残基注釈は該当する段階に達するまで省略され、{} はその段階で選択されたルールがなかったことを示します
• 不連続なフラグメント、モデル、上流のスコアは返された状態のまま保持されます。residue_out_of_range と protein_not_found は型付きの失敗です

---

interpro_get_clan _tool

• Pfam（CL0016）、CDD（cl21453）、またはPIRSF（PIRSF000047）のセットを指定する accession。sourceDatabase（pfam、cdd、pirsf）はプレフィックスから推定されます。メンバーは cursor でページ分割され、正の整数 limit は最大100（デフォルトは20）です。上限を超える要求は通知とともに切り詰められ、page.limit に適用後のサイズが示されます
• includeRelationships: true を指定すると、応答上限に収まる分割で関係グラフが追加されます。relationshipsPage.nextOffset を relationshipOffset として渡してください。このパラメーターには includeRelationships の指定が必要です
• includeThumbnail は interpro_get_entry と同様に動作します。セットが見つからない場合は clan_not_found です

---

interpro_find_proteins_by_domain _tool

• accession と、任意の sourceDatabase を指定します。taxonId（NCBI、デフォルトは 9606）と reviewedOnly（デフォルトは true。false の場合、レビュー済みと未レビューのタンパク質が対象です）は query に反映されます
• 任意の isFragment を指定すると、フラグメントとして注釈されたタンパク質（true）、またはフラグメントとして注釈されていないタンパク質（false）を選択できます。省略すると両方が含まれます。false であっても、配列が完全であることは示しません。明示的に指定した選択条件は query に含まれ、カーソルをたどる際も変更しないでください
• 任意の architectureId には、interpro_get_protein_domains の protein.ida_accession を指定できます。40文字の16進数識別子で、小文字に正規化されます。同値であることは、プロバイダーによるPfamアーキテクチャのグループ分けを意味し、機能が同等であることを意味しません。カーソルをたどる際も変更しないでください
• カーソルでページ分割され、正の整数 limit は最大50（デフォルトは20）です。上限を超える要求は通知とともに切り詰められ、page.limit に適用後のサイズが示されます。通常の結果には、タンパク質の概要、一致したエントリーの位置、分類群の系統、およびネイティブの extra_fields.is_fragment 注釈が保持されます。状態が欠落またはnullの場合は不明のままです。アーキテクチャでフィルターした行は、値が提供されていればネイティブの extra_fields.ida_id を保持し、detailAvailability を使用して、エントリーや分類群の詳細が利用できない場合と、実際に空の配列の場合を区別します
• 任意の proteomeId（大文字小文字を区別せず、UP に9桁の数字を続けた形式。正規形は大文字。例：interpro_get_protein_domains の protein.proteome）を指定すると、他の選択条件に加えてUniProtプロテオームを1つに絞り込めます。taxonId はデフォルトの 9606 を含め、引き続き適用されます。プロテオームからタンパク質が返されるのは、taxonId がその生物またはその祖先の場合に限られます。値は query に反映され、カーソルをたどる際も変更しないでください。この場合、行には上流の proteomes 配列が含まれ、アーキテクチャの行には detailAvailability.proteomes が追加されます
• ヒットがない場合も通知付きの成功です。APIは、未知のエントリー、未知の分類群、未知のプロテオーム、および空の積集合を同じように応答するためです

---

interpro_get_structure_domains _ツール

• pdbId は必須です。1tsr のような4文字の PDB ID を指定します。大文字と小文字は区別されません（accession は別名として使用できます）。拡張形式の pdb_0000… ID はサポートされていません。任意の chain を指定すると、マップを1つのタンパク質鎖に限定できます。大文字と小文字は区別されます（A と a は異なります）。核酸鎖は一覧に含まれません
• 各マッチでは、entry でまとめられた鎖レコードが structures に列挙されます。各レコードには、鎖の番号付けでの位置（start／end、1始まり）と著者の番号付けでの位置（auth_start／auth_end。null の場合や欠番がある場合があります）、UniProt の番号付け、および鎖から UniProt への残基マップが含まれます。UniProt へのマッピングがない鎖では、protein は null です
• InterPro は、マッチごとに最大20件の鎖レコードをネストします。chainRecordLimitReached は、その上限に達したマッチを示します。この場合、返されていない鎖が含まれることがあります。1つの鎖をすべて取得するには、chain を指定してください
• セグメントには、レスポンスの上限100,000バイト以内に収まるよう、マッチ全体が含まれます。hasMore が false になるまで coverage.nextCursor をたどってください。最初のセグメントには structure（タンパク質の chains を含むメタデータ）が含まれます
• DNA のみのエントリではマッチなしで成功し、通知が返されます。不明または廃止された ID は structure_not_found、構造内のタンパク質鎖にない鎖は availableChains を含む chain_not_found としてエラーになります

---

interpro_scan_sequence _ツール

• sequence は必須です。残基を示す文字で記述したタンパク質配列を1つ指定します。任意で、その前に FASTA ヘッダー行を1行付けられます（最大100,000文字）。大文字と小文字、空白、改行は無視されます。数字、ギャップ、終止記号（*）は使用できません。入力が空の場合や、FASTA レコードが複数ある場合もエラーになります
• UniParc に登録済みの配列には、事前計算済みのマッチが直ちに返されます（source: "precalculated"）。それ以外の配列では、EBI Job Dispatcher を通じて InterProScan 6 のジョブが1つ開始されます（source: "interproscan"）。通常、処理には約10分かかるため、新規配列の最初の結果は多くの場合、ステータスが submitted、queued、または running の jobId です
• waitSeconds（0～35、既定値は30）は、新たに開始したジョブの結果を待ってから jobId を返すまでの時間を設定します。実行中のジョブがある配列を再度指定すると、同じ jobId が返されます（サーバープロセスごとに追跡されます）。プロセスあたり同時実行できるジョブは最大25件です。上限を超えると、retryAfter を含む rate_limited として呼び出しが失敗します
• INTERPRO_SCAN_EMAIL が設定されていない場合、利用できるのは事前計算済みのマッチのみです。それ以外の配列は scan_not_configured としてエラーになります（設定を参照）。ホスト型エンドポイントでは、この値は設定されていません
• マッチは InterProScan のレコードそのままの形式で、最も早い位置を基準にソートされ、1始まりの両端を含む位置で示されます。レコード全体が100,000バイトの上限内に収まるようセグメント化されます。同じ sequence を指定して coverage.nextCursor をたどってください。このツールは読み取り専用ではありません。呼び出しによってジョブが開始されることがあります

---

interpro_get_scan_result _ツール

• jobId は必須です。interpro_scan_sequence が返した値を指定してください。waitSeconds（0～35、既定値は30）を指定すると、保留中のジョブの結果を待ちます。0 の場合はステータスを1回確認します
• 完了したジョブでは、マッチとともに status: "finished" が返されます。queued または running の場合はマッチを返さないため、後で再度確認してください。完了したジョブでは、さらに interproVersion と interproscanVersion も返されます。大きな結果は、同じ jobId を指定して coverage.nextCursor をたどると続きが取得できます
• ジョブと結果は、送信から7日後に期限切れになります。不明または期限切れのジョブは scan_not_found、エラーで終了したジョブは scan_failed としてエラーになり、どちらも interpro_scan_sequence に案内します

---

interpro_list_reference _ツール

• topic は必須です。databases、entry_types、accession_patterns、taxa、または release を指定します。最初の4項目はローカルで処理され、ネットワーク呼び出しは行われません。taxa には一般的な例が列挙されますが、すべての分類群が含まれるわけではありません
• release は現在の InterPro のバージョン、日付、およびデータベースごとのエントリ数を取得します。上流からの2つの応答でバージョンが一致しない場合は、release_changed としてエラーになります

特長

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、切り替え可能な認証（none／jwt／oauth）、交換可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレース機能を備えた構造化ログに対応しています。

InterPro 固有の機能：

• 15 個のデータベーススラッグ（interpro、pfam、prosite、profile、smart、cdd、panther、cathgene3d、ssf、ncbifam、hamap、prints、pirsf、sfld、antifam）と 11 個のエントリータイプに対応しています。標準的なアクセッション接頭辞からエントリーのデータベースを推定し、競合するルートはローカルで拒否します。
• InterPro API へのリクエストを毎秒 1 件に制限するプロセス全体で共有のリクエストペーサーを備えています。ツール呼び出しごとに、ペーシング、再試行、すべてのリクエストを含む 50 秒の予算を設定し、上流レスポンスの上限を 4 MiB としています。
• 配列スキャンでは、InterProScan 6 のジョブを送信する前に、API キー不要の Matches API で事前計算済みの結果を確認し、同じ配列の再リクエストには実行中のジョブを再利用します。
• API の本文なし 204 レスポンスを処理できる上流 HTTP/1.1 クライアントを使用します。このレスポンスは Node のネイティブ fetch では拒否されます。
• 上流のメタデータが不足している場合、値を補完せず、null のまま返すか省略します。

エージェントに適した出力：

• content[] には完全な出力をコンパクトな JSON として格納し、すべての URL のインデックスをリンクとして、すべての画像のインデックスを画像として格納します。そのため、一方の形式しか読み取らないクライアントでも同じデータを取得できます。
• クエリにひも付けられた不透明なカーソルを使用し、結果が一部のみの場合は、次に呼び出すべき正確な呼び出しを通知します。
• 型付きの失敗理由（entry_not_found、invalid_cursor、upstream_rate_limited など）それぞれに、復旧のヒントを付けています。
• 座標は配列アノテーションを示すものであり、病原性や臨床的意義を示すものではありません。
• interpro-guide エージェントスキル（識別子チェーン、ゲート、チェーン／著者／UniProt の番号付け）を、MCP 経由、およびプラグインのインストール、npm パッケージ、Docker イメージで公開します。

はじめに

インストール不要で、ホストされたインスタンスに接続できます。

claude mcp add --transport http interpro-mcp-server https://interpro.caseyjhand.com/mcp

または、ローカルで実行します。

claude mcp add interpro-mcp-server -- npx -y @cyanheads/interpro-mcp-server

その他のクライアントでは、MCP 設定ファイルに次の内容を追加してください。

{
  "mcpServers": {
    "interpro-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/interpro-mcp-server"]
    }
  }
}

API キーは不要です。Docker またはソースからのビルドについては、サーバーの実行を参照してください。

設定

InterPro API に API キーは不要です。サーバーには任意の変数が 1 つあり、以下はこのフレームワークでよく設定される変数です。

変数	説明	デフォルト
INTERPRO_SCAN_EMAIL	InterProScan ジョブの送信時に EBI Job Dispatcher が必要とする任意の連絡先メールアドレスです。未設定の場合、interpro_scan_sequence は UniParc にすでに登録されている配列の事前計算済みマッチを引き続き返し、それ以外の配列では scan_not_configured として失敗します。interpro_get_scan_result は既存のジョブを引き続き読み取ります。サーバーのすべての呼び出し元で 1 つのアドレスを共有し、EBI はジョブデータとともにそのアドレスを 7 日間保持します。ホストされたエンドポイントでは、この変数を設定しません。	未設定
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_HTTP_HOST	HTTP サーバーのホスト。	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	HTTP エンドポイントのパス。	/mcp
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。認証を有効にすると、各ツールにそのツールの tool:<tool_name>:read スコープが必要です。ジョブを開始できる interpro_scan_sequence には、tool:interpro_scan_sequence:write が必要です。	none
MCP_LOG_LEVEL	ログレベル（debug、info、notice、warning、error）。	info
LOGS_DIR	ログファイルのディレクトリ（Node.js のみ）。	<app-root>/logs
STORAGE_PROVIDER_TYPE	ストレージバックエンド：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	OpenTelemetry を有効にします。	false

よく使用するフレームワークのオーバーライドについては、.env.example を参照してください。

サーバーの実行

ローカル開発

Bun v1.4.0 以上（または Node.js v24 以降）が必要です。

• クローンしてインストール：

  git clone https://github.com/cyanheads/interpro-mcp-server.git
  cd interpro-mcp-server && bun install
  cp .env.example .env   # optional; the server needs no keys
  

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -p 3010:3010 ghcr.io/cyanheads/interpro-mcp-server:latest

イメージはデフォルトで HTTP トランスポート、ステートレスセッションモードを使用し、ログを /var/log/interpro-mcp-server に出力します。MCP クライアントから stdio 経由で実行するには、"command": "docker" と "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/interpro-mcp-server:latest"] を使用します。ローカルでビルドするには、docker build -t interpro-mcp-server . を実行します。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドします。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツールを登録し、InterPro および sequence-scan サービスを起動します。
src/config	サーバー固有の環境変数の解析（INTERPRO_SCAN_EMAIL）を行います。
src/mcp-server/tools	ツール定義（*.tool.ts）です。ツールは 9 個あります。
src/services/interpro	InterPro サービスです。HTTP/1.1 アダプター、ペーサーと期限設定、アクセッションのルーティング、カーソル、スキーマ、共有結果フォーマッターを含みます。
src/services/sequence-scan	配列の解析、事前計算済みルックアップ、InterProScan ジョブの送信とポーリング、スキャン結果のセグメント化を行います。
skills/	公開されているエージェントスキル（interpro-guide）です。MCP 経由で提供され、パッケージにも同梱されます。
tests/	src/ の構成を反映したユニットテストと統合テストです。

開発ガイド

開発ガイドラインとアーキテクチャのルールについては、CLAUDE.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch は使用しません。
• リクエスト単位のログ記録には ctx.log を使用します。
• 新しいツールは src/index.ts の createApp() 配列に登録します。
• 外部 API の呼び出しはラップします。生データを検証し、ドメイン型に正規化して、出力スキーマに従って返します。不足しているフィールドを決して捏造しないでください。

コントリビューション

問題の報告を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。

データは、EMBL-EBI API を通じて InterPro およびそのメンバーデータベースから取得しています。ライセンスはメンバーデータベースごとに異なるため、InterPro とデータの提供元データベースを明記してください。InterPro のライセンスページおよび EMBL-EBI の利用規約を参照してください。