@youdotcom-oss/mcp 3.3.0 → 3.4.0

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

@@ -1,119 +0,0 @@
-import { afterEach, beforeEach, describe, expect, spyOn, test } from 'bun:test'
-import { Client } from '@modelcontextprotocol/sdk/client/index.js'
-import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { SearchResponse } from '@youdotcom-oss/api'
-import * as api from '@youdotcom-oss/api'
-import { registerSearchTool } from '../register-search-tool.ts'
-
-const emptyResponse: SearchResponse = {
-  results: { web: [], news: [] },
-  metadata: { search_uuid: 'test', query: 'test', latency: 0 },
-}
-
-const oneResultResponse: SearchResponse = {
-  results: {
-    web: [
-      {
-        url: 'https://example.com',
-        title: 'Example',
-        description: 'A test result',
-        snippets: ['snippet'],
-        page_age: '2025-01-01T00:00:00',
-        authors: [],
-      },
-    ],
-    news: [],
-  },
-  metadata: { search_uuid: 'test', query: 'test', latency: 0.1 },
-}
-
-let mockFetchResponse: SearchResponse | Error = emptyResponse
-let fetchSearchResultsSpy: ReturnType<typeof spyOn<typeof api, 'fetchSearchResults'>> | undefined
-let generateErrorReportLinkSpy: ReturnType<typeof spyOn<typeof api, 'generateErrorReportLink'>> | undefined
-
-type Cleanup = () => Promise<void>
-
-const setupMcpClient = async (): Promise<{ client: Client; cleanup: Cleanup }> => {
-  const server = new McpServer({ name: 'test', version: '0.0.0' }, { capabilities: { logging: {}, tools: {} } })
-  registerSearchTool({
-    mcp: server,
-    YDC_API_KEY: 'test-key',
-    getUserAgent: () => 'test-agent',
-  })
-
-  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
-  await server.connect(serverTransport)
-
-  const client = new Client({ name: 'test-client', version: '0.0.0' })
-  await client.connect(clientTransport)
-
-  const cleanup = async () => {
-    await client.close()
-    await server.close()
-  }
-
-  return { client, cleanup }
-}
-
-describe('registerSearchTool', () => {
-  let cleanup: Cleanup | undefined
-
-  beforeEach(() => {
-    mockFetchResponse = emptyResponse
-    fetchSearchResultsSpy = spyOn(api, 'fetchSearchResults').mockImplementation(async () => {
-      if (mockFetchResponse instanceof Error) throw mockFetchResponse
-      return mockFetchResponse
-    })
-    generateErrorReportLinkSpy = spyOn(api, 'generateErrorReportLink').mockImplementation(
-      () => 'https://example.com/report',
-    )
-  })
-
-  afterEach(async () => {
-    if (cleanup) {
-      await cleanup()
-      cleanup = undefined
-    }
-    fetchSearchResultsSpy?.mockRestore()
-    fetchSearchResultsSpy = undefined
-    generateErrorReportLinkSpy?.mockRestore()
-    generateErrorReportLinkSpy = undefined
-  })
-
-  test('handles empty search results gracefully', async () => {
-    const result = await setupMcpClient()
-    cleanup = result.cleanup
-
-    const toolResult = await result.client.callTool({ name: 'you-search', arguments: { query: 'nonexistent' } })
-
-    expect(toolResult.content).toEqual([{ type: 'text', text: 'No results found.' }])
-    expect(toolResult.structuredContent).toEqual(emptyResponse)
-  })
-
-  test('returns formatted results for successful search', async () => {
-    mockFetchResponse = oneResultResponse
-    const result = await setupMcpClient()
-    cleanup = result.cleanup
-
-    const toolResult = await result.client.callTool({ name: 'you-search', arguments: { query: 'example' } })
-
-    const text = (toolResult.content as Array<{ type: string; text: string }>)[0]?.text
-    expect(text).toContain('Example')
-    expect(text).toContain('https://example.com')
-
-    expect(toolResult.structuredContent).toEqual(oneResultResponse)
-  })
-
-  test('returns error when API call fails', async () => {
-    mockFetchResponse = new Error('API rate limit exceeded')
-    const result = await setupMcpClient()
-    cleanup = result.cleanup
-
-    const toolResult = await result.client.callTool({ name: 'you-search', arguments: { query: 'test' } })
-
-    expect(toolResult.isError).toBe(true)
-    const text = (toolResult.content as Array<{ type: string; text: string }>)[0]?.text
-    expect(text).toContain('API rate limit exceeded')
-  })
-})

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

