@youdotcom-oss/mcp 3.2.3 → 3.4.0

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

@@ -1,291 +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(result).toHaveProperty('content')
-    expect(result).toHaveProperty('structuredContent')
-    expect(result).toHaveProperty('fullResponse')
-    expect(Array.isArray(result.content)).toBe(true)
-    expect(result.content[0]).toHaveProperty('type', 'text')
-    expect(result.content[0]).toHaveProperty('text')
-    expect(result.content[0]?.text).toContain('WEB RESULTS:')
-    expect(result.content[0]?.text).toContain('Test Title')
-    // URL and page_age should be in text content
-    expect(result.content[0]?.text).toContain('URL: https://example.com')
-    expect(result.content[0]?.text).toContain('Published: 2023-01-01T00:00:00')
-    expect(result.structuredContent).toHaveProperty('resultCounts')
-    expect(result.structuredContent.resultCounts).toHaveProperty('web', 1)
-    expect(result.structuredContent.resultCounts).toHaveProperty('news', 0)
-    expect(result.structuredContent.resultCounts).toHaveProperty('total', 1)
-    // All fields 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.results?.web?.[0]).toMatchObject({
-      url: 'https://example.com',
-      title: 'Test Title',
-      page_age: '2023-01-01T00:00:00',
-      snippets: ['snippet 1', 'snippet 2'],
-    })
-    expect(result.fullResponse).toBe(mockResponse)
-  })
-
-  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.content[0]?.text).toContain('NEWS RESULTS:')
-    expect(result.content[0]?.text).toContain('News Title')
-    expect(result.content[0]?.text).toContain('Published: 2023-01-01T00:00:00')
-    // URL and Description should be in text content (routed through formatSearchResultsText)
-    expect(result.content[0]?.text).toContain('URL: https://news.com/article')
-    expect(result.content[0]?.text).toContain('Description: News description')
-    expect(result.structuredContent).toHaveProperty('resultCounts')
-    expect(result.structuredContent.resultCounts).toHaveProperty('web', 0)
-    expect(result.structuredContent.resultCounts).toHaveProperty('news', 1)
-    expect(result.structuredContent.resultCounts).toHaveProperty('total', 1)
-    // All fields should be in structuredContent.results
-    expect(result.structuredContent).toHaveProperty('results')
-    expect(result.structuredContent.results?.news).toBeDefined()
-    expect(result.structuredContent.results?.news?.length).toBe(1)
-    expect(result.structuredContent.results?.news?.[0]).toMatchObject({
-      url: 'https://news.com/article',
-      title: 'News Title',
-      page_age: '2023-01-01T00:00:00',
-    })
-  })
-
-  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.content[0]?.text).toContain('WEB RESULTS:')
-    expect(result.content[0]?.text).toContain('NEWS RESULTS:')
-    expect(result.content[0]?.text).toContain(`=${'='.repeat(49)}`)
-    // URLs should be in text content
-    expect(result.content[0]?.text).toContain('URL: https://web.com')
-    expect(result.content[0]?.text).toContain('URL: https://news.com/article')
-    expect(result.structuredContent.resultCounts).toHaveProperty('web', 1)
-    expect(result.structuredContent.resultCounts).toHaveProperty('news', 1)
-    expect(result.structuredContent.resultCounts).toHaveProperty('total', 2)
-    // All fields should be in structuredContent.results
-    expect(result.structuredContent).toHaveProperty('results')
-    expect(result.structuredContent.results?.web).toBeDefined()
-    expect(result.structuredContent.results?.news).toBeDefined()
-    expect(result.structuredContent.results?.web?.length).toBe(1)
-    expect(result.structuredContent.results?.news?.length).toBe(1)
-    expect(result.structuredContent.results?.web?.[0]).toMatchObject({
-      url: 'https://web.com',
-      title: 'Web Title',
-      page_age: '2023-01-01T00:00:00',
-      snippets: ['web snippet'],
-    })
-    expect(result.structuredContent.results?.news?.[0]).toMatchObject({
-      url: 'https://news.com/article',
-      title: 'News Title',
-      page_age: '2023-01-01T00:00:00',
-    })
-  })
-
-  test('includes contents in structuredContent and text indicator when livecrawl returns page content', () => {
-    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)
-
-    // Text content should include the contents indicator
-    expect(result.content[0]?.text).toContain('Page content available:')
-    expect(result.content[0]?.text).toContain('chars (markdown)')
-    expect(result.content[0]?.text).toContain('chars (html)')
-
-    // structuredContent should include contents
-    expect(result.structuredContent.results?.web?.[0]).toMatchObject({
-      url: 'https://example.com',
-      title: 'Livecrawl Title',
-      contents: {
-        markdown: 'Full page content in markdown format.',
-        html: '<p>Full page content in HTML format.</p>',
-      },
-    })
-  })
-
-  test('omits contents when not present in response', () => {
-    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.content[0]?.text).not.toContain('Page content available:')
-    expect(result.structuredContent.results?.web?.[0]?.contents).toBeUndefined()
-  })
-
-  test('includes contents 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)
-
-    // Text content should include the contents indicator for news too
-    expect(result.content[0]?.text).toContain('Page content available:')
-    expect(result.content[0]?.text).toContain('chars (markdown)')
-
-    // structuredContent should include contents for news
-    expect(result.structuredContent.results?.news?.[0]).toMatchObject({
-      url: 'https://news.com/article',
-      title: 'News with Content',
-      contents: { markdown: 'Full news article content in markdown.' },
-    })
-  })
-
-  test('includes snippets in structuredContent for web results', () => {
-    const mockResponse: SearchResponse = {
-      results: {
-        web: [
-          {
-            url: 'https://example.com',
-            title: 'With Snippets',
-            description: 'Has snippets',
-            snippets: ['first snippet', 'second snippet'],
-          },
-        ],
-        news: [],
-      },
-      metadata: {
-        search_uuid: 'test-uuid',
-        query: 'test',
-        latency: 0.1,
-      },
-    }
-
-    const result = formatSearchResults(mockResponse)
-
-    expect(result.structuredContent.results?.web?.[0]?.snippets).toEqual(['first snippet', 'second snippet'])
-  })
-})

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')
-}

package/src/stdio-server.ts

@@ -1,24 +0,0 @@
-#!/usr/bin/env node
-import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
-import { registerContentsTool } from './contents/register-contents-tool.ts'
-import { getMcpServer } from './get-mcp-server.ts'
-import { registerResearchTool } from './research/register-research-tool.ts'
-import { registerSearchTool } from './search/register-search-tool.ts'
-import { useGetClientVersion } from './shared/use-client-version.ts'
-
-const YDC_API_KEY = process.env.YDC_API_KEY || undefined
-
-try {
-  const mcp = getMcpServer()
-  const getUserAgent = useGetClientVersion(mcp)
-
-  registerSearchTool({ mcp, YDC_API_KEY, getUserAgent })
-  registerContentsTool({ mcp, YDC_API_KEY, getUserAgent })
-  registerResearchTool({ mcp, YDC_API_KEY, getUserAgent })
-
-  const transport = new StdioServerTransport()
-  await mcp.connect(transport)
-} catch (error) {
-  process.stderr.write(`Failed to start MCP server: ${error}\n`)
-  process.exit(1)
-}