@youdotcom-oss/mcp 2.0.8 → 2.1.0

package/README.md

@@ -5,6 +5,7 @@ The You.com MCP Server gives your AI agents **real-time access to the latest web
 ## Features
 
 - **Web and news search**: Comprehensive search using You.com's unified Search API with advanced search operators
+- **Research**: Comprehensive answers with cited sources, configurable effort (lite to exhaustive)
 - **Content extraction**: Extract and retrieve full content from web pages in markdown or HTML format
 - **Multiple transport protocols**: STDIO and Streamable HTTP support
 - **Bearer Token Authentication**: Secure API access in HTTP mode
@@ -180,13 +181,18 @@ For setup, follow the MCP installation [guide](https://zed.dev/docs/ai/mcp#as-cu
 
 ## Available tools
 
-This MCP server provides two tools that work seamlessly with your AI agent through natural language:
+This MCP server provides three tools that work seamlessly with your AI agent through natural language:
 
 ### you-search
 Comprehensive web and news search with advanced filtering capabilities. Perfect for finding current information, research articles, documentation, and news stories.
 
 **When to use**: When you need to search the web for information, filter by specific sites/file types, or get the latest news on a topic.
 
+### you-research
+Research with comprehensive answers and cited sources. Configurable effort levels (lite, standard, deep, exhaustive) let you trade speed for thoroughness.
+
+**When to use**: When you need in-depth answers to complex questions, research reports with citations, or thorough analysis that goes beyond simple search results.
+
 ### you-contents
 Extract full page content from URLs in markdown, HTML, or structured metadata formats. Useful for documentation analysis, content processing, SEO data extraction, and batch URL processing.
 
@@ -208,6 +214,12 @@ Here are common scenarios showing when and how to use each tool with natural lan
 - "Get the latest news about renewable energy from the past week"
 - "Find PDF files about machine learning algorithms"
 
+**Use you-research when:**
+- "Give me a comprehensive analysis of the current state of AI regulation"
+- "Research the pros and cons of WebAssembly vs JavaScript for performance-critical applications"
+- "What are the latest breakthroughs in quantum computing? Include sources."
+- "Provide a detailed comparison of React, Vue, and Svelte with citations"
+
 ### Content extraction & analysis
 
 **Use you-contents when:**
@@ -221,9 +233,9 @@ Here are common scenarios showing when and how to use each tool with natural lan
 ### Combined workflows
 
 Your AI agent can combine multiple tools in a single conversation:
-1. **Research + Extract**: "Search for the best TypeScript tutorials, then extract the content from the top 3 results"
-2. **Question + Deep Dive**: "What is WebAssembly? Then search for real-world examples and extract code samples"
-3. **News + Analysis**: "Find recent articles about AI regulation, then summarize the key points"
+1. **Search + Extract**: "Search for the best TypeScript tutorials, then extract the content from the top 3 results"
+2. **Research + Deep Dive**: "Research WebAssembly performance benefits, then extract code samples from the cited sources"
+3. **News + Research**: "Find recent articles about AI regulation, then research the policy implications"
 
 ### Pro tips
 

package/bin/stdio.js

@@ -4,25 +4,43 @@ var __getProtoOf = Object.getPrototypeOf;
 var __defProp = Object.defineProperty;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
+function __accessProp(key) {
+  return this[key];
+}
+var __toESMCache_node;
+var __toESMCache_esm;
 var __toESM = (mod, isNodeMode, target) => {
+  var canCache = mod != null && typeof mod === "object";
+  if (canCache) {
+    var cache = isNodeMode ? __toESMCache_node ??= new WeakMap : __toESMCache_esm ??= new WeakMap;
+    var cached = cache.get(mod);
+    if (cached)
+      return cached;
+  }
   target = mod != null ? __create(__getProtoOf(mod)) : {};
   const to = isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target;
   for (let key of __getOwnPropNames(mod))
     if (!__hasOwnProp.call(to, key))
       __defProp(to, key, {
-        get: () => mod[key],
+        get: __accessProp.bind(mod, key),
         enumerable: true
       });
+  if (canCache)
+    cache.set(mod, to);
   return to;
 };
 var __commonJS = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __returnValue = (v) => v;
+function __exportSetter(name, newValue) {
+  this[name] = __returnValue.bind(null, newValue);
+}
 var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, {
       get: all[name],
       enumerable: true,
       configurable: true,
-      set: (newValue) => all[name] = () => newValue
+      set: __exportSetter.bind(all, name)
     });
 };
 