@@ -1,192 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import type { SearchResponse } from '@youdotcom-oss/api'
-import { formatSearchResults } from '../search.utils.ts'
-
-describe('formatSearchResults', () => {
-  test('formats web results correctly', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [
-          {
-            url: 'https://example.com',
-            title: 'Test Title',
-            description: 'Test description',
-            snippets: ['snippet 1', 'snippet 2'],
-            page_age: '2023-01-01T00:00:00',
-            authors: ['Author Name'],
-          },
-        ],
-        news: [],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'test query',
-        latency: 0.1,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(Array.isArray(result)).toBe(true)
-    expect(result[0]).toHaveProperty('type', 'text')
-    expect(result[0]).toHaveProperty('text')
-    expect(result[0]?.text).toContain('WEB RESULTS:')
-    expect(result[0]?.text).toContain('Test Title')
-    expect(result[0]?.text).toContain('URL: https://example.com')
-    expect(result[0]?.text).toContain('Published: 2023-01-01T00:00:00')
-  })
-
-  test('formats news results correctly', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [],
-        news: [
-          {
-            title: 'News Title',
-            description: 'News description',
-            page_age: '2023-01-01T00:00:00',
-            url: 'https://news.com/article',
-          },
-        ],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'test query',
-        latency: 0.1,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result[0]?.text).toContain('NEWS RESULTS:')
-    expect(result[0]?.text).toContain('News Title')
-    expect(result[0]?.text).toContain('Published: 2023-01-01T00:00:00')
-    expect(result[0]?.text).toContain('URL: https://news.com/article')
-    expect(result[0]?.text).toContain('Description: News description')
-  })
-
-  test('formats both web and news results', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [
-          {
-            url: 'https://web.com',
-            title: 'Web Title',
-            description: 'Web description',
-            snippets: ['web snippet'],
-            page_age: '2023-01-01T00:00:00',
-            authors: ['Web Author'],
-          },
-        ],
-        news: [
-          {
-            title: 'News Title',
-            description: 'News description',
-            page_age: '2023-01-01T00:00:00',
-            url: 'https://news.com/article',
-          },
-        ],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'test query',
-        latency: 0.1,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result[0]?.text).toContain('WEB RESULTS:')
-    expect(result[0]?.text).toContain('NEWS RESULTS:')
-    expect(result[0]?.text).toContain(`=${'='.repeat(49)}`)
-    expect(result[0]?.text).toContain('URL: https://web.com')
-    expect(result[0]?.text).toContain('URL: https://news.com/article')
-  })
-
-  test('includes page content indicator when livecrawl returns contents', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [
-          {
-            url: 'https://example.com',
-            title: 'Livecrawl Title',
-            description: 'A page with content',
-            snippets: ['snippet'],
-            page_age: '2023-01-01T00:00:00',
-            authors: [],
-            contents: {
-              markdown: 'Full page content in markdown format.',
-              html: '<p>Full page content in HTML format.</p>',
-            },
-          },
-        ],
-        news: [],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'livecrawl test',
-        latency: 0.5,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result[0]?.text).toContain('Page content available:')
-    expect(result[0]?.text).toContain('chars (markdown)')
-    expect(result[0]?.text).toContain('chars (html)')
-  })
-
-  test('omits content indicator when livecrawl contents absent', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [
-          {
-            url: 'https://example.com',
-            title: 'No Content',
-            description: 'A page without livecrawl',
-            snippets: ['snippet'],
-          },
-        ],
-        news: [],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'test',
-        latency: 0.1,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result[0]?.text).not.toContain('Page content available:')
-  })
-
-  test('includes content indicator for news results with livecrawl', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [],
-        news: [
-          {
-            title: 'News with Content',
-            description: 'Breaking news',
-            page_age: '2023-01-01T00:00:00',
-            url: 'https://news.com/article',
-            contents: {
-              markdown: 'Full news article content in markdown.',
-            },
-          },
-        ],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'news livecrawl test',
-        latency: 0.4,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result[0]?.text).toContain('Page content available:')
-    expect(result[0]?.text).toContain('chars (markdown)')
-  })
-})

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

