@youdotcom-oss/mcp 3.1.0 → 3.2.0-next.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "3.1.0",
-  "description": "You.com MCP STDIO bridge — proxies STDIO to the remote You.com MCP server at api.you.com/mcp",
+  "version": "3.2.0-next.1",
+  "description": "You.com MCP server — web search, AI research, and content extraction via You.com APIs",
   "license": "MIT",
   "engines": {
     "node": ">=18",
@@ -21,25 +21,29 @@
     "mcp",
     "web search",
     "model context protocol",
-    "stdio bridge"
+    "ai research"
   ],
   "bin": "bin/stdio.js",
   "type": "module",
+  "exports": {
+    ".": "./src/main.ts"
+  },
   "files": [
     "bin/stdio.js",
+    "src",
     "server.json"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "bun build ./src/stdio-bridge.ts --outfile ./bin/stdio.js --target=node",
+    "build": "bun build ./src/stdio-server.ts --outfile ./bin/stdio.js --target=node",
     "check": "bun run check:biome && bun run check:types && bun run check:package",
     "check:biome": "biome check",
     "check:package": "format-package --check",
     "check:types": "tsc --noEmit",
     "check:write": "biome check --write && bun run format:package",
-    "dev": "bun src/stdio-bridge.ts",
+    "dev": "bun src/stdio-server.ts",
     "format:package": "format-package --write",
     "inspector": "test -n \"$YDC_API_KEY\" || (echo 'YDC_API_KEY is not set' && exit 1); mcp-inspector --config mcp-inspector.json -e YDC_API_KEY=$YDC_API_KEY",
     "prepublishOnly": "bun run build",
@@ -48,7 +52,9 @@
   },
   "mcpName": "io.github.youdotcom-oss/mcp",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.25.3"
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@youdotcom-oss/api": "0.5.1",
+    "zod": "^4.3.6"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "0.21.1"

package/src/contents/contents.schemas.ts

@@ -0,0 +1,30 @@
+import * as z from 'zod'
+
+/**
+ * Structured content schema for MCP response
+ * Includes full content and metadata for each URL
+ */
+export const ContentsStructuredContentSchema = z.object({
+  count: z.number().describe('URLs processed'),
+  formats: z.array(z.string()).describe('Content formats requested'),
+  items: z
+    .array(
+      z.object({
+        url: z.string().describe('URL'),
+        title: z.string().optional().describe('Title'),
+        markdown: z.string().optional().describe('Markdown content'),
+        html: z.string().optional().describe('HTML content'),
+        metadata: z
+          .object({
+            favicon_url: z.string().describe('Favicon URL'),
+            site_name: z.string().optional().nullable().describe('Site name'),
+          })
+          .optional()
+          .nullable()
+          .describe('Page metadata'),
+      }),
+    )
+    .describe('Extracted items'),
+})
+
+export type ContentsStructuredContent = z.infer<typeof ContentsStructuredContentSchema>

package/src/contents/contents.utils.ts

