paleobiology-mcp-server

---

概要

古生物学データベース（PBDB）を通じて、およそ5億4千万年にわたる化石の生物多様性を調べられます。分類群の化石産出期間を特定し、分類群、地質時代、場所を指定して化石の産出記録やコレクションを検索し、地質時代を通じた多様性をプロットできます。

ツール

ツール	説明
paleobiology_search_occurrences	分類群、地質年代、地理的位置、堆積環境で化石産出記録を検索します。各行には現代と古生代の両方の座標が含まれます。DataCanvas が有効な場合、広範な検索結果はキャンバスに出力され、SQL で操作できます。
paleobiology_get_taxon	分類群名または taxon_no から分類群を特定し、有効名、階級、分類、FAD/LAD の範囲を取得します。名前解決の窓口です。
paleobiology_get_diversity	地質年代にわたるクレードの多様性／出現／絶滅曲線を計算します。
paleobiology_list_intervals	地質年代尺度を参照します。名称付きの区間と絶対年代（Ma）の境界を相互に検索できます。
paleobiology_search_collections	地域、地質年代、地層、岩相で化石コレクション（産地）を検索します。
paleobiology_get_references	産出記録とコレクションの行にある reference_no を完全な引用情報（著者、年、タイトル、出版物、ページ、DOI）に解決します。
paleobiology_dataframe_query	DataCanvas 上に用意された産出記録セットに対して、読み取り専用の SQL SELECT を実行します。DataCanvas が有効な場合のみ表示されます。
paleobiology_dataframe_describe	DataCanvas 上に用意されたテーブルと列を一覧表示します。DataCanvas が有効な場合のみ表示されます。
paleobiology_dataframe_drop	TTL の期限前にメモリを解放するため、用意されたテーブルを 1 つ削除します。オプトイン機能で、DataCanvas も必要です。

リソース

リソース	説明
paleobiology://occurrence/{occurrence_no}	化石産出記録 1 件の詳細情報（現代と古生代の座標、分類、地層、産地）。
paleobiology://taxon/{taxon_no}	化石の生息期間と分類を含む分類群レコード 1 件。
paleobiology://reference/{reference_no}	書誌情報 1 件（書式付き引用情報と構造化フィールド）。

リソースのデータはすべてツールからも取得できます。リソースは、リソースを表示するクライアント向けに、paleobiology_search_occurrences／paleobiology_get_taxon／paleobiology_get_references の単一レコード読み取りを反映します。ツールのみを扱うクライアントでも、失われる情報はありません。

---

機能リファレンス

paleobiology_search_occurrences _tool

• 分類群、年代、地理的位置、環境、または collection_no のフィルターを少なくとも 1 つ指定する必要があります。クレードには base_name または base_id、完全一致には taxon_name を使用します。limit（デフォルト 100、1 回の呼び出しで最大 500）と offset でページを指定します。レスポンスは 100,000 バイト以内に収まり、通知には続きの取得に使用するオフセットが示されます
• 現代と古生代の座標、名称付き区間と Ma 年代、地層、上位分類を、PBDB の実際の一致件数を示す totalCount とともに返します。エラーは、missing_filter、conflicting_taxon_filter、incomplete_bbox、inverted_ma_range、および PBDB が使用できない値に対する pbdb_invalid_parameter（PBDB の理由を含む）です
• DataCanvas が有効な場合、インライン表示するには大きすぎるページはキャンバスに格納され、canvas_id と table_name が返されます。これらを paleobiology_dataframe_describe に渡してから、SQL を実行します。キャンバスの上限に達した場合は、再試行可能な canvas_capacity_exhausted エラーが発生します。既存の canvas_id を渡すか、メッセージに示された値まで limit を下げてください。DataCanvas が無効な場合、上限を超えるページは切り詰められます

---

paleobiology_get_taxon _tool

