MCP Research Friend Server

resmi

Alat riset, termasuk penyimpanan dokumen berbasis Sqlite

GitHub

Dokumentasi

Research Friend

Pembantu yang ramah untuk asisten AI yang perlu mencari sesuatu di web dan mengelola simpanan riset lokal.

Research Friend adalah server MCP yang memberikan kemampuan kepada perangkat AI Anda untuk mengambil halaman web dan mencari di internet. Ia menggunakan peramban web sungguhan di balik layar, sehingga tetap berfungsi bahkan dengan situs web modern yang sangat bergantung pada JavaScript. Ia juga menyertakan "simpanan" lokal untuk menyimpan dokumen, mengekstrak teks, dan mencari di seluruh pustaka Anda.

Untuk memanfaatkan semua fiturnya, Anda memerlukan klien MCP yang mendukung prompt (umum) dan sampling (kurang umum). Kami membangun Research Friend bersama Chabeau, yang mendukung keduanya.

Apa yang bisa dilakukannya?

  • Mengambil halaman web dengan peramban sungguhan (termasuk situs yang sarat JS)
  • Mengambil PDF dan mengekstrak konten teksnya
  • Mencari di web melalui DuckDuckGo atau Google
  • Memelihara simpanan lokal dokumen untuk pencarian, daftar, dan ekstraksi

Memulai

Anda memerlukan Node.js versi 20 atau lebih baru yang terinstal di komputer Anda.

1. Instal dependensi

Buka terminal di folder ini dan jalankan:

npm install

2. Instal dukungan peramban

Research Friend menggunakan Playwright untuk mengendalikan peramban web. Setelah menginstal dependensi, Anda perlu menginstal peramban:

npx playwright install chromium

Ini mengunduh salinan Chromium yang akan digunakan Playwright. Ini terpisah dari peramban apa pun yang sudah Anda instal.

3. Mulai server

node src/index.js

Server berkomunikasi melalui stdio (input/output standar), yang merupakan cara klien MCP terhubung dengannya.

Menambahkan ke klien MCP Anda

Cara Anda menambahkan Research Friend bergantung pada klien MCP yang Anda gunakan. Berikut adalah contoh umum seperti apa konfigurasinya:

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

Ganti /path/to/mcp-research-friend dengan jalur sebenarnya ke folder ini di komputer Anda.

Alat

Alat web

friendly_web_fetch

Mengambil halaman web dan mengembalikan kontennya. Secara default, mengembalikan markdown dengan tautan yang dipertahankan — ideal untuk LLM. Menggunakan Readability untuk mengekstrak konten utama (menghilangkan navigasi, iklan, dll.). Untuk PDF, paginasi, atau pencarian dalam konten, gunakan friendly_web_extract sebagai gantinya.

Parameter:

  • url (wajib) - Alamat web yang akan diambil
  • outputFormat - Format keluaran: markdown (default), text, atau html
  • waitMs - Waktu ekstra untuk menunggu setelah halaman dimuat, jika konten muncul perlahan
  • timeoutMs - Berapa lama menunggu sebelum menyerah (default: 15 detik)
  • maxChars - Jumlah maksimum konten yang akan dikembalikan (default: 40.000 karakter)
  • includeHtml - Atur ke true untuk juga mengembalikan HTML mentah bersama konten
  • headless - Atur ke false untuk melihat jendela peramban (berguna untuk debugging)

Mengembalikan:

  • url - URL yang diminta
  • finalUrl - URL setelah pengalihan apa pun
  • title - Judul halaman
  • content - Konten yang diekstrak (dalam format yang diminta)
  • html - HTML mentah (hanya jika includeHtml true)
  • meta - Metadata halaman (deskripsi, penulis, waktu publikasi, dll.)
  • fetchedAt - Stempel waktu ISO saat halaman diambil
  • truncated - Apakah konten dipotong agar sesuai dengan maxChars

friendly_search

Mencari di web dan mengembalikan daftar hasil.

Parameter:

  • query (wajib) - Apa yang akan dicari
  • engine - Mesin pencari mana yang akan digunakan (duckduckgo atau google)
  • maxResults - Berapa banyak hasil yang akan dikembalikan (default: 10, maksimum: 50)
  • timeoutMs - Berapa lama menunggu sebelum menyerah (default: 15 detik)
  • headless - Atur ke false untuk melihat jendela peramban