@@ -0,0 +1,85 @@
+import type { ContentsApiResponse } from '@youdotcom-oss/api'
+import type { ContentsStructuredContent } from './contents.schemas.ts'
+
+/**
+ * Format contents API response for MCP output
+ * Returns full content in both text and structured formats
+ * @param response - Validated API response
+ * @param formats - Formats used for extraction
+ * @returns Formatted response with content and structuredContent
+ */
+export const formatContentsResponse = (
+  response: ContentsApiResponse,
+  formats: string[],
+): {
+  content: Array<{ type: 'text'; text: string }>
+  structuredContent: ContentsStructuredContent
+} => {
+  // Build text content with full extracted content
+  const textParts: string[] = [`Successfully extracted content from ${response.length} URL(s):\n`]
+  textParts.push(`Formats: ${formats.join(', ')}\n`)
+
+  const items: ContentsStructuredContent['items'] = []
+
+  for (const item of response) {
+    // Add header for this item
+    textParts.push(`\n## ${item.title || 'Untitled'}`)
+    textParts.push(`URL: ${item.url}\n`)
+    textParts.push('---\n')
+
+    // Add content based on requested formats
+    if (formats.includes('markdown') && item.markdown) {
+      textParts.push('\n### Markdown Content\n')
+      textParts.push(item.markdown)
+      textParts.push('\n')
+    }
+
+    if (formats.includes('html') && item.html) {
+      // Text output is a brief preview only — full HTML is in structuredContent.items[].html
+      textParts.push('\n### HTML Content\n')
+      textParts.push(`Length: ${item.html.length} characters\n`)
+      textParts.push(item.html.substring(0, 500))
+      if (item.html.length > 500) {
+        textParts.push('...\n(truncated for display — full HTML available in structuredContent)')
+      }
+      textParts.push('\n')
+    }
+
+    if (formats.includes('metadata') && item.metadata) {
+      textParts.push('\n### Metadata\n')
+
+      if (item.metadata.site_name) {
+        textParts.push(`**Site Name:** ${item.metadata.site_name}\n`)
+      }
+
+      if (item.metadata.favicon_url) {
+        textParts.push(`**Favicon:** ${item.metadata.favicon_url}\n`)
+      }
+    }
+
+    textParts.push('\n---\n')
+
+    // Add to structured content
+    items.push({
+      url: item.url,
+      title: item.title ?? undefined,
+      markdown: item.markdown ?? undefined,
+      html: item.html ?? undefined,
+      metadata: item.metadata ?? undefined,
+    })
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: textParts.join('\n'),
+      },
+    ],
+    structuredContent: {
+      count: response.length,
+      formats,
+      items,
+    },
+  }
+}

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

@@ -0,0 +1,93 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { ContentsQuerySchema, fetchContents, generateErrorReportLink } from '@youdotcom-oss/api'
+import { getLogger } from '../shared/get-logger.ts'
+import { ContentsStructuredContentSchema } from './contents.schemas.ts'
+import { formatContentsResponse } from './contents.utils.ts'
+
+/**
+ * Register the you-contents tool with the MCP server
+ * Extracts and returns full content from multiple URLs in markdown or HTML format
+ */
+export const registerContentsTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  mcp: McpServer
+  YDC_API_KEY?: string
+  getUserAgent: () => string
+}) => {
+  // Register the tool
+  mcp.registerTool(
+    'you-contents',
+    {
+      title: 'Extract Web Page Contents',
+      description: 'Extract page content in markdown or HTML',
+      inputSchema: ContentsQuerySchema.shape,
+      outputSchema: ContentsStructuredContentSchema.shape,
+    },
+    async (contentsQuery, { sendNotification }) => {
+      const logger = getLogger(sendNotification)
+
+      try {
+        // Validate and parse input
+        const { urls, formats, format, crawl_timeout } = contentsQuery
+
+        // Handle backward compatibility: prefer formats array, fallback to format string, default to ['markdown']
+        const requestFormats = formats || (format ? [format] : ['markdown'])
+
+        // Log the request
+        const timeoutInfo = crawl_timeout ? ` with timeout: ${crawl_timeout}s` : ''
+        await logger({
+          level: 'info',
+          data: `Contents API call initiated for ${urls.length} URL(s) with formats: ${requestFormats.join(', ')}${timeoutInfo}`,
+        })
+
+        // Fetch contents from API
+        const response = await fetchContents({
+          contentsQuery,
+          YDC_API_KEY,
+          getUserAgent,
+        })
+
+        // Format response with full content
+        const { content, structuredContent } = formatContentsResponse(response, requestFormats)
+
+        // Log success
+        await logger({
+          level: 'info',
+          data: `Contents API call successful: extracted ${response.length} page(s)`,
+        })
+
+        return {
+          content,
+          structuredContent,
+        }
+      } catch (err: unknown) {
+        // Handle and log errors
+        const errorMessage = err instanceof Error ? err.message : String(err)
+        const reportLink = generateErrorReportLink({
+          errorMessage,
+          tool: 'you-contents',
+          clientInfo: getUserAgent(),
+        })
+
+        await logger({
+          level: 'error',
+          data: `Contents API call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
+        })
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error extracting contents: ${errorMessage}`,
+            },
+          ],
+          structuredContent: undefined,
+          isError: true,
+        }
+      }
+    },
+  )
+}

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

