@youdotcom-oss/mcp 1.3.3 → 1.3.5-next.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.3.3",
+  "version": "1.3.5-next.11",
   "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.7",
-    "@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.22.0",
-    "hono": "^4.10.6",
-    "zod": "3.25.76"
+    "@modelcontextprotocol/inspector": "0.17.5"
   }
 }

package/src/contents/contents.schemas.ts

@@ -20,7 +20,7 @@ export type ContentsQuery = z.infer<typeof ContentsQuerySchema>;
  */
 const ContentsItemSchema = z.object({
   url: z.string().describe('URL'),
-  title: z.string().describe('Title'),
+  title: z.string().optional().describe('Title'),
   html: z.string().optional().describe('HTML content'),
   markdown: z.string().optional().describe('Markdown content'),
 });
@@ -44,7 +44,7 @@ export const ContentsStructuredContentSchema = z.object({
     .array(
       z.object({
         url: z.string().describe('URL'),
-        title: z.string().describe('Title'),
+        title: z.string().optional().describe('Title'),
         content: z.string().describe('Extracted content'),
         contentLength: z.number().describe('Content length'),
       }),

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