@youdotcom-oss/mcp 2.1.0 → 3.1.0

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

@@ -1,87 +0,0 @@
-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.registerTool(
-    'you-search',
-    {
-      title: 'Web Search',
-      description: 'Web and news search via You.com',
-      inputSchema: SearchQuerySchema.shape,
-      outputSchema: SearchStructuredContentSchema.shape,
-    },
-    async (searchQuery) => {
-      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
-
-        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.' }],
-            structuredContent: {
-              resultCounts: {
-                web: 0,
-                news: 0,
-                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 }
-      } catch (err: unknown) {
-        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: [
-            {
-              type: 'text' as const,
-              text: `Error: ${errorMessage}`,
-            },
-          ],
-          structuredContent: undefined,
-          isError: true,
-        }
-      }
-    },
-  )
-}

package/src/search/search.schema.ts

@@ -1,38 +0,0 @@
-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>

package/src/search/search.utils.ts

@@ -1,70 +0,0 @@
-import type { NewsResult, SearchResponse } from '@youdotcom-oss/api'
-import { formatSearchResultsText } from '../shared/format-search-results-text.ts'
-
-export const formatSearchResults = (response: SearchResponse) => {
-  let formattedResults = ''
-
-  // Format web results using shared utility
-  if (response.results.web?.length) {
-    const webResults = formatSearchResultsText(response.results.web)
-    formattedResults += `WEB RESULTS:\n\n${webResults}`
-  }
-
-  // Format news results
-  if (response.results.news?.length) {
-    const newsResults = response.results.news
-      .map(
-        (article: NewsResult) =>
-          `Title: ${article.title}\nURL: ${article.url}\nDescription: ${article.description}\nPublished: ${article.page_age}`,
-      )
-      .join('\n\n---\n\n')
-
-    if (formattedResults) {
-      formattedResults += `\n\n${'='.repeat(50)}\n\n`
-    }
-    formattedResults += `NEWS RESULTS:\n\n${newsResults}`
-  }
-
-  // Extract fields for structuredContent
-  const structuredResults: {
-    web?: Array<{ url: string; title: string; page_age?: string }>
-    news?: Array<{ url: string; title: string; page_age: string }>
-  } = {}
-
-  if (response.results.web?.length) {
-    structuredResults.web = response.results.web.map((result) => {
-      const item: { url: string; title: string; page_age?: string } = {
-        url: result.url,
-        title: result.title,
-      }
-      if (result.page_age) item.page_age = result.page_age
-      return item
-    })
-  }
-
-  if (response.results.news?.length) {
-    structuredResults.news = response.results.news.map((article) => ({
-      url: article.url,
-      title: article.title,
-      page_age: article.page_age,
-    }))
-  }
-
-  return {
-    content: [
-      {
-        type: 'text' as const,
-        text: `Search Results for "${response.metadata.query}":\n\n${formattedResults}`,
-      },
-    ],
-    structuredContent: {
-      resultCounts: {
-        web: response.results.web?.length || 0,
-        news: response.results.news?.length || 0,
-        total: (response.results.web?.length || 0) + (response.results.news?.length || 0),
-      },
-      results: Object.keys(structuredResults).length > 0 ? structuredResults : undefined,
-    },
-    fullResponse: response,
-  }
-}

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

@@ -1,156 +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',
-    })
-    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 should be in text content
-    expect(result.content[0]?.text).toContain('URL: https://news.com/article')
-    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',
-    })
-    expect(result.structuredContent.results?.news?.[0]).toMatchObject({
-      url: 'https://news.com/article',
-      title: 'News Title',
-      page_age: '2023-01-01T00:00:00',
-    })
-  })
-})

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

@@ -1,49 +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
-}
-
-/**
- * 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}`)
-      }
-
-      return parts.join('\n')
-    })
-    .join('\n\n')
-}

package/src/shared/get-logger.ts

@@ -1,10 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { LoggingMessageNotification } from '@modelcontextprotocol/sdk/types.js'
-
-/**
- * Creates a logger function that sends messages through MCP server
- * Used by tool registration files
- */
-export const getLogger = (mcp: McpServer) => async (params: LoggingMessageNotification['params']) => {
-  await mcp.server.sendLoggingMessage(params)
-}

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.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
-
-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 server: ${error}\n`)
-  process.exit(1)
-}