Documentation for your agent Website License npm version

Ref MCP

ModelContextProtocolサーバーであり、AIコーディングツールやエージェントがAPI、サービス、ライブラリなどのドキュメントにアクセスできるようにします。エージェントがドキュメントを高速かつトークン効率よく最新の状態に保つためのワンストップショップです。

詳細については 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トークンを返します。これにより、Refは標準的な fetch() Webスクレイピングの大きな問題、つまり大きなドキュメントページにヒットした際に20kトークン以上をコンテキストに取り込んでしまい、そのほとんどが無関係であるという問題を回避できます。

Related MCP server: Firebase Realtime Database

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

1. コンテキストが多いとモデルの性能が低下する

2025年7月現在、トークンを多く入力するほどモデルの性能が低下することは十分に文書化されています。モデルが長いコンテキストを扱えるようになったという話を聞いたことがあるかもしれませんが、それはある程度真実ですが、全体像ではありません。研究に関する簡単な入門として、Chromaチームによるこのビデオをご覧ください。

2. トークンにはコストがかかる

Claude Opusをバックグラウンドエージェントとして使用しており、エージェントがドキュメントのコンテキストを取り込むことから始めるとします。10,000トークンのコンテキストを取り込み、そのうち4,000が関連しており、6,000が余分なノイズだったと仮定します。API価格では、その6kトークンは1ステップあたり約$0.09かかります。もし1つのプロンプトでOpusを11ステップ使用した場合、理由もなく$1を費やしたことになります。

セットアップ

RefをMCPサーバーとしてセットアップするには、streamable-httpサーバー（推奨）またはローカルstdioサーバー（レガシー）の2つのオプションがあります。

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

Streamable HTTP (推奨)

Install Ref MCP in Cursor

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

stdio

Install Ref MCP in Cursor (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

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

パラメータ:

query (必須): 関連するドキュメントを検索するためのクエリ。完全な文章または質問である必要があります。

ref_read_url

URLからコンテンツを取得し、Refで読みやすいようにMarkdownに変換するツールです。関連コンテンツのURLを返す ref_search_documentation ツールと組み合わせて使用すると強力です。

パラメータ:

url (必須): 読み込むWebページの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

または、ウォッチャーとインスペクターの両方を実行します:

npm run dev

ローカル開発

リポジトリをクローンします
依存関係をインストールします:

npm install

プロジェクトをビルドします:

npm run build

自動リビルドを行う開発用:

npm run watch

ライセンス

MIT

Ref