• name または taxon_no で分類群を特定し、有効名、階級、分類、親分類群、産出記録件数、Ma 単位の FAD/LAD 範囲を取得します。返される taxon_no は、産出記録、多様性、コレクションの各検索で受け付けられる base_id です
• show_children を指定すると、呼び出しごとに直近の子分類群を最大 200 件追加します。children_truncated と children_offset で、続きがあるかどうかと、続きの取得位置がわかります
• 型付きエラー：name と taxon_no の両方が送信された場合は、taxon_not_found、missing_selector、conflicting_selector

---

paleobiology_get_diversity _ツール

• 分岐群（base_name または base_id）が必要です。必要に応じて interval または max_ma／min_ma で範囲を指定できます。count（genera、species、families）と resolution（period、epoch、age）を選択します。デフォルトは属、期間単位です
• サンプル数、推定数、出現数、絶滅数、レンジスルー数、産出数を含む全ビンを、古い順にインラインで返します
• 型付きエラー：missing_filter、conflicting_taxon_filter、inverted_ma_range、PBDB で使用できない値（不明な期間など）に対する pbdb_invalid_parameter

---

paleobiology_list_intervals _ツール

• name、min_ma／max_ma の重複期間、または level（eon、era、period、epoch、age）で絞り込みます。フィルターを省略すると、同梱の ICS 時間尺度を参照できます
• 期間の順位、Ma 境界、parent_no、利用可能な場合は上流の scale を返します。source（bundled_ics／pbdb_upstream）と snapshot_version でソースを特定します。スナップショットにない名前には PBDB を使用します
• 型付きエラー：一致する名前がない場合の interval_not_found、スナップショット外の名前を PBDB で解決できない場合の再試行可能な interval_lookup_unavailable、max_ma が min_ma より小さい場合の inverted_ma_range

---

paleobiology_search_collections _ツール

• 分類群、年代、地理、formation、lithology、environment のいずれかのフィルターが必要です。limit（デフォルトは 100、1 回の呼び出しで最大 500）と offset でページ分割します。応答は 100,000 バイト以内に収まり、通知には続きの取得に使うオフセットが示されます
• 合計値とともに、産地の座標、年代、地層、岩相、環境、n_occs を返します。その産地の動物相を取得するには、collection_no を paleobiology_search_occurrences に渡します
• 型付きエラー：missing_filter、conflicting_taxon_filter、incomplete_bbox、inverted_ma_range、PBDB で使用できない値（不明な期間、または唯一のフィルターとして指定された不明な岩相など）に対する pbdb_invalid_parameter

---

paleobiology_get_references _ツール

• 出現またはコレクションの行から 1～500 件の reference_nos を渡します。最初の 25 件の重複しない ID は 1 回の PBDB リクエストで解決され、残りは次回の呼び出し用に remaining_reference_nos として返されます
• 参照情報をリクエスト順に返します。PBDB の形式そのままのプレーンテキストの citation に加え、記録がある場合は title、year、authors、editors、publication、volume、issue、ページ、publisher、language、doi を返します
• PBDB に参照情報がない ID は通知とともに not_found に含まれます。見つからないことも結果であり、エラーではありません

---

paleobiology_dataframe_query _ツール

• paleobiology_search_occurrences によってステージングされた出現セットに対し、返された table_name を使用して読み取り専用 SQL SELECT を実行します。書き込み操作やファイル読み取り関数は拒否されます
• classification 列は JSON です。ランクごとに集計するには json_extract_string(classification, '$.family') を使用します（$.phylum、$.class、$.order、$.genus も使用できます）
• 応答は 100,000 バイト以内に収まり、通知には残りを取得する ORDER BY … LIMIT/OFFSET が示されます。truncated: true は、row_count がキャンバスの行数上限に達したことを意味します
• DataCanvas が有効な場合（CANVAS_PROVIDER_TYPE=duckdb）にのみ表示されます

---

paleobiology_dataframe_describe _ツール

• キャンバスにステージングされたテーブルを、それぞれの行数、列名、型、NULL 許容性とともに一覧表示します。識別子を確認するには、paleobiology_dataframe_query の前に呼び出してください
• DataCanvas が有効な場合（CANVAS_PROVIDER_TYPE=duckdb）にのみ表示されます

---

paleobiology_dataframe_drop _ツール

