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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.3.4",
+  "version": "1.3.5-next.12",
   "description": "You.com API Model Context Protocol Server",
   "license": "MIT",
   "engines": {
@@ -9,12 +9,13 @@
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/youdotcom-oss/youdotcom-mcp-server.git"
+    "url": "git+https://github.com/youdotcom-oss/dx-toolkit.git",
+    "directory": "packages/mcp"
   },
   "bugs": {
-    "url": "https://github.com/youdotcom-oss/youdotcom-mcp-server/issues"
+    "url": "https://github.com/youdotcom-oss/dx-toolkit/issues"
   },
-  "homepage": "https://github.com/youdotcom-oss/youdotcom-mcp-server/tree/main#readme",
+  "homepage": "https://github.com/youdotcom-oss/dx-toolkit/tree/main/packages/mcp#readme",
   "author": "You.com (https://you.com)",
   "keywords": [
     "mcp",
@@ -23,19 +24,17 @@
   ],
   "bin": "bin/stdio.js",
   "type": "module",
-  "main": "./src/main.ts",
+  "main": "./src/utils.ts",
   "exports": {
-    ".": "./src/main.ts"
+    ".": "./src/utils.ts",
+    "./http": "./src/http.ts",
+    "./stdio": "./src/stdio.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"
+    "./src/**",
+    "!./src/**/tests/*",
+    "!./src/**/*.spec.@(tsx|ts)"
   ],
   "publishConfig": {
     "access": "public"
@@ -54,41 +53,19 @@
     "inspect": "bash -c 'source .env 2>/dev/null || true; bunx @modelcontextprotocol/inspector -e YDC_API_KEY=$YDC_API_KEY bun dev'",
     "lint": "biome lint",
     "lint:fix": "biome lint --write",
-    "prepare": "git config core.hooksPath .hooks",
     "start": "bun run bin/http",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
     "test:coverage:watch": "bun test --coverage --watch",
     "test:watch": "bun test --watch"
   },
-  "lint-staged": {
-    "*.{ts,tsx}": [
-      "biome check --write --no-errors-on-unmatched"
-    ],
-    "*.{json,md}": [
-      "biome format --write --no-errors-on-unmatched"
-    ],
-    "package.json": [
-      "format-package --write"
-    ]
-  },
-  "peerDependencies": {
-    "zod": "^3.25.76"
+  "dependencies": {
+    "zod": "^4.1.13",
+    "@hono/mcp": "^0.2.0",
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "hono": "^4.10.7"
   },
   "devDependencies": {
-    "@biomejs/biome": "2.3.8",
-    "@commitlint/cli": "^20.1.0",
-    "@commitlint/config-conventional": "^20.0.0",
-    "@eslint/js": "9.39.1",
-    "@modelcontextprotocol/inspector": "0.17.2",
-    "@types/bun": "latest",
-    "typescript": "5.9.3",
-    "lint-staged": "^16.2.7",
-    "format-package": "^7.0.0",
-    "@hono/bun-compress": "0.1.0",
-    "@hono/mcp": "0.2.0",
-    "@modelcontextprotocol/sdk": "1.24.2",
-    "hono": "^4.10.7",
-    "zod": "4.1.13"
+    "@modelcontextprotocol/inspector": "0.17.5"
   }
 }

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

@@ -0,0 +1,90 @@
+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 { ContentsQuerySchema, ContentsStructuredContentSchema } from './contents.schemas.ts';
+import { fetchContents, formatContentsResponse } from './contents.utils.ts';
+
+/**
+ * Register the you-contents tool with the MCP server
+ * Extracts and returns full content from multiple URLs in markdown or HTML format
+ */
+export const registerContentsTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  mcp: McpServer;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}) => {
+  // Register the tool
+  mcp.registerTool(
+    'you-contents',
+    {
+      title: 'Extract Web Page Contents',
+      description: 'Extract page content in markdown or HTML',
+      inputSchema: ContentsQuerySchema.shape,
+      outputSchema: ContentsStructuredContentSchema.shape,
+    },
+    async (toolInput) => {
+      const logger = getLogger(mcp);
+
+      try {
+        // Validate and parse input
+        const contentsQuery = ContentsQuerySchema.parse(toolInput);
+        const { urls, format = 'markdown' } = contentsQuery;
+
+        // Log the request
+        await logger({
+          level: 'info',
+          data: `Contents API call initiated for ${urls.length} URL(s) with format: ${format}`,
+        });
+
+        // Fetch contents from API
+        const response = await fetchContents({
+          contentsQuery,
+          YDC_API_KEY,
+          getUserAgent,
+        });
+
+        // Format response with full content
+        const { content, structuredContent } = formatContentsResponse(response, format);
+
+        // Log success
+        await logger({
+          level: 'info',
+          data: `Contents API call successful: extracted ${response.length} page(s)`,
+        });
+
+        return {
+          content,
+          structuredContent,
+        };
+      } catch (err: unknown) {
+        // Handle and log errors
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const reportLink = generateErrorReportLink({
+          errorMessage,
+          tool: 'you-contents',
+          clientInfo: getUserAgent(),
+        });
+
+        await logger({
+          level: 'error',
+          data: `Contents API call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error extracting contents: ${errorMessage}`,
+            },
+          ],
+          structuredContent: undefined,
+          isError: true,
+        };
+      }
+    },
+  );
+};

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

