@youdotcom-oss/mcp 1.3.2 → 1.3.3

package/src/search/search.schemas.ts

@@ -0,0 +1,126 @@
+import * as z from 'zod';
+
+export const SearchQuerySchema = z.object({
+  query: z.string().min(1, 'Query is required').describe('Search query (supports +, -, site:, filetype:, lang:)'),
+  count: z.number().int().min(1).max(20).optional().describe('Max results per section'),
+  freshness: z.enum(['day', 'week', 'month', 'year']).optional().describe('Filter by freshness'),
+  offset: z.number().int().min(0).max(9).optional().describe('Pagination offset'),
+  country: z
+    .enum([
+      'AR',
+      'AU',
+      'AT',
+      'BE',
+      'BR',
+      'CA',
+      'CL',
+      'DK',
+      'FI',
+      'FR',
+      'DE',
+      'HK',
+      'IN',
+      'ID',
+      'IT',
+      'JP',
+      'KR',
+      'MY',
+      'MX',
+      'NL',
+      'NZ',
+      'NO',
+      'CN',
+      'PL',
+      'PT',
+      'PH',
+      'RU',
+      'SA',
+      'ZA',
+      'ES',
+      'SE',
+      'CH',
+      'TW',
+      'TR',
+      'GB',
+      'US',
+    ])
+    .optional()
+    .describe('Country code'),
+  safesearch: z.enum(['off', 'moderate', 'strict']).optional().describe('Filter level'),
+  site: z.string().optional().describe('Specific domain'),
+  fileType: z.string().optional().describe('File type'),
+  language: z.string().optional().describe('ISO 639-1 language code'),
+  excludeTerms: z.string().optional().describe('Terms to exclude (pipe-separated)'),
+  exactTerms: z.string().optional().describe('Exact terms (pipe-separated)'),
+});
+
+export type SearchQuery = z.infer<typeof SearchQuerySchema>;
+
+const WebResultSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  snippets: z.array(z.string()).describe('Content snippets'),
+  page_age: z.string().optional().describe('Publication timestamp'),
+  authors: z.array(z.string()).optional().describe('Authors'),
+});
+
+const NewsResultSchema = z.object({
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  page_age: z.string().describe('Publication timestamp'),
+  url: z.string().describe('URL'),
+});
+
+export type NewsResult = z.infer<typeof NewsResultSchema>;
+
+const MetadataSchema = z.object({
+  request_uuid: z.string().optional().describe('Request ID'),
+  query: z.string().describe('Query'),
+  latency: z.number().describe('Latency in seconds'),
+});
+
+export const SearchResponseSchema = z.object({
+  results: z.object({
+    web: z.array(WebResultSchema).optional(),
+    news: z.array(NewsResultSchema).optional(),
+  }),
+  metadata: MetadataSchema.partial(),
+});
+
+export type SearchResponse = z.infer<typeof SearchResponseSchema>;
+
+// Minimal schema for structuredContent (reduces payload duplication)
+// Excludes metadata (query, request_uuid, latency) as these are not actionable by LLM
+export const SearchStructuredContentSchema = z.object({
+  resultCounts: z.object({
+    web: z.number().describe('Web results'),
+    news: z.number().describe('News results'),
+    total: z.number().describe('Total results'),
+  }),
+  results: z
+    .object({
+      web: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+          }),
+        )
+        .optional()
+        .describe('Web results'),
+      news: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+          }),
+        )
+        .optional()
+        .describe('News results'),
+    })
+    .optional()
+    .describe('Search results'),
+});
+
+export type SearchStructuredContent = z.infer<typeof SearchStructuredContentSchema>;

package/src/search/search.utils.ts

