@youdotcom-oss/mcp 1.3.2 → 1.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.3.2",
+  "version": "1.3.4",
   "description": "You.com API Model Context Protocol Server",
   "license": "MIT",
   "engines": {
@@ -23,8 +23,16 @@
   ],
   "bin": "bin/stdio.js",
   "type": "module",
+  "main": "./src/main.ts",
+  "exports": {
+    ".": "./src/main.ts"
+  },
   "files": [
     "bin/stdio.js",
+    "src/**/*.schemas.ts",
+    "src/**/*.utils.ts",
+    "src/shared/check-response-for-errors.ts",
+    "src/shared/format-search-results-text.ts",
     "AGENTS.md",
     "CONTRIBUTING.md",
     "docs/API.md"
@@ -64,8 +72,11 @@
       "format-package --write"
     ]
   },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
   "devDependencies": {
-    "@biomejs/biome": "2.3.6",
+    "@biomejs/biome": "2.3.8",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@eslint/js": "9.39.1",
@@ -75,10 +86,9 @@
     "lint-staged": "^16.2.7",
     "format-package": "^7.0.0",
     "@hono/bun-compress": "0.1.0",
-    "@hono/mcp": "0.1.5",
-    "@modelcontextprotocol/sdk": "1.22.0",
-    "hono": "^4.10.6",
-    "neverthrow": "8.2.0",
-    "zod": "3.25.76"
+    "@hono/mcp": "0.2.0",
+    "@modelcontextprotocol/sdk": "1.24.2",
+    "hono": "^4.10.7",
+    "zod": "4.1.13"
   }
 }

package/src/contents/contents.schemas.ts

