Ref MCP Server

官方

為你的程式碼代理提供最新的文件。涵蓋數千個公開儲存庫與網站。由 ref.tools 建置。

GitHub
1.1k

文件

Documentation for your agent smithery badge Website License npm version

Ref MCP

一個 ModelContextProtocol 伺服器，讓您的 AI 編碼工具或代理能夠存取 API、服務、程式庫等文件。這是讓您的代理以快速且節省 token 的方式保持文件最新的全方位解決方案。

更多資訊請參閱 ref.tools

針對性搜尋，精準找到正確的上下文

Ref 的工具旨在配合模型搜尋的方式，同時使用盡可能少的上下文來減少 上下文腐化。目標是找到您的編碼代理成功所需的確切上下文，同時使用最少的 token。

根據提示的複雜度，像 Claude Code 這類 LLM 編碼代理通常會進行一次或多次搜尋，然後選擇幾個資源進行更深入的閱讀。

對於一個關於 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 個 token。這有助於 Ref 避免標準 fetch() 網頁爬取的一個重大問題，也就是當它遇到大型文件頁面時，您很容易最終將 20k 以上的 token 拉入上下文，其中大部分都是不相關的。

為什麼最小化文件上下文中的 token 很重要？

1. 更多上下文會讓模型變笨

截至 2025 年 7 月，有充分記錄顯示，當您輸入更多 token 時，模型會變得更笨。您可能聽說過模型現在非常擅長處理長上下文，這某種程度上是對的，但並非全貌。如需一些研究的快速入門，請觀看 Chroma 團隊的這段影片。

2. Token 花費 $$$

想像一下，您正在使用 Claude Opus 作為背景代理，您一開始讓代理拉取文件上下文，假設它拉取了 10000 個 token 的上下文，其中 4000 個是相關的，6000 個是額外的雜訊。以 API 定價計算，那 6k 個 token 每個步驟大約花費 $0.09 美元。如果一個提示最終使用 Opus 執行了 11 個步驟，您就毫無理由地花費了 $1 美元。

設定

將 Ref 設定為 MCP 伺服器有兩種選項，可透過 streamable-http 伺服器（建議）或本機 stdio 伺服器（舊版）。

此儲存庫包含舊版的 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

一個強大的搜尋工具，用於查閱技術文件。非常適合尋找事實或程式碼片段。可用於搜尋網路或 GitHub 上的公開文件，以及來自私人資源（如儲存庫和 PDF）的文件。

參數：

  • query（必要）：用於搜尋相關文件的查詢。這應該是一個完整的句子或問題。

ref_read_url

一個從 URL 擷取內容並將其轉換為 Markdown 以便於使用 Ref 閱讀的工具。當與傳回相關內容 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
  1. 建置專案：
npm run build
  1. 用於自動重新建置的開發：
npm run watch

授權

MIT