Reference Data Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.2.0更新於 Oct 29, 2026

Countries, timezones, elements, constants, HTTP status codes, unit conversion, and MIME type lookup.

已驗證Streamable HTTP可網頁執行開發者工具資料與分析

概覽

AI 產生的概覽

離線參考資料伺服器,提供國家、時區、元素週期表、物理常數、單位換算、HTTP 狀態碼與 MIME 類型查詢。

可以做什麼
  • 依名稱、ISO 代碼、地區、語言或貨幣查詢與篩選國家
  • 依 IANA ID、國家或城市查詢時區,並在時區間換算時間(含日光節約時間偏移)
  • 依符號、原子序、類別、族或週期查詢與篩選元素
  • 依名稱、符號或別名查詢 CODATA 2022 物理常數
  • 在長度、質量、體積、溫度等單位領域之間換算數值
  • 依數字、關鍵字、類型字串或副檔名查詢 HTTP 狀態碼與 MIME 類型
適用情境
適合需要可靠、可引用的參考事實而非網路猜測的情境:國家詮釋資料、跨日光節約時間的會議時間換算、化學與物理查詢、單位計算,以及除錯 API 與內容類型時的 HTTP 和 MIME 細節。
執行需求
可使用公開託管的 Streamable HTTP 端點(無需安裝),或透過 npx/bunx、Docker 或原始碼在本機執行。本機執行需 Bun v1.4.0+ 或 Node.js v24+。無需 API 金鑰或帳號;選用環境變數可設定傳輸方式、HTTP 主機與連接埠、驗證模式與日誌等級。
安裝前請注意
皆為唯讀查詢且不呼叫外部 API,風險較低。託管端點是第三方公開實例,使用時查詢內容會離開本機;若需留在本機可自行部署。自行部署並對外開放 HTTP 實例前,應檢查選用的驗證模式(jwt、oauth)與綁定設定。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Reference Data Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Freference-data-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@cyanheads/reference-data-mcp-server

Look up countries, timezones, periodic table elements, physical constants, units, HTTP status codes, and MIME types via MCP. STDIO or Streamable HTTP.

10 Tools • 3 Reference Resource Families • 1 Agent Skill


Overview

Countries, timezones, periodic table elements, physical constants, units, HTTP status codes, and MIME types in one place. Look up, search, and convert across all of them, entirely offline with no API keys or rate limits.

Tools

ToolDescription
ref_geo_lookupLook up a country by name, ISO alpha-2, or alpha-3 code.
ref_geo_searchSearch and filter countries by region, subregion, language, or currency.
ref_timezone_lookupGet timezone info by IANA ID, country code, or city name.
ref_timezone_convertConvert a local datetime from one timezone to another.
ref_element_lookupLook up a periodic table element by name, symbol, or atomic number.
ref_element_searchFilter periodic table elements by category, group, period, or property range.
ref_constant_lookupLook up a CODATA 2022 physical constant by name, symbol, or alias.
ref_unit_convertConvert a numeric value between compatible units of measure.
ref_http_statusLook up an HTTP status code by number or keyword.
ref_mime_typeLook up a MIME type by type string or file extension.

Resources

ResourceDescription
ref://countries/{alpha2}Full country record by ISO alpha-2 code.
ref://elements/{number}Full element record by atomic number.
ref://timezones/{iana_id}Timezone info by IANA ID (slashes percent-encoded as %2F).
skill://reference-data-guide/SKILL.mdAgent guide for resolving locations and converting meeting times across DST transitions.

The three reference families use four URI template routes: countries, elements, encoded timezone IDs, and an unencoded-timezone-slash route that returns retry guidance. The guide is a separate skill resource.

Reference data is also reachable via tools — use ref_geo_lookup, ref_element_lookup, and ref_timezone_lookup when you need flexible query modes or country search.

The reference-data guide is included in plugin installs and available through MCP resource discovery or the Skills extension (skills/list and skills/get). It covers location resolution, repeated-hour disambiguation, and search-completeness gates.


Capability reference

