journal-search-mcp

MCP Server (Node.js + TypeScript, Streamable HTTP transport) untuk pencarian dan verifikasi jurnal akademik PDF. Dipanggil oleh Claude sebagai MCP client/orchestrator. Claude tidak pernah membaca isi dokumen mentah — semua pembacaan/pemahaman konten PDF didelegasikan ke sub-agent Gemini Flash Lite yang mengembalikan JSON pendek.

Lihat specs.md (dokumen asli) untuk spesifikasi lengkap. README ini hanya ringkasan cara menjalankan.

Instalasi

npm install
cp .env.example .env
# isi .env: TAVILY_API_KEY, GEMINI_API_KEYS, MCP_API_KEY minimal

Menjalankan lokal

npm run build
npm start
# atau untuk development dengan watch mode:
npm run dev   # di terminal lain: node dist/index.js setiap kali rebuild

Server akan listen di http://localhost:3000 (atau MCP_PORT/PORT kalau di-set).

Cek cepat:

curl http://localhost:3000/health
curl "http://localhost:3000/test?key=ISI_MCP_API_KEY_ANDA"

Endpoint MCP untuk dipasang di Claude:

http://localhost:3000/mcp?key=ISI_MCP_API_KEY_ANDA

REST API (HTTP biasa)

Selain MCP, setiap tool juga bisa dipanggil lewat REST endpoint HTTP biasa — berguna untuk integrasi dengan backend non-MCP, Postman, curl, atau agent yang ingin akses JSON langsung tanpa protokol MCP.

Autentikasi

Sama seperti MCP endpoint: API key dikirim lewat query string ?key=....

POST /api/verify-pdf?key=ISI_MCP_API_KEY_ANDA

Kalau key salah atau tidak ada → 401 { "error": "invalid_or_missing_api_key" }.

Daftar endpoint

Method	Path	Deskripsi
POST	/api/tavily-search	Pencarian web umum (Tavily Search)
POST	/api/tavily-extract	Ekstraksi konten halaman web
POST	/api/tavily-crawl	Crawl/jelajahi situs
POST	/api/verify-pdf	Verifikasi magic bytes PDF dari URL
POST	/api/analyze-journal-standard	Analisis jurnal standar (worker round-robin)
POST	/api/analyze-journal-custom	Analisis jurnal dengan prompt/field kustom
POST	/api/search-and-check-journals	Tool komposit: search → verify → judge
GET	/api/tools	Daftar semua tool yang tersedia (metadata)

Semua endpoint POST menerima Content-Type: application/json. Input body mengikuti schema yang sama dengan tool MCP — lihat src/schemas/toolSchemas.ts.

Contoh request

# Verifikasi PDF
curl -X POST "http://localhost:3000/api/verify-pdf?key=ISI_MCP_API_KEY_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/paper.pdf"}'

Response sukses (200):

{
  "url": "https://example.com/paper.pdf",
  "is_pdf": true,
  "detected_signature": "%PDF-",
  "http_status": 200
}

Response validasi gagal (400):

{
  "error": "invalid_input",
  "error_detail": "url: url harus valid"
}

Response tanpa/ salah API key (401):

{
  "error": "invalid_or_missing_api_key"
}

Discovery

curl "http://localhost:3000/api/tools?key=ISI_MCP_API_KEY_ANDA"

Mengembalikan daftar 7 tool dengan nama, method HTTP, dan path masing-masing.

Tools yang tersedia

Tool	Deskripsi
tavily_search	Pass-through pencarian web umum
tavily_extract	Pass-through ekstraksi konten halaman web
tavily_crawl	Pass-through crawl situs
verify_pdf	Cek magic bytes URL — benar PDF atau bukan
analyze_journal_standard	verify → extract → judge (worker gemini-1/2 round-robin)
analyze_journal_custom	Sama seperti standard, tapi worker gemini-3 + custom prompt opsional
search_and_check_journals	Tool komposit utama: search → verify → judge, banyak kandidat sekaligus

Error handling

Semua tool tidak pernah throw ke MCP client — setiap kegagalan (download gagal, bukan PDF, semua API key rate limited, JSON tidak valid dari Gemini, dll) dibungkus jadi field error / error_detail pada JSON output. Lihat kode error lengkap di src/types.ts (ToolErrorCode) dan §11 specs.md.

Level HTTP (di luar tool JSON):

• 401 invalid_or_missing_api_key
• 500 server_misconfigured_missing_mcp_api_key
• 400 invalid_json_body
• 404 not_found

Testing

npm run typecheck

Lihat §12 specs.md untuk testing plan lengkap (unit test rate limiter, key pool, magic bytes checker, integration test dengan PDF publik, dll — belum di-generate otomatis di sini, tulis sesuai kebutuhan Anda dengan test runner pilihan, mis. vitest).

Deploy ke Render

Lihat render.yaml (infra-as-code) dan §14 specs.md. Ringkas:

• Type: Web Service
• Build: npm install && npm run build
• Start: node dist/index.js
• Health check path: /health
• PORT otomatis di-inject Render — jangan hardcode port lain.
• Set semua secret (TAVILY_API_KEY, GEMINI_API_KEYS, MCP_API_KEY) manual lewat Render Dashboard → Environment (jangan commit ke repo).

Non-goals fase ini

• Worker 4 (Lightpanda/browser-rendering) — slot sudah disiapkan di workerPool.ts, tapi memanggilnya akan return error not_implemented.
• Caching hasil analisis.
• OCR untuk PDF hasil scan.
• Multi-user auth (hanya satu shared MCP_API_KEY).