ref-tools-ref-tools-mcp

Ref MCP

AI コーディングツールやエージェントが、API、サービス、ライブラリなどのドキュメントにアクセスできるようにする、ModelContextProtocol サーバーです。エージェントを最新のドキュメントにすばやく、トークン効率よく対応させるためのワンストップショップです。

詳しくは ref.tools をご覧ください。

必要なコンテキストを見つけるエージェント検索

Ref のツールは、モデルによる検索方法に合わせて設計されており、コンテキストの劣化を抑えるため、使用するコンテキストをできるだけ少なくします。目標は、コーディングエージェントが成功するために必要なコンテキストだけを、最小限のトークンで見つけることです。

プロンプトの複雑さに応じて、Claude Code のような LLM コーディングエージェントは通常、1 回以上検索してから、さらに詳しく読むリソースをいくつか選びます。

Figma の Comment REST API に関する簡単な質問では、必要な情報だけを取得するために、数回の呼び出しを行います。

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

より複雑な場合、LLM は検索結果を読みながらプロンプトを調整しようとします。たとえば、次のようになります。

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref は MCP セッションを活用して検索の軌跡を追跡し、コンテキストの使用量を最小限に抑えます。ほかにもさまざまなアイデアを開発中ですが、ここではこれまでに実装した内容をご紹介します。

1. 検索結果のフィルタリング

セッション中に同じような検索を繰り返しても、Ref は同じ結果を返しません。従来は、次の結果にページを進めて検索結果をさらに調べますが、この方法ではエージェントがページを進めながら、同時にプロンプトも調整できます。

2. ページの重要な部分を取得

ドキュメントのページを読む際、Ref はエージェントのセッション内の検索履歴を利用して、関連性の低いセクションを除外し、最も関連性の高い 5k トークンを返します。これにより、一般的な fetch() によるウェブスクレイピングで起こりがちな大きな問題を避けられます。大規模なドキュメントページを読み込むと、関連性の低い情報がほとんどであるにもかかわらず、20k を超えるトークンが簡単にコンテキストに取り込まれてしまう問題です。

ドキュメントのコンテキストから使用するトークンを最小限に抑えることが重要なのはなぜですか？

1. コンテキストが増えると、モデルの性能が落ちる

2025 年 7 月時点で、モデルはトークンを多く入力するほど性能が落ちることがよく知られています。モデルが長いコンテキストを扱えるようになったという話を聞いたことがあるかもしれません。ある程度は事実ですが、それだけでは全体像を捉えていません。研究の概要を知りたい方は、Chroma チームによるこの動画をご覧ください。

2. トークンには $$$ がかかる

Claude Opus をバックグラウンドエージェントとして使い、エージェントにドキュメントのコンテキストを取得させたとします。取得したコンテキストが 10000 トークンで、そのうち 4000 トークンが関連情報、6000 トークンが余分なノイズだったとします。API 料金では、この余分な 6k トークンに 1 ステップあたり約 $0.09 かかります。Opus で 1 つのプロンプトを処理するのに 11 ステップかかると、何のためにもならないのに $1 を費やすことになります。

セットアップ

Ref を MCP サーバーとしてセットアップする方法は 2 つあります。ストリーミング可能な HTTP サーバー（推奨）を使う方法と、ローカルの stdio サーバー（レガシー）を使う方法です。

このリポジトリには、レガシーの stdio サーバーが含まれています。

ストリーミング可能な HTTP（推奨）

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

ツール

Ref MCP サーバーは、エージェントのニーズに応えるドキュメント関連のツールをすべて提供します。

ref_search_documentation

技術ドキュメントを調べるための強力な検索ツールです。事実やコードスニペットを見つけるのに最適です。ウェブや GitHub 上の公開ドキュメントのほか、リポジトリや PDF などのプライベートなリソースも検索できます。

パラメーター：

• query（必須）：関連するドキュメントを検索するクエリです。完全な文または質問を指定してください。

ref_read_url

URL のコンテンツを取得し、Ref で読みやすい Markdown に変換するツールです。関連コンテンツの URL を返す ref_search_documentation ツールと組み合わせて使うと、効果を発揮します。

パラメーター：

• url（必須）：読み込むウェブページの URL です。

OpenAI のディープリサーチ対応

Ref はディープリサーチのソースとして使用できます。OpenAI では特定のツール定義が必要となるため、OpenAI クライアントで使用する場合、Ref は同じツールを少し異なる名前で提供します。

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

開発

npm install
npm run dev

Inspector を使って実行する

開発やデバッグには、MCP Inspector ツールを使用できます。Inspector は、MCP サーバーとのやり取りをテストおよび監視するためのビジュアルインターフェースを提供します。

詳しいセットアップ手順については、Inspector のドキュメントをご覧ください。

Inspector でローカルテストするには：

npm run inspect

または、ウォッチャーと Inspector の両方を実行します：

npm run dev

ローカル開発

1. リポジトリをクローンします
2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

npm run build

4. 自動再ビルドを有効にして開発するには：

npm run watch

ライセンス

MIT