@@ -0,0 +1,123 @@
+import { describe, expect, test } from 'bun:test'
+import type { ContentsApiResponse } from '@youdotcom-oss/api'
+import { formatContentsResponse } from '../contents.utils.ts'
+
+describe('formatContentsResponse', () => {
+  test('formats single markdown content correctly', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Example Page',
+        markdown: '# Hello\n\nThis is a test page with some content.',
+      },
+    ]
+
+    const result = formatContentsResponse(mockResponse, ['markdown'])
+
+    expect(result).toHaveProperty('content')
+    expect(result).toHaveProperty('structuredContent')
+    expect(Array.isArray(result.content)).toBe(true)
+    expect(result.content[0]).toHaveProperty('type', 'text')
+    expect(result.content[0]).toHaveProperty('text')
+
+    const text = result.content[0]?.text
+    expect(text).toContain('Example Page')
+    expect(text).toContain('https://example.com')
+    expect(text).toContain('Formats: markdown')
+    expect(text).toContain('# Hello')
+    expect(text).toContain('This is a test page with some content.')
+
+    expect(result.structuredContent).toHaveProperty('count', 1)
+    expect(result.structuredContent).toHaveProperty('formats')
+    expect(result.structuredContent.formats).toEqual(['markdown'])
+    expect(result.structuredContent.items).toHaveLength(1)
+
+    const item = result.structuredContent.items[0]
+    expect(item).toBeDefined()
+
+    expect(item).toHaveProperty('url', 'https://example.com')
+    expect(item).toHaveProperty('title', 'Example Page')
+    expect(item).toHaveProperty('markdown', '# Hello\n\nThis is a test page with some content.')
+  })
+
+  test('formats multiple items correctly', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example1.com',
+        title: 'Page 1',
+        markdown: 'Content 1',
+      },
+      {
+        url: 'https://example2.com',
+        title: 'Page 2',
+        markdown: 'Content 2',
+      },
+    ]
+
+    const result = formatContentsResponse(mockResponse, ['markdown'])
+
+    expect(result.structuredContent.count).toBe(2)
+    expect(result.structuredContent.items).toHaveLength(2)
+
+    const text = result.content[0]?.text
+    expect(text).toContain('Page 1')
+    expect(text).toContain('Page 2')
+    expect(text).toContain('https://example1.com')
+    expect(text).toContain('https://example2.com')
+  })
+
+  test('handles html format', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'HTML Page',
+        html: '<html><body><h1>Hello</h1></body></html>',
+      },
+    ]
+
+    const result = formatContentsResponse(mockResponse, ['html'])
+
+    expect(result.structuredContent.formats).toEqual(['html'])
+    const text = result.content[0]?.text
+    expect(text).toContain('Formats: html')
+    expect(text).toContain('<html>')
+  })
+
+  test('includes full content for long text', () => {
+    const longContent = 'a'.repeat(1000)
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Long Page',
+        markdown: longContent,
+      },
+    ]
+
+    const result = formatContentsResponse(mockResponse, ['markdown'])
+
+    const text = result.content[0]?.text
+    // Full content should be included (not truncated)
+    expect(text).toContain(longContent)
+
+    // Structured content should have full markdown content
+    const item = result.structuredContent.items[0]
+    expect(item?.markdown).toBe(longContent)
+  })
+
+  test('handles empty content gracefully', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Empty Page',
+        markdown: '',
+      },
+    ]
+
+    const result = formatContentsResponse(mockResponse, ['markdown'])
+
+    expect(result.structuredContent.items[0]?.markdown).toBe('')
+    const text = result.content[0]?.text
+    expect(text).toContain('Empty Page')
+    // Empty content should still be handled gracefully
+  })
+})

