Ref MCP Server

Ref MCP

Server ModelContextProtocol yang memberikan akses ke dokumentasi API, layanan, pustaka, dll. kepada alat atau agen coding AI Anda. Ini adalah toko serba ada untuk menjaga agen Anda tetap terkini tentang dokumentasi dengan cara yang cepat dan hemat token.

Untuk info lebih lanjut, lihat ref.tools

Pencarian agentik untuk konteks yang tepat

Alat-alat Ref dirancang untuk mencocokkan cara model mencari sambil menggunakan konteks sesedikit mungkin untuk mengurangi context rot. Tujuannya adalah menemukan konteks yang tepat yang dibutuhkan agen coding Anda agar berhasil sambil menggunakan token minimum.

Tergantung pada kompleksitas prompt, agen coding LLM seperti Claude Code biasanya akan melakukan satu atau lebih pencarian dan kemudian memilih beberapa sumber daya untuk dibaca lebih mendalam.

Untuk kueri sederhana tentang Figma Comment REST API, ia akan melakukan beberapa panggilan untuk mendapatkan apa yang dibutuhkannya:

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

Untuk situasi yang lebih kompleks, LLM akan mencoba menyempurnakan prompt-nya saat membaca hasil. Contohnya:

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 memanfaatkan sesi MCP untuk melacak lintasan pencarian dan meminimalkan penggunaan konteks. Ada lebih banyak ide yang sedang dikembangkan, tetapi inilah yang telah kami implementasikan sejauh ini.

1. Memfilter hasil pencarian

Untuk pencarian serupa yang berulang dalam satu sesi, Ref tidak akan pernah mengembalikan hasil yang berulang. Secara tradisional, Anda menggali lebih dalam hasil pencarian dengan berpindah ke halaman berikutnya, tetapi pendekatan ini memungkinkan agen untuk berpindah halaman DAN menyesuaikan prompt secara bersamaan.

2. Mengambil bagian halaman yang penting

Saat membaca halaman dokumentasi, Ref akan menggunakan riwayat pencarian sesi agen untuk menghilangkan bagian yang kurang relevan dan mengembalikan 5k token yang paling relevan. Ini membantu Ref menghindari masalah besar dengan web scraping fetch() standar, yaitu ketika mengenai halaman dokumentasi besar, Anda dapat dengan mudah menarik 20k+ token ke dalam konteks, yang sebagian besar tidak relevan.

Mengapa meminimalkan token dari konteks dokumentasi itu penting?

1. Lebih banyak konteks membuat model lebih bodoh

Telah terdokumentasi dengan baik bahwa per Juli 2025, model menjadi lebih bodoh saat Anda memasukkan lebih banyak token. Anda mungkin pernah mendengar bahwa model sekarang hebat dengan konteks panjang dan itu agak benar, tetapi bukan gambaran keseluruhannya. Untuk pengantar singkat tentang beberapa penelitian, lihat video ini dari tim di Chroma.

2. Token memerlukan biaya $$$

Bayangkan Anda menggunakan Claude Opus sebagai agen latar belakang dan Anda memulai dengan meminta agen menarik konteks dokumentasi, dan anggaplah ia menarik 10000 token konteks dengan 4000 relevan dan 6000 noise tambahan. Dengan harga API, 6k token itu berharga sekitar $0,09 PER LANGKAH. Jika satu prompt akhirnya memakan 11 langkah dengan Opus, Anda telah menghabiskan $1 tanpa alasan.

Pengaturan

Ada dua opsi untuk mengatur Ref sebagai server MCP, baik melalui server streamable-http (disarankan) atau server stdio lokal (lawas).

Repositori ini berisi server stdio lawas.

Streamable HTTP (disarankan)

"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>
  }
}

Alat

Server Ref MCP menyediakan semua alat terkait dokumentasi untuk kebutuhan agen Anda.

ref_search_documentation

Alat pencarian yang kuat untuk memeriksa dokumentasi teknis. Bagus untuk menemukan fakta atau potongan kode. Dapat digunakan untuk mencari dokumentasi publik di web atau github, serta dari sumber daya pribadi seperti repositori dan pdf.

Parameter:

• query (wajib): Kueri untuk mencari dokumentasi yang relevan. Ini harus berupa kalimat lengkap atau pertanyaan.

ref_read_url

Alat yang mengambil konten dari URL dan mengonversinya menjadi markdown agar mudah dibaca dengan Ref. Ini sangat berguna saat digunakan bersama dengan alat ref_search_documentation yang mengembalikan URL konten yang relevan.

Parameter:

• url (wajib): URL halaman web yang akan dibaca.

Dukungan deep research OpenAI

Ref dapat digunakan sebagai sumber untuk deep research. OpenAI memerlukan definisi alat tertentu, jadi saat digunakan dengan klien OpenAI, Ref akan menyediakan alat yang sama dengan penamaan yang sedikit berbeda.

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

Pengembangan

npm install
npm run dev

Menjalankan dengan Inspector

Untuk tujuan pengembangan dan debugging, Anda dapat menggunakan alat MCP Inspector. Inspector menyediakan antarmuka visual untuk menguji dan memantau interaksi server MCP.

Kunjungi dokumentasi Inspector untuk petunjuk pengaturan terperinci.

Untuk menguji secara lokal dengan Inspector:

npm run inspect

Atau jalankan watcher dan inspector sekaligus:

npm run dev

Pengembangan Lokal

1. Kloning repositori
2. Instal dependensi:

npm install

3. Bangun proyek:

npm run build

4. Untuk pengembangan dengan pembangunan ulang otomatis:

npm run watch

Lisensi

MIT