@youdotcom-oss/mcp 1.5.0 → 1.6.0

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

@@ -1,122 +1,43 @@
-import { describe, expect, setDefaultTimeout, test } from 'bun:test';
-import type { ExpressAgentMcpResponse } from '../express.schemas.ts';
-import { callExpressAgent, formatExpressAgentResponse } from '../express.utils.ts';
+import { describe, expect, setDefaultTimeout, test } from 'bun:test'
+import type { ExpressAgentMcpResponse } from '@youdotcom-oss/api'
+import { formatExpressAgentResponse } from '../express.utils.ts'
 
-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');
-    },
-    { 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 },
-  );
-});
+setDefaultTimeout(20_000)
 
 describe('formatExpressAgentResponse', () => {
   test('formats response with answer only (no search results)', () => {
     const mockResponse: ExpressAgentMcpResponse = {
       answer: 'The capital of France is Paris.',
       agent: 'express',
-    };
+    }
 
-    const result = formatExpressAgentResponse(mockResponse);
+    const result = formatExpressAgentResponse(mockResponse)
 
     // Verify content array has 1 item (answer only)
-    expect(result).toHaveProperty('content');
-    expect(Array.isArray(result.content)).toBe(true);
-    expect(result.content.length).toBe(1);
+    expect(result).toHaveProperty('content')
+    expect(Array.isArray(result.content)).toBe(true)
+    expect(result.content.length).toBe(1)
 
     // Verify answer content
-    expect(result.content[0]).toHaveProperty('type', 'text');
-    expect(result.content[0]).toHaveProperty('text');
-    expect(result.content[0]?.text).toContain('Express Agent Answer');
-    expect(result.content[0]?.text).toContain('The capital of France is Paris.');
+    expect(result.content[0]).toHaveProperty('type', 'text')
+    expect(result.content[0]).toHaveProperty('text')
+    expect(result.content[0]?.text).toContain('Express Agent Answer')
+    expect(result.content[0]?.text).toContain('The capital of France is Paris.')
 
     // Verify structuredContent is minimal (not full response)
-    expect(result).toHaveProperty('structuredContent');
-    expect(result).toHaveProperty('fullResponse');
-    expect(result.structuredContent).toHaveProperty('answer');
-    expect(result.structuredContent).toHaveProperty('hasResults');
-    expect(result.structuredContent).toHaveProperty('resultCount');
-    expect(result.structuredContent).toHaveProperty('agent');
-    expect(result.structuredContent.answer).toBe(mockResponse.answer);
-    expect(result.structuredContent.hasResults).toBe(false);
-    expect(result.structuredContent.resultCount).toBe(0);
+    expect(result).toHaveProperty('structuredContent')
+    expect(result).toHaveProperty('fullResponse')
+    expect(result.structuredContent).toHaveProperty('answer')
+    expect(result.structuredContent).toHaveProperty('hasResults')
+    expect(result.structuredContent).toHaveProperty('resultCount')
+    expect(result.structuredContent).toHaveProperty('agent')
+    expect(result.structuredContent.answer).toBe(mockResponse.answer)
+    expect(result.structuredContent.hasResults).toBe(false)
+    expect(result.structuredContent.resultCount).toBe(0)
     // No results, so results field should be undefined
-    expect(result.structuredContent.results).toBeUndefined();
-    expect(result.fullResponse).toEqual(mockResponse);
-  });
+    expect(result.structuredContent.results).toBeUndefined()
+    expect(result.fullResponse).toEqual(mockResponse)
+  })
 
   test('formats response with answer and search results', () => {
     const mockResponse: ExpressAgentMcpResponse = {
@@ -136,60 +57,60 @@ describe('formatExpressAgentResponse', () => {
         ],
       },
       agent: 'express',
-    };
+    }
 
-    const result = formatExpressAgentResponse(mockResponse);
+    const result = formatExpressAgentResponse(mockResponse)
 
     // Verify content array has 2 items (answer + search results)
-    expect(result.content.length).toBe(2);
+    expect(result.content.length).toBe(2)
 
     // Verify answer comes FIRST
-    expect(result.content[0]?.type).toBe('text');
-    expect(result.content[0]?.text).toContain('Express Agent Answer');
-    expect(result.content[0]?.text).toContain('Quantum computing is advancing rapidly');
+    expect(result.content[0]?.type).toBe('text')
+    expect(result.content[0]?.text).toContain('Express Agent Answer')
+    expect(result.content[0]?.text).toContain('Quantum computing is advancing rapidly')
 
     // Verify search results come SECOND
-    expect(result.content[1]?.type).toBe('text');
-    expect(result.content[1]?.text).toContain('Search Results');
-    expect(result.content[1]?.text).toContain('Quantum Computing Breakthrough');
-    expect(result.content[1]?.text).toContain('Latest in Quantum Research');
+    expect(result.content[1]?.type).toBe('text')
+    expect(result.content[1]?.text).toContain('Search Results')
+    expect(result.content[1]?.text).toContain('Quantum Computing Breakthrough')
+    expect(result.content[1]?.text).toContain('Latest in Quantum Research')
     // URLs should be in text content
-    expect(result.content[1]?.text).toContain('https://example.com/quantum1');
-    expect(result.content[1]?.text).toContain('https://example.com/quantum2');
+    expect(result.content[1]?.text).toContain('https://example.com/quantum1')
+    expect(result.content[1]?.text).toContain('https://example.com/quantum2')
 
     // Verify structuredContent is minimal with counts
-    expect(result.structuredContent).toHaveProperty('answer');
-    expect(result.structuredContent).toHaveProperty('hasResults');
-    expect(result.structuredContent).toHaveProperty('resultCount');
-    expect(result.structuredContent.answer).toBe(mockResponse.answer);
-    expect(result.structuredContent.hasResults).toBe(true);
-    expect(result.structuredContent.resultCount).toBe(2);
+    expect(result.structuredContent).toHaveProperty('answer')
+    expect(result.structuredContent).toHaveProperty('hasResults')
+    expect(result.structuredContent).toHaveProperty('resultCount')
+    expect(result.structuredContent.answer).toBe(mockResponse.answer)
+    expect(result.structuredContent.hasResults).toBe(true)
+    expect(result.structuredContent.resultCount).toBe(2)
 
     // URLs should be in structuredContent.results
-    expect(result.structuredContent).toHaveProperty('results');
-    expect(result.structuredContent.results?.web).toBeDefined();
-    expect(result.structuredContent.results?.web?.length).toBe(2);
+    expect(result.structuredContent).toHaveProperty('results')
+    expect(result.structuredContent.results?.web).toBeDefined()
+    expect(result.structuredContent.results?.web?.length).toBe(2)
     expect(result.structuredContent.results?.web?.[0]).toEqual({
       url: 'https://example.com/quantum1',
       title: 'Quantum Computing Breakthrough',
-    });
+    })
     expect(result.structuredContent.results?.web?.[1]).toEqual({
       url: 'https://example.com/quantum2',
       title: 'Latest in Quantum Research',
-    });
+    })
 
     // Verify fullResponse has complete data
