ground_statement

Instructions

Implementation Reference

• src/index.ts:130-231 (handler)

  The main handler for executing the 'ground_statement' tool. It validates input, makes a POST request to Jina AI's grounding API with optional site restrictions and no-cache header, handles errors including specific URL validation failures, and returns the grounding response as JSON.

  this.server.setRequestHandler(
  	CallToolRequestSchema,
  	async (request) => {
  		if (request.params.name !== 'ground_statement') {
  			throw new McpError(
  				ErrorCode.MethodNotFound,
  				`Unknown tool: ${request.params.name}`,
  			);
  		}
  
  		const args = request.params.arguments;
  
  		if (!is_valid_grounding_args(args)) {
  			throw new McpError(
  				ErrorCode.InvalidParams,
  				'Invalid parameters. Required: statement (string). Optional: references (string[]), no_cache (boolean)',
  			);
  		}
  
  		try {
  			const headers: Record<string, string> = {
  				'Content-Type': 'application/json',
  				Accept: 'application/json',
  				Authorization: `Bearer ${JINAAI_API_KEY}`,
  			};
  
  			// Add optional headers
  			if (args.references?.length) {
  				headers['X-Site'] = args.references.join(',');
  			}
  			if (args.no_cache) {
  				headers['X-No-Cache'] = 'true';
  			}
  
  			const response = await fetch(this.base_url, {
  				method: 'POST',
  				headers,
  				body: JSON.stringify({
  					statement: args.statement.trim(),
  				}),
  			});
  
  			if (!response.ok) {
  				const error_text = await response.text();
  				let error_json;
  				try {
  					error_json = JSON.parse(error_text);
  				} catch {
  					throw new Error(
  						`HTTP error! status: ${response.status}, message: ${error_text}`,
  					);
  				}
  
  				// Handle specific error cases
  				if (error_json.status === 42206) {
  					throw new McpError(
  						ErrorCode.InvalidParams,
  						'The provided URLs did not contain relevant information for fact-checking. This can happen when:\n' +
  						'1. The URLs are not publicly accessible\n' +
  						'2. The URLs do not contain information about the specific statement\n' +
  						'3. The information exists but is not in an easily searchable format\n\n' +
  						'Suggestions:\n' +
  						'- Remove the URL restrictions to search the entire web\n' +
  						'- Provide different URLs that you are certain contain the information\n' +
  						'- Verify the URLs are publicly accessible and contain relevant content',
  					);
  				}
  
  				// Handle other API errors
  				throw new Error(
  					`API error! status: ${response.status}, message: ${error_json.readableMessage || error_json.message || error_text}`,
  				);
  			}
  
  			const result = (await response.json()) as {
  				code: number;
  				status: number;
  				data: GroundingResponse;
  			};
  
  			if (result.code !== 200) {
  				throw new Error(`API error! status: ${result.status}`);
  			}
  
  			return {
  				content: [
  					{
  						type: 'text',
  						text: JSON.stringify(result.data, null, 2),
  					},
  				],
  			};
  		} catch (error) {
  			const message =
  				error instanceof Error ? error.message : String(error);
  			throw new McpError(
  				ErrorCode.InternalError,
  				`Failed to ground statement: ${message}`,
  			);
  		}
  	},
  );

• src/index.ts:97-124 (schema)

  Input schema for the ground_statement tool, defining parameters: statement (required string), references (optional array of strings), no_cache (optional boolean).

  inputSchema: {
  	type: 'object',
  	properties: {
  		statement: {
  			type: 'string',
  			description: 'Statement to be grounded',
  		},
  		references: {
  			type: 'array',
  			items: {
  				type: 'string',
  			},
  			description:
  				'Optional list of URLs to restrict search to. Only provide URLs that are ' +
  				'publicly accessible and contain information relevant to the statement. ' +
  				'If the URLs do not contain the necessary information, the grounding will fail. ' +
  				'For best results, either provide URLs you are certain contain the information, ' +
  				'or omit this parameter to search the entire web.',
  		},
  		no_cache: {
  			type: 'boolean',
  			description:
  				'Whether to bypass cache for fresh results',
  			default: false,
  		},
  	},
  	required: ['statement'],
  },

• src/index.ts:90-126 (registration)

  Registration of the ground_statement tool in the ListTools response, including name, description, and input schema reference.

  	{
  		name: 'ground_statement',
  		description:
  			'Ground a statement using real-time web search results to check factuality. ' +
  			'When providing URLs via the references parameter, ensure they are publicly accessible ' +
  			'and contain relevant information about the statement. If the URLs do not contain ' +
  			'the necessary information, try removing the URL restrictions to search the entire web.',
  		inputSchema: {
  			type: 'object',
  			properties: {
  				statement: {
  					type: 'string',
  					description: 'Statement to be grounded',
  				},
  				references: {
  					type: 'array',
  					items: {
  						type: 'string',
  					},
  					description:
  						'Optional list of URLs to restrict search to. Only provide URLs that are ' +
  						'publicly accessible and contain information relevant to the statement. ' +
  						'If the URLs do not contain the necessary information, the grounding will fail. ' +
  						'For best results, either provide URLs you are certain contain the information, ' +
  						'or omit this parameter to search the entire web.',
  				},
  				no_cache: {
  					type: 'boolean',
  					description:
  						'Whether to bypass cache for fresh results',
  					default: false,
  				},
  			},
  			required: ['statement'],
  		},
  	},
  ],

• src/index.ts:50-60 (helper)

  Helper function to validate the arguments for the ground_statement tool against GroundingOptions interface.

  const is_valid_grounding_args = (
  	args: any,
  ): args is GroundingOptions =>
  	typeof args === 'object' &&
  	args !== null &&
  	typeof args.statement === 'string' &&
  	args.statement.trim() !== '' &&
  	(args.references === undefined ||
  		(Array.isArray(args.references) &&
  			args.references.every((ref: string) => typeof ref === 'string'))) &&
  	(args.no_cache === undefined || typeof args.no_cache === 'boolean');

• src/index.ts:28-48 (schema)

  TypeScript interfaces defining the input (GroundingOptions) and output (GroundingResponse, GroundingReference) structures for the ground_statement tool.

  interface GroundingReference {
  	url: string; // Source URL
  	keyQuote: string; // Supporting quote from the source
  	isSupportive: boolean; // Whether the reference supports or contradicts the statement
  }
  
  interface GroundingResponse {
  	factuality: number; // Score between 0-1 indicating confidence
  	result: boolean; // True if statement is verified as factual
  	reason: string; // Explanation of the verification result
  	references: GroundingReference[]; // Supporting/contradicting sources (up to 30)
  	usage: {
  		tokens: number; // Number of tokens processed
  	};
  }
  
  interface GroundingOptions {
  	statement: string; // Statement to verify
  	references?: string[]; // Optional list of URLs to restrict search to
  	no_cache?: boolean; // Whether to bypass cache for fresh results
  }