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 到期前释放内存。须主动启用；还需要 DataCanvas。

资源

资源	描述
paleobiology://occurrence/{occurrence_no}	一条完整的化石出现记录——现代坐标和古地理坐标、分类体系、地层、地点。
paleobiology://taxon/{taxon_no}	一条分类单元记录，包含其化石分布范围和分类体系。
paleobiology://reference/{reference_no}	一条书目参考——格式化引文及其结构化字段。

所有资源数据也可通过工具访问——对于支持显示资源的客户端，资源会提供 paleobiology_search_occurrences／paleobiology_get_taxon／paleobiology_get_references 的单条记录读取结果。仅支持工具的客户端不会缺少任何数据。

---

能力参考

paleobiology_search_occurrences _工具

• 至少需要一个分类单元、年代、地理位置、环境或 collection_no 筛选条件。对演化支使用 base_name 或 base_id，精确匹配使用 taxon_name；使用 limit（默认值为 100，每次调用最多 500）和 offset 进行分页。响应大小不超过 100,000 字节，通知会标明用于继续查询的 offset
• 返回现代坐标和古地理坐标、命名时间段和 Ma 年龄、地层及更高层级的分类信息，并提供 totalCount，表示 PBDB 的实际匹配数。错误包括：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 _工具

• 按 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，每次调用最多 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 会通过一次 PBDB 请求解析，其余 ID 会在 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 暂存的出现记录集执行只读 SQL SELECT，使用其返回的 table_name；写入和读取文件的函数会被拒绝
• 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 _工具

• 列出画布上暂存的表，并显示每个表的行数以及列名／类型／可空性——在调用 paleobiology_dataframe_query 前调用此工具，以查找标识符
• 仅在 DataCanvas 已启用时列出（CANVAS_PROVIDER_TYPE=duckdb）

---

paleobiology_dataframe_drop _工具

• 根据 canvas_id + table_name 删除一个暂存表，以便在其 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 专属功能：

• 为古生物学数据库（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）
• 多样性计数反映采样和采集工作量，并非过去的真实多样性

面向 Agent 的输出：

• 每条出现记录都包含两套坐标——现代经度／纬度和古经度／纬度，并清楚标注，因此 Agent 不会把深时化石绘制在现代海岸线上
• 每个年代都包含两种时间表示——命名时间段及其 Ma 边界
• 每条记录都包含来源信息：reference_no 可用于 paleobiology_get_references，工具和资源还附带 CC BY attribution
• 上游缺失的字段（古坐标、地层、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 密钥——古生物学数据库完全开放。

安装

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	古生物学数据库 API 基础 URL。可覆盖为镜像/代理地址或固定的 API 版本。	https://paleobiodb.org/data1.2
PBDB_TIMEOUT_MS	每次请求的超时时间（毫秒）。针对大型类群的多样性查询可能会比较慢。	30000
PBDB_MAX_OCCURRENCES	每次出现记录/采集记录调用拉取的行数上限（工具最多拉取 500 行，因此只有设置较低值才会生效）。	1000
CANVAS_PROVIDER_TYPE	设置为 duckdb 可启用 DataCanvas 溢出路径，并列出 paleobiology_dataframe_* 工具。	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 检测（跨度、指标、完成日志）。	false
OTEL_EXPORTER_OTLP_ENDPOINT	用于跟踪和指标的 OTLP 基础 URL。日志需要单独设置端点。	未设置
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	将 OTLP 日志导出到此确切 URL。	未设置
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	古生物学数据库 HTTP 客户端、规范化处理和领域类型。
src/services/intervals	对内置 ICS 地质时间尺度快照建立的内存索引。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参见 CLAUDE.md/AGENTS.md。简要说明：

• 处理程序抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求级日志，使用 ctx.state 存储租户级数据
• 通过 src/mcp-server/*/definitions/index.ts 中的 barrel 文件注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；不要捏造缺失字段（缺失的古坐标应视为“未知”，而不是 0,0）

数据归属

数据来自 Paleobiology Database，采用 CC BY 4.0 许可——下游使用时请注明来源。

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0——详情请参见 LICENSE。