@@ -0,0 +1,55 @@
+import * as z from 'zod';
+
+/**
+ * Input schema for the you-contents tool
+ * Accepts an array of URLs and optional format
+ */
+export const ContentsQuerySchema = z.object({
+  urls: z.array(z.string().url()).min(1).describe('URLs to extract content from'),
+  format: z
+    .enum(['markdown', 'html'])
+    .optional()
+    .default('markdown')
+    .describe('Output format: markdown (text) or html (layout)'),
+});
+
+export type ContentsQuery = z.infer<typeof ContentsQuerySchema>;
+
+/**
+ * Schema for a single content item in the API response
+ */
+const ContentsItemSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().optional().describe('Title'),
+  html: z.string().optional().describe('HTML content'),
+  markdown: z.string().optional().describe('Markdown content'),
+});
+
+/**
+ * API response schema from You.com Contents API
+ * Validates the full response array
+ */
+export const ContentsApiResponseSchema = z.array(ContentsItemSchema);
+
+export type ContentsApiResponse = z.infer<typeof ContentsApiResponseSchema>;
+
+/**
+ * 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'),
+  format: z.string().describe('Content format'),
+  items: z
+    .array(
+      z.object({
+        url: z.string().describe('URL'),
+        title: z.string().optional().describe('Title'),
+        content: z.string().describe('Extracted content'),
+        contentLength: z.number().describe('Content length'),
+      }),
+    )
+    .describe('Extracted items'),
+});
+
+export type ContentsStructuredContent = z.infer<typeof ContentsStructuredContentSchema>;

package/src/contents/contents.utils.ts

@@ -0,0 +1,145 @@
+import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
+import {
+  type ContentsApiResponse,
+  ContentsApiResponseSchema,
+  type ContentsQuery,
+  type ContentsStructuredContent,
+} from './contents.schemas.ts';
+
+const CONTENTS_API_URL = 'https://ydc-index.io/v1/contents';
+
+/**
+ * Fetch content from You.com Contents API
+ * The API accepts multiple URLs in a single request and returns all results
+ * @param contentsQuery - Query parameters including URLs and format
+ * @param YDC_API_KEY - You.com API key
+ * @param getUserAgent - Function to get User-Agent string
+ * @returns Parsed and validated API response
+ */
+export const fetchContents = async ({
+  contentsQuery: { urls, format = 'markdown' },
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  getUserAgent,
+}: {
+  contentsQuery: ContentsQuery;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}): Promise<ContentsApiResponse> => {
+  if (!YDC_API_KEY) {
+    throw new Error('YDC_API_KEY is required for Contents API');
+  }
+
+  // Make single API call with all URLs
+  const options = {
+    method: 'POST',
+    headers: new Headers({
+      'X-API-Key': YDC_API_KEY,
+      'Content-Type': 'application/json',
+      'User-Agent': getUserAgent(),
+    }),
+    body: JSON.stringify({
+      urls,
+      format,
+    }),
+  };
+
+  const response = await fetch(CONTENTS_API_URL, options);
+
+  // Handle HTTP errors
+  if (!response.ok) {
+    const errorCode = response.status;
+
+    // Try to parse error response body
+    let errorDetail = `Failed to fetch contents. HTTP ${errorCode}`;
+    try {
+      const errorBody = await response.json();
+      if (errorBody && typeof errorBody === 'object' && 'detail' in errorBody) {
+        errorDetail = String(errorBody.detail);
+      }
+    } catch {
+      // If parsing fails, use default error message
+    }
+
+    // Handle specific error codes
+    if (errorCode === 401) {
+      throw new Error(`Authentication failed: ${errorDetail}. Please check your You.com API key.`);
+    }
+    if (errorCode === 403) {
+      throw new Error(`Forbidden: ${errorDetail}. Your API key may not have access to the Contents API.`);
+    }
+    if (errorCode === 429) {
+      throw new Error('Rate limited by You.com API. Please try again later.');
+    }
+    if (errorCode >= 500) {
+      throw new Error(`You.com API server error: ${errorDetail}`);
+    }
+
+    throw new Error(errorDetail);
+  }
+
+  const results = await response.json();
+
+  // Check for error field in 200 responses
+  checkResponseForErrors(results);
+
+  // Validate schema
+  const parsedResults = ContentsApiResponseSchema.parse(results);
+
+  return parsedResults;
+};
+
+/**
+ * Format contents API response for MCP output
+ * Returns full content in both text and structured formats
+ * @param response - Validated API response
+ * @param format - Format used for extraction
+ * @returns Formatted response with content and structuredContent
+ */
+export const formatContentsResponse = (
+  response: ContentsApiResponse,
+  format: 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`];
+
+  const items: ContentsStructuredContent['items'] = [];
+
+  for (const item of response) {
+    const contentField = format === 'html' ? item.html : item.markdown;
+    const content = contentField || '';
+
+    // Add full content for this item
+    textParts.push(`\n## ${item.title}`);
+    textParts.push(`URL: ${item.url}`);
+    textParts.push(`Format: ${format}`);
+    textParts.push(`Content Length: ${content.length} characters\n`);
+    textParts.push('---\n');
+    textParts.push(content);
+    textParts.push('\n---\n');
+
+    // Add to structured content with full content
+    items.push({
+      url: item.url,
+      title: item.title,
+      content,
+      contentLength: content.length,
+    });
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: textParts.join('\n'),
+      },
+    ],
+    structuredContent: {
+      count: response.length,
+      format,
+      items,
+    },
+  };
+};

package/src/express/express.schemas.ts