@@ -0,0 +1,188 @@
+import { describe, expect, test } from 'bun:test';
+import type { ContentsApiResponse } from '../contents.schemas.ts';
+import { fetchContents, formatContentsResponse } from '../contents.utils.ts';
+
+const getUserAgent = () => 'MCP/test (You.com; test-client)';
+
+// NOTE: The following tests require a You.com API key with access to the Contents API
+// Using example.com/example.org as test URLs since You.com blocks self-scraping
+describe('fetchContents', () => {
+  test('returns valid response structure for single URL', async () => {
+    const result = await fetchContents({
+      contentsQuery: {
+        urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+        format: 'markdown',
+      },
+      getUserAgent,
+    });
+
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBeGreaterThan(0);
+
+    const firstItem = result[0];
+    expect(firstItem).toBeDefined();
+
+    // Should have markdown content
+    expect(firstItem?.markdown).toBeDefined();
+    expect(typeof firstItem?.markdown).toBe('string');
+  });
+
+  test('handles multiple URLs', async () => {
+    const result = await fetchContents({
+      contentsQuery: {
+        urls: [
+          'https://documentation.you.com/developer-resources/mcp-server',
+          'https://documentation.you.com/developer-resources/python-sdk',
+        ],
+        format: 'markdown',
+      },
+      getUserAgent,
+    });
+
+    expect(Array.isArray(result)).toBe(true);
+    expect(result.length).toBe(2);
+
+    for (const item of result) {
+      expect(item).toHaveProperty('url');
+      expect(item.markdown).toBeDefined();
+    }
+  });
+
+  test('handles html format', async () => {
+    const result = await fetchContents({
+      contentsQuery: {
+        urls: ['https://documentation.you.com/developer-resources/mcp-server'],
+        format: 'html',
+      },
+      getUserAgent,
+    });
+
+    expect(Array.isArray(result)).toBe(true);
+    const firstItem = result[0];
+    expect(firstItem).toBeDefined();
+
+    expect(firstItem?.html).toBeDefined();
+    expect(typeof firstItem?.html).toBe('string');
+  });
+});
+
+describe('formatContentsResponse', () => {
+  test('formats single markdown content correctly', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Example Page',
+        markdown: '# Hello\n\nThis is a test page with some content.',
+      },
+    ];
+
+    const result = formatContentsResponse(mockResponse, 'markdown');
+
+    expect(result).toHaveProperty('content');
+    expect(result).toHaveProperty('structuredContent');
+    expect(Array.isArray(result.content)).toBe(true);
+    expect(result.content[0]).toHaveProperty('type', 'text');
+    expect(result.content[0]).toHaveProperty('text');
+
+    const text = result.content[0]?.text;
+    expect(text).toContain('Example Page');
+    expect(text).toContain('https://example.com');
+    expect(text).toContain('Format: markdown');
+    expect(text).toContain('# Hello');
+    expect(text).toContain('This is a test page with some content.');
+
+    expect(result.structuredContent).toHaveProperty('count', 1);
+    expect(result.structuredContent).toHaveProperty('format', 'markdown');
+    expect(result.structuredContent.items).toHaveLength(1);
+
+    const item = result.structuredContent.items[0];
+    expect(item).toBeDefined();
+
+    expect(item).toHaveProperty('url', 'https://example.com');
+    expect(item).toHaveProperty('title', 'Example Page');
+    expect(item).toHaveProperty('content', '# Hello\n\nThis is a test page with some content.');
+    expect(item?.contentLength).toBe('# Hello\n\nThis is a test page with some content.'.length);
+  });
+
+  test('formats multiple items correctly', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example1.com',
+        title: 'Page 1',
+        markdown: 'Content 1',
+      },
+      {
+        url: 'https://example2.com',
+        title: 'Page 2',
+        markdown: 'Content 2',
+      },
+    ];
+
+    const result = formatContentsResponse(mockResponse, 'markdown');
+
+    expect(result.structuredContent.count).toBe(2);
+    expect(result.structuredContent.items).toHaveLength(2);
+
+    const text = result.content[0]?.text;
+    expect(text).toContain('Page 1');
+    expect(text).toContain('Page 2');
+    expect(text).toContain('https://example1.com');
+    expect(text).toContain('https://example2.com');
+  });
+
+  test('handles html format', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'HTML Page',
+        html: '<html><body><h1>Hello</h1></body></html>',
+      },
+    ];
+
+    const result = formatContentsResponse(mockResponse, 'html');
+
+    expect(result.structuredContent.format).toBe('html');
+    const text = result.content[0]?.text;
+    expect(text).toContain('Format: html');
+    expect(text).toContain('<html>');
+  });
+
+  test('includes full content for long text', () => {
+    const longContent = 'a'.repeat(1000);
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Long Page',
+        markdown: longContent,
+      },
+    ];
+
+    const result = formatContentsResponse(mockResponse, 'markdown');
+
+    const text = result.content[0]?.text;
+    // Full content should be included (not truncated)
+    expect(text).toContain(longContent);
+
+    // Structured content should have full content and correct length
+    const item = result.structuredContent.items[0];
+    expect(item?.content).toBe(longContent);
+    expect(item?.contentLength).toBe(1000);
+  });
+
+  test('handles empty content gracefully', () => {
+    const mockResponse: ContentsApiResponse = [
+      {
+        url: 'https://example.com',
+        title: 'Empty Page',
+        markdown: '',
+      },
+    ];
+
+    const result = formatContentsResponse(mockResponse, 'markdown');
+
+    expect(result.structuredContent.items[0]?.contentLength).toBe(0);
+    const text = result.content[0]?.text;
+    expect(text).toContain('Empty Page');
+    expect(text).toContain('Content Length: 0 characters');
+  });
+});

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

