@youdotcom-oss/mcp 2.0.8 → 2.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "2.0.8",
+  "version": "2.1.1",
   "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.3.4",
+    "@youdotcom-oss/api": "0.4.1",
     "zod": "^4.3.6",
     "@hono/mcp": "^0.2.3",
     "@modelcontextprotocol/sdk": "^1.25.3",

package/src/http.ts

@@ -4,6 +4,7 @@ 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'
 
@@ -40,6 +41,7 @@ const handleMcpRequest = async (c: Context) => {
     getUserAgent,
   })
   registerContentsTool({ mcp, YDC_API_KEY, getUserAgent })
+  registerResearchTool({ mcp, YDC_API_KEY, getUserAgent })
 
   const transport = new StreamableHTTPTransport()
   await mcp.connect(transport)

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) => {
+      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

@@ -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({
+  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

@@ -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: {
+      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,
+      })),
+    },
+  }
+}

package/src/stdio.ts

@@ -2,6 +2,7 @@
 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'
 
@@ -13,6 +14,7 @@ try {
 
   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)

package/src/tests/tool.spec.ts

@@ -3,6 +3,7 @@ import { Client } from '@modelcontextprotocol/sdk/client/index.js'
 import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
 import { $ } from 'bun'
 import type { ContentsStructuredContent } from '../contents/contents.schemas.ts'
+import type { ResearchStructuredContent } from '../research/research.schemas.ts'
 import type { SearchStructuredContent } from '../search/search.schema.ts'
 
 let client: Client
@@ -521,3 +522,128 @@ describe('registerContentsTool', () => {
     { retry: 2 },
   )
 })
+
+describe('registerResearchTool', () => {
+  test('tool is registered and available', async () => {
+    const tools = await client.listTools()
+
+    const researchTool = tools.tools.find((t) => t.name === 'you-research')
+
+    expect(researchTool).toBeDefined()
+    expect(researchTool?.title).toBe('Research')
+    expect(researchTool?.description).toContain('Research a topic')
+  })
+
+  test(
+    'performs basic research successfully',
+    async () => {
+      const result = await client.callTool({
+        name: 'you-research',
+        arguments: {
+          input: 'What is TypeScript?',
+          research_effort: 'lite',
+        },
+      })
+
+      expect(result).toHaveProperty('content')
+      expect(result).toHaveProperty('structuredContent')
+
+      const content = result.content as { type: string; text: string }[]
+      expect(Array.isArray(content)).toBe(true)
+      expect(content[0]).toHaveProperty('type', 'text')
+      expect(content[0]).toHaveProperty('text')
+
+      const text = content[0]?.text
+      expect(typeof text).toBe('string')
+      expect(text?.length).toBeGreaterThan(0)
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'returns structured content with source information',
+    async () => {
+      const result = await client.callTool({
+        name: 'you-research',
+        arguments: {
+          input: 'What are the benefits of REST APIs?',
+          research_effort: 'lite',
+        },
+      })
+
+      const structuredContent = result.structuredContent as ResearchStructuredContent
+      expect(structuredContent).toHaveProperty('content_type', 'text')
+      expect(structuredContent).toHaveProperty('sourceCount')
+      expect(typeof structuredContent.sourceCount).toBe('number')
+      expect(structuredContent.sourceCount).toBeGreaterThan(0)
+
+      expect(structuredContent).toHaveProperty('sources')
+      expect(Array.isArray(structuredContent.sources)).toBe(true)
+      expect(structuredContent.sources.length).toBeGreaterThan(0)
+
+      const source = structuredContent.sources[0]
+      expect(source).toBeDefined()
+      expect(source).toHaveProperty('url')
+      expect(typeof source?.url).toBe('string')
+      expect(source).toHaveProperty('snippetCount')
+      expect(typeof source?.snippetCount).toBe('number')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'text content contains markdown with answer and sources',
+    async () => {
+      const result = await client.callTool({
+        name: 'you-research',
+        arguments: {
+          input: 'What is JWT authentication?',
+          research_effort: 'lite',
+        },
+      })
+
+      const content = result.content as { type: string; text: string }[]
+      const text = content[0]?.text
+      expect(text).toContain('# Answer')
+      expect(text).toContain('## Sources')
+    },
+    { retry: 2 },
+  )
+
+  test(
+    'handles research_effort parameter',
+    async () => {
+      const transport = new StdioClientTransport({
+        command: 'npx',
+        args: [Bun.resolveSync('../../bin/stdio', import.meta.dir)],
+        env: {
+          YDC_API_KEY: process.env.YDC_API_KEY ?? '',
+        },
+      })
+
+      const dedicatedClient = new Client({
+        name: 'test-client-research',
+        version: '0.0.1',
+      })
+
+      await dedicatedClient.connect(transport)
+
+      try {
+        const result = await dedicatedClient.callTool({
+          name: 'you-research',
+          arguments: {
+            input: 'Explain microservices architecture',
+            research_effort: 'standard',
+          },
+        })
+
+        const content = result.content as { type: string; text: string }[]
+        expect(content[0]).toHaveProperty('text')
+        expect(content[0]?.text?.length).toBeGreaterThan(0)
+      } finally {
+        await dedicatedClient.close()
+      }
+    },
+    { retry: 2, timeout: 120_000 },
+  )
+})