package/src/get-mcp-server.ts

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import packageJson from '../package.json' with { type: 'json' }
+
+export const getMcpServer = () =>
+  new McpServer(
+    {
+      name: 'You.com',
+      version: packageJson.version,
+    },
+    {
+      capabilities: {
+        logging: {},
+        tools: { listChanged: true },
+      },
+      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/main.ts

@@ -0,0 +1,8 @@
+export type { ContentsStructuredContent } from './contents/contents.schemas.ts'
+export { registerContentsTool } from './contents/register-contents-tool.ts'
+export { getMcpServer } from './get-mcp-server.ts'
+export { registerResearchTool } from './research/register-research-tool.ts'
+export type { ResearchStructuredContent } from './research/research.schemas.ts'
+export { registerSearchTool } from './search/register-search-tool.ts'
+export type { SearchStructuredContent } from './search/search.schemas.ts'
+export { useGetClientVersion } from './shared/use-client-version.ts'

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

@@ -0,0 +1,69 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { callResearch, generateErrorReportLink, ResearchQuerySchema } from '@youdotcom-oss/api'
+import { getLogger } from '../shared/get-logger.ts'
+import { ResearchStructuredContentSchema } from './research.schemas.ts'
+import { formatResearchResults } from './research.utils.ts'
+
+export const registerResearchTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  mcp: McpServer
+  YDC_API_KEY?: string
+  getUserAgent: () => string
+}) => {
+  mcp.registerTool(
+    'you-research',
+    {
+      title: 'Research',
+      description:
+        'Research a topic with comprehensive answers and cited sources. Configurable effort levels (lite, standard, deep, exhaustive).',
+      inputSchema: ResearchQuerySchema.shape,
+      outputSchema: ResearchStructuredContentSchema.shape,
+    },
+    async (researchQuery, { sendNotification }) => {
+      const logger = getLogger(sendNotification)
+      try {
+        const response = await callResearch({
+          researchQuery,
+          YDC_API_KEY,
+          getUserAgent,
+        })
+
+        const sourceCount = response.output.sources.length
+
+        await logger({
+          level: 'info',
+          data: `Research for "${researchQuery.input.substring(0, 100)}" complete: ${sourceCount} source(s)`,
+        })
+
+        const { content, structuredContent } = formatResearchResults(response)
+        return { content, structuredContent }
+      } catch (err: unknown) {
+        const errorMessage = err instanceof Error ? err.message : String(err)
+        const reportLink = generateErrorReportLink({
+          errorMessage,
+          tool: 'you-research',
+          clientInfo: getUserAgent(),
+        })
+
+        await logger({
+          level: 'error',
+          data: `Research API call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
+        })
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${errorMessage}`,
+            },
+          ],
+          structuredContent: undefined,
+          isError: true,
+        }
+      }
+    },
+  )
+}

package/src/research/research.schemas.ts

@@ -0,0 +1,19 @@
+import * as z from 'zod'
+
+// Minimal schema for structuredContent (reduces payload duplication)
+// Full research content is in the text content field
+export const ResearchStructuredContentSchema = z.object({
+  contentType: z.string().describe('Format of the content field'),
+  sourceCount: z.number().describe('Number of sources used'),
+  sources: z
+    .array(
+      z.object({
+        url: z.string().describe('Source URL'),
+        title: z.string().optional().describe('Source title'),
+        snippetCount: z.number().describe('Number of excerpts from this source'),
+      }),
+    )
+    .describe('Sources used in the research answer'),
+})
+
+export type ResearchStructuredContent = z.infer<typeof ResearchStructuredContentSchema>

package/src/research/research.utils.ts

@@ -0,0 +1,30 @@
+import type { ResearchResponse } from '@youdotcom-oss/api'
+import { formatResearchResponse } from '@youdotcom-oss/api'
+import type { ResearchStructuredContent } from './research.schemas.ts'
+
+export const formatResearchResults = (
+  response: ResearchResponse,
+): {
+  content: Array<{ type: 'text'; text: string }>
+  structuredContent: ResearchStructuredContent
+} => {
+  const text = formatResearchResponse(response)
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text,
+      },
+    ],
+    structuredContent: {
+      contentType: response.output.content_type,
+      sourceCount: response.output.sources.length,
+      sources: response.output.sources.map((source) => ({
+        url: source.url,
+        title: source.title,
+        snippetCount: source.snippets?.length ?? 0,
+      })),
+    },
+  }
+}

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