-    expect(result.fullResponse).toEqual(mockResponse);
-    expect(result.fullResponse.results?.web).toHaveLength(2);
-  });
+    expect(result.fullResponse).toEqual(mockResponse)
+    expect(result.fullResponse.results?.web).toHaveLength(2)
+  })
 
   test('structuredContent validation for answer only', () => {
     const mockResponse: ExpressAgentMcpResponse = {
       answer: 'Neural networks are computational models inspired by biological neurons.',
       agent: 'express',
-    };
+    }
 
-    const result = formatExpressAgentResponse(mockResponse);
+    const result = formatExpressAgentResponse(mockResponse)
 
     // Verify structure matches minimal schema
     expect(result.structuredContent).toMatchObject({
@@ -197,11 +118,11 @@ describe('formatExpressAgentResponse', () => {
       hasResults: false,
       resultCount: 0,
       agent: 'express',
-    });
+    })
 
     // Verify fullResponse has complete data
-    expect(result.fullResponse.results).toBeUndefined();
-  });
+    expect(result.fullResponse.results).toBeUndefined()
+  })
 
   test('structuredContent validation for answer with results', () => {
     const mockResponse: ExpressAgentMcpResponse = {
@@ -216,41 +137,41 @@ describe('formatExpressAgentResponse', () => {
         ],
       },
       agent: 'express',
-    };
+    }
 
-    const result = formatExpressAgentResponse(mockResponse);
+    const result = formatExpressAgentResponse(mockResponse)
 
     // Verify structuredContent is minimal with counts
-    expect(result.structuredContent).toHaveProperty('answer');
-    expect(result.structuredContent).toHaveProperty('hasResults');
-    expect(result.structuredContent).toHaveProperty('resultCount');
-    expect(result.structuredContent).toHaveProperty('agent');
+    expect(result.structuredContent).toHaveProperty('answer')
+    expect(result.structuredContent).toHaveProperty('hasResults')
+    expect(result.structuredContent).toHaveProperty('resultCount')
+    expect(result.structuredContent).toHaveProperty('agent')
     expect(result.structuredContent.answer).toBe(
       'Recent AI breakthroughs include advances in language models and computer vision.',
-    );
-    expect(result.structuredContent.agent).toBe('express');
-    expect(result.structuredContent.hasResults).toBe(true);
-    expect(result.structuredContent.resultCount).toBe(1);
+    )
+    expect(result.structuredContent.agent).toBe('express')
+    expect(result.structuredContent.hasResults).toBe(true)
+    expect(result.structuredContent.resultCount).toBe(1)
 
     // URLs should be in structuredContent.results