@@ -0,0 +1,99 @@
+import * as z from 'zod';
+
+export const ExpressAgentInputSchema = z.object({
+  input: z.string().min(1, 'Input is required').describe('Query or prompt'),
+  tools: z
+    .array(
+      z.object({
+        type: z.enum(['web_search']).describe('Tool type'),
+      }),
+    )
+    .optional()
+    .describe('Tools (web search only)'),
+});
+
+export type ExpressAgentInput = z.infer<typeof ExpressAgentInputSchema>;
+
+// API Response Schema - Validates the full response from You.com API
+
+// Search result content item from web_search.results
+// Note: thumbnail_url, source_type, and provider are API-only pass-through fields not used in MCP output
+const ApiSearchResultItemSchema = z.object({
+  source_type: z.string().optional(),
+  citation_uri: z.string().optional(), // Used as fallback for url in transformation
+  url: z.string(),
+  title: z.string(),
+  snippet: z.string(),
+  thumbnail_url: z.string().optional(), // API-only, not transformed to MCP output
+  provider: z.any().optional(), // API-only, not transformed to MCP output
+});
+
+// Union of possible output item types from API
+const ExpressAgentApiOutputItemSchema = z.union([
+  // web_search.results type - has content array, no text
+  z.object({
+    type: z.literal('web_search.results'),
+    content: z.array(ApiSearchResultItemSchema),
+  }),
+  // message.answer type - has text, no content
+  z.object({
+    type: z.literal('message.answer'),
+    text: z.string(),
+  }),
+]);
+
+export const ExpressAgentApiResponseSchema = z
+  .object({
+    output: z.array(ExpressAgentApiOutputItemSchema),
+    agent: z.string().optional().describe('Agent identifier'),
+    mode: z.string().optional().describe('Agent mode'),
+    input: z.array(z.any()).optional().describe('Input messages'),
+  })
+  .passthrough();
+
+export type ExpressAgentApiResponse = z.infer<typeof ExpressAgentApiResponseSchema>;
+
+// MCP Output Schema - Defines what we return to the MCP client (answer + optional search results, token efficient)
+
+// Search result item for MCP output
+const McpSearchResultItemSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().describe('Title'),
+  snippet: z.string().describe('Snippet'),
+});
+
+// MCP response structure: answer (always) + results (optional when web_search used)
+const ExpressAgentMcpResponseSchema = z.object({
+  answer: z.string().describe('AI answer'),
+  results: z
+    .object({
+      web: z.array(McpSearchResultItemSchema).describe('Web results'),
+    })
+    .optional()
+    .describe('Search results'),
+  agent: z.string().optional().describe('Agent ID'),
+});
+
+export type ExpressAgentMcpResponse = z.infer<typeof ExpressAgentMcpResponseSchema>;
+
+// Minimal schema for structuredContent (reduces payload duplication)
+export const ExpressStructuredContentSchema = z.object({
+  answer: z.string().describe('AI answer'),
+  hasResults: z.boolean().describe('Has web results'),
+  resultCount: z.number().describe('Result count'),
+  agent: z.string().optional().describe('Agent ID'),
+  results: z
+    .object({
+      web: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+          }),
+        )
+        .optional()
+        .describe('Web results'),
+    })
+    .optional()
+    .describe('Search results'),
+});

package/src/express/express.utils.ts

