@youdotcom-oss/mcp 1.3.4 → 1.3.5-next.12

package/src/get-mcp-server.ts

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import packageJson from '../package.json' with { type: 'json' };
+
+export const getMCpServer = () =>
+  new McpServer(
+    {
+      name: 'You.com',
+      version: packageJson.version,
+    },
+    {
+      capabilities: {
+        logging: {},
+        tools: { listChanged: true },
+      },
+      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.`,
+    },
+  );

package/src/http.ts

@@ -0,0 +1,72 @@
+import { StreamableHTTPTransport } from '@hono/mcp';
+import { type Context, Hono } from 'hono';
+import { trimTrailingSlash } from 'hono/trailing-slash';
+import packageJson from '../package.json' with { type: 'json' };
+import { registerContentsTool } from './contents/register-contents-tool.ts';
+import { registerExpressTool } from './express/register-express-tool.ts';
+import { getMCpServer } from './get-mcp-server.ts';
+import { registerSearchTool } from './search/register-search-tool.ts';
+import { useGetClientVersion } from './shared/use-client-version.ts';
+
+const extractBearerToken = (authHeader: string | null): string | null => {
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return null;
+  }
+  return authHeader.slice(7);
+};
+
+const handleMcpRequest = async (c: Context) => {
+  const authHeader = c.req.header('Authorization');
+
+  if (!authHeader) {
+    c.status(401);
+    c.header('Content-Type', 'text/plain');
+    return c.text('Unauthorized: Authorization header required');
+  }
+
+  const YDC_API_KEY = extractBearerToken(authHeader);
+
+  if (!YDC_API_KEY) {
+    c.status(401);
+    c.header('Content-Type', 'text/plain');
+    return c.text('Unauthorized: Bearer token required');
+  }
+  const mcp = getMCpServer();
+  const getUserAgent = useGetClientVersion(mcp);
+
+  registerSearchTool({
+    mcp,
+    YDC_API_KEY,
+    getUserAgent,
+  });
+  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent });
+  registerContentsTool({ mcp, YDC_API_KEY, getUserAgent });
+
+  const transport = new StreamableHTTPTransport();
+  await mcp.connect(transport);
+  const response = await transport.handleRequest(c);
+
+  // Explicitly set Content-Encoding to 'identity' to prevent httpx auto-decompression issues
+  // httpx by default sends Accept-Encoding and attempts decompression, but MCP SSE streams
+  // are not compressed. Setting 'identity' tells clients the response is uncompressed.
+  response?.headers.set('Content-Encoding', 'identity');
+
+  return response;
+};
+
+const app = new Hono();
+app.use(trimTrailingSlash());
+
+app.get('/mcp-health', async (c) => {
+  return c.json({
+    status: 'healthy',
+    timestamp: new Date().toISOString(),
+    version: packageJson.version,
+    service: 'youdotcom-mcp-server',
+  });
+});
+
+app.all('/mcp', handleMcpRequest);
+app.all('/mcp/', handleMcpRequest);
+
+export default app;

package/src/search/register-search-tool.ts

@@ -0,0 +1,87 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { generateErrorReportLink } from '../shared/generate-error-report-link.ts';
+import { getLogger } from '../shared/get-logger.ts';
+import { SearchQuerySchema, SearchStructuredContentSchema } from './search.schemas.ts';
+import { fetchSearchResults, formatSearchResults } from './search.utils.ts';
+
+export const registerSearchTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  mcp: McpServer;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}) => {
+  mcp.registerTool(
+    'you-search',
+    {
+      title: 'Web Search',
+      description: 'Web and news search via You.com',
+      inputSchema: SearchQuerySchema.shape,
+      outputSchema: SearchStructuredContentSchema.shape,
+    },
+    async (searchQuery) => {
+      const logger = getLogger(mcp);
+      try {
+        const response = await fetchSearchResults({
+          searchQuery,
+          YDC_API_KEY,
+          getUserAgent,
+        });
+
+        const webCount = response.results.web?.length ?? 0;
+        const newsCount = response.results.news?.length ?? 0;
+
+        if (!webCount && !newsCount) {
+          await logger({
+            level: 'info',
+            data: `No results found for query: "${searchQuery.query}"`,
+          });
+
+          return {
+            content: [{ type: 'text' as const, text: 'No results found.' }],
+            structuredContent: {
+              resultCounts: {
+                web: 0,
+                news: 0,
+                total: 0,
+              },
+            },
+          };
+        }
+
+        await logger({
+          level: 'info',
+          data: `Search successful for query: "${searchQuery.query}" - ${webCount} web results, ${newsCount} news results (${webCount + newsCount} total)`,
+        });
+
+        const { content, structuredContent } = formatSearchResults(response);
+        return { content, structuredContent };
+      } catch (err: unknown) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const reportLink = generateErrorReportLink({
+          errorMessage,
+          tool: 'you-search',
+          clientInfo: getUserAgent(),
+        });
+
+        await logger({
+          level: 'error',
+          data: `Search API call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${errorMessage}`,
+            },
+          ],
+          structuredContent: undefined,
+          isError: true,
+        };
+      }
+    },
+  );
+};

package/src/search/tests/search.utils.spec.ts

@@ -0,0 +1,217 @@
+import { describe, expect, test } from 'bun:test';
+import type { SearchResponse } from '../search.schemas.ts';
+import { fetchSearchResults, formatSearchResults } from '../search.utils.ts';
+
+const getUserAgent = () => 'MCP/test (You.com; test-client)';
+
+describe('fetchSearchResults', () => {
+  test('returns valid response structure for basic query', async () => {
+    const result = await fetchSearchResults({
+      searchQuery: { query: 'latest stock news' },
+      getUserAgent,
+    });
+
+    expect(result).toHaveProperty('results');
+    expect(result).toHaveProperty('metadata');
+    expect(result.results).toHaveProperty('web');
+    expect(result.results).toHaveProperty('news');
+    expect(Array.isArray(result.results.web)).toBe(true);
+    expect(Array.isArray(result.results.news)).toBe(true);
+
+    // Assert required metadata fields
+    expect(typeof result.metadata?.query).toBe('string');
+
+    // Optional fields: only assert type if present
+    if (result.metadata?.request_uuid !== undefined) {
+      expect(typeof result.metadata.request_uuid).toBe('string');
+    }
+  });
+
+  test('handles search with filters', async () => {
+    const result = await fetchSearchResults({
+      searchQuery: {
+        query: 'javascript tutorial',
+        count: 3,
+        freshness: 'week',
+        country: 'US',
+      },
+      getUserAgent,
+    });
+
+    expect(result.results.web?.length).toBeLessThanOrEqual(3);
+    expect(result.metadata?.query).toContain('javascript tutorial');
+  });
+
+  test('validates response schema', async () => {
+    const result = await fetchSearchResults({
+      searchQuery: { query: 'latest technology news' },
+      getUserAgent,
+    });
+
+    // Test that web results have required properties
+    // biome-ignore lint/style/noNonNullAssertion: Test
+    const webResult = result.results.web![0];
+
+    expect(webResult).toHaveProperty('url');
+    expect(webResult).toHaveProperty('title');
+    expect(webResult).toHaveProperty('description');
+    expect(webResult).toHaveProperty('snippets');
+    expect(Array.isArray(webResult?.snippets)).toBe(true);
+
+    // Test that news results have required properties
+    // biome-ignore lint/style/noNonNullAssertion: Test
+    const newsResult = result.results.news![0];
+    expect(newsResult).toHaveProperty('url');
+    expect(newsResult).toHaveProperty('title');
+    expect(newsResult).toHaveProperty('description');
+    expect(newsResult).toHaveProperty('page_age');
+  });
+});
+
+describe('formatSearchResults', () => {
+  test('formats web results correctly', () => {
+    const mockResponse: SearchResponse = {
+      results: {
+        web: [
+          {
+            url: 'https://example.com',
+            title: 'Test Title',
+            description: 'Test description',
+            snippets: ['snippet 1', 'snippet 2'],
+            page_age: '2023-01-01T00:00:00',
+            authors: ['Author Name'],
+          },
+        ],
+        news: [],
+      },
+      metadata: {
+        request_uuid: 'test-uuid',
+        query: 'test query',
+        latency: 0.1,
+      },
+    };
+
+    const result = formatSearchResults(mockResponse);
+
+    expect(result).toHaveProperty('content');
+    expect(result).toHaveProperty('structuredContent');
+    expect(result).toHaveProperty('fullResponse');
+    expect(Array.isArray(result.content)).toBe(true);
+    expect(result.content[0]).toHaveProperty('type', 'text');
+    expect(result.content[0]).toHaveProperty('text');
+    expect(result.content[0]?.text).toContain('WEB RESULTS:');
+    expect(result.content[0]?.text).toContain('Test Title');
+    // URLs should NOT be in text content
+    expect(result.content[0]?.text).not.toContain('https://example.com');
+    expect(result.structuredContent).toHaveProperty('resultCounts');
+    expect(result.structuredContent.resultCounts).toHaveProperty('web', 1);
+    expect(result.structuredContent.resultCounts).toHaveProperty('news', 0);
+    expect(result.structuredContent.resultCounts).toHaveProperty('total', 1);
+    // URLs should be in structuredContent.results
+    expect(result.structuredContent).toHaveProperty('results');
+    expect(result.structuredContent.results?.web).toBeDefined();
+    expect(result.structuredContent.results?.web?.length).toBe(1);
+    expect(result.structuredContent.results?.web?.[0]).toEqual({
+      url: 'https://example.com',
+      title: 'Test Title',
+    });
+    expect(result.fullResponse).toBe(mockResponse);
+  });
+
+  test('formats news results correctly', () => {
+    const mockResponse: SearchResponse = {
+      results: {
+        web: [],
+        news: [
+          {
+            title: 'News Title',
+            description: 'News description',
+            page_age: '2023-01-01T00:00:00',
+            url: 'https://news.com/article',
+          },
+        ],
+      },
+      metadata: {
+        request_uuid: 'test-uuid',
+        query: 'test query',
+        latency: 0.1,
+      },
+    };
+
+    const result = formatSearchResults(mockResponse);
+
+    expect(result.content[0]?.text).toContain('NEWS RESULTS:');
+    expect(result.content[0]?.text).toContain('News Title');
+    expect(result.content[0]?.text).toContain('Published: 2023-01-01T00:00:00');
+    // URLs should NOT be in text content
+    expect(result.content[0]?.text).not.toContain('https://news.com/article');
+    expect(result.structuredContent).toHaveProperty('resultCounts');
+    expect(result.structuredContent.resultCounts).toHaveProperty('web', 0);
+    expect(result.structuredContent.resultCounts).toHaveProperty('news', 1);
+    expect(result.structuredContent.resultCounts).toHaveProperty('total', 1);
+    // URLs should be in structuredContent.results
+    expect(result.structuredContent).toHaveProperty('results');
+    expect(result.structuredContent.results?.news).toBeDefined();
+    expect(result.structuredContent.results?.news?.length).toBe(1);
+    expect(result.structuredContent.results?.news?.[0]).toEqual({
+      url: 'https://news.com/article',
+      title: 'News Title',
+    });
+  });
+
+  test('formats both web and news results', () => {
+    const mockResponse: SearchResponse = {
+      results: {
+        web: [
+          {
+            url: 'https://web.com',
+            title: 'Web Title',
+            description: 'Web description',
+            snippets: ['web snippet'],
+            page_age: '2023-01-01T00:00:00',
+            authors: ['Web Author'],
+          },
+        ],
+        news: [
+          {
+            title: 'News Title',
+            description: 'News description',
+            page_age: '2023-01-01T00:00:00',
+            url: 'https://news.com/article',
+          },
+        ],
+      },
+      metadata: {
+        request_uuid: 'test-uuid',
+        query: 'test query',
+        latency: 0.1,
+      },
+    };
+
+    const result = formatSearchResults(mockResponse);
+
+    expect(result.content[0]?.text).toContain('WEB RESULTS:');
+    expect(result.content[0]?.text).toContain('NEWS RESULTS:');
+    expect(result.content[0]?.text).toContain(`=${'='.repeat(49)}`);
+    // URLs should NOT be in text content
+    expect(result.content[0]?.text).not.toContain('https://web.com');
+    expect(result.content[0]?.text).not.toContain('https://news.com/article');
+    expect(result.structuredContent.resultCounts).toHaveProperty('web', 1);
+    expect(result.structuredContent.resultCounts).toHaveProperty('news', 1);
+    expect(result.structuredContent.resultCounts).toHaveProperty('total', 2);
+    // URLs should be in structuredContent.results
+    expect(result.structuredContent).toHaveProperty('results');
+    expect(result.structuredContent.results?.web).toBeDefined();
+    expect(result.structuredContent.results?.news).toBeDefined();
+    expect(result.structuredContent.results?.web?.length).toBe(1);
+    expect(result.structuredContent.results?.news?.length).toBe(1);
+    expect(result.structuredContent.results?.web?.[0]).toEqual({
+      url: 'https://web.com',
+      title: 'Web Title',
+    });
+    expect(result.structuredContent.results?.news?.[0]).toEqual({
+      url: 'https://news.com/article',
+      title: 'News Title',
+    });
+  });
+});

package/src/shared/generate-error-report-link.ts

@@ -0,0 +1,37 @@
+import packageJson from '../../package.json' with { type: 'json' };
+/**
+ * Generates a mailto link for error reporting with pre-filled context
+ * Used by tool error handlers to provide easy error reporting
+ */
+export const generateErrorReportLink = ({
+  errorMessage,
+  tool,
+  clientInfo,
+}: {
+  errorMessage: string;
+  tool: string;
+  clientInfo: string;
+}): string => {
+  const subject = `MCP Server Issue v${packageJson.version}`;
+  const body = `Server Version: v${packageJson.version}
+Client: ${clientInfo}
+Tool: ${tool}
+
+Error Message:
+${errorMessage}
+
+Steps to Reproduce:
+1.
+2.
+3.
+
+Additional Context:
+`;
+
+  const params = new URLSearchParams({
+    subject,
+    body,
+  });
+
+  return `mailto:support@you.com?${params.toString()}`;
+};

package/src/shared/get-logger.ts

@@ -0,0 +1,10 @@
+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 const getLogger = (mcp: McpServer) => async (params: LoggingMessageNotification['params']) => {
+  await mcp.server.sendLoggingMessage(params);
+};

package/src/shared/tests/shared.utils.spec.ts

@@ -0,0 +1,160 @@
+import { describe, expect, test } from 'bun:test';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { useGetClientVersion } from '../use-client-version.ts';
+
+describe('useGetClientVersion', () => {
+  test('returns formatted string with all fields present', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'test-client',
+          version: '1.0.0',
+          title: 'Test Client',
+          websiteUrl: 'https://example.com',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(
+      /^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; Test Client; https:\/\/example\.com\)$/,
+    );
+  });
+
+  test('returns formatted string with name and version only', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'test-client',
+          version: '1.0.0',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0\)$/);
+  });
+
+  test('returns UNKNOWN when no client version available', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => null,
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; UNKNOWN\)$/);
+  });
+
+  test('returns UNKNOWN when getClientVersion returns undefined', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => undefined,
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; UNKNOWN\)$/);
+  });
+
+  test('filters out empty strings from fields', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'test-client',
+          version: '1.0.0',
+          title: '', // Empty string should be filtered out
+          websiteUrl: 'https://example.com',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; https:\/\/example\.com\)$/);
+    expect(result).not.toContain(';;'); // No double semicolons
+  });
+
+  test('filters out null values from fields', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'test-client',
+          version: '1.0.0',
+          title: null, // Null should be filtered out
+          websiteUrl: 'https://example.com',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0; https:\/\/example\.com\)$/);
+  });
+
+  test('handles partial fields - name, version, and title only', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'Claude Desktop',
+          version: '0.7.6',
+          title: 'Claude Desktop App',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; Claude Desktop; 0\.7\.6; Claude Desktop App\)$/);
+  });
+
+  test('handles Claude Desktop client info format', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'Claude Desktop',
+          version: '0.7.6',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+    const result = getUserAgent();
+
+    expect(result).toMatch(/^MCP\/[\d.]+(-[\w.]+)? \(You\.com; Claude Desktop; 0\.7\.6\)$/);
+  });
+
+  test('returns a function that can be called multiple times', () => {
+    const mockMcp = {
+      server: {
+        getClientVersion: () => ({
+          name: 'test-client',
+          version: '1.0.0',
+        }),
+      },
+    } as unknown as McpServer;
+
+    const getUserAgent = useGetClientVersion(mockMcp);
+
+    // Call multiple times to ensure consistent results
+    const result1 = getUserAgent();
+    const result2 = getUserAgent();
+    const result3 = getUserAgent();
+
+    const pattern = /^MCP\/[\d.]+(-[\w.]+)? \(You\.com; test-client; 1\.0\.0\)$/;
+    expect(result1).toMatch(pattern);
+    expect(result2).toMatch(pattern);
+    expect(result3).toMatch(pattern);
+  });
+});

package/src/shared/use-client-version.ts

@@ -0,0 +1,21 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import packageJson from '../../package.json' with { type: 'json' };
+
+/**
+ * Creates User-Agent string for API requests
+ * Used by search and express agent API calls
+ */
+const setUserAgent = (client: string) => `MCP/${packageJson.version} (You.com; ${client})`;
+
+/**
+ * Get's function that returns a formatted client version information into a string
+ * Used by stdio.ts and http.ts for logging/debugging
+ */
+export const useGetClientVersion = (mcp: McpServer) => () => {
+  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');
+};

package/src/stdio.ts

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerContentsTool } from './contents/register-contents-tool.ts';
+import { registerExpressTool } from './express/register-express-tool.ts';
+import { getMCpServer } from './get-mcp-server.ts';
+import { registerSearchTool } from './search/register-search-tool.ts';
+import { useGetClientVersion } from './shared/use-client-version.ts';
+
+const YDC_API_KEY = process.env.YDC_API_KEY;
+
+try {
+  const mcp = getMCpServer();
+  const getUserAgent = useGetClientVersion(mcp);
+
+  registerSearchTool({ mcp, YDC_API_KEY, getUserAgent });
+  registerExpressTool({ mcp, YDC_API_KEY, getUserAgent });
+  registerContentsTool({ mcp, YDC_API_KEY, getUserAgent });
+
+  const transport = new StdioServerTransport();
+  await mcp.connect(transport);
+} catch (error) {
+  process.stderr.write(`Failed to start server: ${error}\n`);
+  process.exit(1);
+}

package/src/tests/exports.spec.ts

@@ -0,0 +1,24 @@
+// src/tests/exports.spec.ts
+import { describe, expect, test } from 'bun:test';
+import * as exports from '@youdotcom-oss/mcp';
+
+describe('Package exports', () => {
+  test('should export all required schemas', async () => {
+    // Schemas
+    expect(exports.ContentsQuerySchema).toBeDefined();
+    expect(exports.ExpressAgentInputSchema).toBeDefined();
+    expect(exports.SearchQuerySchema).toBeDefined();
+
+    // Utilities
+    expect(exports.fetchContents).toBeDefined();
+    expect(exports.formatContentsResponse).toBeDefined();
+    expect(exports.callExpressAgent).toBeDefined();
+    expect(exports.formatExpressAgentResponse).toBeDefined();
+    expect(exports.fetchSearchResults).toBeDefined();
+    expect(exports.formatSearchResults).toBeDefined();
+
+    // Shared utilities
+    expect(exports.checkResponseForErrors).toBeDefined();
+    expect(exports.formatSearchResultsText).toBeDefined();
+  });
+});