ref_geo_lookup tool

  • Accepts fuzzy name matching ("Brasil" resolves to "Brazil"); a fuzzy hit adds an enrichment notice naming the canonical result
  • Lookup modes: auto (alpha2 → alpha3 → name), name, alpha2, alpha3; numeric ISO codes are not supported
  • Returns capital, region/subregion, languages, currencies, calling codes, TLD, flag emoji, and IANA timezone IDs

ref_geo_search tool

  • At least one filter required (no_filters error otherwise): keyword (name, native name, capital, subregion), region, subregion, language (ISO 639-1 code or name), or currency (ISO 4217 code or name)
  • Limit 1–100 (default 20); truncated flag and totalMatches count when results are cut off
  • Empty result set returns a notice echoing the applied filters

ref_timezone_lookup tool

  • Lookup modes: auto (IANA ID → country code → city name), iana, country; partial city matching ("Tokyo" → "Asia/Tokyo", "NY" → "America/New_York")
  • Country-code queries return every timezone observed in that country
  • Optional at (ISO 8601) evaluates DST state at a specific moment instead of now; malformed values raise invalid_at
  • Returns current/standard UTC offsets, DST status and abbreviations, major cities, and country codes

ref_timezone_convert tool

  • datetime must be a local ISO 8601 string without an offset (regex-enforced, e.g. 2026-05-24T15:30:00); from_tz/to_tz accept full IANA IDs or unambiguous city names
  • Rejects out-of-range calendar dates and spring-forward DST gaps as invalid_datetime; unrecognized zones as invalid_timezone
  • Returns source and target local datetimes with their respective UTC offsets, plus the UTC equivalent

ref_element_lookup tool

  • Lookup modes: auto (atomic number → symbol → name), name, symbol, number
  • Full property set: atomic mass (atomic_mass_estimated flag), electron configuration, group/period/block, category, Pauling electronegativity, density, melting/boiling points in kelvin, phase at STP, radioactivity, natural occurrence, discovery data
  • Data sourced from PubChem/IUPAC 2024; synthetic or unstable elements return null for experimentally inaccessible properties

ref_element_search tool

  • At least one filter required (no_filters error otherwise): category (partial match), group (1–18), period (1–7), atomic-number range, or atomic-mass range
  • Valid categories: alkali metal, alkaline earth metal, transition metal, post-transition metal, metalloid, reactive nonmetal, noble gas, lanthanide, actinide
  • Returns summaries (atomic number, symbol, name, mass, category) plus a totalMatches count and a notice when nothing matches

ref_constant_lookup tool

  • Fuzzy alias matching: "speed of light", "c", "Avogadro's number", "N_A", "Planck", "h", "Boltzmann", "k_B" all resolve against 32 CODATA 2022 constants
  • match_strategy discriminates how the query resolved: exact_symbol, exact_name, or fuzzy (closest candidate — verify before reuse)
  • Returns value, SI unit expression, absolute/relative uncertainty (exact flag for defined constants), CODATA identifier, and up to 3 related constants

ref_unit_convert tool

  • 11 measurement domains: length, mass, volume, temperature (non-linear C/F/K/R), speed, pressure, energy, power, frequency, digital storage, angle
  • Mass mt is the metric tonne (1000 kg); t is the US short ton (907.18 kg) — distinct units, easily confused
  • Typed errors: incompatible_units (mismatched quantities), unknown_unit (unrecognized abbreviation), below_absolute_zero (with the Kelvin equivalent)

ref_http_status tool

  • Numeric queries (e.g., "404") return an exact match; keyword queries (e.g., "not found", "too many requests") return the closest match plus alternatives
  • Returns reason phrase, description, category (1xx–5xx), cacheability per RFC 9110, and the defining RFC with section reference

ref_mime_type tool

  • Accepts "image/webp", ".webp", or "webp" interchangeably
  • Extension lookups return the canonical MIME type first; additional types sharing the extension are listed as alternatives
  • Returns extensions, a compressibility flag (relevant for Content-Encoding decisions), and the data source (iana/apache/nginx)

