@microlink/mcp 2.2.0 → 2.4.0

package/README.md

@@ -161,7 +161,7 @@ Each tool is a thin wrapper over a [`microlink.io`](https://github.com/microlink
 ### Response shape
 
 - Each tool returns the library's **direct result** under `structuredContent.data` (and the same value as pretty-printed JSON text). For example `microlink_markdown` → `{ data: "# Title\n..." }`, `microlink_screenshot` → `{ data: { url, type, width, height, size } }`, `microlink_links` → `{ data: ["https://...", ...] }`.
-- On failure the tool sets MCP `isError` and returns `{ error: { message, code?, status?, statusCode?, url?, more? } }`. A `429` also includes a free-quota `hint`.
+- On failure the tool sets MCP `isError` and returns `{ error: { message, code?, status?, statusCode?, url?, more?, details? } }`, where `message` carries the specific cause reported by the API. Capability errors that retrying cannot fix (for example `EPROXYNEEDED` or `EINTEGRATION`) also include machine-readable `reason` (`upgrade_required`), `capability`, an `upgrade` object with the plan and pricing URL, and an agent-facing `hint` with the next step. A `429` includes `reason: "quota_exceeded"` and a free-quota `hint`.
 
 Parameters labeled `PRO` in the official Microlink docs require a paid plan.
 For compatibility with some MCP clients:
@@ -522,7 +522,7 @@ The `MICROLINK_API_KEY` environment variable is the recommended approach for mos
 
 If an API key is present, requests are sent to `https://pro.microlink.io`; otherwise they go to `https://api.microlink.io` (free endpoint).
 
-When the free endpoint returns `429`, this MCP adds a clear hint in the tool error message: free daily quota reached (`50 requests/day`) and upgrade/API key guidance at [microlink.io/#pricing](https://microlink.io/#pricing).
+When the free endpoint returns `429`, this MCP adds a clear hint in the tool error message: free daily quota reached, plus upgrade/API key guidance at [microlink.io/#pricing](https://microlink.io/#pricing).
 
 ## License
 

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.4.0",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -66,5 +66,5 @@
     "access": "public"
   },
   "type": "module",
-  "gitHead": "6a9b3891741143671b096d53c0d9e69f6b62cb94"
+  "gitHead": "de05659e0fe9d49ba25643efbcb9914d5332ca91"
 }

package/src/microlink-client.js

@@ -1,7 +1,25 @@
 import createClient, { MicrolinkError } from 'microlink.io'
 
-const FREE_QUOTA_EXCEEDED_HINT =
-  'Free daily quota reached (50 requests/day). Extend your limit by getting an API key at https://microlink.io/#pricing.'
+const UPGRADE_URL = 'https://microlink.io/#pricing'
+
+const FREE_QUOTA_EXCEEDED_HINT = `Free daily quota reached. Extend your limit by getting an API key at ${UPGRADE_URL}.`
+
+// Actionable guidance for capability errors that retrying cannot fix:
+// what happened, why, and how to continue. `reason` and `capability` are
+// machine-readable so clients can react programmatically; `hint` is the
+// agent-facing next step.
+const ERROR_GUIDANCE = {
+  EPROXYNEEDED: {
+    reason: 'upgrade_required',
+    capability: 'proxy',
+    hint: `The target website is behind antibot protection and needs the Microlink proxy network, included in PRO plans. The request is correct: get an API key at ${UPGRADE_URL}, pass it as \`apiKey\` (or set MICROLINK_API_KEY) and repeat the same call.`
+  },
+  EINTEGRATION: {
+    reason: 'upgrade_required',
+    capability: 'integration',
+    hint: `This capability requires a PRO plan. Get an API key at ${UPGRADE_URL}, pass it as \`apiKey\` (or set MICROLINK_API_KEY) and repeat the same call.`
+  }
+}
 
 // A single shared client; the per-request apiKey travels in the options bag.
 export const client = createClient()
@@ -25,13 +43,38 @@ export function asToolResult (value) {
   }
 }
 
