@youdotcom-oss/mcp 1.6.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.6.0",
+  "version": "2.0.0",
   "description": "You.com API Model Context Protocol Server - For programmatic API access, use @youdotcom-oss/api",
   "license": "MIT",
   "engines": {
@@ -56,7 +56,7 @@
   },
   "mcpName": "io.github.youdotcom-oss/mcp",
   "dependencies": {
-    "@youdotcom-oss/api": "0.1.1",
+    "@youdotcom-oss/api": "0.2.0",
     "zod": "^4.3.6",
     "@hono/mcp": "^0.2.3",
     "@modelcontextprotocol/sdk": "^1.25.3",

package/src/contents/contents.schemas.ts

@@ -16,12 +16,12 @@ export const ContentsStructuredContentSchema = z.object({
         html: z.string().optional().describe('HTML content'),
         metadata: z
           .object({
-            jsonld: z.array(z.record(z.string(), z.unknown())).optional(),
-            opengraph: z.record(z.string(), z.string()).optional(),
-            twitter: z.record(z.string(), z.string()).optional(),
+            favicon_url: z.string().describe('Favicon URL'),
+            site_name: z.string().optional().nullable().describe('Site name'),
           })
           .optional()
-          .describe('Structured metadata'),
+          .nullable()
+          .describe('Page metadata'),
       }),
     )
     .describe('Extracted items'),

package/src/contents/contents.utils.ts

@@ -47,30 +47,12 @@ export const formatContentsResponse = (
     if (formats.includes('metadata') && item.metadata) {
       textParts.push('\n### Metadata\n')
 
-      if (item.metadata.jsonld && item.metadata.jsonld.length > 0) {
-        textParts.push('\n**JSON-LD:**\n')
-        const jsonldStr = JSON.stringify(item.metadata.jsonld, null, 2)
-        if (jsonldStr.length > 2000) {
-          textParts.push(jsonldStr.substring(0, 2000))
-          textParts.push('\n...(truncated for display, see structuredContent for full data)')
-        } else {
-          textParts.push(jsonldStr)
-        }
-        textParts.push('\n')
+      if (item.metadata.site_name) {
+        textParts.push(`**Site Name:** ${item.metadata.site_name}\n`)
       }
 
-      if (item.metadata.opengraph) {
-        textParts.push('\n**OpenGraph:**\n')
-        for (const [key, value] of Object.entries(item.metadata.opengraph)) {
-          textParts.push(`- ${key}: ${value}\n`)
-        }
-      }
-
-      if (item.metadata.twitter) {
-        textParts.push('\n**Twitter:**\n')
-        for (const [key, value] of Object.entries(item.metadata.twitter)) {
-          textParts.push(`- ${key}: ${value}\n`)
-        }
+      if (item.metadata.favicon_url) {
+        textParts.push(`**Favicon:** ${item.metadata.favicon_url}\n`)
       }
     }
 
@@ -79,10 +61,10 @@ export const formatContentsResponse = (
     // Add to structured content
     items.push({
       url: item.url,
-      title: item.title,
-      markdown: item.markdown,
-      html: item.html,
-      metadata: item.metadata,
+      title: item.title ?? undefined,
+      markdown: item.markdown ?? undefined,
+      html: item.html ?? undefined,
+      metadata: item.metadata ?? undefined,
     })
   }
 

package/src/http.ts

@@ -3,7 +3,6 @@ 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'
@@ -39,7 +38,6 @@ const handleMcpRequest = async (c: Context) => {
     YDC_API_KEY,
     getUserAgent,
   })
-  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent })
   registerContentsTool({ mcp, YDC_API_KEY, getUserAgent })
 
   const transport = new StreamableHTTPTransport()

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

@@ -1,6 +1,6 @@
 /**
- * Generic search result type that works for both Search and Express APIs
- * Used by both search.utils.ts and express.utils.ts
+ * Generic search result type for Search API results
+ * Used by search.utils.ts
  */
 type GenericSearchResult = {
   url: string
@@ -13,7 +13,7 @@ type GenericSearchResult = {
 
 /**
  * Format array of search results into display text
- * Used by both search and express agent formatting
+ * Used by search result formatting
  * @param results - Array of search results to format
  */
 export const formatSearchResultsText = (results: GenericSearchResult[]): string => {
@@ -38,7 +38,7 @@ export const formatSearchResultsText = (results: GenericSearchResult[]): string
       if (result.snippets && result.snippets.length > 0) {
         parts.push(`Snippets:\n- ${result.snippets.join('\n- ')}`)
       }
-      // Handle single snippet (from Express API)
+      // Handle single snippet
       else if (result.snippet) {
         parts.push(`Snippet: ${result.snippet}`)
       }

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

@@ -3,7 +3,7 @@ import packageJson from '../../package.json' with { type: 'json' }
 
 /**
  * Creates User-Agent string for API requests
- * Used by search and express agent API calls
+ * Used by search and contents API calls
  */
 const setUserAgent = (client: string) => `MCP/${packageJson.version} (You.com; ${client})`
 

package/src/stdio.ts

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 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'
@@ -13,7 +12,6 @@ try {
   const getUserAgent = useGetClientVersion(mcp)
 
   registerSearchTool({ mcp, YDC_API_KEY, getUserAgent })
-  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent })
   registerContentsTool({ mcp, YDC_API_KEY, getUserAgent })
 
   const transport = new StdioServerTransport()

package/src/tests/tool.spec.ts

@@ -212,13 +212,12 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles site parameter',
+    'handles site: operator in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'react components',
-          site: 'github.com',
+          query: 'react components site:github.com',
         },
       })
 
