worms-marine-taxa-mcp-server

---

概要

World Register of Marine Species（WoRMS）の海洋生物分類情報を提供します。学名または一般名を AphiaID に解決し、採用名をたどり、キー不要の WoRMS REST API から分類、シノニム、分布、形質、外部識別子を取得します。

AphiaID のセレクターには、正の安全な整数、小数文字列、または urn:lsid:marinespecies.org:taxname:137205 のような正規 WoRMS LSID を指定できます。返される AphiaID は数値のままです。その他の LSID には、externalId と type: "lsid" を指定して worms_crosswalk_id を使用するか、worms_resolve_taxon で学名を解決してください。

ツール

ツール	説明
worms_resolve_taxon	学名（完全一致またはあいまい一致）または一般名を1つ解決し、AphiaIDと有効名へのリンクを取得します
worms_get_taxon	AphiaIDでAphiaレコード全体を取得します。一般名または情報源を任意で含められます
worms_get_classification	ルートから先端までの分類を取得します。直接の子を任意で含められます
worms_get_synonyms	AphiaIDに対応する有効な分類群の同義語を一覧表示します
worms_get_distributions	記録された分布を取得します。ステータス、定着手段、侵略性、または出現状況で絞り込めます
worms_get_traits	情報源と継承情報を含む属性ツリー（体サイズ、機能群、保全リスト）を取得します
worms_crosswalk_id	AphiaIDを9つの外部識別子システムに対応付けるか、外部IDから逆引きします
worms_list_reference	識別子システム、ステータス、環境フラグ、分布の絞り込み値、ランク、形質の定義を一覧表示します

機能リファレンス

worms_resolve_taxon _ツール

• 空でないnamesリスト（入力数の合計上限なし。上流リクエスト1回につき最大50件）、またはvernacularのいずれか一方を指定します。両方は指定できません。fuzzy: trueでTAXAMATCHによる照合を有効にします。namesではmarineOnlyとextantOnlyの既定値はtrueです。一般名検索では、記録された一般名全体に一致するものを検索します。または、vernacularMatch: "contains"を指定すると、テキストを含む記録済みの名前をすべて検索します（grouperは完全一致では見つかりませんが、部分一致では多数見つかります）。一般名検索にはどちらのフィルターも適用されません
• 各結果にはinputIndex（重複を含む）、status、validAphiaId、validNameを含むすべての一致結果、見つからなかった場合のguidance行が保持されます。nextInputOffsetとnextMatchOffsetを使って続きから取得します
• 一般名の結果は、上流のoffset（1始まり、50件刻み）とローカルのresultOffsetでページ分割されます

---

worms_get_taxon _ツール

• 空でないaphiaIdsリストを指定します。入力数の合計上限はなく、リクエスト1回につき最大50件を取得します。変更していないリストを使い、nextInputOffsetで続きから取得します。不明なIDはfound: falseとして位置を維持します。取得前に送信されたすべての要素が検証されます
• includeVernaculars: true（IDは1つのみ）を指定すると一般名が追加され、vernacularOffsetでページ分割されます。検索に失敗した場合は、レコードの横にvernacularErrorが返されます
• includeSources: true（IDは1つのみ。includeVernacularsとは併用不可）を指定すると、その分類群の情報源が追加されます。たとえばoriginal descriptionやbasis of recordが対象で、reference、page、url、link、fulltext、doiはそのまま返されます。任意のsourceUse: "original description"を指定すると、sourceOffsetとバイト数の上限を適用する前に、大文字と小文字を区別せず、用途の値全体で絞り込みます。空欄の場合はフィルターを省略し、値が入力されている場合は前後の空白を取り除きません。変更していないオプションを指定してnextSourceOffsetで続きから取得すると、完全な主要レコードが再度返され、選択されたすべての行を順番に再構成できます
• 情報源の取得に成功すると、選択された書誌全体の件数をsourceTotalCountで報告します。有効なフィルターがある場合に限り、フィルター適用前の件数をunfilteredSourceCountで報告します。通知により、一致する用途がない場合、書誌が空の場合、オフセットが範囲を超えている場合を区別します。検索に失敗した場合は、件数を含めずにレコードの横にsourcesErrorが返されます。includeSourcesが指定されていない場合、sourceUseは無効です

---

worms_get_classification _ツール

