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

Related MCP server: litra-paper-search-mcp

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

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

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).