MCP Research Friend Server

resmi

Araştırma araçları, Sqlite destekli bir belge deposu dahil

GitHub

Dokümantasyon

Research Friend

Yapay zeka asistanlarının web'de arama yapması ve yerel bir araştırma arşivini yönetmesi için dost bir yardımcı.

Research Friend, yapay zeka araçlarınıza web sayfalarını getirme ve internette arama yapma yeteneği kazandıran bir MCP sunucusudur. Arka planda gerçek bir web tarayıcısı kullanır, bu nedenle yoğun olarak JavaScript kullanan modern web sitelerinde bile çalışır. Ayrıca belgeleri depolamak, metin çıkarmak ve kütüphanenizde arama yapmak için yerel bir "arşiv" içerir.

Tüm özelliklerinden yararlanmak için, istemleri (yaygın) ve örneklemeyi (daha az yaygın) destekleyen bir MCP istemcisine ihtiyacınız olacak. Research Friend'i, her ikisini de destekleyen Chabeau ile birlikte geliştiriyoruz.

Neler yapabilir?

  • Web sayfalarını getirir (JS ağırlıklı siteler dahil) gerçek bir tarayıcı ile
  • PDF'leri getirir ve metin içeriklerini çıkarır
  • Web'de arama yapar DuckDuckGo veya Google aracılığıyla
  • Yerel bir arşiv tutar; arama, listeleme ve çıkarma için belgeleri saklar

Başlarken

Bilgisayarınızda Node.js sürüm 20 veya daha yenisinin yüklü olması gerekir.

1. Bağımlılıkları yükleyin

Bu klasörde bir terminal açın ve şunu çalıştırın:

npm install

2. Tarayıcı desteğini yükleyin

Research Friend, bir web tarayıcısını kontrol etmek için Playwright kullanır. Bağımlılıkları yükledikten sonra tarayıcıyı yüklemeniz gerekir:

npx playwright install chromium

Bu, Playwright'ın kullanacağı bir Chromium kopyasını indirir. Halihazırda yüklü olan tarayıcılarınızdan ayrıdır.

3. Sunucuyu başlatın

node src/index.js

Sunucu, MCP istemcilerinin bağlandığı stdio (standart giriş/çıkış) üzerinden iletişim kurar.

MCP istemcinize ekleme

Research Friend'i nasıl ekleyeceğiniz, hangi MCP istemcisini kullandığınıza bağlıdır. İşte yapılandırmanın nasıl görünebileceğine dair genel bir örnek:

[[mcp_servers]]
id = "research-friend"
command = "node"
args = ["/path/to/mcp-research-friend/src"]
transport = "stdio"

/path/to/mcp-research-friend kısmını, bilgisayarınızdaki bu klasörün gerçek yolu ile değiştirin.

Araçlar

Web araçları

friendly_web_fetch

Bir web sayfasını getirir ve içeriğini döndürür. Varsayılan olarak, bağlantılar korunmuş şekilde markdown döndürür — LLM'ler için idealdir. Ana içeriği (gezinme, reklamlar vb. çıkarılarak) ayıklamak için Readability kullanır. PDF'ler, sayfalandırma veya içerik içinde arama için bunun yerine friendly_web_extract kullanın.

Parametreler:

  • url (gerekli) - Getirilecek web adresi
  • outputFormat - Çıktı formatı: markdown (varsayılan), text veya html
  • waitMs - İçerik yavaş görünüyorsa, sayfa yüklendikten sonra beklenecek ek süre
  • timeoutMs - Vazgeçmeden önce ne kadar bekleneceği (varsayılan: 15 saniye)
  • maxChars - Döndürülecek maksimum içerik miktarı (varsayılan: 40.000 karakter)
  • includeHtml - İçerikle birlikte ham HTML'i de döndürmek için true olarak ayarlayın
  • headless - Tarayıcı penceresini görmek için false olarak ayarlayın (hata ayıklama için kullanışlıdır)

Döndürülenler:

  • url - İstenen URL
  • finalUrl - Yönlendirmelerden sonraki URL
  • title - Sayfa başlığı
  • content - Ayıklanan içerik (istenen formatta)
  • html - Ham HTML (yalnızca includeHtml true ise)
  • meta - Sayfa meta verileri (açıklama, yazar, yayınlanma zamanı vb.)
  • fetchedAt - Sayfanın getirildiği zamana ait ISO zaman damgası
  • truncated - İçeriğin maxChars sığacak şekilde kesilip kesilmediği

friendly_search

Web'de arama yapar ve sonuç listesini döndürür.