• canvas_id と table_name を指定してステージングされたテーブルを 1 つ削除し、TTL の期限前にメモリを解放します。存在しないテーブルを削除した場合はエラーではなく dropped: false を返します
• オプトイン方式です。DataCanvas が有効で、PALEOBIOLOGY_DATAFRAME_DROP_ENABLED=true に設定されている必要があります
• 型付きエラー：キャンバスの期限が切れている場合、または存在したことがない場合の canvas_not_found

---

paleobiology://occurrence/{occurrence_no} _リソース

• パスパラメーター occurrence_no は、paleobiology_search_occurrences の出力に含まれる、正規表現で検証された正の整数です
• ツールと同じ完全な出現記録の詳細を返します。採用名／同定名、年代、現代と古生物の座標、地層／層序、産地に加え、CC BY 4.0 の attribution フィールドを含みます
• 型付きエラー：occurrence_not_found

---

paleobiology://taxon/{taxon_no} _リソース

• パスパラメーター taxon_no は、paleobiology_get_taxon または出現記録の accepted_no に含まれる、正規表現で検証された正の整数です
• paleobiology_get_taxon と完全に同じ形式です。採用名、ランク、分類、親分類群、FAD/LAD の範囲に加え、CC BY 4.0 の attribution フィールドを含みます
• 型付きエラー：taxon_not_found

---

paleobiology://reference/{reference_no} _リソース

• パスパラメーター reference_no は、出現記録またはコレクションの行に含まれる、正規表現で検証された正の整数です
• paleobiology_get_references のエントリーと同じレコードに、CC BY 4.0 の attribution フィールドを加えて返します
• 型付きエラー：reference_not_found

---

特長

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

PBDB 固有の機能：

• Paleobiology Database（PBDB）REST API 用の型安全なクライアントです。vocab=pbdb を指定することで、簡潔なコードを手作業でマッピングせずに、読みやすいフィールド名を上流から直接取得します
• 同梱の ICS 地質年代スケールのスナップショットにより、paleobiology_list_intervals はネットワーク呼び出しなしで、国際スケールの名称付き時間区分と絶対 Ma 境界の対応を解決します。サブステージや地域名については PBDB への照会にフォールバックします
• 広範な出現記録クエリ向けのオプションの DataCanvas スピル（CANVAS_PROVIDER_TYPE=duckdb）：インラインプレビューに加え、読み取り専用 SQL でクエリできるステージ済みテーブルを提供します（時間区分ごとの件数、地層／国別のグループ化、classification JSON 列からの科ごとの集計など）
• 認証不要、API キー不要 — PBDB は完全に公開されており、MCP_AUTH_MODE のデフォルト値は none です
• 多様性の件数は、過去の真の多様性ではなく、サンプリングと採集の取り組みを反映します

エージェントが扱いやすい出力：

• すべての出現記録に、現代の経度／緯度と古生物の経度／緯度という2種類の座標系を明確にラベル付けして含めるため、エージェントが深い地質年代の化石を現代の海岸線上にプロットすることはありません
• すべての年代に、名称付き時間区分と Ma 境界の両方の時間表現を含めます
• すべての行に出典情報を含めます。paleobiology_get_references 用の reference_no に加え、ツールとリソースに CC BY の帰属情報を含めます
• 上流のフィールドが欠落している場合（古生物座標、地層、late_interval など）は、ゼロで埋めずに省略します

---

はじめに

公開ホストインスタンス

公開インスタンスを https://paleobiology.caseyjhand.com/mcp で利用できます。インストールは不要です。Streamable HTTP 経由で、任意の MCP クライアントを接続してください。

{
  "mcpServers": {
    "paleobiology-mcp-server": {
      "type": "streamable-http",
      "url": "https://paleobiology.caseyjhand.com/mcp"
    }
  }
}

セルフホスト／ローカル

以下のいずれかを MCP クライアントの設定ファイルに追加してください。PBDB はキー不要のため、API キーは必要ありません。

bunx を使用する場合：

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

または npx を使用する場合（Bun は不要です）：

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

または Docker を使用する場合：

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

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動してください。

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