• aphiaIdを1つ指定します。ranksはルートから先端までの系統です。WoRMSに系統がない場合はfound: falseになります
• includeChildren: trueを指定すると、直接の子のページを1つ（50行）追加します（offset、marineOnly、extantOnly）。子の検索に失敗した場合は、系統の横にchildrenErrorが返されます
• 送信されたAphiaIDには、それ自体に記録された系統が保持されます。noticeには、リンク先の有効なAphiaID、または有効な代替表現に対する優先AphiaIDが示されます。ステータスの検索に失敗した場合は、系統の横にstatusErrorが返されます

---

worms_get_synonyms _ツール

• 有効かどうかを問わず、aphiaIdを1つ指定します。その有効な分類群（validAphiaId）の同義語が、上流のoffsetごとに50件一覧表示されます
• foundとguidanceにより、分類群が見つからない場合と、有効なIDが知られていない名前とを区別します

---

worms_get_distributions _tool

• aphiaIdを1つ指定します。任意のrecordStatus（valid、doubtful、inaccurate）、establishmentMeans、invasiveness、occurrenceの各フィルターはAND条件で組み合わせます。recordStatusは大文字と小文字、および前後の空白を無視し、小文字のコードをそのまま返します。その他のフィルターは、値が入力されている場合、空白をトリミングせずに大文字と小文字を区別せず完全一致で照合します。確認されている値はworms_list_referenceのトピックdistribution_termsにあります。空のフィルターは省略されます
• unfilteredCountとfilteredCountを返します。各行には、ローカリティ、そのMarineRegionsのlocationId、ステータスフィールドがソース順で含まれます
• WoRMSはレコードを個々の名前の用法に紐付けるため、デフォルトではそのAphiaID自身のレコードを取得します。includeSynonyms: trueを指定すると、受け入れられた分類群のレコードとそのシノニムのレコードを結合します。1回につきシノニムは10件で、各行にはsourceAphiaIdタグが付きます。synonymUnionには対象範囲、続きから取得するためのnextSynonymOffset、およびfailedSynonymsが含まれます
• noticeにはリンク先の受け入れられたAphiaIDが示され、受け入れられた別表記と優先されるAphiaIDが区別されます。includeSynonymsを指定しない場合、ステータスの取得に失敗すると、行とともにstatusErrorが返されます

---

worms_get_traits _tool

• aphiaIdを1つ指定します。includeInherited（デフォルトはtrue）を指定すると、上位分類群に記録された属性も追加されます。受け入れられた分類群では、includeInheritedの設定にかかわらず、WoRMSはそのシノニムに記録された属性も返します。どちらの場合も、inheritedFromには元の分類群が示されます
• noticeにはリンク先の受け入れられたAphiaIDが示され、受け入れられた別表記と優先されるAphiaIDが区別されます。ステータスの取得に失敗すると、属性とともにstatusErrorが返されます
• すべてのノードは、完全なツリー内のnodeIndex、parentIndex、depthを保持します。そのため、ページをまたいでも単位と修飾子が値に紐付いたままになります。値と参照は原文のままです
• measurementType（大文字と小文字を区別せず完全一致。例：Body size）を指定すると、一致する各ノードとそのサブツリーおよび祖先が、インデックスを変更せずに保持されます。totalCountはその集合の件数、unfilteredCountはツリー全体の件数です

---

worms_crosswalk_id _tool

• aphiaId（順方向）またはtypeを伴うexternalId（逆方向）のどちらか一方を指定します。順方向では、typeを1つ指定するか、次の9種類すべてを指定します：algaebase、bold、dyntaxa、fishbase、iucn、lsid、ncbi、tsn、gisd
• 順方向では、タイプごとのids、typeTotals（0は記録なしを示します）、エラーが発生したシステムのfailedTypesを返します。逆方向では、foundと完全なレコードを返します。IDは不透明な文字列のまま扱われ、先頭のゼロも保持されます

---

worms_list_reference _tool

• topic：external_id_types、statuses、environment_flags、distribution_termsはオフラインで提供され、ranksとtrait_typesはライブで取得されます
• statusesには、WoRMSのマニュアルとREST APIで説明されている28種類のステータスが含まれ、それぞれに1行の説明とgroup（accepted、unaccepted、uncertain、technical）が付いています。レコードのステータスは、junior subjective synonymのように具体的な理由そのものの場合があるため、status === "unaccepted"ではなくグループで判定してください。このガイドは網羅的ではありません
• distribution_termsには、WoRMSの分布情報で確認されているestablishmentMeans、invasiveness、occurrenceの値が一覧表示されます。これはworms_get_distributionsの値全体一致フィルターに使用します。一覧は網羅的ではありません
• resultOffsetを使ってページを取得します。形質の定義では、ページをまたいでもツリー内のインデックスが維持されます

機能

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

WoRMS 固有の機能：