-    expect(result.structuredContent).toHaveProperty('results');
-    expect(result.structuredContent.results?.web).toBeDefined();
-    expect(result.structuredContent.results?.web?.length).toBe(1);
+    expect(result.structuredContent).toHaveProperty('results')
+    expect(result.structuredContent.results?.web).toBeDefined()
+    expect(result.structuredContent.results?.web?.length).toBe(1)
     expect(result.structuredContent.results?.web?.[0]).toEqual({
       url: 'https://example.com/ai-breakthrough',
       title: 'AI Breakthrough 2025',
-    });
+    })
 
     // Verify fullResponse has complete search results
-    expect(result.fullResponse).toEqual(mockResponse);
-    expect(result.fullResponse.results).toBeDefined();
-    expect(Array.isArray(result.fullResponse.results?.web)).toBe(true);
-    expect(result.fullResponse.results?.web.length).toBe(1);
+    expect(result.fullResponse).toEqual(mockResponse)
+    expect(result.fullResponse.results).toBeDefined()
+    expect(Array.isArray(result.fullResponse.results?.web)).toBe(true)
+    expect(result.fullResponse.results?.web.length).toBe(1)
 
     // Verify search result fields in fullResponse
-    const searchResult = result.fullResponse.results?.web[0];
-    expect(searchResult?.url).toBe('https://example.com/ai-breakthrough');
-    expect(searchResult?.title).toBe('AI Breakthrough 2025');
-    expect(searchResult?.snippet).toBe('Major advances in artificial intelligence.');
-  });
-});
+    const searchResult = result.fullResponse.results?.web[0]
+    expect(searchResult?.url).toBe('https://example.com/ai-breakthrough')
+    expect(searchResult?.title).toBe('AI Breakthrough 2025')
+    expect(searchResult?.snippet).toBe('Major advances in artificial intelligence.')
+  })
+})

package/src/get-mcp-server.ts

@@ -1,5 +1,5 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import packageJson from '../package.json' with { type: 'json' };
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import packageJson from '../package.json' with { type: 'json' }
 
 export const getMCpServer = () =>
   new McpServer(
@@ -14,4 +14,4 @@ export const getMCpServer = () =>
       },
       instructions: `Use this server to search the web, get AI-powered answers with web context, and extract content from web pages using You.com. The you-contents tool extracts page content and returns it in markdown or HTML format. Use HTML format for layout preservation, interactive content, and visual fidelity; use markdown for text extraction and simpler consumption.`,
     },