Parametreler:

  • query (gerekli) - Aranacak şey
  • engine - Hangi arama motorunun kullanılacağı (duckduckgo veya google)
  • maxResults - Kaç sonuç döndürüleceği (varsayılan: 10, maksimum: 50)
  • timeoutMs - Vazgeçmeden önce ne kadar bekleneceği (varsayılan: 15 saniye)
  • headless - Tarayıcı penceresini görmek için false olarak ayarlayın

Döndürülenler:

  • query - Kullanılan arama sorgusu
  • engine - Hangi arama motorunun kullanıldığı
  • results - Her biri title, url ve snippet içeren sonuç dizisi
  • searchedAt - Aramanın yapıldığı zamana ait ISO zaman damgası
  • fallback_result_html - Sayfanın ham HTML'i (yalnızca hiç sonuç bulunamazsa dahil edilir)
  • debug_info - Arama girişimi hakkında tanısal bilgiler

CAPTCHA işleme: Başsız modda çalışırken bir CAPTCHA algılanırsa, araç otomatik olarak görünür bir tarayıcı penceresiyle yeniden dener. Bu, CAPTCHA'yı manuel olarak çözme şansı verir. debug_info.retried alanı, bu yedeğin kullanılıp kullanılmadığını gösterir.

friendly_web_extract

Bir URL'den içerik çıkarır. URL'nin bir PDF'ye mi yoksa bir web sayfasına mı işaret ettiğini otomatik olarak algılar ve her birini uygun şekilde işler.

Parametreler:

  • url (gerekli) - Getirilecek URL (PDF veya web sayfası)
  • maxChars - Döndürülecek maksimum metin miktarı (varsayılan: 40.000 karakter)
  • offset - Başlanacak karakter konumu (varsayılan: 0). Büyük içeriklerde sayfalandırma yapmak için bunu kullanın.
  • search - Tam içerik yerine bir ifade arayın ve eşleşmeleri çevreleyen bağlamla birlikte döndürün
  • contextChars - Her arama eşleşmesi etrafındaki bağlam karakterleri (varsayılan: 200)
  • waitMs - Dinamik içerik için sayfa yüklendikten sonra beklenecek ek süre (yalnızca web sayfaları)
  • timeoutMs - Vazgeçmeden önce ne kadar bekleneceği (varsayılan: 15 saniye, yalnızca web sayfaları)
  • headless - Tarayıcı penceresini görmek için false olarak ayarlayın (yalnızca web sayfaları)

Döndürülenler (normal mod):

  • url - İstenen URL
  • contentType - pdf veya html
  • title - Sayfa/belge başlığı
  • author - PDF yazarı (varsa, yalnızca PDF'ler)
  • creationDate - PDF'in oluşturulma zamanı (varsa, yalnızca PDF'ler)
  • pageCount - Sayfa sayısı (yalnızca PDF'ler)
  • totalChars - Toplam karakter (sayfalandırma için offset ile kullanın)
  • offset - Kullanılan ofset
  • content - Ayıklanan metin içeriği
  • fetchedAt - ISO zaman damgası
  • truncated - Bu parçadan sonra daha fazla içerik kalıp kalmadığı

Döndürülenler (arama modu):

  • url, contentType, title, totalChars, fetchedAt - Yukarıdakiyle aynı
  • search - Kullanılan arama ifadesi
  • matchCount - Bulunan eşleşme sayısı
  • matches - Her biri position, context, prefix ve suffix içeren eşleşme dizisi

friendly_web_ask

Bir URL'yi (PDF veya web sayfası) getirir ve bir LLM'nin bu konuda soruları yanıtlamasını sağlar. İçerik türünü otomatik olarak algılar. Belge ayrı bir bağlamda işlenir, böylece ana konuşmanız kompakt kalır.

Parametreler:

  • url (gerekli) - Getirilecek URL (PDF veya web sayfası)
  • ask (gerekli) - LLM için soru veya talimat (özetle, bilgi çıkar, soruları yanıtla vb.)
  • askMaxInputTokens - LLM çağrısı başına maksimum girdi token'ı (varsayılan: 150.000)
  • askMaxOutputTokens - LLM çağrısı başına maksimum çıktı token'ı (varsayılan: 4.096)
  • askTimeout - Milisaniye cinsinden zaman aşımı (varsayılan: 300.000 = 5 dakika)
  • askSplitAndSynthesize - Büyük belgeler için: parçalara böl, her birini işle, sonra sonuçları sentezle (varsayılan: false). Uyarı: çok fazla token tüketir.
  • waitMs - Dinamik içerik için sayfa yüklendikten sonra beklenecek ek süre (yalnızca web sayfaları)
  • timeoutMs - Vazgeçmeden önce ne kadar bekleneceği (varsayılan: 15 saniye, yalnızca web sayfaları)
  • headless - Tarayıcı penceresini görmek için false olarak ayarlayın (yalnızca web sayfaları)

Döndürülenler:

  • url - İstenen URL
  • contentType - pdf veya html
  • title - Sayfa/belge başlığı
  • totalChars - Belgedeki toplam karakter
  • ask - Verilen talimat
  • answer - LLM'nin yanıtı
  • model - Yanıtı oluşturan model
  • chunksProcessed - İşlenen parça sayısı (küçük belgeler için 1, askSplitAndSynthesize kullanırken daha fazla)
  • fetchedAt - ISO zaman damgası

Soru modu, bir LLM'nin belgeyi herhangi bir talimatla işlemesini sağlamak için MCP örneklemesini kullanır. Bu şunlar için kullanışlıdır:

  • Bağlamı aşırı yükleyebilecek büyük belgeler
  • Ana konuşmadaki token maliyetlerini düşük tutmak

askSplitAndSynthesize etkinleştirildiğinde, askMaxInputTokens aşan belgeler otomatik olarak örtüşen parçalara bölünür. Her parça ayrı ayrı işlenir ve sonuçlar tek bir tutarlı yanıt halinde sentezlenir. Nihai yanıt, belgenin dilinden bağımsız olarak, isteğinizle aynı dilde sağlanır.

Belge arşivi

Arşiv, yerel, aranabilir bir belge kütüphanesidir. PDF'leri, HTML dosyalarını ve düz metni (Markdown/TXT) destekler. Bir belge eklediğinizde, Research Friend orijinal dosyayı saklar, metni çıkarır (PDF'ler/HTML için) ve meta verileri yerel bir veritabanına kaydeder. Aramalar, hızlı, ifadeye duyarlı eşleştirme için arka planda ripgrep kullanır.