@@ -0,0 +1,67 @@
+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 { ExpressAgentInputSchema, ExpressStructuredContentSchema } from './express.schemas.ts';
+import { callExpressAgent, formatExpressAgentResponse } from './express.utils.ts';
+
+export const registerExpressTool = ({
+  mcp,
+  YDC_API_KEY,
+  getUserAgent,
+}: {
+  mcp: McpServer;
+  YDC_API_KEY?: string;
+  getUserAgent: () => string;
+}) => {
+  mcp.registerTool(
+    'you-express',
+    {
+      title: 'Express Agent',
+      description: 'Fast AI answers with web search',
+      inputSchema: ExpressAgentInputSchema.shape,
+      outputSchema: ExpressStructuredContentSchema.shape,
+    },
+    async (agentInput) => {
+      const logger = getLogger(mcp);
+
+      try {
+        const response = await callExpressAgent({
+          agentInput,
+          YDC_API_KEY,
+          getUserAgent,
+        });
+
+        await logger({
+          level: 'info',
+          data: `Express agent call successful for input: "${agentInput.input}"`,
+        });
+
+        const { content, structuredContent } = formatExpressAgentResponse(response);
+        return { content, structuredContent };
+      } catch (err: unknown) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const reportLink = generateErrorReportLink({
+          errorMessage,
+          tool: 'you-express',
+          clientInfo: getUserAgent(),
+        });
+
+        await logger({
+          level: 'error',
+          data: `Express agent call failed: ${errorMessage}\n\nReport this issue: ${reportLink}`,
+        });
+
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: `Error: ${errorMessage}`,
+            },
+          ],
+          structuredContent: undefined,
+          isError: true,
+        };
+      }
+    },
+  );
+};

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

