内容
<div align="center">
<h1>古生物学MCP服务器</h1>
<p><b>搜索化石记录，解析分类单元的化石范围，绘制多样性曲线，并通过MCP查询地质时间表。支持STDIO或Streamable HTTP。</b>
<div>7 个工具 • 2 个资源</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/paleobiology-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/paleobiology-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/paleobiology-mcp-server/releases/latest/download/paleobiology-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=paleobiology-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvcGFsZW9iaW9sb2d5LW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22paleobiology-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A5B%22-Y%22%2C%22%40cyanheads%2Fpaleobiology-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
---
## 工具
八个工具（默认七个）—— 五个针对古生物学数据库的领域工具，以及针对暂存发生集的SQL的三项DataCanvas工具。大型的发生结果会溢出到画布中；其他领域工具返回内联。
| 工具名称 | 描述 |
|:----------|:------------|
| `paleobiology_search_occurrences` | 按分类单元、地质时间、地理位置和沉积环境搜索化石记录。每一行都带有现代和古老坐标。旗舰工具；广泛的结果会溢出到DataCanvas进行SQL查询。 |
| `paleobiology_get_taxon` | 通过名称或`taxon_no`解析分类单元，获取其接受的名称、等级、分类、父分类单元、发生次数和首/末次出现（FAD/LAD）范围。运行此工具首先解析其他工具的名称。 |
| `paleobiology_get_diversity` | 计算一个进化枝在地质时间上的多样性/起源/灭绝曲线，按时期、纪元或年龄分段。返回完整的分段集。 |
| `paleobiology_list_intervals` | 查询地质时间表 - 从宙到年龄，带有绝对年龄（Ma）边界和嵌套。通过捆绑的ICS快照提供；无需网络调用。 |
| `paleobiology_search_collections` | 按区域和地质时间查找化石集合（产地），及其形成、岩性、沉积环境和共生化石数量。分页内联显示。 |
| `paleobiology_dataframe_query` | 对暂存的发生集运行只读SQL `SELECT`查询。仅限SELECT查询。 |
| `paleobiology_dataframe_describe` | 列出暂存到DataCanvas的表和列。在调用`paleobiology_dataframe_query`之前调用以发现表和列名。 |
| `paleobiology_dataframe_drop` | 删除单个暂存表以释放内存，过期前。需选择性启用 - 当`PALEOBIOLOGY_DATAFRAME_DROP_ENABLED=true`时注册。 |
---
### `paleobiology_search_occurrences`
搜索化石记录，过滤条件包括分类单元、地质时间、地理位置和环境 - 旗舰工具。
- `base_name`（一个进化枝及其所有后代）或`taxon_name`（精确）用于分类单元过滤
- 通过命名间隔（例如`Maastrichtian`）或`max_ma`/`min_ma`范围和/或经纬度边界框确定年龄
- `environment`枚举：`marine`，`terrestrial`，`freshwater`
- 每行都带有两个不同的坐标系统 - **现代**经纬度（岩石当前位置）和**古老**经纬度（陆块沉积时的位置）- 以及地层和年龄间隔
- 广泛查询返回多行：内联预览回答即刻问题，全套结果暂存到DataCanvas（`canvas_id` + `table_name`）通过`paleobiology_dataframe_query`进行SQL查询
- 重用`canvas_id` **替换**该画布的发生表 - 每次搜索都重新暂存全套结果，不会累积调用
---
### `paleobiology_get_taxon`
通过名称或整数`taxon_no`解析分类单元，获取其完整记录和化石时间范围 - 名称解析网关，依赖于发生和多样性工具。
- 返回接受的名称、等级、更高分类、直接父分类单元、发生次数和FAD/LAD范围（Ma）
- `show_children`还列出直接的子分类单元
- PBDB分类法是有偏见的，可能与GBIF的主干不同，因此接受的名称可能与搜索的名称不同 - 响应同时显示两者
---
### `paleobiology_get_diversity`
计算一个进化枝在地质时间上的多样性/起源/灭绝曲线。
- 进化枝包含`base_name`，以命名间隔（例如`Mesozoic`）或`max_ma`/`min_ma`范围为界
- `count`枚举：`genera`，`species`，`families`; `resolution`枚举：`period`，`epoch`，`age`
- 完整的分段集返回内联（多样性系列是一个有界的地质间隔集）
- 计数反映**采样**的多样性，受采集工作和岩石可用性的偏差 - 而不是真正过去的多样性
---
### `paleobiology_search_collections`
查找化石集合（产地）按区域和地质时间 - “这里挖掘了什么，来自什么岩石”。
- 每个产地返回位置、年龄（命名间隔和Ma）、地层和岩层、岩性、沉积环境和共生化石数量
- 按`base_name`、命名间隔或`max_ma`/`min_ma`范围、经纬度边界框、`formation`或`lithology`名称和/或`environment`过滤
- 结果通过`limit`/`offset`分页内联显示；响应显示是否还有更多结果
- 从一行中获取`collection_no` - 或相同的bbox+interval - 进入`paleobiology_search_occurrences`查看一起发现的 fauna
---
## 资源和提示
| 类型 | 名称 | 描述 |
|:---|:---|:---|
| 资源 | `paleobiology://occurrence/{occurrence_no}` | 一个化石记录，包含完整详细信息 - 现代 + 古老坐标、分类、地层、产地。 |
| 资源 | `paleobiology://taxon/{taxon_no}` | 一个分类单元记录，包含其化石范围和分类。 |
所有资源数据也可通过工具获取 - 资源镜像单个记录的`paleobiology_search_occurrences` / `paleobiology_get_taxon`，适用于显示资源的客户端。仅限工具的客户端不会损失任何功能。`occurrence_no`和`taxon_no`是来自这些工具输出的裸整数。
---
## 功能
构建于[`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):
- 声明式工具、资源和提示定义 - 每个基元一个文件，框架处理注册和验证
- 统一错误处理 - 处理程序抛出，框架捕获、分类和格式化
- 可插拔身份验证：`none`，`jwt`，`oauth`（默认运行`none` - PBDB无密钥）
- 可交换存储后端：`in-memory`，`filesystem`，`Supabase`，`Cloudflare KV/R2/D1`
- 带有可选OpenTelemetry跟踪的结构化日志记录
- STDIO和Streamable HTTP传输
古生物学特定：
- 古生物学数据库（PBDB）REST API的类型安全客户端，请求`vocab=pbdb`，以便从上游直接获取可读字段名称，而不是手动映射简洁代码
- 捆绑的ICS地质时间尺度快照 - `paleobiology_list_intervals`在没有网络调用的情况下解析命名间隔↔绝对Ma边界
- 发生查询的大画布溢出：内联预览 + 暂存表可通过只读SQL查询（按间隔计数，按地层/国家/岩性分组）
代理友好输出：
- 每个发生记录的两个坐标系统 - 现代经纬度和古老经纬度 - 明确标记，以便代理不会将深时化石绘制到现代海岸线
- 每个年龄的两个时间表示 - 命名的间隔 **和** 其Ma边界
- 来源和诚实 - 每行携带其`reference_no`，响应携带CC-BY归属，稀疏的上游字段（古坐标、地层、`late_interval`）被省略而不是归零，多样性计数被标记为采样
---
## 快速入门
将以下内容之一添加到您的MCP客户端配置文件中。PBDB是无密钥的 - 不需要API密钥。
使用bunx：
```json
{
"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）：
```json
{
"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：
```json
{
"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，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# 服务器监听 http://localhost:3010/mcp
```
要启用大型发生集的SQL查询，请设置`CANVAS_PROVIDER_TYPE=duckdb`（`@duckdb/node-api`同级依赖项随`dependencies`一起发布）。如果没有它，`paleobiology_search_occurrences`仍然会返回其内联预览；`paleobiology_dataframe_*`工具会失败并显示明确的“画布禁用”消息。
### 先决条件
- [Bun v1.3](https://bun.sh/) 或更高版本（或Node.js v24+）。
- 无API密钥 - 古生物学数据库是完全开放的。
### 安装
1. **克隆仓库：**
```sh
git clone https://github.com/cyanheads/paleobiology-mcp-server.git
```
2. **导航到目录：**
```sh
cd paleobiology-mcp-server
```
3. **安装依赖项：**
```sh
bun install
```
4. **配置环境（可选）：**
```sh
cp .env.example .env
# 编辑.env以覆盖默认值 - 所有变量都是可选的
```
## 配置
所有变量都是可选的 - 服务器在没有配置的情况下运行对公共PBDB API的访问。
| 变量 | 描述 | 默认值 |
|:---------|:------------|:--------|
| `PBDB_BASE_URL` | 古生物学数据库API基础。覆盖镜像/代理或固定API版本。 | `https://paleobiodb.org/data1.2` |
| `PBDB_TIMEOUT_MS` | 每个请求的超时毫秒数。大型进化枝的多样性查询可能很慢。 | `30000` |
| `PBDB_MAX_OCCURRENCES` | 每个发生/集合调用的硬上限行数。 | `1000` |
| `CANVAS_PROVIDER_TYPE` | 设置为`duckdb`以启用DataCanvas溢出路径和`paleobiology_dataframe_*`工具。 | `none` |
| `PALEOBIOLOGY_DATAFRAME_DROP_ENABLED` | 注册`paleobiology_dataframe_drop`。当未设置时，从`tools/list`中消失。 | `false` |
| `MCP_TRANSPORT_TYPE` | 传输：`stdio`或`http`。 | `stdio` |
| `MCP_HTTP_PORT` | HTTP服务器端口。 | `3010` |
| `MCP_AUTH_MODE` | 身份验证模式：`none`，`jwt`或`oauth`。 | `none` |
| `MCP_LOG_LEVEL` | 日志级别（RFC 5424）。 | `info` |
| `OTEL_ENABLED` | 启用[OpenTelemetry仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry)（跨度，指标，完成日志）。 | `false` |
查看[`.env.example`](./.env.example)以获取完整的覆盖项列表。
## 运行服务器
### 本地开发
- **构建并运行：
```sh
# 一次性构建
bun run rebuild
# 运行构建的服务器
bun run start:stdio
# 或
bun run start:http
```
- **运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全检查
bun run test # Vitest测试套件
bun run lint:mcp # 验证MCP定义对抗规范
```
### Docker
```sh
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`](./CLAUDE.md)以获取开发指南和架构规则。简版：
- 处理程序抛出，框架捕获 - 工具逻辑中没有`try/catch`
- 使用`ctx.log`进行请求范围的日志记录，使用`ctx.state`进行租户范围的存储
- 通过`src/mcp-server/*/definitions/index.ts`中的桶注册新工具和资源
- 包装外部API调用：验证原始数据 -> 规范化为域类型 -> 返回输出模式；永远不要构造缺少的字段（缺少的古坐标是“未知”，不是`0,0`）
## 贡献
问题和拉取请求是欢迎的。运行检查和测试后再提交：
```sh
bun run devcheck
bun run test
```
## 许可证
Apache-2.0 - 参见[LICENSE](LICENSE)以获取详细信息。
数据来自[古生物学数据库](https://paleobiodb.org)，许可证CC BY 4.0 - 在下游使用时请注明来源。
