ref-tools/ref-tools-mcp
Helping coding agents never make mistakes working with public or private libraries without wasting the context window.
Ref MCP – 用於文件查詢的 Model-Context-Protocol 伺服器
它是什麼 – Ref MCP 是一個實作了 Model Context Protocol (MCP) 的小型 Node-JS 服務。它讓基於 LLM 的編碼助理（例如 Claude Code、Cursor）僅能擷取 API 或函式庫文件中真正需要的部分，從而保持較低的 Token 數量並降低成本。
為什麼重要 – 當代理程式在網路上搜尋函式簽章或使用範例時，原始 HTML 可能會達到數萬個 Token。將所有內容餵給模型會浪費上下文、增加模型推理的雜訊，並提高 API 成本。Ref MCP 透過以下方式解決此問題：
- 搜尋優先 – 代理程式使用自然語言查詢呼叫
ref_search_documentation。Ref 會回傳一個相符的簡短 URL 清單。 - 選擇性讀取 – 代理程式隨後呼叫
ref_read_url。Ref 會利用工作階段的搜尋記錄將頁面修剪為最相關的約 5k 個 Token，並捨棄不相關的部分。 - 工作階段感知 – 同一個 MCP 工作階段中的重複搜尋會被去重，且伺服器會記住頁面中哪些部分已經被讀取，進一步減少 Token 浪費。
透過 MCP 公開的核心工具
| 工具 | 用途 | 參數 |
|---|---|---|
ref_search_documentation (別名 search) |
對公開文件、GitHub repos、PDF 等進行全文搜尋 | query – 描述代理程式需求的句子或問題 |
ref_read_url (別名 fetch) |
擷取 URL 並回傳經過 Markdown 處理且篩選過相關性的片段 | url – 要讀取的頁面 |
如何執行
- Streamable-HTTP 伺服器 (推薦) – 將伺服器部署於
https://api.ref.tools/mcp，並透過簡單的 JSON 設定將您的代理程式指向它。 - 傳統 stdio 伺服器 – 使用
npx ref-tools-mcp@latest在本地執行。儲存庫中包含此模式的程式碼。
兩種模式都需要從 ref.tools 取得的 API 金鑰 (REF_API_KEY)。
典型工作流程範例
Agent: SEARCH "Figma API post comment endpoint documentation"
Ref MCP → 回傳 Figma 文件 URL (≈54 tokens)
Agent: READ https://www.figma.com/developers/api#post-comments-endpoint
Ref MCP → 僅回傳描述該端點的 385-token 片段
對於更複雜的查詢，代理程式可以交替進行額外的搜尋與讀取，Ref 會記住工作階段狀態以避免重複結果。
開發與除錯
npm run dev– 啟動具備熱重載功能的伺服器。npm run inspect– 啟動 MCP Inspector UI 進行工具呼叫的視覺化測試。- 提供標準 Node 指令碼 (
build,watch等)。
授權 – MIT，因此您可以自由地將此伺服器嵌入或修改到您自己的 AI 工具堆疊中。
總結 – Ref MCP 是 LLM 代理程式與不斷增長的技術文件海洋之間實用且具備 Token 效率的橋樑，讓代理程式在不被無關文字淹沒的情況下保持最新狀態。
相關
- 專案
- 專案
- 專案
- 專案