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 _tool

• あいまいな名前の照合に対応しています（「Brasil」は「Brazil」に解決されます）。あいまい一致した場合は、正規の結果名を示す補足通知が追加されます
• 検索モード：auto（alpha2 → alpha3 → name）、name、alpha2、alpha3。ISO 数値コードには対応していません
• 首都、地域／小地域、言語、通貨、国際電話番号、市外局番、TLD、旗の絵文字、IANA タイムゾーン ID を返します

---

ref_geo_search _tool

• 少なくとも1つのフィルターが必要です（それ以外の場合は no_filters エラー）：キーワード（国名、現地語名、首都、小地域）、地域、小地域、言語（ISO 639-1 コードまたは名前）、通貨（ISO 4217 コードまたは名前）
• 上限は1～100（デフォルトは20）です。結果が上限を超えた場合は truncated フラグと totalMatches 件数が返されます
• 結果がない場合は、適用されたフィルターを示す通知が返されます

---

ref_timezone_lookup _tool

• 検索モード：auto（IANA ID → 国コード → 都市名）、iana、country。都市名の部分一致に対応しています（「Tokyo」→「Asia/Tokyo」、「NY」→「America/New_York」）
• 国コードで検索すると、その国で使用されているすべてのタイムゾーンが返されます
• オプションの at（ISO 8601）を指定すると、現在ではなく特定の時点の DST 状態を評価します。不正な値の場合は invalid_at が発生します
• 現在／標準の UTC オフセット、DST の状態と略称、主要都市、国コードを返します

---

ref_timezone_convert _tool

• datetime は、オフセットを含まないローカルの ISO 8601 文字列である必要があります（正規表現で検証されます。例：2026-05-24T15:30:00）。from_tz／to_tz には完全な IANA ID または一意に特定できる都市名を指定できます
• 範囲外の日付と、春季の DST 開始時に生じる時刻の欠落は invalid_datetime、認識できないゾーンは invalid_timezone として拒否されます
• 変換元と変換先のローカル日時、それぞれの UTC オフセット、および UTC 換算値を返します

---

ref_element_lookup _tool

• 検索モード：auto（原子番号 → 元素記号 → 名前）、name、symbol、number
• 完全な特性セット：原子量（atomic_mass_estimated フラグ）、電子配置、族／周期／ブロック、分類、ポーリング電気陰性度、密度、ケルビン単位の融点／沸点、標準状態での相、放射能、天然存在、発見データ
• データは PubChem/IUPAC 2024 に基づいています。合成元素または不安定元素について、実験的に取得できない特性は null を返します

---

ref_element_search _tool

• 少なくとも1つのフィルターが必要です（それ以外の場合は no_filters エラー）：分類（部分一致）、族（1～18）、周期（1～7）、原子番号の範囲、または原子量の範囲
• 有効な分類：アルカリ金属、アルカリ土類金属、遷移金属、典型金属、半金属、反応性非金属、希ガス、ランタノイド、アクチノイド
• 原子番号、元素記号、名前、原子量、分類の概要に加え、totalMatches 件数を返します。一致する結果がない場合は通知も返されます

---

ref_constant_lookup _tool

• あいまいな別名の照合に対応しています：「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 _tool

• 11 の測定領域：長さ、質量、体積、温度（非線形の C/F/K/R）、速度、圧力、エネルギー、電力、周波数、デジタルストレージ、角度
• 質量の mt はメートルトン（1000 kg）です。t は米国ショートトン（907.18 kg）で、別の単位です。混同しやすいため注意してください
• 型付きエラー：incompatible_units（数量の不一致）、unknown_unit（認識できない略語）、below_absolute_zero（ケルビン換算値を含む）

---

ref_http_status _tool

• 数値でのクエリ（例：「404」）には完全一致を返します。キーワードでのクエリ（例：「not found」「too many requests」）には最も近い一致と代替候補を返します
• 理由フレーズ、説明、カテゴリ（1xx～5xx）、RFC 9110 に基づくキャッシュ可否、および該当セクションを含む定義 RFC を返します

---

ref_mime_type _tool

• 「image/webp」、「.webp」、「webp」のいずれの形式でも指定できます
• 拡張子で検索すると、正規の MIME タイプを最初に返します。同じ拡張子を共有する追加のタイプは代替候補として一覧表示されます
• 拡張子、圧縮可能フラグ（Content-Encoding の判断に関連）、およびデータソース（iana/apache/nginx）を返します

---

ref://countries/{alpha2} _resource

• application/json 形式の国の完全なレコードを返します。フィールドは ref_geo_lookup と同じです
• alpha2 は大文字と小文字を区別しません。一致するコードがない場合は notFound エラーを返します

---

ref://elements/{number} _resource

• application/json 形式の元素の完全なレコードを返します。フィールドは ref_element_lookup と同じです
• number は 1～118 の整数文字列である必要があります。範囲外または一致しない値の場合は notFound を返します

---

ref://timezones/{iana_id} _resource

• 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 キー、レート制限はありません
• オフライン環境やエアギャップ環境でも動作します
• 7 つの専門サービス：geo（countries-list）、timezone（Node.js Intl + @vvo/tzdb）、elements（PubChem/IUPAC 2024、118 元素）、constants（CODATA 2022、32 項目）、units（convert-units）、HTTP ステータス（IANA registry）、MIME タイプ（mime-db、約 1,000 種類）

エージェントに適した出力：

• すべてのツールで構造化エラーコントラクトを提供します。型付き 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 インストルメンテーション（スパン、メトリクス、完了ログ）を有効にします。	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 トランスポート、stateless セッションモードで、ログは /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/	ドメインサービスとの統合（geo、timezone、elements、constants、units、http-status、mime）。
tests/	src/ に対応するユニットテスト。
docs/	生成されたドキュメント（tree.md、design.md）。
changelog/	バージョンごとの変更履歴ファイル。

---

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md を参照してください。要点は以下のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します — ツールのロジック内で try/catch を使わないでください
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用します
• 新しいツールとリソースは src/index.ts に直接登録します
• データの完全性：生データを検証 → ドメイン型に正規化 → 出力スキーマを返却します。欠落しているフィールドを捏造しないでください

---

コントリビューション

Issue を歓迎します。提出前にチェックとテストを実行してください：

bun run devcheck
bun run test

---

ライセンス

Apache-2.0 — 詳細は LICENSE を参照してください。