@@ -0,0 +1,114 @@
+import { describe, expect, test } from 'bun:test'
+import type { ResearchResponse } from '@youdotcom-oss/api'
+import { formatResearchResults } from '../research.utils.ts'
+
+describe('formatResearchResults', () => {
+  test('formats research response with sources correctly', () => {
+    const mockResponse: ResearchResponse = {
+      output: {
+        content: '# Research Answer\n\nThis is a comprehensive answer about the topic.',
+        content_type: 'text',
+        sources: [
+          {
+            url: 'https://example.com/source1',
+            title: 'Source One',
+            snippets: ['First snippet', 'Second snippet'],
+          },
+          {
+            url: 'https://example.com/source2',
+            title: 'Source Two',
+            snippets: ['Another snippet'],
+          },
+        ],
+      },
+    }
+
+    const result = formatResearchResults(mockResponse)
+
+    expect(result).toHaveProperty('content')
+    expect(result).toHaveProperty('structuredContent')
+    expect(Array.isArray(result.content)).toBe(true)
+    expect(result.content[0]).toHaveProperty('type', 'text')
+    expect(result.content[0]).toHaveProperty('text')
+
+    const text = result.content[0]?.text
+    expect(text).toContain('Research Answer')
+    expect(text).toContain('Source One')
+    expect(text).toContain('https://example.com/source1')
+
+    expect(result.structuredContent.contentType).toBe('text')
+    expect(result.structuredContent.sourceCount).toBe(2)
+    expect(result.structuredContent.sources).toHaveLength(2)
+    expect(result.structuredContent.sources[0]).toMatchObject({
+      url: 'https://example.com/source1',
+      title: 'Source One',
+      snippetCount: 2,
+    })
+    expect(result.structuredContent.sources[1]).toMatchObject({
+      url: 'https://example.com/source2',
+      title: 'Source Two',
+      snippetCount: 1,
+    })
+  })
+
+  test('handles source with undefined title', () => {
+    const mockResponse: ResearchResponse = {
+      output: {
+        content: 'Answer text',
+        content_type: 'text',
+        sources: [
+          {
+            url: 'https://example.com/no-title',
+            snippets: ['A snippet'],
+          },
+        ],
+      },
+    }
+
+    const result = formatResearchResults(mockResponse)
+
+    expect(result.structuredContent.sourceCount).toBe(1)
+    expect(result.structuredContent.sources[0]).toMatchObject({
+      url: 'https://example.com/no-title',
+      title: undefined,
+      snippetCount: 1,
+    })
+  })
+
+  test('handles source with empty snippets array', () => {
+    const mockResponse: ResearchResponse = {
+      output: {
+        content: 'Answer with no-snippet source',
+        content_type: 'text',
+        sources: [
+          {
+            url: 'https://example.com/empty-snippets',
+            title: 'Empty Snippets Source',
+            snippets: [],
+          },
+        ],
+      },
+    }
+
+    const result = formatResearchResults(mockResponse)
+
+    expect(result.structuredContent.sourceCount).toBe(1)
+    expect(result.structuredContent.sources[0]?.snippetCount).toBe(0)
+  })
+
+  test('handles response with zero sources', () => {
+    const mockResponse: ResearchResponse = {
+      output: {
+        content: 'An answer with no cited sources.',
+        content_type: 'text',
+        sources: [],
+      },
+    }
+
+    const result = formatResearchResults(mockResponse)
+
+    expect(result.structuredContent.sourceCount).toBe(0)
+    expect(result.structuredContent.sources).toHaveLength(0)
+    expect(result.content[0]?.text).toContain('An answer with no cited sources.')
+  })
+})