Ref MCP Server

Ref MCP

Yapay zeka kodlama aracınıza veya aracınıza API'ler, servisler, kütüphaneler vb. için dokümantasyona erişim sağlayan bir ModelContextProtocol sunucusu. Aracınızı hızlı ve token açısından verimli bir şekilde dokümantasyon konusunda güncel tutmak için tek adresiniz.

Daha fazlası için bilgi: ref.tools

Tam doğru bağlam için aracısal arama

Ref'in araçları, bağlam çürümesini azaltmak için mümkün olduğunca az bağlam kullanırken modellerin arama yapma şekline uyacak şekilde tasarlanmıştır. Amaç, minimum token kullanarak kodlama aracınızın başarılı olması için tam olarak ihtiyaç duyduğu bağlamı bulmaktır.

İstemin karmaşıklığına bağlı olarak, Claude Code gibi LLM kodlama aracıları genellikle bir veya daha fazla arama yapacak ve ardından daha derinlemesine okumak için birkaç kaynak seçecektir.

Figma'nın Comment REST API'si hakkında basit bir sorgu için, tam olarak ihtiyacı olanı almak için birkaç çağrı yapacaktır:

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

Daha karmaşık durumlarda, LLM sonuçları okurken istemini iyileştirmeye çalışacaktır. Örneğin:

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, arama yörüngesini izlemek ve bağlam kullanımını en aza indirmek için MCP oturumlarından yararlanır. Üzerinde çalışılan çok daha fazla fikir var ancak şimdiye kadar uyguladıklarımız şunlardır.

1. Arama sonuçlarını filtreleme

Bir oturumda tekrarlanan benzer aramalar için Ref asla tekrarlanan sonuçlar döndürmez. Geleneksel olarak, bir sonraki sonuca sayfalayarak arama sonuçlarının derinliklerine inersiniz ancak bu yaklaşım, aracının aynı anda hem sayfalama yapmasına hem de istemi ayarlamasına olanak tanır.

2. Sayfanın önemli kısmını getirme

Bir dokümantasyon sayfasını okurken Ref, daha az alakalı bölümleri çıkarmak ve en alakalı 5k token'ı döndürmek için aracının oturum arama geçmişini kullanır. Bu, Ref'in standart fetch() web kazıma ile ilgili büyük bir sorundan kaçınmasına yardımcı olur; bu sorun, büyük bir dokümantasyon sayfasına ulaştığında kolayca bağlama 20k+ token çekebilmenizdir ve bunların çoğu alakasızdır.

Dokümantasyon bağlamından gelen token'ları en aza indirmek neden önemlidir?

1. Daha fazla bağlam modelleri aptallaştırır

Temmuz 2025 itibarıyla, daha fazla token koydukça modellerin aptallaştığı iyi belgelenmiştir. Modellerin artık uzun bağlamla ne kadar iyi olduğunu duymuş olabilirsiniz ve bu bir bakıma doğrudur ancak resmin tamamı bu değildir. Bazı araştırmalara hızlı bir giriş için, Chroma ekibinden bu videoya göz atın.

2. Token'lar paraya mal olur $$$

Claude Opus'u bir arka plan aracısı olarak kullandığınızı ve aracının dokümantasyon bağlamını çekmesiyle başladığınızı ve 4000'i alakalı, 6000'i ekstra gürültü olmak üzere 10000 token bağlam çektiğini varsayalım. API fiyatlandırmasında, bu 6k token ADIM BAŞINA yaklaşık 0,09$'a mal olur. Bir istem Opus ile 11 adım sürerse, sebepsiz yere 1$ harcamış olursunuz.

Kurulum

Ref'i bir MCP sunucusu olarak kurmak için iki seçenek vardır: streamable-http sunucusu (önerilir) veya yerel stdio sunucusu (eski).

Bu repo, eski stdio sunucusunu içerir.

Streamable HTTP (önerilir)

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

Araçlar

Ref MCP sunucusu, aracınızın ihtiyaçları için dokümantasyonla ilgili tüm araçları sağlar.

ref_search_documentation

Teknik dokümantasyonu kontrol etmek için güçlü bir arama aracı. Gerçekleri veya kod parçacıklarını bulmak için harikadır. Web'deki veya github'daki genel dokümantasyonun yanı sıra repo'lar ve pdf'ler gibi özel kaynaklarda arama yapmak için kullanılabilir.

Parametreler:

• query (gerekli): İlgili dokümantasyonu aramak için sorgu. Bu tam bir cümle veya soru olmalıdır.

ref_read_url

Bir URL'den içerik getiren ve Ref ile kolay okuma için markdown'a dönüştüren bir araç. Bu, ilgili içeriğin url'lerini döndüren ref_search_documentation aracıyla birlikte kullanıldığında güçlüdür.

Parametreler:

• url (gerekli): Okunacak web sayfasının URL'si.

OpenAI derin araştırma desteği

Ref, derin araştırma için bir kaynak olarak kullanılabilir. OpenAI belirli araç tanımları gerektirir, bu nedenle bir OpenAI istemcisiyle kullanıldığında Ref, biraz farklı adlandırmayla aynı araçları sağlayacaktır.

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

Geliştirme

npm install
npm run dev

Inspector ile Çalıştırma

Geliştirme ve hata ayıklama amacıyla MCP Inspector aracını kullanabilirsiniz. Inspector, MCP sunucu etkileşimlerini test etmek ve izlemek için görsel bir arayüz sağlar.

Ayrıntılı kurulum talimatları için Inspector dokümantasyonunu ziyaret edin.

Inspector ile yerel olarak test etmek için:

npm run inspect

Veya hem watcher'ı hem de inspector'ı çalıştırın:

npm run dev

Yerel Geliştirme

1. Depoyu klonlayın
2. Bağımlılıkları yükleyin:

npm install

3. Projeyi derleyin:

npm run build

4. Otomatik yeniden derleme ile geliştirme için:

npm run watch

Lisans

MIT