Arşiv konumu

Arşiv ~/.research-friend/ altında bulunur:

  • inbox/ - İşlenmek üzere dosyaları buraya bırakın
  • store/ - Düzenlenmiş belge depolama ve ayıklanmış metin
  • stash.db - Meta veri veritabanı

Desteklenen dosya türleri

  • PDF: .pdf (metin ayıklanır)
  • HTML: .html, .htm (metin ayıklanır)
  • Markdown: .md, .markdown (düz metin olarak saklanır)
  • Metin: .txt (düz metin olarak saklanır)

Arşiv araçları

stash_open_inbox

Daha kolay sürükle-bırak için arşiv gelen kutusu klasörünü dosya yöneticinizde açın.

Döndürülenler:

  • opened - Klasör açma isteğinin gönderilip gönderilmediği
  • inboxPath - Gelen kutusunun mutlak yolu
  • command - Kullanılan işletim sistemi komutu
  • args - Kullanılan komut argümanları

stash_process_inbox

inbox/ içindeki dosyaları işleyin, konulara göre sınıflandırın, metni çıkarın ve sonuçları saklayın. Uzun belgeler için sınıflandırma, konu doğruluğunu artırmak amacıyla örneklenmiş bölümleri (başlangıç/orta/son artı birkaç rastgele parça) kullanır.

Döndürülenler:

  • processed - Başarıyla işlenen dosya adları dizisi
  • errors - Karşılaşılan hatalar
  • documents - Oluşturulan belge kayıtları dizisi

reindex_stash

Arşivlenmiş belgeler için özetleri yeniden oluşturun, konuları yeniden tahsis edin ve mağaza meta verilerini güncelleyin. ids atlanır veya boş bırakılırsa, tüm belgeler yeniden indekslenir.

Parametreler:

  • ids - Yeniden indekslenecek belge kimlikleri (isteğe bağlı)

Döndürülenler:

  • reindexed - Yeniden indekslenen belge kimlikleri
  • errors - Karşılaşılan hatalar
  • documents - Güncellenen belge kayıtları dizisi

stash_list

Arşivdeki belgeleri listeler.

Parametreler:

  • topic - Bir konuya filtrele (isteğe bağlı)
  • limit - Maksimum sonuç (varsayılan: 50)
  • offset - Sayfalandırma ofseti (varsayılan: 0)

Döndürülenler:

  • type - all veya topic
  • totalDocuments - Toplam belge (yalnızca type, all olduğunda)
  • count - Sayfalandırmadan sonra döndürülen sonuçlar
  • offset - Kullanılan sayfalandırma ofseti
  • limit - Kullanılan sayfalandırma limiti
  • topics - Bilinen konuların ve belge sayılarının özeti
  • documents - Meta verilerle birlikte belge listesi (bir konu listelenirken isPrimary içerir)

stash_search