ref://countries/{alpha2} resource

  • Full country record as application/json — same fields as ref_geo_lookup
  • alpha2 accepts either case; an unmatched code returns a notFound error

ref://elements/{number} resource

  • Full element record as application/json — same fields as ref_element_lookup
  • number must be an integer string 1–118; out-of-range or unmatched values return notFound

ref://timezones/{iana_id} resource

  • Timezone record as application/json — same fields as ref_timezone_lookup, plus evaluated_at
  • Slashes in the IANA ID must be percent-encoded as %2F (e.g. America%2FNew_York); an unencoded slash matches a separate catch-all that returns an actionable error with the correctly encoded URI

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Reference-data-specific:

  • Entirely in-memory — all datasets load at startup; no runtime network calls, no API keys, no rate limits
  • Works offline and in air-gapped environments
  • Seven specialized services: geo (countries-list), timezone (Node.js Intl + @vvo/tzdb), elements (PubChem/IUPAC 2024, 118 elements), constants (CODATA 2022, 32 entries), units (convert-units), HTTP status (IANA registry), MIME types (mime-db, ~1,000 types)

Agent-friendly output:

  • Structured error contracts on every tool — typed reason codes (no_match, no_filters, unknown_unit, incompatible_units, below_absolute_zero, invalid_timezone, invalid_datetime, invalid_at) with actionable recovery hints
  • Discriminated outputs where relevant — truncated flag on search results, alternatives arrays on MIME/HTTP keyword matches, atomic_mass_estimated flag on element data, match_strategy on constant lookups
  • Consistent null for genuinely unknown or inapplicable values rather than absent fields

Getting started

Public Hosted Instance

A public instance is available at https://reference-data.caseyjhand.com/mcp — no installation required. It serves Streamable HTTP; each client takes its own config shape.

For Claude Code:

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

For Cline (cline_mcp_settings.json):

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

For Cursor (mcp.json):

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

Claude Desktop adds remote servers under Settings → Connectors.

Self-Hosted / Local

Add the following to your MCP client configuration file:

json
{  "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"      }    }  }}

Or with npx (no Bun required):

json
{  "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"      }    }  }}

Or with Docker:

json
{  "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"      ]    }  }}

For Streamable HTTP, set the transport and start the server:

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

Prerequisites

  • Bun v1.4.0 or higher (or Node.js v24+).
  • No API keys required — this server is entirely self-contained.

Installation

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/reference-data-mcp-server.git
  1. Navigate into the directory:
sh
cd reference-data-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment (optional):
sh
cp .env.example .env# edit .env if you want to override transport or logging defaults

Configuration

No API keys are required. All configuration is optional overrides of framework defaults.

VariableDescriptionDefault
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_HTTP_HOSTHost for HTTP server.127.0.0.1
MCP_SESSION_MODESession mode: stateful, stateless, or auto (schema default auto resolves to stateful).stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424): debug, info, notice, warning, error.info
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
OTEL_ENABLEDEnable OpenTelemetry instrumentation (spans, metrics, completion logs).false

See .env.example for the full list of optional overrides.


Running the server

Local development

sh
# One-time buildbun run rebuild
# Run the built serverbun run start:stdio# orbun run start:http
sh
bun run devcheck   # Lint, format, typecheck, securitybun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

sh
docker build -t reference-data-mcp-server .docker run --rm -p 3010:3010 reference-data-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/reference-data-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.


Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources and inits services.
src/data/Static datasets (periodic table, physical constants, HTTP status codes).
src/mcp-server/tools/Tool definitions (*.tool.ts).
src/mcp-server/resources/Resource definitions (*.resource.ts).
src/services/Domain service integrations (geo, timezone, elements, constants, units, http-status, mime).
tests/Unit tests mirroring src/.
docs/Generated docs (tree.md, design.md).
changelog/Per-version changelog files.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

  • Handlers throw, framework catches — no try/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
  • Register new tools and resources directly in src/index.ts
  • Data integrity: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 0b66e49

工具

10

ref_geo_lookup

Country Lookup

