reference-data-mcp-server

---

概述

在一处查询国家、时区、元素周期表中的元素、物理常数、计量单位、HTTP 状态码和 MIME 类型。可查询、搜索并进行转换，完全离线运行，无需 API 密钥，也没有速率限制。

工具

工具	描述
ref_geo_lookup	按名称、ISO alpha-2 或 alpha-3 代码查询国家。
ref_geo_search	按地区、次级地区、语言或货币搜索和筛选国家。
ref_timezone_lookup	按 IANA ID、国家代码或城市名称获取时区信息。
ref_timezone_convert	将本地日期时间从一个时区转换到另一个时区。
ref_element_lookup	按名称、符号或原子序数查询元素周期表中的元素。
ref_element_search	按类别、族、周期或属性范围筛选元素周期表中的元素。
ref_constant_lookup	按名称、符号或别名查询 CODATA 2022 物理常数。
ref_unit_convert	在兼容的计量单位之间转换数值。
ref_http_status	按编号或关键字查询 HTTP 状态码。
ref_mime_type	按类型字符串或文件扩展名查询 MIME 类型。

资源

资源	描述
ref://countries/{alpha2}	按 ISO alpha-2 代码查询完整国家记录。
ref://elements/{number}	按原子序数查询完整元素记录。
ref://timezones/{iana_id}	按 IANA ID 查询时区信息（斜杠会进行百分号编码，编码为 %2F）。

所有资源数据也可通过工具访问 — 如果需要灵活的查询模式或国家搜索，请使用 ref_geo_lookup、ref_element_lookup 和 ref_timezone_lookup。

---

功能参考

ref_geo_lookup _工具

• 支持模糊名称匹配（“Brasil”会解析为“Brazil”）；模糊匹配成功时会添加说明，注明规范名称
• 查询模式：auto（alpha2 → alpha3 → 名称）、name、alpha2、alpha3；不支持数字 ISO 代码
• 返回首都、区域/次区域、语言、货币、电话区号、顶级域名、国旗表情符号和 IANA 时区 ID

---

ref_geo_search _工具

• 至少需要一个筛选条件（否则会返回 no_filters 错误）：关键词（名称、本地名称、首都、次区域）、区域、次区域、语言（ISO 639-1 代码或名称）或货币（ISO 4217 代码或名称）
• 限制为 1–100（默认值为 20）；结果被截断时会返回 truncated 标记和 totalMatches 数量
• 无结果时会返回说明，并列出已应用的筛选条件

---

ref_timezone_lookup _工具

• 查询模式：auto（IANA ID → 国家代码 → 城市名称）、iana、country；支持城市名称部分匹配（“Tokyo” → “Asia/Tokyo”，“NY” → “America/New_York”）
• 国家代码查询会返回该国所有观测到的时区
• 可选参数 at（ISO 8601）用于评估特定时刻的夏令时状态，而非当前状态；格式错误的值会引发 invalid_at
• 返回当前/标准 UTC 偏移量、夏令时状态及缩写、主要城市和国家代码

---

ref_timezone_convert _工具

• datetime 必须是没有偏移量的本地 ISO 8601 字符串（通过正则表达式强制校验，例如 2026-05-24T15:30:00）；from_tz/to_tz 接受完整 IANA ID 或无歧义的城市名称
• 超出范围的日历日期和春季夏令时跳变造成的无效时间会被拒绝，并返回 invalid_datetime；无法识别的时区会返回 invalid_timezone
• 返回源和目标本地日期时间及其各自的 UTC 偏移量，以及对应的 UTC 时间

---

ref_element_lookup _工具

• 查询模式：auto（原子序数 → 元素符号 → 名称）、name、symbol、number
• 完整属性集：原子质量（atomic_mass_estimated 标记）、电子排布、族/周期/区、类别、鲍林电负性、密度、以开尔文为单位的熔点/沸点、标准状况下的物态、放射性、自然存在情况、发现数据
• 数据来源于 PubChem/IUPAC 2024；合成或不稳定元素在实验上无法测得的属性会返回 null

---

ref_element_search _工具

• 至少需要一个筛选条件（否则会返回 no_filters 错误）：类别（部分匹配）、族（1–18）、周期（1–7）、原子序数范围或原子质量范围
• 有效类别：碱金属、碱土金属、过渡金属、后过渡金属、类金属、活泼非金属、稀有气体、镧系元素、锕系元素
• 返回摘要（原子序数、元素符号、名称、质量、类别）以及 totalMatches 数量；无匹配结果时会附带说明

---

ref_constant_lookup _工具

• 支持模糊别名匹配：“speed of light”、“c”、“Avogadro's number”、“N_A”、“Planck”、“h”、“Boltzmann”、“k_B” 均可匹配 32 个 CODATA 2022 常数
• match_strategy 用于区分查询的解析方式：exact_symbol、exact_name 或 fuzzy（最接近的候选项 — 再次使用前请核实）
• 返回数值、SI 单位表达式、绝对/相对不确定度（定义常数带有 exact 标记）、CODATA 标识符和最多 3 个相关常数

---

ref_unit_convert _工具

• 11 个测量领域：长度、质量、体积、温度（C/F/K/R 非线性换算）、速度、压力、能量、功率、频率、数字存储、角度
• 质量单位 mt 是公吨（1000 kg）；t 是美制短吨（907.18 kg）——这是不同的单位，很容易混淆
• 类型化错误：incompatible_units（量不匹配）、unknown_unit（无法识别的缩写）、below_absolute_zero（附带开尔文等值）