Mengembalikan:

  • query - Kueri pencarian yang digunakan
  • engine - Mesin pencari mana yang digunakan
  • results - Array hasil, masing-masing dengan title, url, dan snippet
  • searchedAt - Stempel waktu ISO saat pencarian dilakukan
  • fallback_result_html - HTML mentah halaman (hanya disertakan jika tidak ada hasil yang ditemukan)
  • debug_info - Informasi diagnostik tentang upaya pencarian

Penanganan CAPTCHA: Jika CAPTCHA terdeteksi saat berjalan dalam mode headless, alat secara otomatis mencoba lagi dengan jendela peramban yang terlihat. Ini memberi Anda kesempatan untuk menyelesaikan CAPTCHA secara manual. Bidang debug_info.retried menunjukkan apakah fallback ini digunakan.

friendly_web_extract

Mengekstrak konten dari URL. Mendeteksi secara otomatis apakah URL mengarah ke PDF atau halaman web dan menangani masing-masing dengan tepat.

Parameter:

  • url (wajib) - URL yang akan diambil (PDF atau halaman web)
  • maxChars - Jumlah maksimum teks yang akan dikembalikan (default: 40.000 karakter)
  • offset - Posisi karakter untuk memulai (default: 0). Gunakan ini untuk melakukan paginasi melalui konten besar.
  • search - Cari frasa dan kembalikan kecocokan dengan konteks sekitarnya alih-alih konten penuh
  • contextChars - Karakter konteks di sekitar setiap kecocokan pencarian (default: 200)
  • waitMs - Waktu ekstra untuk menunggu setelah halaman dimuat untuk konten dinamis (hanya halaman web)
  • timeoutMs - Berapa lama menunggu sebelum menyerah (default: 15 detik, hanya halaman web)
  • headless - Atur ke false untuk melihat jendela peramban (hanya halaman web)

Mengembalikan (mode normal):

  • url - URL yang diminta
  • contentType - Baik pdf atau html
  • title - Judul halaman/dokumen
  • author - Penulis PDF (hanya PDF, jika tersedia)
  • creationDate - Kapan PDF dibuat (hanya PDF, jika tersedia)
  • pageCount - Jumlah halaman (hanya PDF)
  • totalChars - Total karakter (gunakan dengan offset untuk paginasi)
  • offset - Offset yang digunakan
  • content - Konten teks yang diekstrak
  • fetchedAt - Stempel waktu ISO
  • truncated - Apakah lebih banyak konten tersisa setelah potongan ini

Mengembalikan (mode pencarian):

  • url, contentType, title, totalChars, fetchedAt - Sama seperti di atas
  • search - Frasa pencarian yang digunakan
  • matchCount - Jumlah kecocokan yang ditemukan
  • matches - Array kecocokan, masing-masing dengan position, context, prefix, dan suffix

friendly_web_ask

Mengambil URL (PDF atau halaman web) dan meminta LLM menjawab pertanyaan tentangnya. Mendeteksi jenis konten secara otomatis. Dokumen diproses dalam konteks terpisah, menjaga percakapan utama Anda tetap ringkas.

Parameter:

  • url (wajib) - URL yang akan diambil (PDF atau halaman web)
  • ask (wajib) - Pertanyaan atau instruksi untuk LLM (meringkas, mengekstrak info, menjawab pertanyaan, dll.)
  • askMaxInputTokens - Token input maksimum per panggilan LLM (default: 150.000)
  • askMaxOutputTokens - Token output maksimum per panggilan LLM (default: 4.096)
  • askTimeout - Timeout dalam milidetik (default: 300.000 = 5 menit)
  • askSplitAndSynthesize - Untuk dokumen besar: bagi menjadi potongan, proses masing-masing, lalu sintesis hasil (default: false). Peringatan: mengonsumsi banyak token.
  • waitMs - Waktu ekstra untuk menunggu setelah halaman dimuat untuk konten dinamis (hanya halaman web)
  • timeoutMs - Berapa lama menunggu sebelum menyerah (default: 15 detik, hanya halaman web)
  • headless - Atur ke false untuk melihat jendela peramban (hanya halaman web)

