worms-marine-taxa-mcp-server

---

概述

来自 World Register of Marine Species（WoRMS） 的海洋分类学数据。将学名或俗名解析为 AphiaID，追踪接受名，并从无需密钥的 WoRMS REST API 获取分类、异名、分布、特征和外部标识符。

每个 AphiaID 选择器都接受正的安全整数、十进制字符串或规范的 WoRMS LSID，例如 urn:lsid:marinespecies.org:taxname:137205；返回的 AphiaID 始终为数字。对于其他 LSID，请使用 worms_crosswalk_id，并传入 externalId 和 type: "lsid"；也可以使用 worms_resolve_taxon 解析学名。

工具

工具	描述
worms_resolve_taxon	将学名（精确或模糊）或一个俗名解析为 AphiaID，并提供接受名链接
worms_get_taxon	按 AphiaID 获取完整的 Aphia 记录，可选包含俗名或来源
worms_get_classification	获取从根到末端的分类，可选包含直接子项
worms_get_synonyms	列出 AphiaID 对应的接受分类单元的同义名
worms_get_distributions	获取记录的分布，可按状态、定居方式、入侵性或出现情况筛选
worms_get_traits	获取属性树（体型、功能群、保护名录），包含来源和继承信息
worms_crosswalk_id	将 AphiaID 映射到九种外部标识符系统，或反向解析外部 ID
worms_list_reference	列出标识符系统、状态、环境标记、分布筛选值、分类阶元和性状定义

功能参考

worms_resolve_taxon _工具

• 需提供非空的 names 列表（输入总量不限，每次上游请求最多 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 列表，输入总量不限，每次请求最多获取 50 个；使用未更改的列表和 nextInputOffset 继续获取。未知 ID 会在原位置保留为 found: false；获取前会验证每个提交的元素
• includeVernaculars: true（仅限一个 ID）会添加俗名，并使用 vernacularOffset 分页；查找失败时，会在记录旁返回 vernacularError
• includeSources: true（仅限一个 ID，不能与 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；ranks 是从根到末端的谱系，WoRMS 没有记录时返回 found: false
• includeChildren: true 会添加一页直接子项（每页 50 行），可使用 offset、marineOnly 和 extantOnly；子项查找失败时，会在谱系旁返回 childrenError
• 提交的 AphiaID 保留其自身记录的谱系。notice 会指出其关联的接受 AphiaID，或接受名的首选 AphiaID 表示形式；状态查找失败时，会在谱系旁返回 statusError

---

worms_get_synonyms _工具

• 一个 aphiaId，无论是否为接受名：同义名均按其接受分类单元（validAphiaId）列出，上游 offset 每页 50 个
• found 和 guidance 可区分分类单元缺失与名称没有已知接受 ID 的情况

---

worms_get_distributions _工具

• 一个 aphiaId；可选的 recordStatus（valid、doubtful、inaccurate）、establishmentMeans、invasiveness 和 occurrence 筛选条件按 AND 组合。recordStatus 不区分大小写，并忽略首尾空白，回显时使用其小写代码；其他筛选条件按不区分大小写的完整值匹配，不会去除非空字符串的首尾空白，观测到的值见 worms_list_reference 的 distribution_terms 主题。空白筛选条件会被忽略
• 报告 unfilteredCount 和 filteredCount；每行包含地点、其 MarineRegions locationId 以及状态字段，顺序与源数据一致
• WoRMS 会将记录关联到单个名称用法，因此默认情况下，工具只读取该 AphiaID 自身的记录。includeSynonyms: true 会合并接受分类单元及其同物异名的记录，每次调用处理 10 个同物异名，每行均标记 sourceAphiaId；synonymUnion 会报告处理窗口、用于继续处理的 nextSynonymOffset 以及任何 failedSynonyms
• notice 会指出关联的已接受 AphiaID，并区分已接受的替代表示与首选 AphiaID；若未设置 includeSynonyms，状态查询失败时会在各行旁返回 statusError

---

worms_get_traits _工具

• 一个 aphiaId；includeInherited（默认值为 true）会添加记录在高阶分类单元上的属性。对于已接受的分类单元，无论 includeInherited 设置为何值，WoRMS 也会返回记录在其同物异名上的属性；两种情况下，inheritedFrom 都会指出来源分类单元
• notice 会指出关联的已接受 AphiaID，并区分已接受的替代表示与首选 AphiaID；状态查询失败时会在各属性旁返回 statusError
• 每个节点都保留完整树中的 nodeIndex、parentIndex 和 depth，因此翻页时单位和限定词仍与对应值关联；值和引用均按原样返回
• measurementType（按不区分大小写的完整值匹配，例如 Body size）会保留每个匹配节点及其子树和祖先节点，索引保持不变；totalCount 统计该结果集，unfilteredCount 统计整棵树

---

worms_crosswalk_id _工具

• aphiaId（正向查询）或带有 type 的 externalId（反向查询）必须且只能提供一个。正向查询可读取一种 type，也可读取全部九种：algaebase、bold、dyntaxa、fishbase、iucn、lsid、ncbi、tsn、gisd
• 正向查询按类型返回 ids、typeTotals（0 表示没有记录）以及出错系统对应的 failedTypes；反向查询返回 found 和完整记录。ID 保持为不透明字符串，包括前导零

---

worms_list_reference _工具

• topic：external_id_types、statuses、environment_flags 和 distribution_terms 离线提供；ranks 和 trait_types 实时读取
• statuses 涵盖 WoRMS 手册和 REST API 文档记录的 28 种状态，每种都附有一行释义和一个 group（accepted、unaccepted、uncertain、technical）。记录的状态可能就是具体原因本身，例如 junior subjective synonym，因此应检查 group，而不是检查 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 模糊名称匹配，支持海洋和现存筛选；每个匹配项和记录均包含其接受名链接
• 使用共享请求队列：同一时间仅发送一个上游请求，每次请求启动间隔 500 ms，工具截止时间为 45 秒，响应上限为 8 MiB
• 每次调用单独检索，不使用缓存或批量采集，符合 WoRMS Web 服务指南的要求
• 每个响应均包含 WoRMS 署名信息（doi:10.14284/170）；引用 WoRMS 编辑委员会，并在重用结果时保留每条记录的引文（条款）

便于 Agent 使用的输出：

• 按字节限制分页：读取时返回完整条目，响应上限为 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）。包含八个只读工具。
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 文件。