---

ref_http_status _工具

• 数字查询（例如，“404”）返回精确匹配；关键词查询（例如，“not found”“too many requests”）返回最接近的匹配项及其他选项
• 返回原因短语、描述、类别（1xx–5xx）、根据 RFC 9110 判断的可缓存性，以及定义该状态码的 RFC 和章节引用

---

ref_mime_type _工具

• 可交替接受 "image/webp"、".webp" 或 "webp"
• 扩展名查询会首先返回规范 MIME 类型；共享该扩展名的其他类型将列为备选项
• 返回扩展名、可压缩标记（与 Content-Encoding 决策相关）和数据来源（iana/apache/nginx）

---

ref://countries/{alpha2} _资源

• 以 application/json 格式返回完整国家记录，字段与 ref_geo_lookup 相同
• alpha2 接受任意大小写；代码不匹配时返回 notFound 错误

---

ref://elements/{number} _资源

• 以 application/json 格式返回完整元素记录，字段与 ref_element_lookup 相同
• number 必须是 1–118 的整数字符串；超出范围或不匹配时返回 notFound

---

ref://timezones/{iana_id} _资源

• 以 application/json 格式返回时区记录，字段与 ref_timezone_lookup 相同，另含 evaluated_at
• IANA ID 中的斜杠必须进行百分号编码，写作 %2F（例如 America%2FNew_York）；未编码的斜杠会匹配单独的兜底路由，该路由会返回可执行的错误提示，其中包含正确编码后的 URI

---

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

参考数据特有功能：

• 完全在内存中运行——所有数据集均在启动时加载；运行时不进行网络调用，无需 API 密钥，也没有速率限制
• 可在离线和气隙环境中运行
• 七种专用服务：地理（countries-list）、时区（Node.js Intl + @vvo/tzdb）、元素（PubChem/IUPAC 2024，118 种元素）、常量（CODATA 2022，32 条）、单位（convert-units）、HTTP 状态（IANA 注册表）、MIME 类型（mime-db，约 1,000 种类型）

便于 Agent 使用的输出：

• 每个工具都提供结构化错误约定——类型化的 reason 代码（no_match、no_filters、unknown_unit、incompatible_units、below_absolute_zero、invalid_timezone、invalid_datetime、invalid_at），并附带可执行的恢复提示
• 在适用场景下提供区分明确的输出——搜索结果带有 truncated 标记，MIME/HTTP 关键词匹配结果带有 alternatives 数组，元素数据带有 atomic_mass_estimated 标记，常量查询带有 match_strategy
• 对于确实未知或不适用的值，统一使用 null，而非省略字段

---

入门

公共托管实例

可使用公共实例 https://reference-data.caseyjhand.com/mcp，无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

对于 Claude Code：

claude mcp add --transport http reference-data-mcp-server https://reference-data.caseyjhand.com/mcp

对于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "streamableHttp",
      "url": "https://reference-data.caseyjhand.com/mcp"
    }
  }
}

对于 Cursor（mcp.json）：

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "url": "https://reference-data.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop 可在 Settings → Connectors 下添加远程服务。

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中：

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

或者使用 npx（无需 Bun）：

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

或者使用 Docker：

{
  "mcpServers": {
    "reference-data-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/reference-data-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 密钥——此服务完全独立运行。

安装

1. 克隆代码仓库：

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

2. 进入目录：

cd reference-data-mcp-server

3. 安装依赖：

bun install

4. 配置环境（可选）：

cp .env.example .env
# edit .env if you want to override transport or logging defaults

---

配置

无需 API 密钥。所有配置都是对框架默认值的可选覆盖。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务的端口。	3010
MCP_HTTP_HOST	HTTP 服务的主机。	127.0.0.1
MCP_SESSION_MODE	会话模式：stateful、stateless 或 auto（架构默认值 auto 会解析为 stateful）。	stateless
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（RFC 5424）：debug、info、notice、warning、error。	info
LOGS_DIR	日志文件目录（仅限 Node.js）。	<project-root>/logs
OTEL_ENABLED	启用 OpenTelemetry 插桩（spans、指标、完成日志）。	false

完整的可选覆盖项列表请参阅 .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 reference-data-mcp-server .
docker run --rm -p 3010:3010 reference-data-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/reference-data-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

---

项目结构

目录	用途
src/index.ts	createApp() 入口——注册工具和资源并初始化服务。
src/data/	静态数据集（元素周期表、物理常数、HTTP 状态码）。
src/mcp-server/tools/	工具定义（*.tool.ts）。
src/mcp-server/resources/	资源定义（*.resource.ts）。
src/services/	领域服务集成（地理、时区、元素、常数、单位、http-status、mime）。
tests/	与 src/ 对应的单元测试。
docs/	生成的文档（tree.md、design.md）。
changelog/	按版本分类的变更日志文件。

---

开发指南

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

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 存储租户范围内的数据
• 在 src/index.ts 中直接注册新工具和资源
• 数据完整性：校验原始数据 → 规范化为领域类型 → 返回输出架构；切勿伪造缺失字段

---

贡献

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

bun run devcheck
bun run test

---

许可证

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