@youdotcom-oss/mcp 1.5.1 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@youdotcom-oss/mcp",
-  "version": "1.5.1",
-  "description": "You.com API Model Context Protocol Server",
+  "version": "1.6.0",
+  "description": "You.com API Model Context Protocol Server - For programmatic API access, use @youdotcom-oss/api",
   "license": "MIT",
   "engines": {
     "node": ">=18",
@@ -24,14 +24,8 @@
   ],
   "bin": "bin/stdio.js",
   "type": "module",
-  "main": "./src/main.ts",
   "exports": {
-    ".": {
-      "types": "./dist/main.d.ts",
-      "default": "./src/main.ts"
-    },
-    "./http": "./src/http.ts",
-    "./stdio": "./src/stdio.ts"
+    "./http": "./src/http.ts"
   },
   "files": [
     "bin/stdio.js",
@@ -44,36 +38,31 @@
     "access": "public"
   },
   "scripts": {
-    "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",
+    "build": "bun build ./src/stdio.ts --outfile ./bin/stdio.js --target=node",
     "check": "bun run check:biome && bun run check:types && bun run check:package",
     "check:biome": "biome check",
     "check:package": "format-package --check",
     "check:types": "tsc --noEmit",
-    "check:write": "bun run format && bun run lint:fix && bun run format:package",
+    "check:write": "biome check --write && bun run format:package",
     "dev": "bun src/stdio.ts",
-    "format": "biome format --write",
-    "format:check": "biome format",
     "format:package": "format-package --write",
     "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",
-    "start": "bun run bin/http",
+    "prepublishOnly": "bun run build",
+    "start": "bun run src/http.ts",
     "test": "bun test",
     "test:coverage": "bun test --coverage",
     "test:coverage:watch": "bun test --coverage --watch",
     "test:watch": "bun test --watch"
   },
   "mcpName": "io.github.youdotcom-oss/mcp",
-  "types": "./dist/main.d.ts",
   "dependencies": {
-    "zod": "^4.3.5",
+    "@youdotcom-oss/api": "0.1.1",
+    "zod": "^4.3.6",
     "@hono/mcp": "^0.2.3",
-    "@modelcontextprotocol/sdk": "^1.25.2",
-    "hono": "^4.11.4"
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "hono": "^4.11.7"
   },
   "devDependencies": {
-    "@modelcontextprotocol/inspector": "0.18.0"
+    "@modelcontextprotocol/inspector": "0.19.0"
   }
 }

package/src/contents/contents.schemas.ts

