@youdotcom-oss/mcp 2.1.0 → 3.1.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "2.1.0",
-  "description": "You.com API Model Context Protocol Server - For programmatic API access, use @youdotcom-oss/api",
+  "version": "3.1.0",
+  "description": "You.com MCP STDIO bridge — proxies STDIO to the remote You.com MCP server at api.you.com/mcp",
   "license": "MIT",
   "engines": {
     "node": ">=18",
@@ -20,49 +20,37 @@
   "keywords": [
     "mcp",
     "web search",
-    "model context protocol"
+    "model context protocol",
+    "stdio bridge"
   ],
   "bin": "bin/stdio.js",
   "type": "module",
-  "exports": {
-    "./http": "./src/http.ts"
-  },
   "files": [
     "bin/stdio.js",
-    "./dist/**",
-    "./src/**",
-    "!./src/**/tests/*",
-    "!./src/**/*.spec.@(tsx|ts)"
+    "server.json"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "bun build ./src/stdio.ts --outfile ./bin/stdio.js --target=node",
+    "build": "bun build ./src/stdio-bridge.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.ts",
+    "dev": "bun src/stdio-bridge.ts",
     "format:package": "format-package --write",
-    "inspect": "bash -c 'source .env 2>/dev/null || true; bunx @modelcontextprotocol/inspector -e YDC_API_KEY=$YDC_API_KEY bun dev'",
+    "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",
-    "start": "bun run src/http.ts",
     "test": "bun test",
-    "test:coverage": "bun test --coverage",
-    "test:coverage:watch": "bun test --coverage --watch",
     "test:watch": "bun test --watch"
   },
   "mcpName": "io.github.youdotcom-oss/mcp",
   "dependencies": {
-    "@youdotcom-oss/api": "0.4.0",
-    "zod": "^4.3.6",
-    "@hono/mcp": "^0.2.3",
-    "@modelcontextprotocol/sdk": "^1.25.3",
-    "hono": "^4.11.7"
+    "@modelcontextprotocol/sdk": "^1.25.3"
   },
   "devDependencies": {
-    "@modelcontextprotocol/inspector": "0.20.0"
+    "@modelcontextprotocol/inspector": "0.21.1"
   }
 }

package/server.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.youdotcom-oss/mcp",
+  "title": "You.com Web Access & AI",
+  "description": "Web search, AI agent, and content extraction via You.com APIs",
+  "version": "3.0.0",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://api.you.com/mcp",
+      "headers": [
+        {
+          "name": "Authorization",
+          "description": "Bearer (You.com API key)",
+          "isRequired": false,
+          "isSecret": true
+        }
+      ]
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@youdotcom-oss/mcp",
+      "version": "3.0.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "YDC_API_KEY",
+          "description": "You.com API key (optional — omit for free tier)",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "MCP_SERVER_URL",
+          "description": "Remote MCP server URL (defaults to https://api.you.com/mcp)",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "uri"
+        }
+      ]
+    }
+  ],
+  "repository": {
+    "url": "https://github.com/youdotcom-oss/dx-toolkit",
+    "source": "github"
+  }
+}

package/src/contents/contents.schemas.ts

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

@@ -1,84 +0,0 @@
-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) {
-      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)')
-      }
-      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

@@ -1,94 +0,0 @@
-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 (toolInput) => {
-      const logger = getLogger(mcp)
-
-      try {
-        // Validate and parse input
-        const contentsQuery = ContentsQuerySchema.parse(toolInput)
-        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

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

@@ -1,17 +0,0 @@
-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/http.ts

@@ -1,94 +0,0 @@
-import { StreamableHTTPTransport } from '@hono/mcp'
-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 { 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 extractBearerToken = (authHeader: string | null): string | null => {
-  if (!authHeader || !authHeader.startsWith('Bearer ')) {
-    return null
-  }
-  return authHeader.slice(7)
-}
-
-const handleMcpRequest = async (c: Context) => {
-  const authHeader = c.req.header('Authorization')
-
-  let YDC_API_KEY: string | undefined
-
-  if (authHeader) {
-    const token = extractBearerToken(authHeader)
-
-    if (!token) {
-      c.status(401)
-      c.header('Content-Type', 'text/plain')
-      return c.text('Unauthorized: Invalid Bearer token format')
-    }
-
-    YDC_API_KEY = token
-  }
-
-  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 StreamableHTTPTransport()
-  await mcp.connect(transport)
-  const response = await transport.handleRequest(c)
-
-  // Explicitly set Content-Encoding to 'identity' to prevent httpx auto-decompression issues
-  // httpx by default sends Accept-Encoding and attempts decompression, but MCP SSE streams
-  // are not compressed. Setting 'identity' tells clients the response is uncompressed.
-  response?.headers.set('Content-Encoding', 'identity')
-
-  return response
-}
-
-const return405MethodNotAllowed = (c: Context) => {
-  c.status(405)
-  c.header('Allow', 'POST')
-  c.header('Content-Type', 'application/json')
-  return c.json({
-    jsonrpc: '2.0',
-    error: {
-      code: -32000,
-      message: 'Method Not Allowed: Use POST to send MCP requests',
-    },
-    id: null,
-  })
-}
-
-const app = new Hono()
-app.use(trimTrailingSlash())
-
-app.get('/mcp-health', async (c) => {
-  return c.json({
-    status: 'healthy',
-    timestamp: new Date().toISOString(),
-    version: packageJson.version,
-    service: 'youdotcom-mcp-server',
-  })
-})
-
-// POST handler for MCP requests (per MCP Streamable HTTP spec)
-app.post('/mcp', handleMcpRequest)
-app.post('/mcp/', handleMcpRequest)
-
-// Fallback for other methods - returns 405 per MCP spec
-// Spec: "The server MUST either return Content-Type: text/event-stream
-// or else return HTTP 405 Method Not Allowed"
-app.all('/mcp', return405MethodNotAllowed)
-app.all('/mcp/', return405MethodNotAllowed)
-
-export default app

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

@@ -1,69 +0,0 @@
-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) => {
-      const logger = getLogger(mcp)
-      try {
-        const response = await callResearch({
-          researchQuery,
-          YDC_API_KEY,
-          getUserAgent,
-        })
-
-        const sourceCount = response.output.sources.length
-
-        await logger({
-          level: 'info',
-          data: `Research successful for input: "${researchQuery.input.substring(0, 100)}" - ${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

@@ -1,19 +0,0 @@
-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({
-  content_type: 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

@@ -1,30 +0,0 @@
-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: {
-      content_type: 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,
-      })),
-    },
-  }
-}