@youdotcom-oss/mcp 1.3.8 → 1.3.9-next.1

package/dist/contents/contents.schemas.d.ts

@@ -0,0 +1,39 @@
+import * as z from 'zod';
+/**
+ * Input schema for the you-contents tool
+ * Accepts an array of URLs and optional format
+ */
+export declare const ContentsQuerySchema: z.ZodObject<{
+    urls: z.ZodArray<z.ZodString>;
+    format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        html: "html";
+    }>>>;
+}, z.core.$strip>;
+export type ContentsQuery = z.infer<typeof ContentsQuerySchema>;
+/**
+ * API response schema from You.com Contents API
+ * Validates the full response array
+ */
+export declare const ContentsApiResponseSchema: z.ZodArray<z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    html: z.ZodOptional<z.ZodString>;
+    markdown: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>>;
+export type ContentsApiResponse = z.infer<typeof ContentsApiResponseSchema>;
+/**
+ * Structured content schema for MCP response
+ * Includes full content and metadata for each URL
+ */
+export declare const ContentsStructuredContentSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    format: z.ZodString;
+    items: z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        content: z.ZodString;
+        contentLength: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type ContentsStructuredContent = z.infer<typeof ContentsStructuredContentSchema>;

package/dist/contents/contents.utils.d.ts

