datamuse-mcp-server

---

概要

Datamuse API を利用した、文章作成、編集、パズル、命名のための単語検索です。特定の意味を持つ韻を踏む語を探したり、語彙上の別表現を調べたり、意味、音、綴り、関係性の条件を組み合わせたりできます。

ツール

ツール	説明
datamuse_find_rhymes	意味や綴りによる絞り込みを任意で指定して、完全韻または近似韻を検索します
datamuse_find_synonyms	同義語、反意語、上位カテゴリ、下位の種類を検索します
datamuse_find_words	意味、音、綴り、名前付きの語彙関係を、文脈やトピックのヒントと組み合わせます
datamuse_list_reference	関係、メタデータ、条件の組み合わせ、サービスの制限に関するオフラインのガイダンスを読み取ります
datamuse_get_word_info	指定された綴りの未加工メタデータを検索し、インデックス付きで部分的な結果を返します

機能リファレンス

datamuse_find_rhymes _ツール

• word は必須です。rhyme_type は exact（デフォルト）または near を指定し、両者を混在させることはできません。任意の means_like と spelled_like で同じ検索を絞り込めます。英語のみ
• 共通の検索設定：limit（デフォルト 20）、offset（デフォルト 0）、include_definitions、include_pronunciation、include_ipa（メタデータオプションのデフォルトは false）。各行には Datamuse が提供するメタデータが含まれます

---

datamuse_find_synonyms _ツール

• word は必須です。relation は synonyms（デフォルト）、antonyms、broader（直接の上位語）、narrower（直接の下位語）を指定します。英語のみ
• 韻の検索と同じ共通の検索設定を使用します。統計的な関連語は datamuse_find_words の associated 関係で検索できます

---

datamuse_find_words _ツール

• means_like、sounds_like、spelled_like（上流のスペルパターン）のいずれか、または最大14個のrelations: [{ relation, word }]が必須です。これらはすべてAND条件として扱われ、同じリレーションを繰り返し指定できます。left_context、right_context、およびそれぞれ単語1語からなる最大5個のtopicsは、並び順のみに影響します
• リレーション：exact_rhyme、near_rhyme、synonyms、antonyms、broader、narrower、parts、wholes、nouns_modified_by、adjectives_describing、followers、predecessors、associated、homophones、consonant_match。それぞれの方向についてはdatamuse_list_referenceで確認できます
• vocabularyはen（デフォルト）またはesです。スペイン語では意味、音、スペルの制約を利用できますが、リレーションは利用できません。拒否理由は型付きで、missing_constraint、unsupported_vocabulary_relation、invalid_context_hintがあります

スペルパターンは、DatamuseがサポートするOneLook構文に従って解釈されます。

パターン	意味
*, ?	任意の長さ、または1文字
//listen	アナグラム。lets inなどのフレーズも含みます
c@t, s#@p	@はyを含む英語の母音1文字、#は子音1文字に一致します
*+abc	使用する文字をa、b、cに限定します。文字の繰り返しや空白も使用できます
b????-e	eを含まない5文字のパターン
hipopatamus	ワイルドカード構文を使わない、類似したスペル

アナグラムを調べるには、{"spelled_like":"//listen"}を指定してdatamuse_find_wordsを呼び出します。+lettersは使用可能な文字を限定し、-lettersは使用不可の文字を指定します。どちらも、指定したすべての文字を必ず含める必要はありません。

---

datamuse_get_word_info _ツール

空白でないwordsを1～100個指定します。各語は200文字以内です。最初の10個は共有リクエスト予算内で順次処理され、それ以降の項目はprocessing_capを返します。20秒の期限には、すべてのリクエスト、再試行、待機時間が含まれます。項目の失敗後も完了済みの結果は保持され、処理待ちの項目にはdeadline_exceededが返されます。呼び出し元によるキャンセルで処理は停止します。

include_definitions、include_pronunciation、include_ipaの各オプションは共通して適用されます。インデックス付きの各結果には、前後の空白を除去した呼び出し元のinputと、完全な生のrow、復旧方法を含む失敗理由、または未処理の理由のいずれかが含まれます。指定されたスペルとUnicode小文字化後に一致する、queryタグ付きのエコーのみが受け入れられます。Ice Creamの場合、生のrow.word='ice cream'が返ることはありますが、訂正後の語に置き換えられることはありません。存在しないメタデータは欠落したままとなり、重複した語もそれぞれのインデックスを保持します。検索結果とは異なり、両方のMCPインターフェースで検索結果全体が返され、バイト数による分割はありません。

datamuse_list_reference _ツール

• topicはall（デフォルト）、relations、metadata、combinations、limitationsのいずれかです
• ネットワークリクエストを送信せず、静的なsections: [{ topic, text }]を返します

特長

@cyanheads/mcp-ts-core を基盤としており、stdio および Streamable HTTP トランスポート、差し替え可能な認証（none／jwt／oauth）、切り替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレーシングに対応した構造化ログを備えています。

Datamuse 固有の機能：

