@youdotcom-oss/mcp 1.3.7 → 1.3.9

package/src/contents/tests/contents.utils.spec.ts

@@ -7,63 +7,75 @@ const getUserAgent = () => 'MCP/test (You.com; test-client)';
 // NOTE: The following tests require a You.com API key with access to the Contents API
 // Using example.com/example.org as test URLs since You.com blocks self-scraping
 describe('fetchContents', () => {
-  test('returns valid response structure for single URL', async () => {
-    const result = await fetchContents({
-      contentsQuery: {
-        urls: ['https://documentation.you.com/developer-resources/mcp-server'],
-        format: 'markdown',
-      },
-      getUserAgent,
-    });
-
-    expect(Array.isArray(result)).toBe(true);
-    expect(result.length).toBeGreaterThan(0);
-
-    const firstItem = result[0];
-    expect(firstItem).toBeDefined();
-
-    // Should have markdown content
-    expect(firstItem?.markdown).toBeDefined();
-    expect(typeof firstItem?.markdown).toBe('string');
-  });
-
-  test('handles multiple URLs', async () => {
-    const result = await fetchContents({
-      contentsQuery: {
-        urls: [
-          'https://documentation.you.com/developer-resources/mcp-server',
-          'https://documentation.you.com/developer-resources/python-sdk',
-        ],
-        format: 'markdown',
-      },
-      getUserAgent,
-    });
-
-    expect(Array.isArray(result)).toBe(true);
-    expect(result.length).toBe(2);
-
-    for (const item of result) {
-      expect(item).toHaveProperty('url');
-      expect(item.markdown).toBeDefined();
-    }
-  });
-
-  test('handles html format', async () => {
-    const result = await fetchContents({
-      contentsQuery: {
-        urls: ['https://documentation.you.com/developer-resources/mcp-server'],
-        format: 'html',
-      },
-      getUserAgent,
-    });
-
-    expect(Array.isArray(result)).toBe(true);
-    const firstItem = result[0];
-    expect(firstItem).toBeDefined();
-
-    expect(firstItem?.html).toBeDefined();
-    expect(typeof firstItem?.html).toBe('string');
-  });
+  test(
+    'returns valid response structure for single URL',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+          format: 'markdown',
+        },
+        getUserAgent,
+      });
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBeGreaterThan(0);
+
+      const firstItem = result[0];
+      expect(firstItem).toBeDefined();
+
+      // Should have markdown content
+      expect(firstItem?.markdown).toBeDefined();
+      expect(typeof firstItem?.markdown).toBe('string');
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'handles multiple URLs',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: [
+            'https://documentation.you.com/developer-resources/mcp-server',
+            'https://documentation.you.com/developer-resources/python-sdk',
+          ],
+          format: 'markdown',
+        },
+        getUserAgent,
+      });
+
+      expect(Array.isArray(result)).toBe(true);
+      expect(result.length).toBe(2);
+
+      for (const item of result) {
+        expect(item).toHaveProperty('url');
+        expect(item.markdown).toBeDefined();
+      }
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'handles html format',
+    async () => {
+      const result = await fetchContents({
+        contentsQuery: {
+          urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+          format: 'html',
+        },
+        getUserAgent,
+      });
+
+      expect(Array.isArray(result)).toBe(true);
+      const firstItem = result[0];
+      expect(firstItem).toBeDefined();
+
+      expect(firstItem?.html).toBeDefined();
+      expect(typeof firstItem?.html).toBe('string');
+    },
+    { retry: 2 },
+  );
 });
 
 describe('formatContentsResponse', () => {

package/src/express/express.utils.ts

@@ -1,3 +1,4 @@
+import { EXPRESS_API_URL } from '../shared/api-constants.ts';
 import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
 import { formatSearchResultsText } from '../shared/format-search-results-text.ts';
 import {
@@ -7,9 +8,6 @@ import {
   type ExpressAgentMcpResponse,
 } from './express.schemas.ts';
 
-// Express Agent Constants
-const AGENTS_RUN_URL = 'https://api.you.com/v1/agents/runs';
-
 /**
  * Checks response status and throws appropriate errors for agent API calls
  */
@@ -70,7 +68,7 @@ export const callExpressAgent = async ({
     body: JSON.stringify(requestBody),
   };
 
-  const response = await fetch(AGENTS_RUN_URL, options);
+  const response = await fetch(EXPRESS_API_URL, options);
 
   if (!response.ok) {
     await agentThrowOnFailedStatus(response);

package/src/express/tests/express.utils.spec.ts

@@ -7,68 +7,80 @@ const getUserAgent = () => 'MCP/test (You.com; test-client)';
 setDefaultTimeout(20_000);
 
 describe('callExpressAgent', () => {
-  test('returns answer only (WITHOUT web_search tools)', async () => {
-    const result = await callExpressAgent({
-      agentInput: { input: 'What is machine learning?' },
-      getUserAgent,
-    });
-
-    // Verify MCP response structure
-    expect(result).toHaveProperty('answer');
-    expect(typeof result.answer).toBe('string');
-    expect(result.answer.length).toBeGreaterThan(0);
-
-    // Should NOT have results when web_search is not used
-    expect(result.results).toBeUndefined();
-
-    expect(result.agent).toBe('express');
-  });
-
-  test('returns answer and search results (WITH web_search tools)', async () => {
-    const result = await callExpressAgent({
-      agentInput: {
-        input: 'Latest developments in quantum computing',
-        tools: [{ type: 'web_search' }],
-      },
-      getUserAgent,
-    });
-
-    // Verify MCP response has both answer and results
-    expect(result).toHaveProperty('answer');
-    expect(typeof result.answer).toBe('string');
-    expect(result.answer.length).toBeGreaterThan(0);
-
-    expect(result).toHaveProperty('results');
-    expect(result.results).toHaveProperty('web');
-    expect(Array.isArray(result.results?.web)).toBe(true);
-    expect(result.results?.web.length).toBeGreaterThan(0);
-
-    // Verify each search result has required fields
-    const firstResult = result.results?.web[0];
-    expect(firstResult).toHaveProperty('url');
-    expect(firstResult).toHaveProperty('title');
-    expect(firstResult).toHaveProperty('snippet');
-    expect(typeof firstResult?.url).toBe('string');
-    expect(typeof firstResult?.title).toBe('string');
-    expect(typeof firstResult?.snippet).toBe('string');
-    expect(firstResult?.url.length).toBeGreaterThan(0);
-    expect(firstResult?.title.length).toBeGreaterThan(0);
-
-    expect(result.agent).toBe('express');
-  }, 30000);
-
-  test('works without optional parameters', async () => {
-    const result = await callExpressAgent({
-      agentInput: { input: 'What is the capital of France?' },
-      getUserAgent,
-      // No progressToken or sendProgress provided
-    });
-
-    // Should work normally without progress tracking
-    expect(result).toHaveProperty('answer');
-    expect(result.answer.length).toBeGreaterThan(0);
-    expect(result.agent).toBe('express');
-  });
+  test(
+    'returns answer only (WITHOUT web_search tools)',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: { input: 'What is machine learning?' },
+        getUserAgent,
+      });
+
+      // Verify MCP response structure
+      expect(result).toHaveProperty('answer');
+      expect(typeof result.answer).toBe('string');
+      expect(result.answer.length).toBeGreaterThan(0);
+
+      // Should NOT have results when web_search is not used
+      expect(result.results).toBeUndefined();
+
+      expect(result.agent).toBe('express');
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'returns answer and search results (WITH web_search tools)',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: {
+          input: 'Latest developments in quantum computing',
+          tools: [{ type: 'web_search' }],
+        },
+        getUserAgent,
+      });
+
+      // Verify MCP response has both answer and results
+      expect(result).toHaveProperty('answer');
+      expect(typeof result.answer).toBe('string');
+      expect(result.answer.length).toBeGreaterThan(0);
+
+      expect(result).toHaveProperty('results');
+      expect(result.results).toHaveProperty('web');
+      expect(Array.isArray(result.results?.web)).toBe(true);
+      expect(result.results?.web.length).toBeGreaterThan(0);
+
+      // Verify each search result has required fields
+      const firstResult = result.results?.web[0];
+      expect(firstResult).toHaveProperty('url');
+      expect(firstResult).toHaveProperty('title');
+      expect(firstResult).toHaveProperty('snippet');
+      expect(typeof firstResult?.url).toBe('string');
+      expect(typeof firstResult?.title).toBe('string');
+      expect(typeof firstResult?.snippet).toBe('string');
+      expect(firstResult?.url.length).toBeGreaterThan(0);
+      expect(firstResult?.title.length).toBeGreaterThan(0);
+
+      expect(result.agent).toBe('express');
+    },
+    { timeout: 30_000, retry: 2 },
+  );
+
+  test(
+    'works without optional parameters',
+    async () => {
+      const result = await callExpressAgent({
+        agentInput: { input: 'What is the capital of France?' },
+        getUserAgent,
+        // No progressToken or sendProgress provided
+      });
+
+      // Should work normally without progress tracking
+      expect(result).toHaveProperty('answer');
+      expect(result.answer.length).toBeGreaterThan(0);
+      expect(result.agent).toBe('express');
+    },
+    { retry: 2 },
+  );
 });
 
 describe('formatExpressAgentResponse', () => {

package/src/main.ts

@@ -0,0 +1,9 @@
+export * from './contents/contents.schemas.ts';
+export * from './contents/contents.utils.ts';
+export * from './express/express.schemas.ts';
+export * from './express/express.utils.ts';
+export * from './search/search.schemas.ts';
+export * from './search/search.utils.ts';
+export * from './shared/api-constants.ts';
+export * from './shared/check-response-for-errors.ts';
+export * from './shared/format-search-results-text.ts';

package/src/search/search.schemas.ts

@@ -2,8 +2,8 @@ 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'),
+  count: z.number().int().min(1).max(100).optional().describe('Max results per section'),
+  freshness: z.string().optional().describe('day/week/month/year or YYYY-MM-DDtoYYYY-MM-DD'),
   offset: z.number().int().min(0).max(9).optional().describe('Pagination offset'),
   country: z
     .enum([
@@ -52,6 +52,8 @@ export const SearchQuerySchema = z.object({
   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)'),
+  livecrawl: z.enum(['web', 'news', 'all']).optional().describe('Live-crawl sections for full content'),
+  livecrawl_formats: z.enum(['html', 'markdown']).optional().describe('Format for crawled content'),
 });
 
 export type SearchQuery = z.infer<typeof SearchQuerySchema>;
@@ -63,6 +65,15 @@ const WebResultSchema = z.object({
   snippets: z.array(z.string()).describe('Content snippets'),
   page_age: z.string().optional().describe('Publication timestamp'),
   authors: z.array(z.string()).optional().describe('Authors'),
+  thumbnail_url: z.string().optional().describe('Thumbnail image URL'),
+  favicon_url: z.string().optional().describe('Favicon URL'),
+  contents: z
+    .object({
+      html: z.string().optional().describe('Full HTML content'),
+      markdown: z.string().optional().describe('Full Markdown content'),
+    })
+    .optional()
+    .describe('Live-crawled page content'),
 });
 
 const NewsResultSchema = z.object({
@@ -70,12 +81,20 @@ const NewsResultSchema = z.object({
   description: z.string().describe('Description'),
   page_age: z.string().describe('Publication timestamp'),
   url: z.string().describe('URL'),
+  thumbnail_url: z.string().optional().describe('Thumbnail image URL'),
+  contents: z
+    .object({
+      html: z.string().optional().describe('Full HTML content'),
+      markdown: z.string().optional().describe('Full Markdown content'),
+    })
+    .optional()
+    .describe('Live-crawled page content'),
 });
 
 export type NewsResult = z.infer<typeof NewsResultSchema>;
 
 const MetadataSchema = z.object({
-  request_uuid: z.string().optional().describe('Request ID'),
+  search_uuid: z.string().optional().describe('Unique search request ID'),
   query: z.string().describe('Query'),
   latency: z.number().describe('Latency in seconds'),
 });
@@ -91,7 +110,7 @@ export const SearchResponseSchema = z.object({
 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
+// Excludes metadata (query, search_uuid, latency) as these are not actionable by LLM
 export const SearchStructuredContentSchema = z.object({
   resultCounts: z.object({
     web: z.number().describe('Web results'),

package/src/search/search.utils.ts

@@ -1,3 +1,4 @@
+import { SEARCH_API_URL } from '../shared/api-constants.ts';
 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';
@@ -11,14 +12,14 @@ export const fetchSearchResults = async ({
   YDC_API_KEY?: string;
   getUserAgent: () => string;
 }) => {
-  const url = new URL('https://ydc-index.io/v1/search');
+  const url = new URL(SEARCH_API_URL);
 
   const searchParams = new URLSearchParams();
 
   // Build Query Param
   const searchQuery = [query];
   site && searchQuery.push(`site:${site}`);
-  fileType && searchQuery.push(`fileType:${fileType}`);
+  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');

package/src/search/tests/search.utils.spec.ts

@@ -5,67 +5,135 @@ import { fetchSearchResults, formatSearchResults } from '../search.utils.ts';
 const getUserAgent = () => 'MCP/test (You.com; test-client)';
 
 describe('fetchSearchResults', () => {
-  test('returns valid response structure for basic query', async () => {
-    const result = await fetchSearchResults({
-      searchQuery: { query: 'latest stock news' },
-      getUserAgent,
-    });
+  test(
+    'returns valid response structure for basic query',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: { query: 'latest stock news' },
+        getUserAgent,
+      });
 
-    expect(result).toHaveProperty('results');
-    expect(result).toHaveProperty('metadata');
-    expect(result.results).toHaveProperty('web');
-    expect(result.results).toHaveProperty('news');
-    expect(Array.isArray(result.results.web)).toBe(true);
-    expect(Array.isArray(result.results.news)).toBe(true);
+      expect(result).toHaveProperty('results');
+      expect(result).toHaveProperty('metadata');
+      expect(result.results).toHaveProperty('web');
+      expect(result.results).toHaveProperty('news');
+      expect(Array.isArray(result.results.web)).toBe(true);
+      expect(Array.isArray(result.results.news)).toBe(true);
 
-    // Assert required metadata fields
-    expect(typeof result.metadata?.query).toBe('string');
+      // Assert required metadata fields
+      expect(typeof result.metadata?.query).toBe('string');
 
-    // Optional fields: only assert type if present
-    if (result.metadata?.request_uuid !== undefined) {
-      expect(typeof result.metadata.request_uuid).toBe('string');
-    }
-  });
+      // search_uuid is optional but should be string if present
+      expect(result.metadata?.search_uuid).toBeDefined();
+      expect(typeof result.metadata?.search_uuid).toBe('string');
+    },
+    { retry: 2 },
+  );
 
-  test('handles search with filters', async () => {
-    const result = await fetchSearchResults({
-      searchQuery: {
-        query: 'javascript tutorial',
-        count: 3,
-        freshness: 'week',
-        country: 'US',
-      },
-      getUserAgent,
-    });
+  test(
+    'handles search with filters',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'javascript tutorial',
+          count: 3,
+          freshness: 'week',
+          country: 'US',
+        },
+        getUserAgent,
+      });
 
-    expect(result.results.web?.length).toBeLessThanOrEqual(3);
-    expect(result.metadata?.query).toContain('javascript tutorial');
-  });
+      expect(result.results.web?.length).toBeLessThanOrEqual(3);
+      expect(result.metadata?.query).toContain('javascript tutorial');
+    },
+    { retry: 2 },
+  );
 
-  test('validates response schema', async () => {
-    const result = await fetchSearchResults({
-      searchQuery: { query: 'latest technology news' },
-      getUserAgent,
-    });
+  test(
+    'validates response schema',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: { query: 'latest technology news' },
+        getUserAgent,
+      });
 
-    // Test that web results have required properties
-    // biome-ignore lint/style/noNonNullAssertion: Test
-    const webResult = result.results.web![0];
-
-    expect(webResult).toHaveProperty('url');
-    expect(webResult).toHaveProperty('title');
-    expect(webResult).toHaveProperty('description');
-    expect(webResult).toHaveProperty('snippets');
-    expect(Array.isArray(webResult?.snippets)).toBe(true);
-
-    // Test that news results have required properties
-    // biome-ignore lint/style/noNonNullAssertion: Test
-    const newsResult = result.results.news![0];
-    expect(newsResult).toHaveProperty('url');
-    expect(newsResult).toHaveProperty('title');
-    expect(newsResult).toHaveProperty('description');
-    expect(newsResult).toHaveProperty('page_age');
-  });
+      // Test that web results have required properties
+      // biome-ignore lint/style/noNonNullAssertion: Test
+      const webResult = result.results.web![0];
+
+      expect(webResult).toHaveProperty('url');
+      expect(webResult).toHaveProperty('title');
+      expect(webResult).toHaveProperty('description');
+      expect(webResult).toHaveProperty('snippets');
+      expect(Array.isArray(webResult?.snippets)).toBe(true);
+
+      // Test that news results have required properties
+      // biome-ignore lint/style/noNonNullAssertion: Test
+      const newsResult = result.results.news![0];
+      expect(newsResult).toHaveProperty('url');
+      expect(newsResult).toHaveProperty('title');
+      expect(newsResult).toHaveProperty('description');
+      expect(newsResult).toHaveProperty('page_age');
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'handles livecrawl parameters',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'python tutorial',
+          count: 2,
+          livecrawl: 'web',
+          livecrawl_formats: 'markdown',
+        },
+        getUserAgent,
+      });
+
+      expect(result.results.web?.length).toBeLessThanOrEqual(2);
+      // Livecrawl should return contents field (fails naturally if not present)
+      expect(result.results.web?.[0]).toHaveProperty('contents');
+      expect(result.results.web?.[0]?.contents).toHaveProperty('markdown');
+      expect(typeof result.results.web?.[0]?.contents?.markdown).toBe('string');
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'handles freshness date ranges',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'AI news',
+          freshness: '2024-01-01to2024-12-31',
+          count: 3,
+        },
+        getUserAgent,
+      });
+
+      expect(result).toHaveProperty('results');
+      expect(result.metadata?.query).toContain('AI news');
+    },
+    { retry: 2 },
+  );
+
+  test(
+    'handles count greater than 20',
+    async () => {
+      const result = await fetchSearchResults({
+        searchQuery: {
+          query: 'machine learning',
+          count: 50,
+        },
+        getUserAgent,
+      });
+
+      expect(result.results.web?.length).toBeGreaterThan(0);
+      expect(result.results.web?.length).toBeLessThanOrEqual(50);
+    },
+    { retry: 2 },
+  );
 });
 
 describe('formatSearchResults', () => {
@@ -85,7 +153,7 @@ describe('formatSearchResults', () => {
         news: [],
       },
       metadata: {
-        request_uuid: 'test-uuid',
+        search_uuid: 'test-uuid',
         query: 'test query',
         latency: 0.1,
       },
@@ -132,7 +200,7 @@ describe('formatSearchResults', () => {
         ],
       },
       metadata: {
-        request_uuid: 'test-uuid',
+        search_uuid: 'test-uuid',
         query: 'test query',
         latency: 0.1,
       },
@@ -182,7 +250,7 @@ describe('formatSearchResults', () => {
         ],
       },
       metadata: {
-        request_uuid: 'test-uuid',
+        search_uuid: 'test-uuid',
         query: 'test query',
         latency: 0.1,
       },

package/src/shared/api-constants.ts

@@ -0,0 +1,10 @@
+/**
+ * You.com API endpoints
+ *
+ * These constants define the base URLs for You.com's APIs.
+ * Exported for use in tests and external packages.
+ */
+
+export const SEARCH_API_URL = 'https://ydc-index.io/v1/search';
+export const EXPRESS_API_URL = 'https://api.you.com/v1/agents/runs';
+export const CONTENTS_API_URL = 'https://ydc-index.io/v1/contents';