@@ -6498,7 +6516,7 @@ var require_dist = __commonJS((exports, module) => {
   exports.default = formatsPlugin;
 });
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 import process3 from "node:process";
 
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
@@ -20034,7 +20052,7 @@ function date4(params) {
 // ../../node_modules/.bun/zod@4.3.6/node_modules/zod/v4/classic/external.js
 config(en_default());
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/types.js
 var LATEST_PROTOCOL_VERSION = "2025-11-25";
 var SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, "2025-06-18", "2025-03-26", "2024-11-05", "2024-10-07"];
 var RELATED_TASK_META_KEY = "io.modelcontextprotocol/related-task";
@@ -20876,7 +20894,7 @@ class UrlElicitationRequiredError extends McpError {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
 class ReadBuffer {
   append(chunk) {
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
@@ -20906,7 +20924,7 @@ function serializeMessage(message) {
 `;
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 class StdioServerTransport {
   constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
     this._stdin = _stdin;
@@ -20990,7 +21008,7 @@ var ContentsItemSchema = object({
 var ContentsApiResponseSchema = array(ContentsItemSchema);
 // ../api/src/shared/api.constants.ts
 var SEARCH_API_URL = process.env.YDC_SEARCH_API_URL || "https://api.you.com/v1/agents/search";
-var DEEP_SEARCH_API_URL = process.env.YDC_DEEP_SEARCH_API_URL || "https://api.you.com/v1/deep_search";
+var RESEARCH_API_URL = process.env.YDC_RESEARCH_API_URL || "https://api.you.com/v1/research";
 var CONTENTS_API_URL = process.env.YDC_CONTENTS_API_URL || "https://ydc-index.io/v1/contents";
 
 // ../api/src/shared/check-response-for-errors.ts
@@ -21057,21 +21075,89 @@ var fetchContents = async ({
   const parsedResults = ContentsApiResponseSchema.parse(results);
   return parsedResults;
 };
-// ../api/src/deep-search/deep-search.schemas.ts
-var SearchEffortSchema = _enum2(["low", "medium", "high"]).describe("Search effort level");
-var DeepSearchQuerySchema = object({
-  query: string2().min(1, "Query is required").describe("The research question or complex query requiring in-depth investigation and multi-step reasoning"),
-  search_effort: SearchEffortSchema.optional().default("medium").describe("Computation budget: low (<30s), medium (<60s, default), high (<300s)")
+// ../api/src/research/research.schemas.ts
+var ResearchEffortSchema = _enum2(["lite", "standard", "deep", "exhaustive"]).describe("Controls how much time and effort the Research API spends on your question. Higher effort levels run more searches and dig deeper into sources, at the cost of a longer response time.");
+var ResearchQuerySchema = object({
+  input: string2().min(1, "Input is required").describe("The research question or complex query requiring in-depth investigation and multi-step reasoning. Maximum length: 40,000 characters."),
+  research_effort: ResearchEffortSchema.optional().default("standard").describe("Controls how much time and effort the Research API spends on your question. lite: fast answers, standard: balanced (default), deep: thorough, exhaustive: most comprehensive.")
 });
-var DeepSearchSourceSchema = object({
+var ResearchSourceSchema = object({
   url: string2().describe("Source webpage URL"),
-  title: string2().describe("Source webpage title"),
+  title: string2().optional().describe("Source webpage title"),
   snippets: array(string2()).describe("Relevant excerpts from the source page used in generating the answer")
 });
-var DeepSearchResponseSchema = object({
-  answer: string2().describe("Comprehensive response with inline citations, formatted in Markdown"),
-  results: array(DeepSearchSourceSchema).describe("List of web sources used to generate the answer")
+var ResearchOutputSchema = object({
+  content: string2().describe("Comprehensive response with inline citations, formatted in Markdown"),
+  content_type: _enum2(["text"]).describe("The format of the content field"),
+  sources: array(ResearchSourceSchema).describe("List of web sources used to generate the answer")
 });
+var ResearchResponseSchema = object({
+  output: ResearchOutputSchema.describe("The research output containing the answer and sources")
+});
+// ../api/src/research/research.utils.ts
+var callResearch = async ({
+  researchQuery,
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  getUserAgent
+}) => {
+  if (!YDC_API_KEY) {
+    throw new Error("YDC_API_KEY is required for Research API");
+  }
+  const response = await fetch(RESEARCH_API_URL, {
+    method: "POST",
+    headers: new Headers({
+      "X-API-Key": YDC_API_KEY,
+      "Content-Type": "application/json",
+      "User-Agent": getUserAgent()
+    }),
+    body: JSON.stringify(researchQuery)
+  });
+  if (!response.ok) {
+    const errorCode = response.status;
+    if (errorCode === 429) {
+      throw new Error("Rate limited by You.com API. Please try again later.");
+    } else if (errorCode === 403) {
+      throw new Error("Forbidden. Please check your You.com API key.");
+    } else if (errorCode === 402) {
+      throw new Error("Free tier limit exceeded. Please upgrade at: https://you.com/platform");
+    }
+    throw new Error(`Research API request failed. Error code: ${errorCode}`);
+  }
+  const data = await response.json();
+  checkResponseForErrors(data);
+  return ResearchResponseSchema.parse(data);
+};
+var formatResearchResponse = (response) => {
+  const parts = [];
+  parts.push(`# Answer
+`);
+  parts.push(response.output.content);
+  parts.push(`
+`);
+  if (response.output.sources.length > 0) {
+    parts.push(`
+## Sources
+`);
+    for (const [index, source] of response.output.sources.entries()) {
+      parts.push(`
+### ${index + 1}. ${source.title ?? source.url}
+`);
+      parts.push(`**URL:** ${source.url}
+`);
+      if (source.snippets.length > 0) {
+        parts.push(`
+**Key Excerpts:**
+`);
+        for (const snippet of source.snippets) {
+          parts.push(`> ${snippet}
+`);
+        }
+      }
+    }
+  }
+  return parts.join(`
+`);
+};
 // ../api/src/search/search.schemas.ts
 var LanguageSchema = _enum2([
   "AR",
@@ -21157,7 +21243,6 @@ var SearchQuerySchema = object({
     "CN",
     "PL",
     "PT",
-    "PT-BR",
     "PH",
     "RU",
     "SA",
@@ -25315,7 +25400,7 @@ function object2(shape, params) {
   };
   return new ZodMiniObject(def);
 }
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-compat.js
 function isZ4Schema(s) {
   const schema = s;
   return !!schema._zod;
@@ -25459,7 +25544,7 @@ function getLiteralValue(schema) {
   return;
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/interfaces.js
 function isTerminal(status) {
   return status === "completed" || status === "failed" || status === "cancelled";
 }
@@ -26700,7 +26785,7 @@ var zodToJsonSchema = (schema, options) => {
   }
   return combined;
 };
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/zod-json-schema-compat.js
 function mapMiniTarget(t) {
   if (!t)
     return "draft-7";
@@ -26742,7 +26827,7 @@ function parseWithCompat(schema, data) {
   return result.data;
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/protocol.js
 var DEFAULT_REQUEST_TIMEOUT_MSEC = 60000;
 
 class Protocol {
@@ -27577,7 +27662,7 @@ function mergeCapabilities(base, additional) {
   return result;
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/validation/ajv-provider.js
 var import_ajv = __toESM(require_ajv(), 1);
 var import_ajv_formats = __toESM(require_dist(), 1);
 function createDefaultAjvInstance() {
@@ -27617,7 +27702,7 @@ class AjvJsonSchemaValidator {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/server.js
 class ExperimentalServerTasks {
   constructor(_server) {
     this._server = _server;
@@ -27695,7 +27780,7 @@ class ExperimentalServerTasks {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/helpers.js
 function assertToolsCallTaskCapability(requests, method, entityName) {
   if (!requests) {
     throw new Error(`${entityName} does not support task creation (required for ${method})`);
@@ -27730,7 +27815,7 @@ function assertClientRequestTaskCapability(requests, method, entityName) {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/index.js
 class Server extends Protocol {
   constructor(_serverInfo, options) {
     super(options);
@@ -28063,7 +28148,7 @@ class Server extends Protocol {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/completable.js
 var COMPLETABLE_SYMBOL = Symbol.for("mcp.completable");
 function isCompletable(schema) {
   return !!schema && typeof schema === "object" && COMPLETABLE_SYMBOL in schema;
@@ -28077,7 +28162,7 @@ var McpZodTypeKind;
   McpZodTypeKind2["Completable"] = "McpCompletable";
 })(McpZodTypeKind || (McpZodTypeKind = {}));
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/shared/toolNameValidation.js
 var TOOL_NAME_REGEX = /^[A-Za-z0-9._-]{1,128}$/;
 function validateToolName(name) {
   const warnings = [];
@@ -28135,7 +28220,7 @@ function validateAndWarnToolName(name) {
   return result.isValid;
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/experimental/tasks/mcp-server.js
 class ExperimentalMcpServerTasks {
   constructor(_mcpServer) {
     this._mcpServer = _mcpServer;
@@ -28150,7 +28235,7 @@ class ExperimentalMcpServerTasks {
   }
 }
 
-// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.0+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
+// ../../node_modules/.bun/@modelcontextprotocol+sdk@1.27.1+702d06f8eea47248/node_modules/@modelcontextprotocol/sdk/dist/esm/server/mcp.js
 class McpServer {
   constructor(serverInfo, options) {
     this._registeredResources = {};
@@ -28872,7 +28957,7 @@ var EMPTY_COMPLETION_RESULT = {
 // package.json
 var package_default = {
   name: "@youdotcom-oss/mcp",
-  version: "2.0.8",
+  version: "2.1.0",
   description: "You.com API Model Context Protocol Server - For programmatic API access, use @youdotcom-oss/api",
   license: "MIT",
   engines: {
@@ -28928,7 +29013,7 @@ var package_default = {
   },
   mcpName: "io.github.youdotcom-oss/mcp",
   dependencies: {
-    "@youdotcom-oss/api": "0.3.4",
+    "@youdotcom-oss/api": "0.4.0",
     zod: "^4.3.6",
     "@hono/mcp": "^0.2.3",
     "@modelcontextprotocol/sdk": "^1.25.3",
@@ -28951,6 +29036,92 @@ var getMCpServer = () => new McpServer({
   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.`
 });
 
+// src/research/research.schemas.ts
+var ResearchStructuredContentSchema = object({
+  content_type: string2().describe("Format of the content field"),
+  sourceCount: number2().describe("Number of sources used"),
+  sources: array(object({
+    url: string2().describe("Source URL"),
+    title: string2().optional().describe("Source title"),
+    snippetCount: number2().describe("Number of excerpts from this source")
+  })).describe("Sources used in the research answer")
+});
+
+// src/research/research.utils.ts
+var formatResearchResults = (response) => {
+  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
+      }))
+    }
+  };
+};
+
+// src/research/register-research-tool.ts
+var registerResearchTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent
+}) => {
+  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) {
+      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}
+
+Report this issue: ${reportLink}`
+      });
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${errorMessage}`
+          }
+        ],
+        structuredContent: undefined,
+        isError: true
+      };
+    }
+  });
+};
+
 // src/search/search.schema.ts
 var SearchStructuredContentSchema = object({
   resultCounts: object({
@@ -29154,6 +29325,7 @@ try {
   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 StdioServerTransport;
   await mcp.connect(transport);
 } catch (error48) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "2.0.8",
+  "version": "2.1.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.3.4",
+    "@youdotcom-oss/api": "0.4.0",
     "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 },
+  )
+})