@youdotcom-oss/mcp 1.3.2 → 1.3.3

package/bin/stdio.js

@@ -11154,7 +11154,7 @@ class StdioServerTransport {
 // package.json
 var package_default = {
   name: "@youdotcom-oss/mcp",
-  version: "1.3.2",
+  version: "1.3.3",
   description: "You.com API Model Context Protocol Server",
   license: "MIT",
   engines: {
@@ -11177,8 +11177,16 @@ var package_default = {
   ],
   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"
@@ -11218,8 +11226,11 @@ var package_default = {
       "format-package --write"
     ]
   },
+  peerDependencies: {
+    zod: "^3.25.76"
+  },
   devDependencies: {
-    "@biomejs/biome": "2.3.6",
+    "@biomejs/biome": "2.3.7",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@eslint/js": "9.39.1",
@@ -11229,34 +11240,14 @@ var package_default = {
     "lint-staged": "^16.2.7",
     "format-package": "^7.0.0",
     "@hono/bun-compress": "0.1.0",
-    "@hono/mcp": "0.1.5",
+    "@hono/mcp": "0.2.0",
     "@modelcontextprotocol/sdk": "1.22.0",
     hono: "^4.10.6",
-    neverthrow: "8.2.0",
     zod: "3.25.76"
   }
 };
 
-// src/shared/shared.utils.ts
-var setUserAgent = (client) => `MCP/${package_default.version} (You.com; ${client})`;
-var useGetClientVersion = (mcp) => () => {
-  const clientVersion = mcp.server.getClientVersion();
-  if (clientVersion) {
-    const { name, version, title, websiteUrl } = clientVersion;
-    return setUserAgent([name, version, title, websiteUrl].filter(Boolean).join("; "));
-  }
-  return setUserAgent("UNKNOWN");
-};
-var getLogger = (mcp) => async (params, _sessionId) => {
-  await mcp.server.sendLoggingMessage(params);
-};
-var checkResponseForErrors = (responseData) => {
-  if (typeof responseData === "object" && responseData !== null && "error" in responseData) {
-    const errorMessage = typeof responseData.error === "string" ? responseData.error : JSON.stringify(responseData.error);
-    throw new Error(`You.com API Error: ${errorMessage}`);
-  }
-  return responseData;
-};
+// src/shared/generate-error-report-link.ts
 var generateErrorReportLink = ({
   errorMessage,
   tool,
@@ -11283,24 +11274,10 @@ Additional Context:
   });
   return `mailto:support@you.com?${params.toString()}`;
 };
-var formatSearchResultsText = (results) => {
-  return results.map((result) => {
-    const parts = [`Title: ${result.title}`];
-    if (result.description) {
-      parts.push(`Description: ${result.description}`);
-    }
-    if (result.snippets && result.snippets.length > 0) {
-      parts.push(`Snippets:
-- ${result.snippets.join(`
-- `)}`);
-    } else if (result.snippet) {
-      parts.push(`Snippet: ${result.snippet}`);
-    }
-    return parts.join(`
-`);
-  }).join(`
 
-`);
+// src/shared/get-logger.ts
+var getLogger = (mcp) => async (params) => {
+  await mcp.server.sendLoggingMessage(params);
 };
 
 // src/contents/contents.schemas.ts
@@ -11326,6 +11303,15 @@ var ContentsStructuredContentSchema = objectType({
   })).describe("Extracted items")
 });
 
+// src/shared/check-response-for-errors.ts
+var checkResponseForErrors = (responseData) => {
+  if (typeof responseData === "object" && responseData !== null && "error" in responseData) {
+    const errorMessage = typeof responseData.error === "string" ? responseData.error : JSON.stringify(responseData.error);
+    throw new Error(`You.com API Error: ${errorMessage}`);
+  }
+  return responseData;
+};
+
 // src/contents/contents.utils.ts
 var CONTENTS_API_URL = "https://ydc-index.io/v1/contents";
 var fetchContents = async ({
@@ -11536,6 +11522,27 @@ var ExpressStructuredContentSchema = objectType({
   }).optional().describe("Search results")
 });
 
+// src/shared/format-search-results-text.ts
+var formatSearchResultsText = (results) => {
+  return results.map((result) => {
+    const parts = [`Title: ${result.title}`];
+    if (result.description) {
+      parts.push(`Description: ${result.description}`);
+    }
+    if (result.snippets && result.snippets.length > 0) {
+      parts.push(`Snippets:
+- ${result.snippets.join(`
+- `)}`);
+    } else if (result.snippet) {
+      parts.push(`Snippet: ${result.snippet}`);
+    }
+    return parts.join(`
+`);
+  }).join(`
+
+`);
+};
+
 // src/express/express.utils.ts
 var AGENTS_RUN_URL = "https://api.you.com/v1/agents/runs";
 var agentThrowOnFailedStatus = async (response) => {
@@ -14488,6 +14495,17 @@ Report this issue: ${reportLink}`
   });
 };
 
+// src/shared/use-client-version.ts
+var setUserAgent = (client) => `MCP/${package_default.version} (You.com; ${client})`;
+var useGetClientVersion = (mcp) => () => {
+  const clientVersion = mcp.server.getClientVersion();
+  if (clientVersion) {
+    const { name, version, title, websiteUrl } = clientVersion;
+    return setUserAgent([name, version, title, websiteUrl].filter(Boolean).join("; "));
+  }
+  return setUserAgent("UNKNOWN");
+};
+
 // src/stdio.ts
 var YDC_API_KEY = process.env.YDC_API_KEY;
 try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.3.2",
+  "version": "1.3.3",
   "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.7",
     "@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",
+    "@hono/mcp": "0.2.0",
     "@modelcontextprotocol/sdk": "1.22.0",
     "hono": "^4.10.6",
-    "neverthrow": "8.2.0",
     "zod": "3.25.76"
   }
 }

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().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().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,
+  };
+};