大量の出現記録に対する SQL を有効にするには、CANVAS_PROVIDER_TYPE=duckdb を設定してください（@duckdb/node-api の peer dep は dependencies に含まれています）。設定しない場合も、paleobiology_search_occurrences はインラインプレビューを返しますが、paleobiology_dataframe_* ツールは tools/list から除外されます（HTTP ランディングページでは無効として表示され、有効化に必要な設定も示されます）。

前提条件

• Bun v1.4 以降（または Node.js v24 以降）。
• API キーは不要です — Paleobiology Database は完全に公開されています。

インストール

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

git clone https://github.com/cyanheads/paleobiology-mcp-server.git

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

cd paleobiology-mcp-server

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

bun install

4. 環境を設定します（任意）：

cp .env.example .env
# edit .env to override defaults — all vars are optional

設定

すべての変数は任意です。サーバーは、公開されている PBDB API に対して設定なしで動作します。

変数	説明	デフォルト
PBDB_BASE_URL	Paleobiology Database API のベース URL です。ミラー／プロキシまたは固定された API バージョンを使用する場合に上書きします。	https://paleobiodb.org/data1.2
PBDB_TIMEOUT_MS	リクエストごとのタイムアウト（ミリ秒）です。大きなクレードの多様性クエリには時間がかかることがあります。	30000
PBDB_MAX_OCCURRENCES	occurrence／collection の各呼び出しで取得する行数の上限です（ツールが取得するのは最大 500 件なので、それより小さい値のみ有効です）。	1000
CANVAS_PROVIDER_TYPE	DataCanvas のスピルパスを有効にし、paleobiology_dataframe_* ツールを一覧表示するには、duckdb に設定します。	none
PALEOBIOLOGY_DATAFRAME_DROP_ENABLED	paleobiology_dataframe_drop を有効にします（DataCanvas も有効にする必要があります）。	false
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	ログレベル（RFC 5424）です。	info
OTEL_ENABLED	OpenTelemetry instrumentation（スパン、メトリクス、完了ログ）を有効にします。	false
OTEL_EXPORTER_OTLP_ENDPOINT	トレースとメトリクス用の OTLP ベース URL です。ログには専用のエンドポイントが必要です。	unset
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	指定した正確な URL への OTLP ログエクスポートを有効にします。	unset
LOG_TOOL_FAILURE_PAYLOADS	失敗したツールの引数と結果をログに記録します。キー名はマスキングされますが、自由記述の値に含まれるシークレットは残ります。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	ログに記録するペイロードごとの UTF-8 バイト数の上限です。	16384

任意の上書き設定の全一覧については、.env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # 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 build -t paleobiology-mcp-server .
docker run --rm -p 3010:3010 paleobiology-mcp-server

Dockerfile のデフォルトは HTTP トランスポート、ステートレスセッションモードで、ログは /var/log/paleobiology-mcp-server に出力されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを省略するには、--build-arg OTEL_ENABLED=false を指定してビルドします。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() のエントリーポイントです。ツール／リソースを登録し、サービスを初期化します。
src/config	Zod による、サーバー固有の環境変数の解析と検証です。
src/mcp-server/tools	ツール定義（*.tool.ts）です。
src/mcp-server/resources	リソース定義（*.resource.ts）です。
src/services/pbdb	Paleobiology Database の HTTP クライアント、正規化処理、ドメイン型です。
src/services/intervals	同梱された ICS 地質年代スケールのスナップショットに対するインメモリインデックスです。
tests/	src/ に対応するユニットテストと統合テストです。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックに try/catch は使いません。
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用します。
• src/mcp-server/*/definitions/index.ts のバレルを通じて、新しいツールとリソースを登録します。
• 外部 API 呼び出しをラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに沿って返します。不足しているフィールドを捏造してはいけません（古生物座標が欠落している場合は「不明」であり、0,0 ではありません）。

データの帰属表示

データは Paleobiology Database のもので、CC BY 4.0 ライセンスの下で提供されています。二次利用の際はクレジットを表示してください。

コントリビューション

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

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。