get_reranking
Sort documents by relevance to a user query using the ZeroEntropy Zerank API, enabling AI assistants to retrieve precise information efficiently.
Instructions
Get the reranked document listing
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| api_key | Yes | API key for authentication | |
| documents | Yes | Array of documents to rerank | |
| query | Yes | The search query |
Implementation Reference
- rerank.py:32-82 (handler)Primary handler function for the 'get_reranking' tool. Validates input using RerankRequest, proxies request to ZeroRank API, parses response into RerankResponse, handles various errors.@mcp.tool() async def get_reranking(request: RerankRequest) -> RerankResponse: """Get the reranked document listing Args: request: The RerankRequest object containing query, documents, and api_key Returns: The RerankResponse object containing the reranked document listing """ headers = { "Authorization": f"Bearer {request.api_key}", "Content-Type": "application/json", } async with httpx.AsyncClient() as client: try: response = await client.post( ZERANK_API_BASE, json={ "query": request.query, "documents": request.documents, }, headers=headers, ) response.raise_for_status() result = response.json() if "results" not in result: raise ValueError("Invalid API response format") return RerankResponse( results=[RerankResult(**result) for result in result["results"]] ) except httpx.HTTPStatusError as e: if e.response.status_code == 401: raise ValueError("Invalid API key") elif e.response.status_code == 429: raise ValueError("Rate limit exceeded") else: raise ValueError(f"API error: {e.response.status_code}") except httpx.TimeoutException: raise ValueError("Request timed out") except httpx.RequestError as e: raise ValueError(f"Request error: {str(e)}") except Exception as e: raise ValueError(f"Reranking failed: {str(e)}")
- main.py:17-67 (handler)Handler function for 'get_reranking' tool in Cloudflare Durable Object context. Similar to rerank.py implementation.@self.mcp.tool() async def get_reranking(request: RerankRequest) -> RerankResponse: """Get the reranked document listing Args: request: The RerankRequest object containing query, documents, and api_key Returns: The RerankResponse object containing the reranked document listing """ headers = { "Authorization": f"Bearer {request.api_key}", "Content-Type": "application/json", } async with httpx.AsyncClient() as client: try: response = await client.post( ZERANK_API_BASE, json={ "query": request.query, "documents": request.documents, }, headers=headers, ) response.raise_for_status() result = response.json() if "results" not in result: raise ValueError("Invalid API response format") return RerankResponse( results=[RerankResult(**result) for result in result["results"]] ) except httpx.HTTPStatusError as e: if e.response.status_code == 401: raise ValueError("Invalid API key") elif e.response.status_code == 429: raise ValueError("Rate limit exceeded") else: raise ValueError(f"API error: {e.response.status_code}") except httpx.TimeoutException: raise ValueError("Request timed out") except httpx.RequestError as e: raise ValueError(f"Request error: {str(e)}") except Exception as e: raise ValueError(f"Reranking failed: {str(e)}")
- worker.js:184-231 (handler)Core reranking logic in JavaScript for Cloudflare Worker. Called from tool handler. Validates, calls API, parses, handles errors.async makeRerankRequest(query, documents, apiKey) { const headers = { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", }; const body = JSON.stringify({ query, documents, }); try { const response = await fetch(ZERANK_API_BASE, { method: "POST", headers, body, }); if (!response.ok) { if (response.status === 401) { throw new Error("Invalid API key"); } else if (response.status === 429) { throw new Error("Rate limit exceeded"); } else { throw new Error(`API error: ${response.status}`); } } const result = await response.json(); if (!result.results) { throw new Error("Invalid API response format"); } return RerankResponseSchema.parse({ results: result.results.map(r => ({ index: r.index, relevance_score: r.relevance_score, })), }); } catch (error) { if (error.name === "TypeError" && error.message.includes("fetch")) { throw new Error(`Request error: ${error.message}`); } throw error; } }
- index.js:31-77 (handler)Core reranking logic in JavaScript for Node.js MCP server. Called from tool call handler.async function makeRerankRequest(query, documents, apiKey) { const headers = { "Authorization": `Bearer ${apiKey}`, "Content-Type": "application/json", }; const body = JSON.stringify({ query, documents, }); try { const response = await fetch(ZERANK_API_BASE, { method: "POST", headers, body, }); if (!response.ok) { if (response.status === 401) { throw new Error("Invalid API key"); } else if (response.status === 429) { throw new Error("Rate limit exceeded"); } else { throw new Error(`API error: ${response.status}`); } } const result = await response.json(); if (!result.results) { throw new Error("Invalid API response format"); } return RerankResponseSchema.parse({ results: result.results.map(r => ({ index: r.index, relevance_score: r.relevance_score, })), }); } catch (error) { if (error.name === "TypeError" && error.message.includes("fetch")) { throw new Error(`Request error: ${error.message}`); } throw error; }
- rerank.py:11-30 (schema)Pydantic models for input (RerankRequest), result item (RerankResult), and output (RerankResponse) schema validation.class RerankRequest(BaseModel): query: str = Field(..., min_length=1, max_length=10000) documents: list[str] = Field(..., min_length=1, max_length=1000) api_key: str = Field(..., min_length=1) @field_validator("documents") def validate_documents(cls, v: list[str]) -> list[str]: if not all(doc.strip() for doc in v): raise ValueError("Documents cannot be empty strings") return v class RerankResult(BaseModel): index: int = Field(..., ge=0, le=1000) relevance_score: float = Field(..., ge=0, le=1) class RerankResponse(BaseModel): results: list[RerankResult] = Field(..., min_length=1, max_length=1000)