@@ -229,13 +228,12 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles fileType parameter',
+    'handles filetype: operator in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'documentation',
-          fileType: 'pdf',
+          query: 'documentation filetype:pdf',
         },
       })
 
@@ -246,13 +244,12 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles language parameter',
+    'handles lang: operator in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'tutorial',
-          language: 'es',
+          query: 'tutorial lang:es',
         },
       })
 
@@ -263,13 +260,12 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles exactTerms parameter',
+    'handles + operator for required terms in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'programming',
-          exactTerms: 'javascript|typescript',
+          query: 'programming +javascript +typescript',
         },
       })
 
@@ -280,13 +276,12 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles excludeTerms parameter',
+    'handles - operator for excluded terms in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'tutorial',
-          excludeTerms: 'beginner|basic',
+          query: 'tutorial -beginner -basic',
         },
       })
 
@@ -297,54 +292,17 @@ describe('registerSearchTool', () => {
   )
 
   test(
-    'handles multi-word phrases with parentheses in exactTerms',
-    async () => {
-      const result = await client.callTool({
-        name: 'you-search',
-        arguments: {
-          query: 'programming',
-          exactTerms: '(machine learning)|typescript',
-        },
-      })
-
-      const content = result.content as { type: string; text: string }[]
-      expect(content[0]?.text).toContain('programming')
-    },
-    { retry: 2 },
-  )
-
-  test(
-    'handles multi-word phrases with parentheses in excludeTerms',
-    async () => {
-      const result = await client.callTool({
-        name: 'you-search',
-        arguments: {
-          query: 'programming',
-          excludeTerms: '(social media)|ads',
-        },
-      })
-
-      const content = result.content as { type: string; text: string }[]
-      expect(content[0]?.text).toContain('programming')
-    },
-    { retry: 2 },
-  )
-
-  test(
-    'handles complex search with multiple parameters',
+    'handles complex search with multiple operators in query',
     async () => {
       const result = await client.callTool({
         name: 'you-search',
         arguments: {
-          query: 'machine learning tutorial',
+          query: 'machine learning tutorial site:github.com filetype:md lang:en',
           count: 5,
           offset: 1,
           freshness: 'month',
           country: 'US',
           safesearch: 'moderate',
-          site: 'github.com',
-          fileType: 'md',
-          language: 'en',
         },
       })
 
@@ -431,25 +389,6 @@ describe('registerSearchTool', () => {
     { retry: 2 },
   )
 
-  test(
-    'returns error when both exactTerms and excludeTerms are provided',
-    async () => {
-      const result = await client.callTool({
-        name: 'you-search',
-        arguments: {
-          query: 'programming',
-          exactTerms: 'javascript',
-          excludeTerms: 'beginner',
-        },
-      })
-
-      expect(result.isError).toBe(true)
-      const content = result.content as { type: string; text: string }[]
-      expect(content[0]?.text).toContain('Cannot specify both exactTerms and excludeTerms - please use only one')
-    },
-    { retry: 2 },
-  )
-
   test('handles API errors gracefully', async () => {
     try {
       await client.callTool({

package/src/express/express.schema.ts

@@ -1,23 +0,0 @@
-import * as z from 'zod'
-
-// Minimal schema for structuredContent (reduces payload duplication)
-export const ExpressStructuredContentSchema = z.object({
-  answer: z.string().describe('AI answer'),
-  hasResults: z.boolean().describe('Has web results'),
-  resultCount: z.number().describe('Result count'),
-  agent: z.string().optional().describe('Agent ID'),
-  results: z
-    .object({
-      web: z
-        .array(
-          z.object({
-            url: z.string().describe('URL'),
-            title: z.string().describe('Title'),
-          }),
-        )
-        .optional()
-        .describe('Web results'),
-    })
-    .optional()
-    .describe('Search results'),
-})

package/src/express/express.utils.ts

@@ -1,44 +0,0 @@
-import type { ExpressAgentMcpResponse } from '@youdotcom-oss/api'
-import { formatSearchResultsText } from '../shared/format-search-results-text.ts'
-
-export const formatExpressAgentResponse = (response: ExpressAgentMcpResponse) => {
-  const _agentId = response.agent || 'express'
-  const content: Array<{ type: 'text'; text: string }> = []
-
-  // 1. Answer first (always present)
-  content.push({
-    type: 'text',
-    text: `Express Agent Answer:\n\n${response.answer}`,
-  })
-
-  // 2. Search results second (if present when web_search tool was used) - without URLs in text
-  if (response.results?.web?.length) {
-    const formattedResults = formatSearchResultsText(response.results.web)
-    content.push({
-      type: 'text',
-      text: `\nSearch Results:\n\n${formattedResults}`,
-    })
-  }
-
-  // Extract URLs and titles for structuredContent
-  const structuredResults = response.results?.web?.length
-    ? {
-        web: response.results.web.map((result) => ({
-          url: result.url,
-          title: result.title,
-        })),
-      }
-    : undefined
-
-  return {
-    content,
-    structuredContent: {
-      answer: response.answer,
-      hasResults: !!response.results?.web?.length,
-      resultCount: response.results?.web?.length || 0,
-      agent: response.agent,
-      results: structuredResults,
-    },
-    fullResponse: response,
-  }
-}

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

@@ -1,67 +0,0 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import { callExpressAgent, ExpressAgentInputSchema, generateErrorReportLink } from '@youdotcom-oss/api'
-import { getLogger } from '../shared/get-logger.ts'
-import { ExpressStructuredContentSchema } from './express.schema.ts'
-import { formatExpressAgentResponse } from './express.utils.ts'
-
-export const registerExpressTool = ({
-  mcp,
-  YDC_API_KEY,
-  getUserAgent,
-}: {
-  mcp: McpServer
-  YDC_API_KEY?: string
-  getUserAgent: () => string
-}) => {
-  mcp.registerTool(
-    'you-express',
-    {
-      title: 'Express Agent',
-      description: 'Fast AI answers with web search',
-      inputSchema: ExpressAgentInputSchema.shape,
-      outputSchema: ExpressStructuredContentSchema.shape,
-    },
-    async (agentInput) => {
-      const logger = getLogger(mcp)
-
-      try {
-        const response = await callExpressAgent({
-          agentInput,
-          YDC_API_KEY,
-          getUserAgent,
-        })
-
-        await logger({
-          level: 'info',
-          data: `Express agent call successful for input: "${agentInput.input}"`,
-        })
-
-        const { content, structuredContent } = formatExpressAgentResponse(response)
-        return { content, structuredContent }
-      } catch (err: unknown) {
-        const errorMessage = err instanceof Error ? err.message : String(err)
-        const reportLink = generateErrorReportLink({
-          errorMessage,
-          tool: 'you-express',
-          clientInfo: getUserAgent(),
-        })
-
-        await logger({
-          level: 'error',
-          data: `Express agent call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
-        })
-
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Error: ${errorMessage}`,
-            },
-          ],
-          structuredContent: undefined,
-          isError: true,
-        }
-      }
-    },
-  )
-}

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

@@ -1,177 +0,0 @@
-import { describe, expect, setDefaultTimeout, test } from 'bun:test'
-import type { ExpressAgentMcpResponse } from '@youdotcom-oss/api'
-import { formatExpressAgentResponse } from '../express.utils.ts'
-
-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)
-
-    // 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)
-
-    // 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.')
-
-    // 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)
-    // No results, so results field should be undefined
-    expect(result.structuredContent.results).toBeUndefined()
-    expect(result.fullResponse).toEqual(mockResponse)
-  })
-
-  test('formats response with answer and search results', () => {
-    const mockResponse: ExpressAgentMcpResponse = {
-      answer: 'Quantum computing is advancing rapidly with recent breakthroughs in error correction.',
-      results: {
-        web: [
-          {
-            url: 'https://example.com/quantum1',
-            title: 'Quantum Computing Breakthrough',
-            snippet: 'Scientists achieve quantum error correction milestone.',
-          },
-          {
-            url: 'https://example.com/quantum2',
-            title: 'Latest in Quantum Research',
-            snippet: 'New quantum processor demonstrates superiority.',
-          },
-        ],
-      },
-      agent: 'express',
-    }
-
-    const result = formatExpressAgentResponse(mockResponse)
-
-    // Verify content array has 2 items (answer + search results)
-    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')
-
-    // 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')
-    // 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')
-
-    // 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)
-
-    // 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.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)
-  })
-
-  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)
-
-    // Verify structure matches minimal schema
-    expect(result.structuredContent).toMatchObject({
-      answer: expect.any(String),
-      hasResults: false,
-      resultCount: 0,
-      agent: 'express',
-    })
-
-    // Verify fullResponse has complete data
-    expect(result.fullResponse.results).toBeUndefined()
-  })
-
-  test('structuredContent validation for answer with results', () => {
-    const mockResponse: ExpressAgentMcpResponse = {
-      answer: 'Recent AI breakthroughs include advances in language models and computer vision.',
-      results: {
-        web: [
-          {
-            url: 'https://example.com/ai-breakthrough',
-            title: 'AI Breakthrough 2025',
-            snippet: 'Major advances in artificial intelligence.',
-          },
-        ],
-      },
-      agent: 'express',
-    }
-
-    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.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)
-
-    // 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.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)
-
-    // 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.')
-  })
-})