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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "2.1.1",
-  "description": "You.com API Model Context Protocol Server - For programmatic API access, use @youdotcom-oss/api",
+  "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",
@@ -20,49 +20,43 @@
   "keywords": [
     "mcp",
     "web search",
-    "model context protocol"
+    "model context protocol",
+    "ai research"
   ],
   "bin": "bin/stdio.js",
   "type": "module",
   "exports": {
-    "./http": "./src/http.ts"
+    ".": "./src/main.ts"
   },
   "files": [
     "bin/stdio.js",
-    "./dist/**",
-    "./src/**",
-    "!./src/**/tests/*",
-    "!./src/**/*.spec.@(tsx|ts)"
+    "src",
+    "server.json"
   ],
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "bun build ./src/stdio.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.ts",
+    "dev": "bun src/stdio-server.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.1",
-    "zod": "^4.3.6",
-    "@hono/mcp": "^0.2.3",
-    "@modelcontextprotocol/sdk": "^1.25.3",
-    "hono": "^4.11.7"
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@youdotcom-oss/api": "0.5.1",
+    "zod": "^4.3.6"
   },
   "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.utils.ts

@@ -35,11 +35,12 @@ export const formatContentsResponse = (
     }
 
     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)')
+        textParts.push('...\n(truncated for display — full HTML available in structuredContent)')
       }
       textParts.push('\n')
     }

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

@@ -26,12 +26,11 @@ export const registerContentsTool = ({
       inputSchema: ContentsQuerySchema.shape,
       outputSchema: ContentsStructuredContentSchema.shape,
     },
-    async (toolInput) => {
-      const logger = getLogger(mcp)
+    async (contentsQuery, { sendNotification }) => {
+      const logger = getLogger(sendNotification)
 
       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']

package/src/get-mcp-server.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import packageJson from '../package.json' with { type: 'json' }
 
-export const getMCpServer = () =>
+export const getMcpServer = () =>
   new McpServer(
     {
       name: 'You.com',

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

@@ -22,8 +22,8 @@ export const registerResearchTool = ({
       inputSchema: ResearchQuerySchema.shape,
       outputSchema: ResearchStructuredContentSchema.shape,
     },
-    async (researchQuery) => {
-      const logger = getLogger(mcp)
+    async (researchQuery, { sendNotification }) => {
+      const logger = getLogger(sendNotification)
       try {
         const response = await callResearch({
           researchQuery,
@@ -35,7 +35,7 @@ export const registerResearchTool = ({
 
         await logger({
           level: 'info',
-          data: `Research successful for input: "${researchQuery.input.substring(0, 100)}" - ${sourceCount} source(s)`,
+          data: `Research for "${researchQuery.input.substring(0, 100)}" complete: ${sourceCount} source(s)`,
         })
 
         const { content, structuredContent } = formatResearchResults(response)

package/src/research/research.schemas.ts

@@ -3,7 +3,7 @@ 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'),
+  contentType: z.string().describe('Format of the content field'),
   sourceCount: z.number().describe('Number of sources used'),
   sources: z
     .array(

package/src/research/research.utils.ts

@@ -18,12 +18,12 @@ export const formatResearchResults = (
       },
     ],
     structuredContent: {
-      content_type: response.output.content_type,
+      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,
+        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.')
+  })
+})

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

@@ -1,7 +1,7 @@
 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 { SearchStructuredContentSchema } from './search.schemas.ts'
 import { formatSearchResults } from './search.utils.ts'
 
 export const registerSearchTool = ({
@@ -21,8 +21,8 @@ export const registerSearchTool = ({
       inputSchema: SearchQuerySchema.shape,
       outputSchema: SearchStructuredContentSchema.shape,
     },
-    async (searchQuery) => {
-      const logger = getLogger(mcp)
+    async (searchQuery, { sendNotification }) => {
+      const logger = getLogger(sendNotification)
       try {
         const response = await fetchSearchResults({
           searchQuery,

package/src/shared/get-logger.ts

@@ -1,10 +1,19 @@
-import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
-import type { LoggingMessageNotification } from '@modelcontextprotocol/sdk/types.js'
+import type { LoggingMessageNotification, ServerNotification } from '@modelcontextprotocol/sdk/types.js'
 
 /**
- * Creates a logger function that sends messages through MCP server
- * Used by tool registration files
+ * 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 = (mcp: McpServer) => async (params: LoggingMessageNotification['params']) => {
-  await mcp.server.sendLoggingMessage(params)
-}
+export const getLogger =
+  (sendNotification: (notification: ServerNotification) => Promise<void>) =>
+  async (params: LoggingMessageNotification['params']) => {
+    await sendNotification({ method: 'notifications/message', params })
+  }

package/src/{stdio.ts → stdio-server.ts}

@@ -1,15 +1,15 @@
 #!/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 { 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
+const YDC_API_KEY = process.env.YDC_API_KEY || undefined
 
 try {
-  const mcp = getMCpServer()
+  const mcp = getMcpServer()
   const getUserAgent = useGetClientVersion(mcp)
 
   registerSearchTool({ mcp, YDC_API_KEY, getUserAgent })
@@ -19,6 +19,6 @@ try {
   const transport = new StdioServerTransport()
   await mcp.connect(transport)
 } catch (error) {
-  process.stderr.write(`Failed to start server: ${error}\n`)
+  process.stderr.write(`Failed to start MCP server: ${error}\n`)
   process.exit(1)
 }

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