Look up a country by name, ISO alpha-2 code (2 letters), or ISO alpha-3 code (3 letters). Returns the full record: capital, region, official languages, currencies, calling codes, TLD, flag emoji, and IANA timezone IDs. Accepts fuzzy name matching — "Brasil" and "Brazil" both resolve.

輸入參數byquery必填

ref_timezone_lookup

Timezone Lookup

Get timezone info by IANA ID, country code, or partial city/region name. Returns current UTC offset, standard offset, whether DST is currently active, and major cities in the timezone. When querying by country code (ISO alpha-2), returns all timezones observed in that country. Accepts partial matches — "Tokyo" resolves to "Asia/Tokyo", "NY" resolves to "America/New_York".

輸入參數atbyquery必填

ref_timezone_convert

Timezone Conversion

Convert a local datetime from one timezone to another. Takes a local time string (no UTC offset, e.g., "2026-05-24T15:30:00") interpreted as local time in the source timezone, returns the equivalent local time in the target timezone. Shows both UTC offsets so DST transitions are visible. Accepts full IANA IDs (e.g., "Asia/Tokyo") or unambiguous city names (e.g., "Tokyo").

輸入參數to_tz必填from_tz必填datetime必填

ref_element_lookup

Element Lookup

Look up a periodic table element by name, chemical symbol, or atomic number. Returns the full data record: atomic number, symbol, name, atomic mass (in unified atomic mass units), electron configuration, group, period, block, category (e.g., "noble gas", "transition metal"), Pauling electronegativity, density (g/cm³), melting and boiling points in kelvin, and discovery year. Properties unavailable for synthetic or insufficiently studied elements are returned as null.

輸入參數byquery必填

ref_constant_lookup

Physical Constant Lookup

Look up a fundamental physical constant by name, symbol, or common alias. Returns the CODATA 2022 value, SI unit expression, relative standard uncertainty, and a short description. Recognizes common names and symbols — "speed of light", "c", "Avogadro's number", "N_A", "Planck", "h", "Boltzmann", "k_B" all resolve correctly. Fuzzy matching returns the closest match plus alternatives.

輸入參數query必填

ref_unit_convert

Unit Conversion

Convert a numeric value between compatible units of measure. Supports: length (mm, cm, m, km, in, ft, yd, mi), mass (mcg, mg, g, kg, oz, lb, mt = metric tonne / 1000 kg, t = US short ton / 907.18 kg), volume (ml, cl, dl, l, kl, tsp, Tbs, fl-oz, cup, pnt, qt, gal, m3), temperature (C, F, K, R — non-linear conversions handled), speed (m/s, km/h, knot, ft/s), pressure (Pa, kPa, MPa, hPa, bar, torr, psi), energy (J, kJ, Wh, kWh, MWh), power (W, mW, kW, MW, GW), frequency (Hz, kHz, MHz, GHz), digital storage (b, Kb, Mb, Gb, Tb, B, KB, MB, GB, TB), and angle (deg, rad, grad). Incompatible units (e.g., km to kg) return an error identifying the quantity mismatch.

輸入參數to必填from必填value必填

ref_http_status

HTTP Status Code Lookup

Look up an HTTP status code by number or keyword. Returns the reason phrase, description, category (1xx Informational, 2xx Success, 3xx Redirection, 4xx Client Error, 5xx Server Error), whether the code is cacheable by default, and the defining RFC with section reference. For keyword queries, returns the closest match plus alternatives.

輸入參數query必填

ref_mime_type

MIME Type Lookup

Look up a MIME type by type string or file extension. Accepts "image/webp", ".webp", or "webp". Returns the canonical MIME type, known file extensions, whether the type is compressible (relevant for Content-Encoding decisions), and the data source (iana, apache, nginx). For extension lookups, returns the canonical MIME type — e.g., ".jpg" resolves to "image/jpeg". When multiple types map to an extension, the canonical type is returned first with alternatives listed.

輸入參數query必填

版本歷史

5
  1. v0.2.0最新Oct 29, 2026
  2. v0.1.18Oct 25, 2026
  3. v0.1.17Oct 9, 2026
  4. v0.1.16Sep 21, 2026
  5. v0.1.15Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分