@microlink/mcp 2.2.0 → 2.3.0

package/package.json

@@ -2,7 +2,7 @@
   "name": "@microlink/mcp",
   "description": "MCP server for Microlink API",
   "homepage": "https://github.com/microlinkhq/microlink",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -66,5 +66,5 @@
     "access": "public"
   },
   "type": "module",
-  "gitHead": "6a9b3891741143671b096d53c0d9e69f6b62cb94"
+  "gitHead": "9e479486674289cd4f5257b4c1fd5ad527f6ebb1"
 }

package/src/output-schemas.js

@@ -0,0 +1,108 @@
+import { z } from 'zod'
+
+// Output schemas for every tool's `structuredContent.data` value.
+// They mirror the TypeScript definitions that ship with the library
+// (packages/core/src/index.d.ts, packages/search/src/index.d.ts), which are
+// the canonical contract for response shapes. Index signatures map to
+// `.catchall(z.unknown())` so forward-compatible API fields always validate.
+
+// `Asset` (packages/core/src/index.d.ts).
+const assetSchema = z
+  .object({
+    url: z.string(),
+    type: z.string().optional(),
+    size: z.number().optional(),
+    size_pretty: z.string().optional(),
+    width: z.number().optional(),
+    height: z.number().optional()
+  })
+  .catchall(z.unknown())
+
+// logo/video/audio return `Asset | null`: the primary media field is null
+// when the page has no detectable asset.
+const nullableAssetSchema = assetSchema.nullable()
+
+// `Metadata` (packages/core/src/index.d.ts).
+const metadataSchema = z
+  .object({
+    title: z.string().nullable().optional(),
+    description: z.string().nullable().optional(),
+    url: z.string().nullable().optional()
+  })
+  .catchall(z.unknown())
+
+// `Embed` (packages/core/src/index.d.ts). `embed()` returns `data.iframe`
+// verbatim; a successful response omits it when oEmbed discovery fails,
+// and asToolResult stores that as null.
+const embedSchema = z
+  .object({
+    html: z.string(),
+    scripts: z.array(z.unknown()).optional()
+  })
+  .catchall(z.unknown())
+  .nullable()
+
+// `FunctionResult<unknown>` (packages/core/src/index.d.ts); profiling and
+// logging are optional because the API may omit them.
+const functionResultSchema = z
+  .object({
+    isFulfilled: z.boolean(),
+    value: z.unknown(),
+    profiling: z.record(z.string(), z.unknown()).optional(),
+    logging: z.record(z.string(), z.unknown()).optional()
+  })
+  .catchall(z.unknown())
+
+// Search pages (packages/search/src/index.d.ts) projected to JSON: the lazy
+// helpers (`html()`, `markdown()`, `next()`) are functions and never reach
+// the wire. One tolerant shape covers every vertical, including autocomplete
+// (`{ value }` results).
+const searchResultSchema = z
+  .object({
+    title: z.string().optional(),
+    url: z.string().optional(),
+    description: z.string().optional(),
+    value: z.string().optional()
+  })
+  .catchall(z.unknown())
+
+const searchPageSchema = z
+  .object({
+    results: z.array(searchResultSchema),
+    knowledgeGraph: z.record(z.string(), z.unknown()).optional(),
+    peopleAlsoAsk: z.array(z.record(z.string(), z.unknown())).optional(),
+    relatedSearches: z.array(z.record(z.string(), z.unknown())).optional()
+  })
+  .catchall(z.unknown())
+
+// Content rules return null when the selector matches nothing
+// (verified against the live API: data.markdown/text are null on no match).
+const stringSchema = z.string().nullable()
+const stringArraySchema = z.array(z.string())
+const recordSchema = z.record(z.string(), z.unknown())
+const unknownArraySchema = z.array(z.unknown())
+// Default Lighthouse JSON is an object; `output: 'html' | 'csv'` returns a string.
+const lighthouseSchema = z.union([z.string(), recordSchema])
+
+export const outputSchemas = {
+  metadata: metadataSchema,
+  logo: nullableAssetSchema,
+  markdown: stringSchema,
+  html: stringSchema,
+  text: stringSchema,
+  screenshot: assetSchema,
+  pdf: assetSchema,
+  embed: embedSchema,
+  video: nullableAssetSchema,
+  audio: nullableAssetSchema,
+  links: stringArraySchema,
+  images: stringArraySchema,
+  videos: stringArraySchema,
+  audios: stringArraySchema,
+  emails: stringArraySchema,
+  technologies: unknownArraySchema,
+  lighthouse: lighthouseSchema,
+  search: searchPageSchema,
+  function: functionResultSchema,
+  extract: recordSchema
+}

package/src/schemas.js

@@ -215,8 +215,19 @@ export const metaConfigSchema = objectLikeSchema(
 )
 
 const baseSchema = z.object({
-  url: z.string().url(),
-  apiKey: z.string().min(1).optional()
+  url: z
+    .string()
+    .url()
+    .describe(
+      'Public URL of the page to process. Include the protocol, for example https://example.com.'
+    ),
+  apiKey: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Microlink PRO API key. Omit it unless you have one: requests then use the MICROLINK_API_KEY environment variable or the free endpoint.'
+    )
 })
 
 const fullShape = {
@@ -386,8 +397,19 @@ export const lighthouseInputSchema = baseSchema
 
 export const searchInputSchema = z
   .object({
-    query: z.string().min(1),
-    apiKey: z.string().min(1).optional(),
+    query: z
+      .string()
+      .min(1)
+      .describe(
+        'Google search query. Operators like site:, filetype: or quotes work as-is.'
+      ),
+    apiKey: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        'Microlink API key. Required for this tool: Google search runs on the PRO endpoint.'
+      ),
     type: z
       .enum([
         'search',

package/src/tools/register.js

@@ -4,6 +4,7 @@ import {
   client,
   resolveApiKey
 } from '../microlink-client.js'
+import { outputSchemas } from '../output-schemas.js'
 
 function getHeaderValueCaseInsensitive (headers, headerName) {
   if (!headers || typeof headers !== 'object') {
@@ -79,9 +80,16 @@ export function register (
   invoke,
   annotations = READ_ONLY_ANNOTATIONS
 ) {
+  // Every tool wraps its result as `structuredContent.data`; the output
+  // schema describes that `data` value (see output-schemas.js). Error
+  // results are exempt: the SDK skips output validation when `isError`.
+  const key = name.replace(/^microlink_/, '')
+  const dataSchema = outputSchemas[key]
+  const outputSchema = dataSchema ? { data: dataSchema } : undefined
+
   server.registerTool(
     name,
-    { description, inputSchema, annotations },
+    { description, inputSchema, outputSchema, annotations },
     async (args, extra) => {
       const parsed = inputSchema.safeParse(args)