How jina-ai/mcp works
Project Type and Purpose
• This is a full-stack “serverless microservice” implemented as a Cloudflare Worker, serving as a remote Model Context Protocol (MCP) server.
• It exposes a set of “tools” (read_url, capture_screenshot_url, search_web, etc.) via an SSE-based API endpoint, proxying calls to Jina AI’s Reader, Embeddings, and Reranker services (and a few third-party web/image/arXiv endpoints).
Top-Level Components
• Client(s): LM Studio or any MCP-capable client (or developer’s local proxy via mcp-remote).
• Edge Runtime: Cloudflare Workers (configured via wrangler.jsonc, package.json, tsconfig.json).
• Code Modules inside the Worker:
• Entry Point (src/index.ts) – receives SSE HTTP requests, parses the tool name, and dispatches.
• Tool Layer (src/tools/jina-tools.ts) – implements each tool’s logic (calling the correct Jina API endpoint).
• Utilities (src/utils/*.ts) – shared code for error handling, HTTP fetch wrappers (screenshot, downloader), URL normalization, submodular optimization, etc.
• External Services:
• Jina AI Reader API
• Jina AI Embeddings API
• Jina AI Reranker API
• 3rd-party Web/Image/ArXiv endpoints
Relationships & Data Flow
• Client → (optional) mcp-remote proxy → Worker SSE endpoint
• Worker Entry → Router (in index.ts) → Tool Function
• Tool Function → Utility functions (e.g., normalize URL, download image) → External Jina/3rd-party API
• External API → Utility layer streams/parses response → SSE back to Client
Architectural Patterns & Design Principles
• Serverless single-function microservice
• Layered architecture:
• API Gateway / Request Router
• Service (tool) layer
• Utility / shared library layer
• Single-responsibility modules: each tool and each utility is isolated.
• Streaming architecture (SSE and HTTP streaming fetch).
Technologies & Frameworks
• Cloudflare Workers (JavaScript/TypeScript runtime)
• Wrangler for deployment
• TypeScript modules, npm scripts
• Jina AI HTTP APIs (Reader, Embeddings, Reranker)
• mcp-remote local proxy (npm package)