sort_by_relevance

Instructions

Implementation Reference

• src/tools/jina-tools.ts:459-520 (handler)

  Executes the tool logic by calling the Jina Reranker API (https://api.jina.ai/v1/rerank) with model 'jina-reranker-v2-base-multilingual' to rerank the provided documents by relevance to the query. Handles errors, token check, and formats output as YAML.

  async ({ query, documents, top_n }: { query: string; documents: string[]; top_n?: number }) => {
  	try {
  		const props = getProps();
  
  		const tokenError = checkBearerToken(props.bearerToken);
  		if (tokenError) {
  			return tokenError;
  		}
  
  		if (documents.length === 0) {
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: "No documents provided for reranking",
  					},
  				],
  				isError: true,
  			};
  		}
  
  		const response = await fetch('https://api.jina.ai/v1/rerank', {
  			method: 'POST',
  			headers: {
  				'Accept': 'application/json',
  				'Content-Type': 'application/json',
  				'Authorization': `Bearer ${props.bearerToken}`,
  			},
  			body: JSON.stringify({
  				model: 'jina-reranker-v2-base-multilingual',
  				query,
  				top_n: top_n || documents.length,
  				documents
  			}),
  		});
  
  		if (!response.ok) {
  			return handleApiError(response, "Document reranking");
  		}
  
  		const data = await response.json() as any;
  
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: yamlStringify(data.results),
  				},
  			],
  		};
  	} catch (error) {
  		return {
  			content: [
  				{
  					type: "text" as const,
  					text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  				},
  			],
  			isError: true,
  		};
  	}
  },

• src/tools/jina-tools.ts:455-457 (schema)

  Zod schema defining the input parameters for the tool: query (string), documents (array of strings), top_n (optional number). Used for validation.

  query: z.string().describe("The query or topic to rank documents against (e.g., 'machine learning algorithms', 'climate change solutions')"),
  documents: z.array(z.string()).describe("Array of document texts to rerank by relevance"),
  top_n: z.number().optional().describe("Maximum number of top results to return (default: all documents)")

• src/tools/jina-tools.ts:451-521 (registration)

  Registers the 'sort_by_relevance' tool on the MCP server with name, description, input schema, and handler function. Called from src/index.ts via registerJinaTools.

  server.tool(
  	"sort_by_relevance",
  	"Rerank a list of documents by relevance to a query using Jina Reranker API. Use this when you have multiple documents and want to sort them by how well they match a specific query or topic. Perfect for document retrieval, content filtering, or finding the most relevant information from a collection. Returns documents sorted by relevance score.",
  	{
  		query: z.string().describe("The query or topic to rank documents against (e.g., 'machine learning algorithms', 'climate change solutions')"),
  		documents: z.array(z.string()).describe("Array of document texts to rerank by relevance"),
  		top_n: z.number().optional().describe("Maximum number of top results to return (default: all documents)")
  	},
  	async ({ query, documents, top_n }: { query: string; documents: string[]; top_n?: number }) => {
  		try {
  			const props = getProps();
  
  			const tokenError = checkBearerToken(props.bearerToken);
  			if (tokenError) {
  				return tokenError;
  			}
  
  			if (documents.length === 0) {
  				return {
  					content: [
  						{
  							type: "text" as const,
  							text: "No documents provided for reranking",
  						},
  					],
  					isError: true,
  				};
  			}
  
  			const response = await fetch('https://api.jina.ai/v1/rerank', {
  				method: 'POST',
  				headers: {
  					'Accept': 'application/json',
  					'Content-Type': 'application/json',
  					'Authorization': `Bearer ${props.bearerToken}`,
  				},
  				body: JSON.stringify({
  					model: 'jina-reranker-v2-base-multilingual',
  					query,
  					top_n: top_n || documents.length,
  					documents
  				}),
  			});
  
  			if (!response.ok) {
  				return handleApiError(response, "Document reranking");
  			}
  
  			const data = await response.json() as any;
  
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: yamlStringify(data.results),
  					},
  				],
  			};
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: "text" as const,
  						text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  					},
  				],
  				isError: true,
  			};
  		}
  	},
  );