@@ -0,0 +1,142 @@
+import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
+import { formatSearchResultsText } from '../shared/format-search-results-text.ts';
+import { type NewsResult, type SearchQuery, type SearchResponse, SearchResponseSchema } from './search.schemas.ts';
+
+export const fetchSearchResults = async ({
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  searchQuery: { query, site, fileType, language, exactTerms, excludeTerms, ...rest },
+  getUserAgent,
+}: {
+  searchQuery: SearchQuery;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}) => {
+  const url = new URL('https://ydc-index.io/v1/search');
+
+  const searchParams = new URLSearchParams();
+
+  // Build Query Param
+  const searchQuery = [query];
+  site && searchQuery.push(`site:${site}`);
+  fileType && searchQuery.push(`fileType:${fileType}`);
+  language && searchQuery.push(`lang:${language}`);
+  if (exactTerms && excludeTerms) {
+    throw new Error('Cannot specify both exactTerms and excludeTerms - please use only one');
+  }
+  exactTerms &&
+    searchQuery.push(
+      exactTerms
+        .split('|')
+        .map((term) => `+${term}`)
+        .join(' AND '),
+    );
+  excludeTerms &&
+    searchQuery.push(
+      excludeTerms
+        .split('|')
+        .map((term) => `-${term}`)
+        .join(' AND '),
+    );
+  searchParams.append('query', searchQuery.join(' '));
+
+  // Append additional advanced Params
+  for (const [name, value] of Object.entries(rest)) {
+    if (value) searchParams.append(name, `${value}`);
+  }
+
+  url.search = searchParams.toString();
+
+  const options = {
+    method: 'GET',
+    headers: new Headers({
+      'X-API-Key': YDC_API_KEY || '',
+      'User-Agent': getUserAgent(),
+    }),
+  };
+
+  const response = await fetch(url, options);
+
+  if (!response.ok) {
+    const errorCode = response.status;
+
+    if (errorCode === 429) {
+      throw new Error('Rate limited by You.com API. Please try again later.');
+    } else if (errorCode === 403) {
+      throw new Error('Forbidden. Please check your You.com API key.');
+    }
+
+    throw new Error(`Failed to perform search. Error code: ${errorCode}`);
+  }
+
+  const results = await response.json();
+
+  // Check for error field in 200 responses (e.g., API limit errors)
+  checkResponseForErrors(results);
+
+  const parsedResults = SearchResponseSchema.parse(results);
+
+  return parsedResults;
+};
+
+export const formatSearchResults = (response: SearchResponse) => {
+  let formattedResults = '';
+
+  // Format web results using shared utility (without URLs in text)
+  if (response.results.web?.length) {
+    const webResults = formatSearchResultsText(response.results.web);
+    formattedResults += `WEB RESULTS:\n\n${webResults}`;
+  }
+
+  // Format news results (without URLs in text)
+  if (response.results.news?.length) {
+    const newsResults = response.results.news
+      .map(
+        (article: NewsResult) =>
+          `Title: ${article.title}\nDescription: ${article.description}\nPublished: ${article.page_age}`,
+      )
+      .join('\n\n---\n\n');
+
+    if (formattedResults) {
+      formattedResults += `\n\n${'='.repeat(50)}\n\n`;
+    }
+    formattedResults += `NEWS RESULTS:\n\n${newsResults}`;
+  }
+
+  // Extract URLs and titles for structuredContent
+  const structuredResults: {
+    web?: Array<{ url: string; title: string }>;
+    news?: Array<{ url: string; title: string }>;
+  } = {};
+
+  if (response.results.web?.length) {
+    structuredResults.web = response.results.web.map((result) => ({
+      url: result.url,
+      title: result.title,
+    }));
+  }
+
+  if (response.results.news?.length) {
+    structuredResults.news = response.results.news.map((article) => ({
+      url: article.url,
+      title: article.title,
+    }));
+  }
+
+  return {
+    content: [
+      {
+        type: 'text' as const,
+        text: `Search Results for "${response.metadata.query}":\n\n${formattedResults}`,
+      },
+    ],
+    structuredContent: {
+      resultCounts: {
+        web: response.results.web?.length || 0,
+        news: response.results.news?.length || 0,
+        total: (response.results.web?.length || 0) + (response.results.news?.length || 0),
+      },
+      results: Object.keys(structuredResults).length > 0 ? structuredResults : undefined,
+    },
+    fullResponse: response,
+  };
+};

package/src/shared/check-response-for-errors.ts

@@ -0,0 +1,13 @@
+/**
+ * Checks if a response object contains an error field and throws if found
+ * Handles API responses that return 200 status but contain error messages
+ * Used by both search and express agent utilities
+ */
+export const checkResponseForErrors = (responseData: unknown) => {
+  if (typeof responseData === 'object' && responseData !== null && 'error' in responseData) {
+    const errorMessage =
+      typeof responseData.error === 'string' ? responseData.error : JSON.stringify(responseData.error);
+    throw new Error(`You.com API Error: ${errorMessage}`);
+  }
+  return responseData;
+};

package/src/shared/format-search-results-text.ts

@@ -0,0 +1,41 @@
+/**
+ * Generic search result type that works for both Search and Express APIs
+ * Used by both search.utils.ts and express.utils.ts
+ */
+type GenericSearchResult = {
+  url: string;
+  title: string;
+  description?: string;
+  snippet?: string;
+  snippets?: string[];
+};
+
+/**
+ * Format array of search results into display text
+ * Used by both search and express agent formatting
+ * @param results - Array of search results to format
+ * @param includeUrls - Whether to include URLs in the text (default: true)
+ */
+export const formatSearchResultsText = (results: GenericSearchResult[]): string => {
+  return results
+    .map((result) => {
+      const parts: string[] = [`Title: ${result.title}`];
+
+      // Add description if present (from Search API)
+      if (result.description) {
+        parts.push(`Description: ${result.description}`);
+      }
+
+      // Handle snippets array (from Search API)
+      if (result.snippets && result.snippets.length > 0) {
+        parts.push(`Snippets:\n- ${result.snippets.join('\n- ')}`);
+      }
+      // Handle single snippet (from Express API)
+      else if (result.snippet) {
+        parts.push(`Snippet: ${result.snippet}`);
+      }
+
+      return parts.join('\n');
+    })
+    .join('\n\n');
+};