mcp-omnisearch

Instructions

Implementation Reference

• src/providers/enhancement/jina_grounding/index.ts:38-113 (handler)

  Core implementation of the enhancement logic: validates API key, calls Jina AI grounding API with the content as statement, processes response to return factuality score, verdict, reasoning, references, and metadata.

  async enhance_content(content: string): Promise<EnhancementResult> {
  	const api_key = validate_api_key(
  		config.enhancement.jina_grounding.api_key,
  		this.name,
  	);
  
  	const ground_request = async () => {
  		try {
  			const data = await http_json<JinaGroundingResponse>(
  				this.name,
  				'https://g.jina.ai',
  				{
  					method: 'POST',
  					headers: {
  						'Content-Type': 'application/json',
  						Authorization: `Bearer ${api_key}`,
  					},
  					body: JSON.stringify({ statement: content }),
  					signal: AbortSignal.timeout(
  						config.enhancement.jina_grounding.timeout,
  					),
  				},
  			);
  
  			if (!data?.data) {
  				throw new ProviderError(
  					ErrorType.API_ERROR,
  					'Unexpected response: missing data from Jina Grounding',
  					this.name,
  				);
  			}
  
  			// Format references into a readable string
  			const references_text = data.data.references
  				.map(
  					(ref) =>
  						`${ref.is_supportive ? '✓' : '✗'} ${ref.key_quote} (${
  							ref.url
  						})`,
  				)
  				.join('\n\n');
  
  			return {
  				original_content: content,
  				enhanced_content: `Factuality Score: ${
  					data.data.factuality
  				}\nVerdict: ${
  					data.data.result ? 'True' : 'False'
  				}\n\nReasoning: ${
  					data.data.reason
  				}\n\nReferences:\n${references_text}`,
  				enhancements: [
  					{
  						type: 'fact_verification',
  						description:
  							'Verified factual accuracy against real-time web knowledge',
  					},
  				],
  				sources: data.data.references.map((ref) => ({
  					title: ref.key_quote,
  					url: ref.url,
  				})),
  				source_provider: this.name,
  				meta: {
  					factuality: data.data.factuality,
  					result: data.data.result,
  					token_usage: data.data.usage.tokens,
  				},
  			};
  		} catch (error) {
  			handle_provider_error(error, this.name, 'ground content');
  		}
  	};
  
  	return retry_with_backoff(ground_request);
  }

• src/server/tools.ts:468-509 (registration)

  Dynamically registers the MCP tool 'jina_grounding_enhance' (constructed as `${provider.name}_enhance`) for all enhancement providers, including schema validation for 'content' input and wrapper handler that calls provider.enhance_content().

  // Register enhancement providers
  this.enhancement_providers.forEach((provider) => {
  	server.tool(
  		{
  			name: `${provider.name}_enhance`,
  			description: provider.description,
  			schema: v.object({
  				content: v.pipe(v.string(), v.description('Content')),
  			}),
  		},
  		async ({ content }) => {
  			try {
  				const result = await provider.enhance_content(content);
  				const safe_result = handle_large_result(
  					result,
  					provider.name,
  				);
  				return {
  					content: [
  						{
  							type: 'text' as const,
  							text: JSON.stringify(safe_result, null, 2),
  						},
  					],
  				};
  			} catch (error) {
  				const error_response = create_error_response(
  					error as Error,
  				);
  				return {
  					content: [
  						{
  							type: 'text' as const,
  							text: error_response.error,
  						},
  					],
  					isError: true,
  				};
  			}
  		},
  	);
  });

• src/providers/index.ts:127-133 (registration)

  Conditionally registers the JinaGroundingProvider instance (with name 'jina_grounding') if API key is valid, enabling the 'jina_grounding_enhance' tool.

  	is_api_key_valid(
  		config.enhancement.jina_grounding.api_key,
  		'jina_grounding',
  	)
  ) {
  	register_enhancement_provider(new JinaGroundingProvider());
  }

• src/providers/enhancement/jina_grounding/index.ts:15-31 (schema)

  TypeScript interface defining the expected response structure from Jina Grounding API, used for type-safe parsing in the handler.

  interface JinaGroundingResponse {
  	code: number;
  	status: number;
  	data: {
  		factuality: number;
  		result: boolean;
  		reason: string;
  		references: Array<{
  			url: string;
  			key_quote: string;
  			is_supportive: boolean;
  		}>;
  		usage: {
  			tokens: number;
  		};
  	};
  }