@@ -1,69 +0,0 @@
-/**
- * Generic search result type for Search API results
- * Used by search.utils.ts
- */
-type GenericSearchResult = {
-  url: string
-  title: string
-  description?: string
-  snippet?: string
-  snippets?: string[]
-  page_age?: string
-  contents?: { html?: string; markdown?: string }
-}
-
-/**
- * Format a character count with locale-aware number formatting
- */
-const formatCharCount = (count: number): string => count.toLocaleString()
-
-/**
- * Format array of search results into display text
- * Used by search result formatting
- * @param results - Array of search results to format
- */
-export const formatSearchResultsText = (results: GenericSearchResult[]): string => {
-  return results
-    .map((result) => {
-      const parts: string[] = [`Title: ${result.title}`]
-
-      // Add URL
-      parts.push(`URL: ${result.url}`)
-
-      // Add page age if present
-      if (result.page_age) {
-        parts.push(`Published: ${result.page_age}`)
-      }
-
-      // 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
-      else if (result.snippet) {
-        parts.push(`Snippet: ${result.snippet}`)
-      }
-
-      // Add contents indicator if livecrawl returned page content
-      if (result.contents) {
-        const formats: string[] = []
-        if (result.contents.markdown) {
-          formats.push(`${formatCharCount(result.contents.markdown.length)} chars (markdown)`)
-        }
-        if (result.contents.html) {
-          formats.push(`${formatCharCount(result.contents.html.length)} chars (html)`)
-        }
-        if (formats.length > 0) {
-          parts.push(`Page content available: ${formats.join(', ')}`)
-        }
-      }
-
-      return parts.join('\n')
-    })
-    .join('\n\n')
-}

package/src/shared/get-logger.ts

@@ -1,19 +0,0 @@
-import type { LoggingMessageNotification, ServerNotification } from '@modelcontextprotocol/sdk/types.js'
-
-/**
- * Creates a logger that routes notifications through the request's SSE stream
- *
- * @remarks
- * Uses `extra.sendNotification` from the tool callback, which attaches `relatedRequestId`
- * so the transport routes the message to the POST SSE stream (not the standalone GET stream).
- *
- * @param sendNotification - From the tool callback's `extra` parameter
- * @returns Async function that sends logging notifications
- *
- * @internal
- */
-export const getLogger =
-  (sendNotification: (notification: ServerNotification) => Promise<void>) =>
-  async (params: LoggingMessageNotification['params']) => {
-    await sendNotification({ method: 'notifications/message', params })
-  }

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

@@ -1,95 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import { formatSearchResultsText } from '../format-search-results-text.ts'
-
-describe('formatSearchResultsText', () => {
-  test('formats basic search results with title and URL', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test' }])
-
-    expect(result).toContain('Title: Test')
-    expect(result).toContain('URL: https://example.com')
-  })
-
-  test('includes page_age when present', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test', page_age: '2023-01-01' }])
-
-    expect(result).toContain('Published: 2023-01-01')
-  })
-
-  test('includes description when present', () => {
-    const result = formatSearchResultsText([
-      { url: 'https://example.com', title: 'Test', description: 'A description' },
-    ])
-
-    expect(result).toContain('Description: A description')
-  })
-
-  test('includes snippets array when present', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test', snippets: ['one', 'two'] }])
-
-    expect(result).toContain('Snippets:')
-    expect(result).toContain('- one')
-    expect(result).toContain('- two')
-  })
-
-  test('includes single snippet when present', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test', snippet: 'a snippet' }])
-
-    expect(result).toContain('Snippet: a snippet')
-  })
-
-  test('formats multiple results with separator', () => {
-    const result = formatSearchResultsText([
-      { url: 'https://a.com', title: 'A' },
-      { url: 'https://b.com', title: 'B' },
-    ])
-
-    expect(result).toContain('Title: A')
-    expect(result).toContain('Title: B')
-    expect(result).toContain('\n\n')
-  })
-
-  test('handles empty results array', () => {
-    const result = formatSearchResultsText([])
-
-    expect(result).toBe('')
-  })
-
-  test('includes contents indicator when markdown content is present', () => {
-    const result = formatSearchResultsText([
-      {
-        url: 'https://example.com',
-        title: 'Test',
-        contents: { markdown: 'A'.repeat(4523) },
-      },
-    ])
-
-    expect(result).toContain('Page content available:')
-    expect(result).toContain('4,523 chars (markdown)')
-  })
-
-  test('includes contents indicator for both markdown and html', () => {
-    const result = formatSearchResultsText([
-      {
-        url: 'https://example.com',
-        title: 'Test',
-        contents: { markdown: 'markdown content', html: '<p>html content</p>' },
-      },
-    ])
-
-    expect(result).toContain('Page content available:')
-    expect(result).toContain('chars (markdown)')
-    expect(result).toContain('chars (html)')
-  })
-
-  test('omits contents indicator when contents object has no content', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test', contents: {} }])
-
-    expect(result).not.toContain('Page content available:')
-  })
-
-  test('omits contents indicator when contents is not present', () => {
-    const result = formatSearchResultsText([{ url: 'https://example.com', title: 'Test' }])
-
-    expect(result).not.toContain('Page content available:')
-  })
-})

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