@@ -0,0 +1,28 @@
+import { type ContentsApiResponse, type ContentsQuery, type ContentsStructuredContent } from './contents.schemas.ts';
+/**
+ * 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 declare const fetchContents: ({ contentsQuery: { urls, format }, YDC_API_KEY, getUserAgent, }: {
+    contentsQuery: ContentsQuery;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => Promise<ContentsApiResponse>;
+/**
+ * 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 declare const formatContentsResponse: (response: ContentsApiResponse, format: string) => {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    structuredContent: ContentsStructuredContent;
+};

package/dist/contents/register-contents-tool.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Register the you-contents tool with the MCP server
+ * Extracts and returns full content from multiple URLs in markdown or HTML format
+ */
+export declare const registerContentsTool: ({ mcp, YDC_API_KEY, getUserAgent, }: {
+    mcp: McpServer;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => void;

package/dist/express/express.schemas.d.ts

@@ -0,0 +1,56 @@
+import * as z from 'zod';
+export declare const ExpressAgentInputSchema: z.ZodObject<{
+    input: z.ZodString;
+    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        type: z.ZodEnum<{
+            web_search: "web_search";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ExpressAgentInput = z.infer<typeof ExpressAgentInputSchema>;
+export declare const ExpressAgentApiResponseSchema: z.ZodObject<{
+    output: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        type: z.ZodLiteral<"web_search.results">;
+        content: z.ZodArray<z.ZodObject<{
+            source_type: z.ZodOptional<z.ZodString>;
+            citation_uri: z.ZodOptional<z.ZodString>;
+            url: z.ZodString;
+            title: z.ZodString;
+            snippet: z.ZodString;
+            thumbnail_url: z.ZodOptional<z.ZodString>;
+            provider: z.ZodOptional<z.ZodAny>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, z.ZodObject<{
+        type: z.ZodLiteral<"message.answer">;
+        text: z.ZodString;
+    }, z.core.$strip>]>>;
+    agent: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodString>;
+    input: z.ZodOptional<z.ZodArray<z.ZodAny>>;
+}, z.core.$loose>;
+export type ExpressAgentApiResponse = z.infer<typeof ExpressAgentApiResponseSchema>;
+declare const ExpressAgentMcpResponseSchema: z.ZodObject<{
+    answer: z.ZodString;
+    results: z.ZodOptional<z.ZodObject<{
+        web: z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+            snippet: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    agent: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type ExpressAgentMcpResponse = z.infer<typeof ExpressAgentMcpResponseSchema>;
+export declare const ExpressStructuredContentSchema: z.ZodObject<{
+    answer: z.ZodString;
+    hasResults: z.ZodBoolean;
+    resultCount: z.ZodNumber;
+    agent: z.ZodOptional<z.ZodString>;
+    results: z.ZodOptional<z.ZodObject<{
+        web: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export {};

package/dist/express/express.utils.d.ts

@@ -0,0 +1,45 @@
+import { type ExpressAgentInput, type ExpressAgentMcpResponse } from './express.schemas.ts';
+export declare const callExpressAgent: ({ YDC_API_KEY, agentInput: { input, tools }, getUserAgent, }: {
+    agentInput: ExpressAgentInput;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => Promise<{
+    answer: string;
+    results?: {
+        web: {
+            url: string;
+            title: string;
+            snippet: string;
+        }[];
+    } | undefined;
+    agent?: string | undefined;
+}>;
+export declare const formatExpressAgentResponse: (response: ExpressAgentMcpResponse) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        answer: string;
+        hasResults: boolean;
+        resultCount: number;
+        agent: string | undefined;
+        results: {
+            web: {
+                url: string;
+                title: string;
+            }[];
+        } | undefined;
+    };
+    fullResponse: {
+        answer: string;
+        results?: {
+            web: {
+                url: string;
+                title: string;
+                snippet: string;
+            }[];
+        } | undefined;
+        agent?: string | undefined;
+    };
+};

package/dist/express/register-express-tool.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerExpressTool: ({ mcp, YDC_API_KEY, getUserAgent, }: {
+    mcp: McpServer;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => void;

package/dist/get-mcp-server.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const getMCpServer: () => McpServer;

package/dist/http.d.ts

@@ -0,0 +1,3 @@
+import { Hono } from 'hono';
+declare const app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+export default app;

package/{src/utils.ts → dist/main.d.ts}

@@ -4,5 +4,6 @@ export * from './express/express.schemas.ts';
 export * from './express/express.utils.ts';
 export * from './search/search.schemas.ts';
 export * from './search/search.utils.ts';
+export * from './shared/api-constants.ts';
 export * from './shared/check-response-for-errors.ts';
 export * from './shared/format-search-results-text.ts';

package/dist/search/register-search-tool.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const registerSearchTool: ({ mcp, YDC_API_KEY, getUserAgent, }: {
+    mcp: McpServer;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => void;

package/dist/search/search.schemas.d.ts

@@ -0,0 +1,131 @@
+import * as z from 'zod';
+export declare const SearchQuerySchema: z.ZodObject<{
+    query: z.ZodString;
+    count: z.ZodOptional<z.ZodNumber>;
+    freshness: z.ZodOptional<z.ZodString>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    country: z.ZodOptional<z.ZodEnum<{
+        AR: "AR";
+        AU: "AU";
+        AT: "AT";
+        BE: "BE";
+        BR: "BR";
+        CA: "CA";
+        CL: "CL";
+        DK: "DK";
+        FI: "FI";
+        FR: "FR";
+        DE: "DE";
+        HK: "HK";
+        IN: "IN";
+        ID: "ID";
+        IT: "IT";
+        JP: "JP";
+        KR: "KR";
+        MY: "MY";
+        MX: "MX";
+        NL: "NL";
+        NZ: "NZ";
+        NO: "NO";
+        CN: "CN";
+        PL: "PL";
+        PT: "PT";
+        PH: "PH";
+        RU: "RU";
+        SA: "SA";
+        ZA: "ZA";
+        ES: "ES";
+        SE: "SE";
+        CH: "CH";
+        TW: "TW";
+        TR: "TR";
+        GB: "GB";
+        US: "US";
+    }>>;
+    safesearch: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        moderate: "moderate";
+        strict: "strict";
+    }>>;
+    site: z.ZodOptional<z.ZodString>;
+    fileType: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    excludeTerms: z.ZodOptional<z.ZodString>;
+    exactTerms: z.ZodOptional<z.ZodString>;
+    livecrawl: z.ZodOptional<z.ZodEnum<{
+        web: "web";
+        news: "news";
+        all: "all";
+    }>>;
+    livecrawl_formats: z.ZodOptional<z.ZodEnum<{
+        markdown: "markdown";
+        html: "html";
+    }>>;
+}, z.core.$strip>;
+export type SearchQuery = z.infer<typeof SearchQuerySchema>;
+declare const NewsResultSchema: z.ZodObject<{
+    title: z.ZodString;
+    description: z.ZodString;
+    page_age: z.ZodString;
+    url: z.ZodString;
+    thumbnail_url: z.ZodOptional<z.ZodString>;
+    contents: z.ZodOptional<z.ZodObject<{
+        html: z.ZodOptional<z.ZodString>;
+        markdown: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type NewsResult = z.infer<typeof NewsResultSchema>;
+export declare const SearchResponseSchema: z.ZodObject<{
+    results: z.ZodObject<{
+        web: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+            description: z.ZodString;
+            snippets: z.ZodArray<z.ZodString>;
+            page_age: z.ZodOptional<z.ZodString>;
+            authors: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            thumbnail_url: z.ZodOptional<z.ZodString>;
+            favicon_url: z.ZodOptional<z.ZodString>;
+            contents: z.ZodOptional<z.ZodObject<{
+                html: z.ZodOptional<z.ZodString>;
+                markdown: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+        news: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            title: z.ZodString;
+            description: z.ZodString;
+            page_age: z.ZodString;
+            url: z.ZodString;
+            thumbnail_url: z.ZodOptional<z.ZodString>;
+            contents: z.ZodOptional<z.ZodObject<{
+                html: z.ZodOptional<z.ZodString>;
+                markdown: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>;
+    metadata: z.ZodObject<{
+        search_uuid: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        query: z.ZodOptional<z.ZodString>;
+        latency: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export type SearchResponse = z.infer<typeof SearchResponseSchema>;
+export declare const SearchStructuredContentSchema: z.ZodObject<{
+    resultCounts: z.ZodObject<{
+        web: z.ZodNumber;
+        news: z.ZodNumber;
+        total: z.ZodNumber;
+    }, z.core.$strip>;
+    results: z.ZodOptional<z.ZodObject<{
+        web: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>>;
+        news: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            url: z.ZodString;
+            title: z.ZodString;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SearchStructuredContent = z.infer<typeof SearchStructuredContentSchema>;
+export {};

package/dist/search/search.utils.d.ts

@@ -0,0 +1,96 @@
+import { type SearchQuery, type SearchResponse } from './search.schemas.ts';
+export declare const fetchSearchResults: ({ YDC_API_KEY, searchQuery: { query, site, fileType, language, exactTerms, excludeTerms, ...rest }, getUserAgent, }: {
+    searchQuery: SearchQuery;
+    YDC_API_KEY?: string;
+    getUserAgent: () => string;
+}) => Promise<{
+    results: {
+        web?: {
+            url: string;
+            title: string;
+            description: string;
+            snippets: string[];
+            page_age?: string | undefined;
+            authors?: string[] | undefined;
+            thumbnail_url?: string | undefined;
+            favicon_url?: string | undefined;
+            contents?: {
+                html?: string | undefined;
+                markdown?: string | undefined;
+            } | undefined;
+        }[] | undefined;
+        news?: {
+            title: string;
+            description: string;
+            page_age: string;
+            url: string;
+            thumbnail_url?: string | undefined;
+            contents?: {
+                html?: string | undefined;
+                markdown?: string | undefined;
+            } | undefined;
+        }[] | undefined;
+    };
+    metadata: {
+        search_uuid?: string | undefined;
+        query?: string | undefined;
+        latency?: number | undefined;
+    };
+}>;
+export declare const formatSearchResults: (response: SearchResponse) => {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        resultCounts: {
+            web: number;
+            news: number;
+            total: number;
+        };
+        results: {
+            web?: Array<{
+                url: string;
+                title: string;
+            }>;
+            news?: Array<{
+                url: string;
+                title: string;
+            }>;
+        } | undefined;
+    };
+    fullResponse: {
+        results: {
+            web?: {
+                url: string;
+                title: string;
+                description: string;
+                snippets: string[];
+                page_age?: string | undefined;
+                authors?: string[] | undefined;
+                thumbnail_url?: string | undefined;
+                favicon_url?: string | undefined;
+                contents?: {
+                    html?: string | undefined;
+                    markdown?: string | undefined;
+                } | undefined;
+            }[] | undefined;
+            news?: {
+                title: string;
+                description: string;
+                page_age: string;
+                url: string;
+                thumbnail_url?: string | undefined;
+                contents?: {
+                    html?: string | undefined;
+                    markdown?: string | undefined;
+                } | undefined;
+            }[] | undefined;
+        };
+        metadata: {
+            search_uuid?: string | undefined;
+            query?: string | undefined;
+            latency?: number | undefined;
+        };
+    };
+};

package/dist/shared/api-constants.d.ts

@@ -0,0 +1,9 @@
+/**
+ * You.com API endpoints
+ *
+ * These constants define the base URLs for You.com's APIs.
+ * Exported for use in tests and external packages.
+ */
+export declare const SEARCH_API_URL = "https://ydc-index.io/v1/search";
+export declare const EXPRESS_API_URL = "https://api.you.com/v1/agents/runs";
+export declare const CONTENTS_API_URL = "https://ydc-index.io/v1/contents";

package/dist/shared/check-response-for-errors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Checks if a response object contains an error field and throws if found
+ * Handles API responses that return 200 status but contain error messages
+ * Used by both search and express agent utilities
+ */
+export declare const checkResponseForErrors: (responseData: unknown) => unknown;

package/dist/shared/format-search-results-text.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Generic search result type that works for both Search and Express APIs
+ * Used by both search.utils.ts and express.utils.ts
+ */
+type GenericSearchResult = {
+    url: string;
+    title: string;
+    description?: string;
+    snippet?: string;
+    snippets?: string[];
+};
+/**
+ * Format array of search results into display text
+ * Used by both search and express agent formatting
+ * @param results - Array of search results to format
+ * @param includeUrls - Whether to include URLs in the text (default: true)
+ */
+export declare const formatSearchResultsText: (results: GenericSearchResult[]) => string;
+export {};

package/dist/shared/generate-error-report-link.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Generates a mailto link for error reporting with pre-filled context
+ * Used by tool error handlers to provide easy error reporting
+ */
+export declare const generateErrorReportLink: ({ errorMessage, tool, clientInfo, }: {
+    errorMessage: string;
+    tool: string;
+    clientInfo: string;
+}) => string;

package/dist/shared/get-logger.d.ts

@@ -0,0 +1,7 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { LoggingMessageNotification } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Creates a logger function that sends messages through MCP server
+ * Used by tool registration files
+ */
+export declare const getLogger: (mcp: McpServer) => (params: LoggingMessageNotification["params"]) => Promise<void>;

package/dist/shared/use-client-version.d.ts

@@ -0,0 +1,6 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Get's function that returns a formatted client version information into a string
+ * Used by stdio.ts and http.ts for logging/debugging
+ */
+export declare const useGetClientVersion: (mcp: McpServer) => () => string;

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.3.8",
+  "version": "1.3.9-next.1",
   "description": "You.com API Model Context Protocol Server",
   "license": "MIT",
   "engines": {
@@ -24,14 +24,18 @@
   ],
   "bin": "bin/stdio.js",
   "type": "module",
-  "main": "./src/utils.ts",
+  "main": "./src/main.ts",
   "exports": {
-    ".": "./src/utils.ts",
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./src/main.ts"
+    },
     "./http": "./src/http.ts",
     "./stdio": "./src/stdio.ts"
   },
   "files": [
     "bin/stdio.js",
+    "./dist/**",
     "./src/**",
     "!./src/**/tests/*",
     "!./src/**/*.spec.@(tsx|ts)"
@@ -40,7 +44,9 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun build ./src/stdio.ts --outfile ./bin/stdio.js --target=node",
+    "build": "bun run build:stdio && bun run build:types",
+    "build:stdio": "bun build ./src/stdio.ts --outfile ./bin/stdio.js --target=node",
+    "build:types": "tsc --project tsconfig.json --declaration --emitDeclarationOnly --noEmit false",
     "check": "bun run check:biome && bun run check:types && bun run check:package",
     "check:biome": "biome check",
     "check:package": "format-package --check",
@@ -60,11 +66,12 @@
     "test:watch": "bun test --watch"
   },
   "mcpName": "io.github.youdotcom-oss/mcp",
+  "types": "./dist/main.d.ts",
   "dependencies": {
-    "zod": "^4.1.13",
-    "@hono/mcp": "^0.2.0",
+    "zod": "^4.2.0",
+    "@hono/mcp": "^0.2.2",
     "@modelcontextprotocol/sdk": "^1.24.3",
-    "hono": "^4.10.7"
+    "hono": "^4.11.1"
   },
   "devDependencies": {
     "@modelcontextprotocol/inspector": "0.17.5"

package/src/contents/contents.utils.ts

@@ -1,3 +1,4 @@
+import { CONTENTS_API_URL } from '../shared/api-constants.ts';
 import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
 import {
   type ContentsApiResponse,
@@ -6,8 +7,6 @@ import {
   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