Mengembalikan:

  • url - URL yang diminta
  • contentType - Baik pdf atau html
  • title - Judul halaman/dokumen
  • totalChars - Total karakter dalam dokumen
  • ask - Instruksi yang diberikan
  • answer - Respons LLM
  • model - Model yang menghasilkan respons
  • chunksProcessed - Jumlah potongan yang diproses (1 untuk dokumen kecil, lebih banyak saat menggunakan askSplitAndSynthesize)
  • fetchedAt - Stempel waktu ISO

Mode tanya menggunakan sampling MCP untuk meminta LLM memproses dokumen dengan instruksi apa pun. Ini berguna untuk:

  • Dokumen besar yang akan membanjiri konteks
  • Menjaga biaya token tetap rendah pada percakapan utama

Saat askSplitAndSynthesize diaktifkan, dokumen yang melebihi askMaxInputTokens secara otomatis dibagi menjadi potongan yang tumpang tindih. Setiap potongan diproses secara terpisah, dan hasilnya disintesis menjadi satu jawaban yang koheren. Respons akhir diberikan dalam bahasa yang sama dengan permintaan Anda, terlepas dari bahasa dokumen.

Simpanan dokumen

Simpanan adalah pustaka dokumen lokal yang dapat dicari. Ini mendukung PDF, file HTML, dan teks biasa (Markdown/TXT). Saat Anda menambahkan dokumen, Research Friend menyimpan file asli, mengekstrak teks (untuk PDF/HTML), dan menyimpan metadata dalam basis data lokal. Pencarian menggunakan ripgrep di balik layar untuk pencocokan yang cepat dan sadar frasa.

Lokasi simpanan

Simpanan berada di bawah ~/.research-friend/:

  • inbox/ - Letakkan file di sini untuk diproses
  • store/ - Penyimpanan dokumen terorganisir dan teks yang diekstrak
  • stash.db - Basis data metadata

Jenis file yang didukung

  • PDF: .pdf (teks diekstrak)
  • HTML: .html, .htm (teks diekstrak)
  • Markdown: .md, .markdown (disimpan sebagai teks biasa)
  • Teks: .txt (disimpan sebagai teks biasa)

Alat simpanan

stash_open_inbox

Buka folder kotak masuk simpanan di pengelola file Anda untuk memudahkan seret dan lepas.

Mengembalikan:

  • opened - Apakah permintaan buka folder telah dikirim
  • inboxPath - Jalur absolut ke kotak masuk
  • command - Perintah OS yang digunakan
  • args - Argumen perintah yang digunakan

stash_process_inbox

Memproses file di inbox/, mengklasifikasikannya ke dalam topik, mengekstrak teks, dan menyimpan hasilnya. Untuk dokumen panjang, klasifikasi menggunakan bagian sampel (awal/tengah/akhir ditambah beberapa potongan acak) untuk meningkatkan akurasi topik.

Mengembalikan:

  • processed - Array nama file yang berhasil diproses
  • errors - Kesalahan apa pun yang ditemui
  • documents - Array catatan dokumen yang dibuat

reindex_stash

Menghasilkan ulang ringkasan, mengalokasikan ulang topik, dan memperbarui metadata simpanan untuk dokumen yang disimpan. Jika ids dihilangkan atau kosong, semua dokumen diindeks ulang.

Parameter:

  • ids - ID dokumen yang akan diindeks ulang (opsional)

Mengembalikan:

  • reindexed - ID dokumen yang diindeks ulang
  • errors - Kesalahan apa pun yang ditemui
  • documents - Array catatan dokumen yang diperbarui

stash_list

Mencantumkan dokumen di simpanan.

Parameter:

  • topic - Filter ke topik (opsional)
  • limit - Hasil maks (default: 50)
  • offset - Offset paginasi (default: 0)

Mengembalikan:

  • type - all atau topic
  • totalDocuments - Total dokumen (hanya ketika type adalah all)
  • count - Hasil yang dikembalikan setelah paginasi
  • offset - Offset paginasi yang digunakan
  • limit - Batas paginasi yang digunakan
  • topics - Ringkasan topik yang diketahui dan jumlah dokumen
  • documents - Daftar dokumen dengan metadata (termasuk isPrimary saat mencantumkan topik)

stash_search