@@ -1,160 +0,0 @@
-import { describe, expect, test } from 'bun:test'
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { useGetClientVersion } from '../use-client-version.ts'
-
-describe('useGetClientVersion', () => {
-  test('returns formatted string with all fields present', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'test-client',
-          version: '1.0.0',
-          title: 'Test Client',
-          websiteUrl: 'https://example.com',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(
-      /^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; Test Client; https:\/\/example\.com\)$/,
-    )
-  })
-
-  test('returns formatted string with name and version only', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'test-client',
-          version: '1.0.0',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0\)$/)
-  })
-
-  test('returns UNKNOWN when no client version available', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => null,
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; UNKNOWN\)$/)
-  })
-
-  test('returns UNKNOWN when getClientVersion returns undefined', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => undefined,
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; UNKNOWN\)$/)
-  })
-
-  test('filters out empty strings from fields', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'test-client',
-          version: '1.0.0',
-          title: '', // Empty string should be filtered out
-          websiteUrl: 'https://example.com',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; https:\/\/example\.com\)$/)
-    expect(result).not.toContain(';;') // No double semicolons
-  })
-
-  test('filters out null values from fields', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'test-client',
-          version: '1.0.0',
-          title: null, // Null should be filtered out
-          websiteUrl: 'https://example.com',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; https:\/\/example\.com\)$/)
-  })
-
-  test('handles partial fields - name, version, and title only', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'Claude Desktop',
-          version: '0.7.6',
-          title: 'Claude Desktop App',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; Claude Desktop; 0\.7\.6; Claude Desktop App\)$/)
-  })
-
-  test('handles Claude Desktop client info format', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'Claude Desktop',
-          version: '0.7.6',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-    const result = getUserAgent()
-
-    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; Claude Desktop; 0\.7\.6\)$/)
-  })
-
-  test('returns a function that can be called multiple times', () => {
-    const mockMcp = {
-      server: {
-        getClientVersion: () => ({
-          name: 'test-client',
-          version: '1.0.0',
-        }),
-      },
-    } as unknown as McpServer
-
-    const getUserAgent = useGetClientVersion(mockMcp)
-
-    // Call multiple times to ensure consistent results
-    const result1 = getUserAgent()
-    const result2 = getUserAgent()
-    const result3 = getUserAgent()
-
-    const pattern = /^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0\)$/
-    expect(result1).toMatch(pattern)
-    expect(result2).toMatch(pattern)
-    expect(result3).toMatch(pattern)
-  })
-})

package/src/shared/use-client-version.ts

@@ -1,21 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import packageJson from '../../package.json' with { type: 'json' }
-
-/**
- * Creates User-Agent string for API requests
- * Used by search and contents API calls
- */
-const setUserAgent = (client: string) => `MCP/${packageJson.version} (You.com; ${client})`
-
-/**
- * Get's function that returns a formatted client version information into a string
- * Used by stdio.ts and http.ts for logging/debugging
- */
-export const useGetClientVersion = (mcp: McpServer) => () => {
-  const clientVersion = mcp.server.getClientVersion()
-  if (clientVersion) {
-    const { name, version, title, websiteUrl } = clientVersion
-    return setUserAgent([name, version, title, websiteUrl].filter(Boolean).join('; '))
-  }
-  return setUserAgent('UNKNOWN')
-}