• 海洋種および現存種のフィルターを備えた、完全一致と TAXAMATCH によるあいまいな名前照合。すべての照合結果とレコードに、受け入れられた名前へのリンクが含まれます
• 共有リクエストキューは、上流へのリクエストを一度に 1 件に制限し、開始間隔を 500 ms、ツールの期限を 45 秒、レスポンスの上限を 8 MiB に設定します
• WoRMS の Web サービスに関するガイダンスに従い、キャッシュや一括取得を行わず、呼び出しごとにデータを取得します
• すべてのレスポンスに WoRMS の帰属情報（doi:10.14284/170）が含まれます。結果を再利用する場合は WoRMS Editorial Board をクレジットし、レコードごとの引用を維持してください（利用規約）

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

• バイト数に基づくページ分割：読み取りでは 24,000 バイトのレスポンス内に収まる項目全体を返し、次のオフセットを示します（nextResultOffset、nextInputOffset、上流の page.nextOffset）。上流のページが 50 行すべてを含む場合、推測で判断せず hasMore: null を返します
• 不明な情報は不明のまま：null と欠落フィールドはそのまま引き継がれ、環境フラグの null は未記録を意味し、証拠がない場合に生物学的な不在を示すことはありません
• 部分的な失敗：任意の検索（vernacularError、sourcesError、childrenError、statusError）、同義語の統合における failedSynonyms、およびクロスウォークの failedTypes では、到着したデータを保持し、型付きの理由と復旧のヒントを返します

はじめに

公開ホストインスタンス

公開インスタンス（https://worms-marine-taxa.caseyjhand.com/mcp）を利用できます。インストールは不要です。Streamable HTTP を提供しており、クライアントごとに設定形式が異なります。

Claude Code の場合：

claude mcp add --transport http worms-marine-taxa-mcp-server https://worms-marine-taxa.caseyjhand.com/mcp

Cline（cline_mcp_settings.json）の場合：

{
  "mcpServers": {
    "worms-marine-taxa-mcp-server": {
      "type": "streamableHttp",
      "url": "https://worms-marine-taxa.caseyjhand.com/mcp"
    }
  }
}

Cursor（mcp.json）の場合：

{
  "mcpServers": {
    "worms-marine-taxa-mcp-server": {
      "url": "https://worms-marine-taxa.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop では、Settings → Connectors からリモートサーバーを追加します。

セルフホスト／ローカル

以下を MCP クライアントの設定ファイルに追加します。

{
  "mcpServers": {
    "worms-marine-taxa-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/worms-marine-taxa-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または npx を使用します（Bun は不要です）。

{
  "mcpServers": {
    "worms-marine-taxa-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/worms-marine-taxa-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

または Docker を使用します。

{
  "mcpServers": {
    "worms-marine-taxa-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/worms-marine-taxa-mcp-server:latest"]
    }
  }
}

Streamable HTTP を使用する場合は、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以上（または Node.js v24+）。
• API キーやアカウントは不要です。WoRMS REST API は公開されています。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/worms-marine-taxa-mcp-server.git

2. ディレクトリに移動します：

cd worms-marine-taxa-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env

設定

サーバー独自の変数はありません。以下は共通のフレームワーク設定です。

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_PORT	HTTP サーバーのポート。	3010
MCP_SESSION_MODE	HTTP セッションモード：stateless、stateful、または auto。	stateless
MCP_AUTH_MODE	認証：none、jwt、または oauth。	none
MCP_LOG_LEVEL	ログレベル（debug、info、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 を参照してください。

サーバーの実行

ローカル開発

• 本番版をビルドして実行します：

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

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

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite
  

プロジェクト構成

ディレクトリ	目的
src/mcp-server/tools/definitions	ツール定義（*.tool.ts）。読み取り専用ツールが8つあります。
src/services/worms	WoRMS サービス：ペース調整されたトランスポート、正規化、ドメインスキーマ、レスポンスの予算管理、フォーマット処理。
docs/	設計契約（design.md）と生成されたディレクトリツリー。
tests/	サービス、ツール契約、JSON-RPC の統合テスト。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。オプションの検索で問題が発生した場合は、データを破棄するのではなく、主要データと並べて分類済みの失敗として報告します
• 新しいツールは src/index.ts の createApp() 配列に登録します
• 内部インポートでは、.js 拡張子を含む相対 ESM パスを使用します
• 外部 API 呼び出しは、未加工データの検証 → ドメイン型への正規化 → 出力スキーマの返却、の順にラップします。不足しているフィールドを捏造してはいけません

貢献

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

bun run devcheck
bun run test

ライセンス

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