Mencari nama file dan konten di seluruh simpanan. Semua istilah pencarian harus ada (logika AND). Kecocokan nama file dicantumkan terlebih dahulu. Gunakan tanda kutip untuk frasa tepat.

Parameter:

  • query (wajib) - Istilah pencarian. Gunakan tanda kutip untuk frasa: "sparkling wine"
  • topic - Filter ke topik (opsional)
  • ids - Filter ke ID dokumen tertentu (opsional)
  • limit - Dokumen maks yang akan dikembalikan (default: 20)
  • offset - Offset paginasi (default: 0)
  • maxMatchesPerDoc - Kecocokan maks per dokumen (default: 50)
  • context - Baris konteks di sekitar setiap kecocokan (default: 1, maks: 5). Mengontrol seberapa dekat istilah harus muncul untuk cocok DAN berapa banyak teks sekitarnya yang dikembalikan. Mengembalikan:
  • totalMatches - Total dokumen yang cocok sebelum paginasi
  • count - Hasil yang dikembalikan setelah paginasi
  • results - Array dokumen, masing-masing dengan:
    • id, filename, fileType, summary, charCount, createdAt
    • matchType - filename, content, atau filename+content
    • matches - Array { line, context } untuk setiap lokasi kecocokan

Gunakan nilai line dengan stash_extract untuk langsung melompat ke lokasi kecocokan.

stash_extract

Ekstrak konten dari dokumen yang disimpan untuk dibaca. Gunakan nomor baris dari hasil stash_search untuk langsung melompat ke kecocokan.

Parameter:

  • id (wajib) - ID Dokumen dari stash_list/stash_search
  • maxChars - Jumlah maksimum teks yang akan dikembalikan (default: 40.000 karakter)
  • offset - Posisi karakter untuk memulai (saling eksklusif dengan line)
  • line - Nomor baris untuk memulai (saling eksklusif dengan offset)

Mengembalikan:

  • id, filename, fileType, summary - Metadata dokumen
  • totalChars - Total karakter dalam dokumen
  • offset - Offset karakter (disertakan saat menggunakan line untuk referensi)
  • line - Nomor baris (hanya jika parameter line digunakan)
  • content - Konten teks yang diekstrak
  • truncated - Apakah masih ada konten yang tersisa setelah potongan ini

stash_ask

Minta LLM menjawab pertanyaan tentang dokumen yang disimpan. Dokumen diproses dalam konteks terpisah, menjaga percakapan utama Anda tetap ringkas.

Parameter:

  • id (wajib) - ID Dokumen dari stash_list/stash_search
  • ask (wajib) - Pertanyaan atau instruksi untuk LLM
  • askMaxInputTokens - Token input maksimum per panggilan LLM (default: 150.000)
  • askMaxOutputTokens - Token output maksimum per panggilan LLM (default: 4.096)
  • askTimeout - Batas waktu dalam milidetik (default: 300.000 = 5 menit)
  • askSplitAndSynthesize - Untuk dokumen besar: bagi menjadi beberapa potongan, proses masing-masing, lalu sintesis hasilnya (default: false)

Mengembalikan:

  • id, filename, fileType, summary - Metadata dokumen
  • totalChars - Total karakter dalam dokumen
  • ask - Instruksi yang diberikan
  • answer - Respons LLM
  • model - Model yang menghasilkan respons
  • chunksProcessed - Jumlah potongan yang diproses

Alur umum

  1. Letakkan file ke ~/.research-friend/inbox/
  2. Jalankan stash_process_inbox
  3. Gunakan stash_list untuk menjelajahi topik
  4. Gunakan stash_search untuk menemukan dokumen yang relevan
  5. Gunakan stash_extract untuk membaca dokumen tertentu, atau stash_ask untuk mengajukan pertanyaan tentangnya

Pemecahan Masalah

"Browser closed unexpectedly" atau kesalahan serupa

Coba instal ulang browser:

npx playwright install chromium --force

Di Linux, Anda mungkin juga memerlukan dependensi sistem:

npx playwright install-deps chromium

Server tidak mau mulai

Pastikan Anda menggunakan Node.js 20 atau lebih baru:

node --version

Jika versi Anda lebih lama, kunjungi nodejs.org untuk mengunduh yang lebih baru.

Lisensi

MIT