@youdotcom-oss/mcp 1.3.8 → 1.3.9-next.1

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.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,7 +12,7 @@ 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();
 

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

@@ -5,113 +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?.search_uuid !== undefined) {
-      expect(typeof result.metadata.search_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];
+      // 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);
+      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 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,
-    });
+  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);
-    // If livecrawl worked, results should have contents field
-    if (result.results.web?.[0]?.contents) {
-      expect(result.results.web[0].contents).toHaveProperty('markdown');
-      expect(typeof result.results.web[0].contents.markdown).toBe('string');
-    }
-  });
+      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,
-    });
+  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');
-  });
+      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,
-    });
+  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);
-  });
+      expect(result.results.web?.length).toBeGreaterThan(0);
+      expect(result.results.web?.length).toBeLessThanOrEqual(50);
+    },
+    { retry: 2 },
+  );
 });
 
 describe('formatSearchResults', () => {

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';

package/src/tests/http.spec.ts

@@ -283,36 +283,40 @@ describe('HTTP MCP Endpoint Basic Functionality', () => {
     expect(text).toContain('42');
   });
 
-  test('mcp server handles search tool request for latest tech news', async () => {
-    const response = await fetch(`${baseUrl}/mcp`, {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        Accept: 'application/json, text/event-stream',
-        Authorization: `Bearer ${testApiKey}`,
-      },
-      body: JSON.stringify({
-        jsonrpc: '2.0',
-        method: 'tools/call',
-        id: 100,
-        params: {
-          name: 'you-search',
-          arguments: {
-            query: 'latest tech news',
-            count: 3,
-          },
+  test(
+    'mcp server handles search tool request for latest tech news',
+    async () => {
+      const response = await fetch(`${baseUrl}/mcp`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Accept: 'application/json, text/event-stream',
+          Authorization: `Bearer ${testApiKey}`,
         },
-      }),
-    });
-
-    expect(response.status).toBe(200);
-    expect(response.headers.get('content-type')).toContain('text/event-stream');
-
-    const text = await response.text();
-    expect(text).toContain('data:');
-    expect(text).toContain('jsonrpc');
-    expect(text).toContain('result');
-    expect(text).toContain('latest tech news');
-    expect(text).toContain('Search Results for');
-  });
+        body: JSON.stringify({
+          jsonrpc: '2.0',
+          method: 'tools/call',
+          id: 100,
+          params: {
+            name: 'you-search',
+            arguments: {
+              query: 'latest tech news',
+              count: 3,
+            },
+          },
+        }),
+      });
+
+      expect(response.status).toBe(200);
+      expect(response.headers.get('content-type')).toContain('text/event-stream');
+
+      const text = await response.text();
+      expect(text).toContain('data:');
+      expect(text).toContain('jsonrpc');
+      expect(text).toContain('result');
+      expect(text).toContain('latest tech news');
+      expect(text).toContain('Search Results for');
+    },
+    { retry: 2 },
+  );
 });