@@ -1,49 +1,4 @@
-import * as z from 'zod';
-
-/**
- * Input schema for the you-contents tool
- * Accepts an array of URLs, optional formats array (or legacy format string), and optional crawl timeout
- */
-export const ContentsQuerySchema = z.object({
-  urls: z
-    .array(z.string().url())
-    .min(1)
-    .describe('Array of webpage URLs to extract content from (e.g., ["https://example.com"])'),
-  formats: z
-    .array(z.enum(['markdown', 'html', 'metadata']))
-    .optional()
-    .describe('Output formats: array of "markdown" (text), "html" (layout), or "metadata" (structured data)'),
-  format: z.enum(['markdown', 'html']).optional().describe('(Deprecated) Output format - use formats array instead'),
-  crawl_timeout: z.number().min(1).max(60).optional().describe('Optional timeout in seconds (1-60) for page crawling'),
-});
-
-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().optional().describe('Title'),
-  html: z.string().optional().describe('HTML content'),
-  markdown: z.string().optional().describe('Markdown content'),
-  metadata: z
-    .object({
-      jsonld: z.array(z.record(z.string(), z.unknown())).optional().describe('JSON-LD structured data (Schema.org)'),
-      opengraph: z.record(z.string(), z.string()).optional().describe('OpenGraph meta tags'),
-      twitter: z.record(z.string(), z.string()).optional().describe('Twitter Card metadata'),
-    })
-    .optional()
-    .describe('Structured metadata when available'),
-});
-
-/**
- * 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>;
+import * as z from 'zod'
 
 /**
  * Structured content schema for MCP response
@@ -70,6 +25,6 @@ export const ContentsStructuredContentSchema = z.object({
       }),
     )
     .describe('Extracted items'),
-});
+})
 
-export type ContentsStructuredContent = z.infer<typeof ContentsStructuredContentSchema>;
+export type ContentsStructuredContent = z.infer<typeof ContentsStructuredContentSchema>

package/src/contents/contents.utils.ts

@@ -1,105 +1,5 @@
-import { CONTENTS_API_URL } from '../shared/api-constants.ts';
-import { checkResponseForErrors } from '../shared/check-response-for-errors.ts';
-import {
-  type ContentsApiResponse,
-  ContentsApiResponseSchema,
-  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 const fetchContents = async ({
-  contentsQuery: { urls, formats, format, crawl_timeout },
-  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');
-  }
-
-  // Handle backward compatibility: prefer formats array, fallback to format string, default to ['markdown']
-  const requestFormats = formats || (format ? [format] : ['markdown']);
-
-  // Build request body
-  const requestBody: {
-    urls: string[];
-    formats: string[];
-    crawl_timeout?: number;
-  } = {
-    urls,
-    formats: requestFormats,
-  };
-
-  if (crawl_timeout !== undefined) {
-    requestBody.crawl_timeout = crawl_timeout;
-  }
-
-  // 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(requestBody),
-  };
-
-  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;
-};
+import type { ContentsApiResponse } from '@youdotcom-oss/api'
+import type { ContentsStructuredContent } from './contents.schemas.ts'
 
 /**
  * Format contents API response for MCP output
@@ -112,69 +12,69 @@ export const formatContentsResponse = (
   response: ContentsApiResponse,
   formats: string[],
 ): {
-  content: Array<{ type: 'text'; text: string }>;
-  structuredContent: ContentsStructuredContent;
+  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`];
-  textParts.push(`Formats: ${formats.join(', ')}\n`);
+  const textParts: string[] = [`Successfully extracted content from ${response.length} URL(s):\n`]
+  textParts.push(`Formats: ${formats.join(', ')}\n`)
 
-  const items: ContentsStructuredContent['items'] = [];
+  const items: ContentsStructuredContent['items'] = []
 
   for (const item of response) {
     // Add header for this item
-    textParts.push(`\n## ${item.title || 'Untitled'}`);
-    textParts.push(`URL: ${item.url}\n`);
-    textParts.push('---\n');
+    textParts.push(`\n## ${item.title || 'Untitled'}`)
+    textParts.push(`URL: ${item.url}\n`)
+    textParts.push('---\n')
 
     // Add content based on requested formats
     if (formats.includes('markdown') && item.markdown) {
-      textParts.push('\n### Markdown Content\n');
-      textParts.push(item.markdown);
-      textParts.push('\n');
+      textParts.push('\n### Markdown Content\n')
+      textParts.push(item.markdown)
+      textParts.push('\n')
     }
 
     if (formats.includes('html') && item.html) {
-      textParts.push('\n### HTML Content\n');
-      textParts.push(`Length: ${item.html.length} characters\n`);
-      textParts.push(item.html.substring(0, 500));
+      textParts.push('\n### HTML Content\n')
+      textParts.push(`Length: ${item.html.length} characters\n`)
+      textParts.push(item.html.substring(0, 500))
       if (item.html.length > 500) {
-        textParts.push('...\n(truncated for display)');
+        textParts.push('...\n(truncated for display)')
       }
-      textParts.push('\n');
+      textParts.push('\n')
     }
 
     if (formats.includes('metadata') && item.metadata) {
-      textParts.push('\n### Metadata\n');
+      textParts.push('\n### Metadata\n')
 
       if (item.metadata.jsonld && item.metadata.jsonld.length > 0) {
-        textParts.push('\n**JSON-LD:**\n');
-        const jsonldStr = JSON.stringify(item.metadata.jsonld, null, 2);
+        textParts.push('\n**JSON-LD:**\n')
+        const jsonldStr = JSON.stringify(item.metadata.jsonld, null, 2)
         if (jsonldStr.length > 2000) {
-          textParts.push(jsonldStr.substring(0, 2000));
-          textParts.push('\n...(truncated for display, see structuredContent for full data)');
+          textParts.push(jsonldStr.substring(0, 2000))
+          textParts.push('\n...(truncated for display, see structuredContent for full data)')
         } else {
-          textParts.push(jsonldStr);
+          textParts.push(jsonldStr)
         }
-        textParts.push('\n');
+        textParts.push('\n')
       }
 
       if (item.metadata.opengraph) {
-        textParts.push('\n**OpenGraph:**\n');
+        textParts.push('\n**OpenGraph:**\n')
         for (const [key, value] of Object.entries(item.metadata.opengraph)) {
-          textParts.push(`- ${key}: ${value}\n`);
+          textParts.push(`- ${key}: ${value}\n`)
         }
       }
 
       if (item.metadata.twitter) {
-        textParts.push('\n**Twitter:**\n');
+        textParts.push('\n**Twitter:**\n')
         for (const [key, value] of Object.entries(item.metadata.twitter)) {
-          textParts.push(`- ${key}: ${value}\n`);
+          textParts.push(`- ${key}: ${value}\n`)
         }
       }
     }
 
-    textParts.push('\n---\n');
+    textParts.push('\n---\n')
 
     // Add to structured content
     items.push({
@@ -183,7 +83,7 @@ export const formatContentsResponse = (
       markdown: item.markdown,
       html: item.html,
       metadata: item.metadata,
-    });
+    })
   }
 
   return {
@@ -198,5 +98,5 @@ export const formatContentsResponse = (
       formats,
       items,
     },
-  };
-};
+  }
+}

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

@@ -1,8 +1,8 @@
-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';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { ContentsQuerySchema, fetchContents, generateErrorReportLink } from '@youdotcom-oss/api'
+import { getLogger } from '../shared/get-logger.ts'
+import { ContentsStructuredContentSchema } from './contents.schemas.ts'
+import { formatContentsResponse } from './contents.utils.ts'
 
 /**
  * Register the you-contents tool with the MCP server
@@ -13,9 +13,9 @@ export const registerContentsTool = ({
   YDC_API_KEY,
   getUserAgent,
 }: {
-  mcp: McpServer;
-  YDC_API_KEY?: string;
-  getUserAgent: () => string;
+  mcp: McpServer
+  YDC_API_KEY?: string
+  getUserAgent: () => string
 }) => {
   // Register the tool
   mcp.registerTool(
@@ -27,56 +27,56 @@ export const registerContentsTool = ({
       outputSchema: ContentsStructuredContentSchema.shape,
     },
     async (toolInput) => {
-      const logger = getLogger(mcp);
+      const logger = getLogger(mcp)
 
       try {
         // Validate and parse input
-        const contentsQuery = ContentsQuerySchema.parse(toolInput);
-        const { urls, formats, format, crawl_timeout } = contentsQuery;
+        const contentsQuery = ContentsQuerySchema.parse(toolInput)
+        const { urls, formats, format, crawl_timeout } = contentsQuery
 
         // Handle backward compatibility: prefer formats array, fallback to format string, default to ['markdown']
-        const requestFormats = formats || (format ? [format] : ['markdown']);
+        const requestFormats = formats || (format ? [format] : ['markdown'])
 
         // Log the request
-        const timeoutInfo = crawl_timeout ? ` with timeout: ${crawl_timeout}s` : '';
+        const timeoutInfo = crawl_timeout ? ` with timeout: ${crawl_timeout}s` : ''
         await logger({
           level: 'info',
           data: `Contents API call initiated for ${urls.length} URL(s) with formats: ${requestFormats.join(', ')}${timeoutInfo}`,
-        });
+        })
 
         // Fetch contents from API
         const response = await fetchContents({
           contentsQuery,
           YDC_API_KEY,
           getUserAgent,
-        });
+        })
 
         // Format response with full content
-        const { content, structuredContent } = formatContentsResponse(response, requestFormats);
+        const { content, structuredContent } = formatContentsResponse(response, requestFormats)
 
         // 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 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: [
@@ -87,8 +87,8 @@ export const registerContentsTool = ({
           ],
           structuredContent: undefined,
           isError: true,
-        };
+        }
       }
     },
-  );
-};
+  )
+}