Arşiv genelinde dosya adlarını ve içeriği arayın. Tüm arama terimleri mevcut olmalıdır (VE mantığı). Dosya adı eşleşmeleri önce listelenir. Tam ifadeler için tırnak işareti kullanın.

Parametreler:

  • query (gerekli) - Arama terimleri. İfadeler için tırnak işareti kullanın: "sparkling wine"
  • topic - Bir konuya filtrele (isteğe bağlı)
  • ids - Belirli belge kimliklerine filtrele (isteğe bağlı)
  • limit - Döndürülecek maksimum belge (varsayılan: 20)
  • offset - Sayfalandırma ofseti (varsayılan: 0)
  • maxMatchesPerDoc - Belge başına maksimum eşleşme (varsayılan: 50)
  • context - Her eşleşme etrafındaki bağlam satırları (varsayılan: 1, maks: 5). Hem terimlerin eşleşmesi için ne kadar yakın görünmesi gerektiğini hem de ne kadar çevreleyen metnin döndürüleceğini kontrol eder. Döndürülenler:
  • totalMatches - Sayfalandırmadan önce eşleşen toplam belge sayısı
  • count - Sayfalandırmadan sonra döndürülen sonuçlar
  • results - Her biri şunları içeren belge dizisi:
    • id, filename, fileType, summary, charCount, createdAt
    • matchType - filename, content veya filename+content
    • matches - Her eşleşme konumu için { line, context } dizisi

Doğrudan eşleşme konumlarına atlamak için stash_extract ile line değerlerini kullanın.

stash_extract

Okumak üzere saklanmış bir belgeden içerik çıkarır. Doğrudan eşleşmelere atlamak için stash_search sonuçlarındaki satır numaralarını kullanın.

Parametreler:

  • id (gerekli) - stash_list/stash_search kaynağından belge kimliği
  • maxChars - Döndürülecek maksimum metin miktarı (varsayılan: 40.000 karakter)
  • offset - Başlangıç karakter konumu (line ile karşılıklı olarak birbirini dışlar)
  • line - Başlangıç satır numarası (offset ile karşılıklı olarak birbirini dışlar)

Döndürülenler:

  • id, filename, fileType, summary - Belge üst verisi
  • totalChars - Belgedeki toplam karakter sayısı
  • offset - Karakter ofseti (referans için line kullanıldığında dahil edilir)
  • line - Satır numarası (yalnızca line parametresi kullanıldığında)
  • content - Çıkarılan metin içeriği
  • truncated - Bu parçadan sonra daha fazla içerik kalıp kalmadığı

stash_ask

Saklanmış bir belge hakkında soruları bir LLM'ye yanıtlatır. Belge ayrı bir bağlamda işlenir, böylece ana konuşmanız derli toplu kalır.

Parametreler:

  • id (gerekli) - stash_list/stash_search kaynağından belge kimliği
  • ask (gerekli) - LLM için soru veya talimat
  • askMaxInputTokens - LLM çağrısı başına maksimum girdi token'ı (varsayılan: 150.000)
  • askMaxOutputTokens - LLM çağrısı başına maksimum çıktı token'ı (varsayılan: 4.096)
  • askTimeout - Milisaniye cinsinden zaman aşımı (varsayılan: 300.000 = 5 dakika)
  • askSplitAndSynthesize - Büyük belgeler için: parçalara böl, her birini işle, sonra sonuçları sentezle (varsayılan: false)

Döndürülenler:

  • id, filename, fileType, summary - Belge üst verisi
  • totalChars - Belgedeki toplam karakter sayısı
  • ask - Verilen talimat
  • answer - LLM'nin yanıtı
  • model - Yanıtı oluşturan model
  • chunksProcessed - İşlenen parça sayısı

Tipik akış

  1. Dosyaları ~/.research-friend/inbox/ içine bırakın
  2. stash_process_inbox çalıştırın
  3. Konulara göz atmak için stash_list kullanın
  4. İlgili belgeleri bulmak için stash_search kullanın
  5. Belirli bir belgeyi okumak için stash_extract veya hakkında soru sormak için stash_ask kullanın

Sorun Giderme

"Tarayıcı beklenmedik şekilde kapandı" veya benzer hatalar

Tarayıcıyı yeniden yüklemeyi deneyin:

npx playwright install chromium --force

Linux'ta ayrıca sistem bağımlılıklarına ihtiyacınız olabilir:

npx playwright install-deps chromium

Sunucu başlamıyor

Node.js 20 veya daha yenisini kullandığınızdan emin olun:

node --version

Sürümünüz daha eskiyse, daha yenisini indirmek için nodejs.org adresini ziyaret edin.

Lisans

MIT