@@ -0,0 +1,244 @@
+import { describe, expect, setDefaultTimeout, test } from 'bun:test';
+import type { ExpressAgentMcpResponse } from '../express.schemas.ts';
+import { callExpressAgent, formatExpressAgentResponse } from '../express.utils.ts';
+
+const getUserAgent = () => 'MCP/test (You.com; test-client)';
+
+setDefaultTimeout(20_000);
+
+describe('callExpressAgent', () => {
+  test('returns answer only (WITHOUT web_search tools)', async () => {
+    const result = await callExpressAgent({
+      agentInput: { input: 'What is machine learning?' },
+      getUserAgent,
+    });
+
+    // Verify MCP response structure
+    expect(result).toHaveProperty('answer');
+    expect(typeof result.answer).toBe('string');
+    expect(result.answer.length).toBeGreaterThan(0);
+
+    // Should NOT have results when web_search is not used
+    expect(result.results).toBeUndefined();
+
+    expect(result.agent).toBe('express');
+  });
+
+  test('returns answer and search results (WITH web_search tools)', async () => {
+    const result = await callExpressAgent({
+      agentInput: {
+        input: 'Latest developments in quantum computing',
+        tools: [{ type: 'web_search' }],
+      },
+      getUserAgent,
+    });
+
+    // Verify MCP response has both answer and results
+    expect(result).toHaveProperty('answer');
+    expect(typeof result.answer).toBe('string');
+    expect(result.answer.length).toBeGreaterThan(0);
+
+    expect(result).toHaveProperty('results');
+    expect(result.results).toHaveProperty('web');
+    expect(Array.isArray(result.results?.web)).toBe(true);
+    expect(result.results?.web.length).toBeGreaterThan(0);
+
+    // Verify each search result has required fields
+    const firstResult = result.results?.web[0];
+    expect(firstResult).toHaveProperty('url');
+    expect(firstResult).toHaveProperty('title');
+    expect(firstResult).toHaveProperty('snippet');
+    expect(typeof firstResult?.url).toBe('string');
+    expect(typeof firstResult?.title).toBe('string');
+    expect(typeof firstResult?.snippet).toBe('string');
+    expect(firstResult?.url.length).toBeGreaterThan(0);
+    expect(firstResult?.title.length).toBeGreaterThan(0);
+
+    expect(result.agent).toBe('express');
+  }, 30000);
+
+  test('works without optional parameters', async () => {
+    const result = await callExpressAgent({
+      agentInput: { input: 'What is the capital of France?' },
+      getUserAgent,
+      // No progressToken or sendProgress provided
+    });
+
+    // Should work normally without progress tracking
+    expect(result).toHaveProperty('answer');
+    expect(result.answer.length).toBeGreaterThan(0);
+    expect(result.agent).toBe('express');
+  });
+});
+
+describe('formatExpressAgentResponse', () => {
+  test('formats response with answer only (no search results)', () => {
+    const mockResponse: ExpressAgentMcpResponse = {
+      answer: 'The capital of France is Paris.',
+      agent: 'express',
+    };
+
+    const result = formatExpressAgentResponse(mockResponse);
+
+    // Verify content array has 1 item (answer only)
+    expect(result).toHaveProperty('content');
+    expect(Array.isArray(result.content)).toBe(true);
+    expect(result.content.length).toBe(1);
+
+    // Verify answer content
+    expect(result.content[0]).toHaveProperty('type', 'text');
+    expect(result.content[0]).toHaveProperty('text');
+    expect(result.content[0]?.text).toContain('Express Agent Answer');
+    expect(result.content[0]?.text).toContain('The capital of France is Paris.');
+
+    // Verify structuredContent is minimal (not full response)
+    expect(result).toHaveProperty('structuredContent');
+    expect(result).toHaveProperty('fullResponse');
+    expect(result.structuredContent).toHaveProperty('answer');
+    expect(result.structuredContent).toHaveProperty('hasResults');
+    expect(result.structuredContent).toHaveProperty('resultCount');
+    expect(result.structuredContent).toHaveProperty('agent');
+    expect(result.structuredContent.answer).toBe(mockResponse.answer);
+    expect(result.structuredContent.hasResults).toBe(false);
+    expect(result.structuredContent.resultCount).toBe(0);
+    // No results, so results field should be undefined
+    expect(result.structuredContent.results).toBeUndefined();
+    expect(result.fullResponse).toEqual(mockResponse);
+  });
+
+  test('formats response with answer and search results', () => {
+    const mockResponse: ExpressAgentMcpResponse = {
+      answer: 'Quantum computing is advancing rapidly with recent breakthroughs in error correction.',
+      results: {
+        web: [
+          {
+            url: 'https://example.com/quantum1',
+            title: 'Quantum Computing Breakthrough',
+            snippet: 'Scientists achieve quantum error correction milestone.',
+          },
+          {
+            url: 'https://example.com/quantum2',
+            title: 'Latest in Quantum Research',
+            snippet: 'New quantum processor demonstrates superiority.',
+          },
+        ],
+      },
+      agent: 'express',
+    };
+
+    const result = formatExpressAgentResponse(mockResponse);
+
+    // Verify content array has 2 items (answer + search results)
+    expect(result.content.length).toBe(2);
+
+    // Verify answer comes FIRST
+    expect(result.content[0]?.type).toBe('text');
+    expect(result.content[0]?.text).toContain('Express Agent Answer');
+    expect(result.content[0]?.text).toContain('Quantum computing is advancing rapidly');
+
+    // Verify search results come SECOND (without URLs in text)
+    expect(result.content[1]?.type).toBe('text');
+    expect(result.content[1]?.text).toContain('Search Results');
+    expect(result.content[1]?.text).toContain('Quantum Computing Breakthrough');
+    expect(result.content[1]?.text).toContain('Latest in Quantum Research');
+    // URLs should NOT be in text content
+    expect(result.content[1]?.text).not.toContain('https://example.com/quantum1');
+    expect(result.content[1]?.text).not.toContain('https://example.com/quantum2');
+
+    // Verify structuredContent is minimal with counts
+    expect(result.structuredContent).toHaveProperty('answer');
+    expect(result.structuredContent).toHaveProperty('hasResults');
+    expect(result.structuredContent).toHaveProperty('resultCount');
+    expect(result.structuredContent.answer).toBe(mockResponse.answer);
+    expect(result.structuredContent.hasResults).toBe(true);
+    expect(result.structuredContent.resultCount).toBe(2);
+
+    // URLs should be in structuredContent.results
+    expect(result.structuredContent).toHaveProperty('results');
+    expect(result.structuredContent.results?.web).toBeDefined();
+    expect(result.structuredContent.results?.web?.length).toBe(2);
+    expect(result.structuredContent.results?.web?.[0]).toEqual({
+      url: 'https://example.com/quantum1',
+      title: 'Quantum Computing Breakthrough',
+    });
+    expect(result.structuredContent.results?.web?.[1]).toEqual({
+      url: 'https://example.com/quantum2',
+      title: 'Latest in Quantum Research',
+    });
+
+    // Verify fullResponse has complete data
+    expect(result.fullResponse).toEqual(mockResponse);
+    expect(result.fullResponse.results?.web).toHaveLength(2);
+  });
+
+  test('structuredContent validation for answer only', () => {
+    const mockResponse: ExpressAgentMcpResponse = {
+      answer: 'Neural networks are computational models inspired by biological neurons.',
+      agent: 'express',
+    };
+
+    const result = formatExpressAgentResponse(mockResponse);
+
+    // Verify structure matches minimal schema
+    expect(result.structuredContent).toMatchObject({
+      answer: expect.any(String),
+      hasResults: false,
+      resultCount: 0,
+      agent: 'express',
+    });
+
+    // Verify fullResponse has complete data
+    expect(result.fullResponse.results).toBeUndefined();
+  });
+
+  test('structuredContent validation for answer with results', () => {
+    const mockResponse: ExpressAgentMcpResponse = {
+      answer: 'Recent AI breakthroughs include advances in language models and computer vision.',
+      results: {
+        web: [
+          {
+            url: 'https://example.com/ai-breakthrough',
+            title: 'AI Breakthrough 2025',
+            snippet: 'Major advances in artificial intelligence.',
+          },
+        ],
+      },
+      agent: 'express',
+    };
+
+    const result = formatExpressAgentResponse(mockResponse);
+
+    // Verify structuredContent is minimal with counts
+    expect(result.structuredContent).toHaveProperty('answer');
+    expect(result.structuredContent).toHaveProperty('hasResults');
+    expect(result.structuredContent).toHaveProperty('resultCount');
+    expect(result.structuredContent).toHaveProperty('agent');
+    expect(result.structuredContent.answer).toBe(
+      'Recent AI breakthroughs include advances in language models and computer vision.',
+    );
+    expect(result.structuredContent.agent).toBe('express');
+    expect(result.structuredContent.hasResults).toBe(true);
+    expect(result.structuredContent.resultCount).toBe(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/ai-breakthrough',
+      title: 'AI Breakthrough 2025',
+    });
+
+    // Verify fullResponse has complete search results
+    expect(result.fullResponse).toEqual(mockResponse);
+    expect(result.fullResponse.results).toBeDefined();
+    expect(Array.isArray(result.fullResponse.results?.web)).toBe(true);
+    expect(result.fullResponse.results?.web.length).toBe(1);
+
+    // Verify search result fields in fullResponse
+    const searchResult = result.fullResponse.results?.web[0];
+    expect(searchResult?.url).toBe('https://example.com/ai-breakthrough');
+    expect(searchResult?.title).toBe('AI Breakthrough 2025');
+    expect(searchResult?.snippet).toBe('Major advances in artificial intelligence.');
+  });
+});