• Datamuse の固定 HTTPS /words エンドポイントへのライブクエリに対応します。ローカルミラーやクエリの保存はありません
• すべてのツールとテナントで共有するリクエスト予算：1 秒あたり 1 回の開始、同時進行リクエストは 1 件、上限付きキュー、1 回の再試行です。プロセス内でのみ適用されるため、ほかのプロセスや同じ送信元 IP アドレスを利用するほかのユーザーは考慮されません
• 結果はコーパスから得られた候補であり、語義に依存し、ときには推測されたメタデータ（品詞、音節数、100 万語あたりの f: 頻度）を含みます。辞書としての網羅性や詩作への適性を保証するものではありません

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

• 実際に適用されたクエリの表示と、誠実な上限通知：すべての検索で effectiveQuery、returnedCount、limitReached、truncated に加え、関連する通知と nextOffset を返します。1000 を超える正の安全な整数の上限は、requestedLimit と実際に適用された limit を表示したうえで 1000 に制限されます。無効な整数は I/O の前に拒否されます
• 行単位のナビゲーション：offset は 0〜999 を受け付けます。検索では max=min(1000, offset+limit) 件を取得し、エスケープ処理やエンリッチメントを含むシリアライズ済み MCP サーフェスあたり 64,000 バイト以内で、完全な行を選択します。ローカルでバイト数による切り詰めが発生すると truncated=true になり、nextOffset が示されている場合は、それを指定して再実行してください。1 行が上限を超える場合は、ソフト上限の通知とオフセットの進捗を伴って、その行全体を返します。API の上限に関する通知はバイト数による切り詰めとは別です。呼び出しの間に順位が変わる可能性があるため、オフセットはベストエフォートのナビゲーションであり、重複や欠落が発生する可能性があります。スナップショット、安定したページネーション、総件数、検索の完了を示すものではありません。インデックス 999 より先への継続には対応していません
• フレーズの関係性に関する補完：フレーズを対象とする入力は受け付けられ、そのまま保持されます。関係性クエリの結果が空の場合、フレーズの対応範囲が限られていることを説明し、means_like または sounds_like を提案します。韻に関する案内では、最後の単語を明示的に試すことも提案します
• 発音のオプション：include_pronunciation は md に r を追加し、include_ipa は発音を含めるとともに ipa=1 を追加します。pron: と ipa_pron: の生タグが両方現れることがあります。ARPAbet の強勢を示す数字は、0 が無強勢、1 が第一強勢、2 が第二強勢を意味します。発音は推測による場合や語義に依存する場合があり、存在しないこともあります
• 情報を損なわない行データ：word に加え、Datamuse が送信した score、numSyllables、tags、defs、defHeadword などのフィールドを、変更せず上流の順序のまま保持します。structuredContent とコードフェンス付きの JSON テキストでは同一の内容になります。score は 1 つのクエリ内でのみ結果の順位を示します
• 型付きエラー：アクセスエラー、レート制限（upstream_rate_limited と pacer_shed。retryAfter を含みます）、不正な上流データ、無効な入力について、宣言済みの理由とそれぞれの復旧方法を示します

アクセス、プライバシー、帰属表示

Datamuse は現在、キーなしで 1 日あたり最大 100,000 件のリクエストへのアクセスを案内しており、顧客向けアプリケーションから連絡するよう求めています。2027 年初頭に手動で発行する API キーを導入すると発表していますが、日付は一致していません。利用規約のセクションでは 1 月 1 日、バナーでは 2 月 1 日となっています。キーの形式はまだ公開されていないため、このサーバーではキーなしの API を使用しており、切り替え時にアクセスが中断される可能性があります。

クエリは Datamuse に送信され、翌日の終わりまで一時的なログとして保持されます。サーバーのペイロードログとテレメトリはオプションです。機密性の高いテキストを送信する前に、それらの設定を確認してください。

単語の結果と語彙メタデータは Datamuse から取得しています。データソースと帰属表示の要件については、同社のドキュメントを参照してください。Apache-2.0 ライセンスの対象はこのサーバーのコードであり、上流のデータではありません。

はじめに

以下を MCP クライアントの設定ファイルに追加してください。

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

または npx を使用する場合（Bun は不要です）：

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

または Docker を使用する場合：

{
  "mcpServers": {
    "datamuse-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/datamuse-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 以上。
• 現在、Datamuse の認証情報は不要です。告知済みのキー移行については、アクセス、プライバシー、帰属表示を参照してください。

インストール

1. リポジトリをクローンします：

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

2. ディレクトリに移動します：

cd datamuse-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env for transport, authentication, logging, or telemetry overrides

設定

変数	説明	デフォルト
MCP_TRANSPORT_TYPE	トランスポート：stdio または http。	stdio
MCP_HTTP_HOST	HTTP のバインドアドレス。	127.0.0.1
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	5 つのツール定義と共有の検索拡張処理。
src/services/datamuse	固定エンドポイントのクライアント、共有のペーシング、上流スキーマ、JSON レンダリング。
tests/	サービス、ツール、シリアライズのテスト。
docs/	サーフェス設計と生成されたディレクトリツリー。

開発ガイド

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

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません。
• ログには ctx.log、ストレージには ctx.state を使用します。
• 新しいツールとリソースは、src/index.ts の createApp() 配列に登録します。
• 外部 API 呼び出しはラップします。生データを検証し、ドメイン型に正規化してから、出力スキーマに準拠した値を返します。不足しているフィールドを捏造してはいけません。

貢献

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

bun run devcheck
bun run test

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。