@@ -0,0 +1,157 @@
+import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
+import { formatSearchResultsText } from '../shared/format-search-results-text.ts';
+import {
+  type ExpressAgentApiResponse,
+  ExpressAgentApiResponseSchema,
+  type ExpressAgentInput,
+  type ExpressAgentMcpResponse,
+} from './express.schemas.ts';
+
+// Express Agent Constants
+const AGENTS_RUN_URL = 'https://api.you.com/v1/agents/runs';
+
+/**
+ * Checks response status and throws appropriate errors for agent API calls
+ */
+const agentThrowOnFailedStatus = async (response: Response) => {
+  const errorCode = response.status;
+
+  const errorData = (await response.json()) as {
+    errors?: Array<{ detail?: string }>;
+  };
+
+  if (errorCode === 400) {
+    throw new Error(`Bad Request:\n${JSON.stringify(errorData)}`);
+  } else if (errorCode === 401) {
+    throw new Error(
+      `Unauthorized: The Agent APIs require a valid You.com API key with agent access. Ensure your YDC_API_KEY has permissions for agent endpoints.`,
+    );
+  } else if (errorCode === 403) {
+    throw new Error(`Forbidden: You are not allowed to use the requested tool for this agent or tenant`);
+  } else if (errorCode === 429) {
+    throw new Error('Rate limited by You.com API. Please try again later.');
+  }
+  throw new Error(`Failed to call agent. Error code: ${errorCode}`);
+};
+
+export const callExpressAgent = async ({
+  YDC_API_KEY = process.env.YDC_API_KEY,
+  agentInput: { input, tools },
+  getUserAgent,
+}: {
+  agentInput: ExpressAgentInput;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}) => {
+  const requestBody: {
+    agent: string;
+    input: string;
+    stream: boolean;
+    tools?: Array<{ type: 'web_search' }>;
+  } = {
+    agent: 'express',
+    input,
+    stream: false, // Use non-streaming JSON response
+  };
+
+  // Only include tools if provided
+  if (tools) {
+    requestBody.tools = tools;
+  }
+
+  const options = {
+    method: 'POST',
+    headers: new Headers({
+      Authorization: `Bearer ${YDC_API_KEY || ''}`,
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      'User-Agent': getUserAgent(),
+    }),
+    body: JSON.stringify(requestBody),
+  };
+
+  const response = await fetch(AGENTS_RUN_URL, options);
+
+  if (!response.ok) {
+    await agentThrowOnFailedStatus(response);
+  }
+
+  // Parse JSON response directly
+  const jsonResponse = await response.json();
+
+  // Check for error field in response
+  checkResponseForErrors(jsonResponse);
+
+  // Validate API response schema (full response with all fields)
+  const apiResponse: ExpressAgentApiResponse = ExpressAgentApiResponseSchema.parse(jsonResponse);
+
+  // Find the answer (always present as message.answer, validated by Zod)
+  const answerItem = apiResponse.output.find((item) => item.type === 'message.answer');
+  if (!answerItem) {
+    throw new Error('Express API response missing required message.answer item');
+  }
+
+  // Find search results (optional, present when web_search tool is used)
+  const searchItem = apiResponse.output.find((item) => item.type === 'web_search.results');
+
+  // Transform API response to MCP output format (answer + optional search results, token efficient)
+  const mcpResponse: ExpressAgentMcpResponse = {
+    answer: answerItem.text,
+    agent: apiResponse.agent,
+  };
+
+  // Transform search results if present
+  if (searchItem && 'content' in searchItem && Array.isArray(searchItem.content)) {
+    mcpResponse.results = {
+      web: searchItem.content.map((item) => ({
+        url: item.url || item.citation_uri || '',
+        title: item.title || '',
+        snippet: item.snippet || '',
+      })),
+    };
+  }
+
+  return mcpResponse;
+};
+
+export const formatExpressAgentResponse = (response: ExpressAgentMcpResponse) => {
+  const _agentId = response.agent || 'express';
+  const content: Array<{ type: 'text'; text: string }> = [];
+
+  // 1. Answer first (always present)
+  content.push({
+    type: 'text',
+    text: `Express Agent Answer:\n\n${response.answer}`,
+  });
+
+  // 2. Search results second (if present when web_search tool was used) - without URLs in text
+  if (response.results?.web?.length) {
+    const formattedResults = formatSearchResultsText(response.results.web);
+    content.push({
+      type: 'text',
+      text: `\nSearch Results:\n\n${formattedResults}`,
+    });
+  }
+
+  // Extract URLs and titles for structuredContent
+  const structuredResults = response.results?.web?.length
+    ? {
+        web: response.results.web.map((result) => ({
+          url: result.url,
+          title: result.title,
+        })),
+      }
+    : undefined;
+
+  return {
+    content,
+    structuredContent: {
+      answer: response.answer,
+      hasResults: !!response.results?.web?.length,
+      resultCount: response.results?.web?.length || 0,
+      agent: response.agent,
+      results: structuredResults,
+    },
+    fullResponse: response,
+  };
+};

