# jina-ai/mcp architecture

> Architecture diagram of the GitHub repository jina-ai/mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jina-ai/mcp
- Repository: https://github.com/jina-ai/mcp

## Overview

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

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Clients Layer
    subgraph "Clients" 
        direction TB
        LMStudio["LM Studio"]:::clients
        HTTPClient["Any HTTP Client"]:::clients
        MCPRemote["mcp-remote Proxy"]:::clients
    end

    %% Cloudflare Worker Environment
    subgraph "Cloudflare Worker\n(TypeScript, SSE, Wrangler)" 
        direction TB
        subgraph "API Gateway / Request Router"
            direction TB
            Router["Entry Point / Router"]:::internal
        end
        subgraph "Service Layer / Tools"
            direction TB
            Tools["jina-tools.ts"]:::internal
        end
        subgraph "Utility Layer"
            direction TB
            ErrHandler["api-error-handler.ts"]:::internal
            ImgDownloader["image-downloader.ts"]:::internal
            URLNormalizer["url-normalizer.ts"]:::internal
            SubmodOpt["submodular-optimization.ts"]:::internal
        end
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        JinaGroup(("Jina AI APIs")):::external
        ThirdParty(("3rd-party Web/Image/ArXiv")):::external
    end

    %% Configuration Files
    subgraph "Config & Build"
        direction TB
        Wrangler["wrangler.jsonc"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageJSON["package.json"]:::config
    end

    %% Connections - Request Flow
    LMStudio -->|"SSE HTTP POST"| Router
    HTTPClient -->|"SSE HTTP POST"| Router
    MCPRemote -->|"SSE HTTP POST"| Router

    Router -->|"dispatch tool"| Tools
    Tools -->|"use helpers"| ErrHandler
    Tools -->|"use helpers"| ImgDownloader
    Tools -->|"use helpers"| URLNormalizer
    Tools -->|"use helpers"| SubmodOpt

    Tools -->|"HTTP fetch"| JinaGroup
    ErrHandler -->|"HTTP fetch"| ThirdParty
    ImgDownloader -->|"HTTP fetch"| ThirdParty
    URLNormalizer -->|"HTTP fetch"| ThirdParty

    %% Streaming Responses
    JinaGroup -.->|"SSE stream response"| Router
    ThirdParty -.->|"SSE stream response"| Router
    Router -.->|"SSE stream response"| LMStudio

    %% Click Events
    click Router "https://github.com/jina-ai/mcp/blob/main/src/index.ts"
    click Tools "https://github.com/jina-ai/mcp/blob/main/src/tools/jina-tools.ts"
    click ErrHandler "https://github.com/jina-ai/mcp/blob/main/src/utils/api-error-handler.ts"
    click ImgDownloader "https://github.com/jina-ai/mcp/blob/main/src/utils/image-downloader.ts"
    click SubmodOpt "https://github.com/jina-ai/mcp/blob/main/src/utils/submodular-optimization.ts"
    click URLNormalizer "https://github.com/jina-ai/mcp/blob/main/src/utils/url-normalizer.ts"
    click Wrangler "https://github.com/jina-ai/mcp/blob/main/wrangler.jsonc"
    click TSConfig "https://github.com/jina-ai/mcp/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/jina-ai/mcp/blob/main/package.json"

    %% Styles
    classDef clients fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef internal fill:#FFFF99,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef config fill:#FFFFFF,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef dashed stroke-dasharray: 2 2
    linkStyle default stroke:#333,stroke-width:1px
    class JinaGroup,ThirdParty dashed
```