-  );
+  )

package/src/http.ts

@@ -1,61 +1,61 @@
-import { StreamableHTTPTransport } from '@hono/mcp';
-import { type Context, Hono } from 'hono';
-import { trimTrailingSlash } from 'hono/trailing-slash';
-import packageJson from '../package.json' with { type: 'json' };
-import { registerContentsTool } from './contents/register-contents-tool.ts';
-import { registerExpressTool } from './express/register-express-tool.ts';
-import { getMCpServer } from './get-mcp-server.ts';
-import { registerSearchTool } from './search/register-search-tool.ts';
-import { useGetClientVersion } from './shared/use-client-version.ts';
+import { StreamableHTTPTransport } from '@hono/mcp'
+import { type Context, Hono } from 'hono'
+import { trimTrailingSlash } from 'hono/trailing-slash'
+import packageJson from '../package.json' with { type: 'json' }
+import { registerContentsTool } from './contents/register-contents-tool.ts'
+import { registerExpressTool } from './express/register-express-tool.ts'
+import { getMCpServer } from './get-mcp-server.ts'
+import { registerSearchTool } from './search/register-search-tool.ts'
+import { useGetClientVersion } from './shared/use-client-version.ts'
 
 const extractBearerToken = (authHeader: string | null): string | null => {
   if (!authHeader || !authHeader.startsWith('Bearer ')) {
-    return null;
+    return null
   }
-  return authHeader.slice(7);
-};
+  return authHeader.slice(7)
+}
 
 const handleMcpRequest = async (c: Context) => {
-  const authHeader = c.req.header('Authorization');
+  const authHeader = c.req.header('Authorization')
 
   if (!authHeader) {
-    c.status(401);
-    c.header('Content-Type', 'text/plain');
-    return c.text('Unauthorized: Authorization header required');
+    c.status(401)
+    c.header('Content-Type', 'text/plain')
+    return c.text('Unauthorized: Authorization header required')
   }
 
-  const YDC_API_KEY = extractBearerToken(authHeader);
+  const YDC_API_KEY = extractBearerToken(authHeader)
 
   if (!YDC_API_KEY) {
-    c.status(401);
-    c.header('Content-Type', 'text/plain');
-    return c.text('Unauthorized: Bearer token required');
+    c.status(401)
+    c.header('Content-Type', 'text/plain')
+    return c.text('Unauthorized: Bearer token required')
   }
-  const mcp = getMCpServer();
-  const getUserAgent = useGetClientVersion(mcp);
+  const mcp = getMCpServer()
+  const getUserAgent = useGetClientVersion(mcp)
 
   registerSearchTool({
     mcp,
     YDC_API_KEY,
     getUserAgent,
-  });
-  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent });
-  registerContentsTool({ mcp, YDC_API_KEY, getUserAgent });
+  })
+  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent })
+  registerContentsTool({ mcp, YDC_API_KEY, getUserAgent })
 
-  const transport = new StreamableHTTPTransport();
-  await mcp.connect(transport);
-  const response = await transport.handleRequest(c);
+  const transport = new StreamableHTTPTransport()
+  await mcp.connect(transport)
+  const response = await transport.handleRequest(c)
 
   // Explicitly set Content-Encoding to 'identity' to prevent httpx auto-decompression issues
   // httpx by default sends Accept-Encoding and attempts decompression, but MCP SSE streams
   // are not compressed. Setting 'identity' tells clients the response is uncompressed.
-  response?.headers.set('Content-Encoding', 'identity');
+  response?.headers.set('Content-Encoding', 'identity')
 
-  return response;
-};
+  return response
+}
 
-const app = new Hono();
-app.use(trimTrailingSlash());
+const app = new Hono()
+app.use(trimTrailingSlash())
 
 app.get('/mcp-health', async (c) => {
   return c.json({
@@ -63,10 +63,10 @@ app.get('/mcp-health', async (c) => {
     timestamp: new Date().toISOString(),
     version: packageJson.version,
     service: 'youdotcom-mcp-server',
-  });
-});
+  })
+})
 