package/src/search/search.schemas.ts

@@ -0,0 +1,126 @@
+import * as z from 'zod';
+
+export const SearchQuerySchema = z.object({
+  query: z.string().min(1, 'Query is required').describe('Search query (supports +, -, site:, filetype:, lang:)'),
+  count: z.number().int().min(1).max(20).optional().describe('Max results per section'),
+  freshness: z.enum(['day', 'week', 'month', 'year']).optional().describe('Filter by freshness'),
+  offset: z.number().int().min(0).max(9).optional().describe('Pagination offset'),
+  country: z
+    .enum([
+      'AR',
+      'AU',
+      'AT',
+      'BE',
+      'BR',
+      'CA',
+      'CL',
+      'DK',
+      'FI',
+      'FR',
+      'DE',
+      'HK',
+      'IN',
+      'ID',
+      'IT',
+      'JP',
+      'KR',
+      'MY',
+      'MX',
+      'NL',
+      'NZ',
+      'NO',
+      'CN',
+      'PL',
+      'PT',
+      'PH',
+      'RU',
+      'SA',
+      'ZA',
+      'ES',
+      'SE',
+      'CH',
+      'TW',
+      'TR',
+      'GB',
+      'US',
+    ])
+    .optional()
+    .describe('Country code'),
+  safesearch: z.enum(['off', 'moderate', 'strict']).optional().describe('Filter level'),
+  site: z.string().optional().describe('Specific domain'),
+  fileType: z.string().optional().describe('File type'),
+  language: z.string().optional().describe('ISO 639-1 language code'),
+  excludeTerms: z.string().optional().describe('Terms to exclude (pipe-separated)'),
+  exactTerms: z.string().optional().describe('Exact terms (pipe-separated)'),
+});
+
+export type SearchQuery = z.infer<typeof SearchQuerySchema>;
+
+const WebResultSchema = z.object({
+  url: z.string().describe('URL'),
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  snippets: z.array(z.string()).describe('Content snippets'),
+  page_age: z.string().optional().describe('Publication timestamp'),
+  authors: z.array(z.string()).optional().describe('Authors'),
+});
+
+const NewsResultSchema = z.object({
+  title: z.string().describe('Title'),
+  description: z.string().describe('Description'),
+  page_age: z.string().describe('Publication timestamp'),
+  url: z.string().describe('URL'),
+});
+
+export type NewsResult = z.infer<typeof NewsResultSchema>;
+
+const MetadataSchema = z.object({
+  request_uuid: z.string().optional().describe('Request ID'),
+  query: z.string().describe('Query'),
+  latency: z.number().describe('Latency in seconds'),
+});
+
+export const SearchResponseSchema = z.object({
+  results: z.object({
+    web: z.array(WebResultSchema).optional(),
+    news: z.array(NewsResultSchema).optional(),
+  }),
+  metadata: MetadataSchema.partial(),
+});
+
+export type SearchResponse = z.infer<typeof SearchResponseSchema>;
+
+// Minimal schema for structuredContent (reduces payload duplication)
+// Excludes metadata (query, request_uuid, latency) as these are not actionable by LLM
+export const SearchStructuredContentSchema = z.object({
+  resultCounts: z.object({
+    web: z.number().describe('Web results'),
+    news: z.number().describe('News results'),
+    total: z.number().describe('Total results'),
+  }),
+  results: z
+    .object({
+      web: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+          }),
+        )
+        .optional()
+        .describe('Web results'),
+      news: z
+        .array(
+          z.object({
+            url: z.string().describe('URL'),
+            title: z.string().describe('Title'),
+          }),
+        )
+        .optional()
+        .describe('News results'),
+    })
+    .optional()
+    .describe('Search results'),
+});
+
+export type SearchStructuredContent = z.infer<typeof SearchStructuredContentSchema>;