+const isPlainObject = value =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+
+// The API wraps some failures in a generic top-level message ("The request
+// has been not processed…"), while the specific cause travels in `data`
+// (e.g. `data.url`). Only then should the data-derived message lead: a
+// specific description is the real cause and must not be hidden by
+// auxiliary strings in `data`.
+const GENERIC_API_MESSAGE = 'The request has been not processed.'
+
 export function asErrorResult (error) {
   const isMql = error instanceof MicrolinkError
   const statusCode = isMql ? error.statusCode : undefined
+  const description = isMql ? error.description : undefined
+
+  const details = isMql && isPlainObject(error.data) ? error.data : undefined
+  const detailMessage =
+    details &&
+    Object.values(details)
+      .filter(value => typeof value === 'string')
+      .join(' ')
+
+  const isGenericDescription =
+    typeof description === 'string' &&
+    description.startsWith(GENERIC_API_MESSAGE)
 
   const payload = {
     message:
-      (isMql ? error.description : undefined) || error?.message || String(error)
+      (isGenericDescription ? detailMessage : undefined) ||
+      description ||
+      error?.message ||
+      String(error)
   }
 
   if (isMql) {
@@ -40,9 +83,21 @@ export function asErrorResult (error) {
     if (statusCode) payload.statusCode = statusCode
     if (error.url) payload.url = error.url
     if (error.more) payload.more = error.more
+    if (details) payload.details = details
   }
 
-  if (statusCode === 429) payload.hint = FREE_QUOTA_EXCEEDED_HINT
+  const guidance = isMql && ERROR_GUIDANCE[error.code]
+  if (guidance) {
+    payload.reason = guidance.reason
+    payload.capability = guidance.capability
+    payload.hint = guidance.hint
+    payload.upgrade = { plan: 'pro', url: UPGRADE_URL }
+  }
+
+  if (statusCode === 429) {
+    payload.reason = 'quota_exceeded'
+    payload.hint = FREE_QUOTA_EXCEEDED_HINT
+  }
 
   return {
     isError: true,

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 = {
@@ -231,28 +242,51 @@ const fullShape = {
 // Shared Microlink API query parameters (see microlink.io/docs/api/parameters).
 // Product tools layer their own fields on top; these apply to any URL fetch.
 // `data` is separate: content/collection helpers overwrite it with their field rule.
+// PRO parameters per the Microlink API spec (https://microlink.io/openapi.json):
+// they only take effect with an API key attached to the request.
+const PRO = 'PRO: requires a Microlink API key (Pro plan).'
+
 const browserSchema = {
   adblock: booleanSchema.optional(),
   animations: booleanSchema.optional(),
-  cacheKey: z.string().min(1).optional(),
+  cacheKey: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(`Custom cache key for the request. ${PRO}`),
   click: stringOrStringArraySchema.optional(),
   colorScheme: z.enum(['no-preference', 'light', 'dark']).optional(),
   device: z.string().min(1).optional(),
-  filename: z.string().min(1).optional(),
+  filename: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(`Custom name for the generated asset. ${PRO}`),
   filter: z.string().min(1).optional(),
   force: booleanSchema.optional(),
   headers: objectLikeSchema(
     z.record(z.string(), z.union([z.string(), z.number(), booleanSchema]))
-  ).optional(),
+  )
+    .optional()
+    .describe(`Custom HTTP headers sent to the target URL. ${PRO}`),
   javascript: booleanSchema.optional(),
   mediaType: z.enum(['screen', 'print']).optional(),
   modules: stringOrStringArraySchema.optional(),
   prerender: z.union([z.literal('auto'), booleanSchema]).optional(),
-  proxy: proxySchema.optional(),
+  proxy: proxySchema
+    .optional()
+    .describe(
+      `Proxy rotation to bypass IP rate limits, CAPTCHAs and regional restrictions. ${PRO}`
+    ),
   retry: z.number().int().nonnegative().optional(),
   scripts: stringOrStringArraySchema.optional(),
   scroll: z.string().min(1).optional(),
-  staleTtl: z.union([z.string(), z.number(), booleanSchema]).optional(),
+  staleTtl: z
+    .union([z.string(), z.number(), booleanSchema])
+    .optional()
+    .describe(
+      `Serve stale cached content while refreshing it in the background. ${PRO}`
+    ),
   styles: stringOrStringArraySchema.optional(),
   timeout: stringOrNumberSchema.optional(),
   ttl: stringOrNumberSchema.optional(),
@@ -386,8 +420,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)