-app.all('/mcp', handleMcpRequest);
-app.all('/mcp/', handleMcpRequest);
+app.all('/mcp', handleMcpRequest)
+app.all('/mcp/', handleMcpRequest)
 
-export default app;
+export default app

package/src/search/register-search-tool.ts

@@ -1,17 +1,17 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { generateErrorReportLink } from '../shared/generate-error-report-link.ts';
-import { getLogger } from '../shared/get-logger.ts';
-import { SearchQuerySchema, SearchStructuredContentSchema } from './search.schemas.ts';
-import { fetchSearchResults, formatSearchResults } from './search.utils.ts';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { fetchSearchResults, generateErrorReportLink, SearchQuerySchema } from '@youdotcom-oss/api'
+import { getLogger } from '../shared/get-logger.ts'
+import { SearchStructuredContentSchema } from './search.schema.ts'
+import { formatSearchResults } from './search.utils.ts'
 
 export const registerSearchTool = ({
   mcp,
   YDC_API_KEY,
   getUserAgent,
 }: {
-  mcp: McpServer;
-  YDC_API_KEY?: string;
-  getUserAgent: () => string;
+  mcp: McpServer
+  YDC_API_KEY?: string
+  getUserAgent: () => string
 }) => {
   mcp.registerTool(
     'you-search',
@@ -22,22 +22,22 @@ export const registerSearchTool = ({
       outputSchema: SearchStructuredContentSchema.shape,
     },
     async (searchQuery) => {
-      const logger = getLogger(mcp);
+      const logger = getLogger(mcp)
       try {
         const response = await fetchSearchResults({
           searchQuery,
           YDC_API_KEY,
           getUserAgent,
-        });
+        })
 
-        const webCount = response.results.web?.length ?? 0;
-        const newsCount = response.results.news?.length ?? 0;
+        const webCount = response.results.web?.length ?? 0
+        const newsCount = response.results.news?.length ?? 0
 
         if (!webCount && !newsCount) {
           await logger({
             level: 'info',
             data: `No results found for query: "${searchQuery.query}"`,
-          });
+          })
 
           return {
             content: [{ type: 'text' as const, text: 'No results found.' }],
@@ -48,28 +48,28 @@ export const registerSearchTool = ({
                 total: 0,
               },
             },
-          };
+          }
         }
 
         await logger({
           level: 'info',
           data: `Search successful for query: "${searchQuery.query}" - ${webCount} web results, ${newsCount} news results (${webCount + newsCount} total)`,
-        });
+        })
 
-        const { content, structuredContent } = formatSearchResults(response);
-        return { content, structuredContent };
+        const { content, structuredContent } = formatSearchResults(response)
+        return { content, structuredContent }
       } catch (err: unknown) {
-        const errorMessage = err instanceof Error ? err.message : String(err);
+        const errorMessage = err instanceof Error ? err.message : String(err)
         const reportLink = generateErrorReportLink({
           errorMessage,
           tool: 'you-search',
           clientInfo: getUserAgent(),
-        });
+        })
 
         await logger({
           level: 'error',
           data: `Search API call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
-        });
+        })
 
         return {
           content: [
@@ -80,8 +80,8 @@ export const registerSearchTool = ({
           ],
           structuredContent: undefined,
           isError: true,
-        };
+        }
       }
     },
-  );
-};
+  )
+}

package/src/search/search.schema.ts

@@ -0,0 +1,38 @@
+import * as z from 'zod'
+
+// Minimal schema for structuredContent (reduces payload duplication)
+// 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'),
+    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'),
+            page_age: z.string().optional().describe('Publication timestamp'),
+          }),
+        )
+        .optional()
+        .describe('Web results'),
+      news: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+            page_age: z.string().describe('Publication timestamp'),
+          }),
+        )
+        .optional()
+        .describe('News results'),
+    })
+    .optional()
+    .describe('Search results'),
+})
+
+export type SearchStructuredContent = z.infer<typeof SearchStructuredContentSchema>