@microlink/mcp 1.0.0 → 1.1.0

package/src/microlink-client.js

@@ -1,239 +1,52 @@
-import mql from '@microlink/mql'
+import createClient, { MicrolinkError } from 'microlink.io'
 
-const RESPONSE_HEADER_KEYS = [
-  'x-request-id',
-  'x-pricing-plan',
-  'x-cache-status',
-  'x-cache-ttl',
-  'cf-cache-status',
-  'cache-control',
-  'x-rate-limit-limit',
-  'x-rate-limit-remaining',
-  'x-rate-limit-reset',
-  'x-response-time',
-  'content-type',
-  'content-encoding'
-]
-
-const FREE_ENDPOINT_ORIGIN = 'https://api.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 EMPTY_OBJECT_MEANS_TRUE_FLAGS = ['screenshot', 'pdf', 'insights']
-
-function isPlainObject (value) {
-  return Object.prototype.toString.call(value) === '[object Object]'
-}
-
-function isObject (value) {
-  return value !== null && typeof value === 'object'
-}
-
-function hasSerializableValue (value) {
-  if (value === undefined || value === null) {
-    return false
-  }
-
-  if (Array.isArray(value)) {
-    return value.length > 0
-  }
-
-  if (isPlainObject(value)) {
-    return Object.values(value).some(hasSerializableValue)
-  }
-
-  return true
-}
-
-function getHeaderValue (headers, headerName) {
-  if (!headers) {
-    return null
-  }
-
-  if (typeof headers.get === 'function') {
-    const value = headers.get(headerName)
-    return value ?? null
-  }
-
-  if (typeof headers !== 'object') {
-    return null
-  }
-
-  const lookup = headerName.toLowerCase()
-
-  for (const [key, value] of Object.entries(headers)) {
-    if (key.toLowerCase() === lookup) {
-      return value
-    }
-  }
-
-  return null
-}
-
-function pickResponseHeaders (headers) {
-  const output = {}
-
-  for (const headerName of RESPONSE_HEADER_KEYS) {
-    const value = getHeaderValue(headers, headerName)
-    if (value !== null) {
-      output[headerName] = value
-    }
-  }
-
-  return output
-}
-
-function withForcedFlags (opts, forcedFlags = {}) {
-  const nextOpts = { ...opts }
-
-  // Microlink treats empty objects for these toggles as enabled defaults.
-  // Normalize `{}` -> `true` so query serialization always keeps the flag.
-  for (const flagName of EMPTY_OBJECT_MEANS_TRUE_FLAGS) {
-    if (isPlainObject(nextOpts[flagName]) && !hasSerializableValue(nextOpts[flagName])) {
-      nextOpts[flagName] = true
-    }
-  }
 
-  for (const [flagName, flagValue] of Object.entries(forcedFlags)) {
-    if (!hasSerializableValue(nextOpts[flagName])) {
-      nextOpts[flagName] = flagValue
-    }
-  }
-
-  return nextOpts
-}
-
-function getEndpointFromRequestUrl (requestUrl) {
-  try {
-    return new URL(requestUrl).origin
-  } catch (_) {
-    return requestUrl
-  }
-}
-
-function stripResponseFromBody (body) {
-  if (!isPlainObject(body)) {
-    return body
-  }
+// A single shared client; the per-request apiKey travels in the options bag.
+export const client = createClient()
 
-  const { response, ...payload } = body
-  return payload
-}
-
-function withFreeQuotaHint (message, { requestUrl, statusCode }) {
-  const endpoint = getEndpointFromRequestUrl(requestUrl)
-
-  if (endpoint !== FREE_ENDPOINT_ORIGIN || statusCode !== 429) {
-    return message
-  }
-
-  if (typeof message === 'string' && message.includes('50 requests/day')) {
-    return message
-  }
-
-  if (typeof message === 'string' && message.trim().length > 0) {
-    return `${message} ${FREE_QUOTA_EXCEEDED_HINT}`
-  }
+export { MicrolinkError }
 
-  return FREE_QUOTA_EXCEEDED_HINT
+export function resolveApiKey (inputApiKey, headerApiKey) {
+  return (
+    inputApiKey || headerApiKey || process.env.MICROLINK_API_KEY || undefined
+  )
 }
 
-function toErrorBody (error, requestUrl, statusCode) {
-  if (!isObject(error)) {
-    return {
-      status: 'error',
-      message: withFreeQuotaHint(error instanceof Error ? error.message : String(error), { requestUrl, statusCode }),
-      url: requestUrl
-    }
-  }
-
-  const payload = {}
-
-  for (const key of ['status', 'data', 'more', 'code', 'id', 'report', 'message', 'url']) {
-    if (error[key] !== undefined) {
-      payload[key] = error[key]
-    }
-  }
-
-  if (payload.status === undefined) {
-    payload.status = 'error'
-  }
-
-  if (payload.message === undefined) {
-    payload.message = error.message || 'Microlink request failed.'
-  }
-  payload.message = withFreeQuotaHint(payload.message, { requestUrl, statusCode })
-
-  if (payload.url === undefined) {
-    payload.url = requestUrl
+// Every tool returns the library's direct result (a string, array, or object).
+// MCP `structuredContent` must be an object, so wrap the value under `data`.
+export function asToolResult (value) {
+  const data = value ?? null
+  return {
+    isError: false,
+    structuredContent: { data },
+    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
   }
-
-  return payload
 }
 
-export async function callMicrolink ({ params, forcedFlags = {} }) {
-  const { url, apiKey: requestApiKey, ...rawOpts } = params
-  const envApiKey = process.env.MICROLINK_API_KEY
-  const apiKey = requestApiKey || envApiKey
-  const opts = withForcedFlags(rawOpts, forcedFlags)
-
-  if (apiKey) {
-    opts.apiKey = apiKey
-  }
-
-  const [requestUrl, requestOpts] = mql.getApiUrl(url, opts, {
-    headers: {
-      accept: 'application/json'
-    }
-  })
-  const endpoint = getEndpointFromRequestUrl(requestUrl)
+export function asErrorResult (error) {
+  const isMql = error instanceof MicrolinkError
+  const statusCode = isMql ? error.statusCode : undefined
 
-  try {
-    const body = await mql.fetchFromApi(requestUrl, requestOpts)
-    const response = body?.response
-
-    return {
-      ok: true,
-      statusCode: response?.statusCode ?? 200,
-      requestUrl,
-      finalUrl: response?.url ?? requestUrl,
-      endpoint,
-      headers: pickResponseHeaders(response?.headers),
-      body: stripResponseFromBody(body)
-    }
-  } catch (error) {
-    return {
-      ok: false,
-      statusCode: error?.statusCode ?? 500,
-      requestUrl,
-      finalUrl: error?.url ?? requestUrl,
-      endpoint,
-      headers: pickResponseHeaders(error?.headers),
-      body: toErrorBody(error, requestUrl, error?.statusCode ?? 500)
-    }
+  const payload = {
+    message:
+      (isMql ? error.description : undefined) || error?.message || String(error)
   }
-}
 
-export function asToolResult (result) {
-  const output = {
-    endpoint: result.endpoint,
-    requestUrl: result.requestUrl,
-    finalUrl: result.finalUrl,
-    statusCode: result.statusCode,
-    responseHeaders: result.headers,
-    microlink: result.body
+  if (isMql) {
+    if (error.code) payload.code = error.code
+    if (error.status) payload.status = error.status
+    if (statusCode) payload.statusCode = statusCode
+    if (error.url) payload.url = error.url
+    if (error.more) payload.more = error.more
   }
 
-  const isMicrolinkError = result.body?.status && result.body.status !== 'success'
-  const isError = !result.ok || isMicrolinkError
+  if (statusCode === 429) payload.hint = FREE_QUOTA_EXCEEDED_HINT
 
   return {
-    isError,
-    structuredContent: output,
-    content: [
-      {
-        type: 'text',
-        text: JSON.stringify(output, null, 2)
-      }
-    ]
+    isError: true,
+    structuredContent: { error: payload },
+    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }]
   }
 }

package/src/schemas.js

@@ -1,6 +1,9 @@
 import { z } from 'zod'
 
-const stringOrStringArraySchema = z.union([z.string(), z.array(z.string()).min(1)])
+const stringOrStringArraySchema = z.union([
+  z.string(),
+  z.array(z.string()).min(1)
+])
 const stringOrNumberSchema = z.union([z.string(), z.number()])
 
 function coerceJsonObjectString (value) {
@@ -15,7 +18,11 @@ function coerceJsonObjectString (value) {
 
   try {
     const parsed = JSON.parse(input)
-    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (
+      parsed !== null &&
+      typeof parsed === 'object' &&
+      !Array.isArray(parsed)
+    ) {
       return parsed
     }
   } catch {
@@ -37,17 +44,27 @@ function coerceBooleanString (value) {
 
 const booleanSchema = z.preprocess(coerceBooleanString, z.boolean())
 const objectLikeSchema = schema => z.preprocess(coerceJsonObjectString, schema)
-const toggledObjectSchema = z.union([booleanSchema, objectLikeSchema(z.object({}).catchall(z.unknown()))])
+const toggledObjectSchema = z.union([
+  booleanSchema,
+  objectLikeSchema(z.object({}).catchall(z.unknown()))
+])
 const proxySchema = objectLikeSchema(
   z.union([z.string().min(1), z.object({}).catchall(z.unknown())])
 )
 
+// A CSS selector or an array of selectors (ordered fallbacks / unioned matches),
+// matching what the Microlink API and the microlink.io library accept.
+const selectorSchema = z.union([
+  z.string().min(1),
+  z.array(z.string().min(1)).min(1)
+])
+
 // A single data-extraction rule: CSS selector(s) + optional attr/type/evaluate/nested data.
 const dataSingleRuleSchema = objectLikeSchema(
   z
     .object({
-      selector: z.string().min(1).optional(),
-      selectorAll: z.string().min(1).optional(),
+      selector: selectorSchema.optional(),
+      selectorAll: selectorSchema.optional(),
       attr: z.string().min(1).optional(),
       type: z.string().min(1).optional(),
       evaluate: z.string().min(1).optional(),
@@ -57,9 +74,18 @@ const dataSingleRuleSchema = objectLikeSchema(
 )
 
 // A rule can also be an array of rules used as ordered fallback selectors.
-const dataRuleSchema = z.union([dataSingleRuleSchema, z.array(dataSingleRuleSchema).min(1)])
-
-const waitUntilEventSchema = z.enum(['auto', 'load', 'domcontentloaded', 'networkidle0', 'networkidle2'])
+const dataRuleSchema = z.union([
+  dataSingleRuleSchema,
+  z.array(dataSingleRuleSchema).min(1)
+])
+
+const waitUntilEventSchema = z.enum([
+  'auto',
+  'load',
+  'domcontentloaded',
+  'networkidle0',
+  'networkidle2'
+])
 
 const viewportSchema = objectLikeSchema(
   z
@@ -86,11 +112,14 @@ const screenshotOverlaySchema = objectLikeSchema(
 export const screenshotConfigSchema = objectLikeSchema(
   z
     .object({
+      animated: booleanSchema.optional(),
       codeScheme: z.string().min(1).optional(),
       element: z.string().min(1).optional(),
       fullPage: booleanSchema.optional(),
       omitBackground: booleanSchema.optional(),
+      optimizeForSpeed: booleanSchema.optional(),
       overlay: screenshotOverlaySchema.optional(),
+      palette: booleanSchema.optional(),
       type: z.enum(['jpeg', 'png']).optional()
     })
     .strict()
@@ -113,7 +142,21 @@ const pdfMarginSchema = objectLikeSchema(
 export const pdfConfigSchema = objectLikeSchema(
   z
     .object({
-      format: z.enum(['Letter', 'Legal', 'Tabloid', 'Ledger', 'A0', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6']).optional(),
+      format: z
+        .enum([
+          'Letter',
+          'Legal',
+          'Tabloid',
+          'Ledger',
+          'A0',
+          'A1',
+          'A2',
+          'A3',
+          'A4',
+          'A5',
+          'A6'
+        ])
+        .optional(),
       height: z.string().min(1).optional(),
       landscape: booleanSchema.optional(),
       margin: pdfMarginSchema.optional(),
@@ -125,7 +168,15 @@ export const pdfConfigSchema = objectLikeSchema(
 )
 
 const lighthouseOutputSchema = z.enum(['json', 'html', 'csv'])
-const lighthousePresetSchema = z.enum(['default', 'desktop', 'experimental', 'full', 'lr-desktop', 'lr-mobile', 'perf'])
+const lighthousePresetSchema = z.enum([
+  'default',
+  'desktop',
+  'experimental',
+  'full',
+  'lr-desktop',
+  'lr-mobile',
+  'perf'
+])
 
 const lighthouseConfigSchema = objectLikeSchema(
   z
@@ -186,7 +237,9 @@ const visualSchema = {
   filename: z.string().min(1).optional(),
   filter: z.string().min(1).optional(),
   force: booleanSchema.optional(),
-  headers: objectLikeSchema(z.record(z.string(), z.union([z.string(), z.number(), booleanSchema]))).optional(),
+  headers: objectLikeSchema(
+    z.record(z.string(), z.union([z.string(), z.number(), booleanSchema]))
+  ).optional(),
   javascript: booleanSchema.optional(),
   mediaType: z.enum(['screen', 'print']).optional(),
   modules: stringOrStringArraySchema.optional(),
@@ -202,7 +255,9 @@ const visualSchema = {
   viewport: viewportSchema.optional(),
   waitForSelector: z.string().min(1).optional(),
   waitForTimeout: stringOrNumberSchema.optional(),
-  waitUntil: z.union([waitUntilEventSchema, z.array(waitUntilEventSchema).min(1)]).optional()
+  waitUntil: z
+    .union([waitUntilEventSchema, z.array(waitUntilEventSchema).min(1)])
+    .optional()
 }
 
 export const extractInputSchema = baseSchema
@@ -231,12 +286,6 @@ export const pdfInputSchema = baseSchema
   })
   .strict()
 
-export const insightsInputSchema = baseSchema
-  .extend({
-    insights: z.union([booleanSchema, insightsConfigSchema]).optional()
-  })
-  .strict()
-
 export const audioInputSchema = baseSchema
   .extend({
     proxy: proxySchema.optional(),
@@ -253,19 +302,97 @@ export const videoInputSchema = baseSchema
   })
   .strict()
 
-export const paletteInputSchema = baseSchema
+export const logoInputSchema = baseSchema
   .extend({
-    meta: z.union([booleanSchema, metaConfigSchema]).optional(),
-    palette: booleanSchema.optional()
+    square: booleanSchema.optional()
   })
   .strict()
 
-export const metaInputSchema = baseSchema
+export const metadataInputSchema = baseSchema
   .extend({
     meta: z.union([booleanSchema, metaConfigSchema]).optional()
   })
   .strict()
 
-export const markdownInputSchema = baseSchema.strict()
+// Content tools (markdown/html/text) accept a selector to scope the extraction.
+const contentSchema = baseSchema
+  .extend({
+    selector: selectorSchema.optional(),
+    selectorAll: selectorSchema.optional(),
+    type: z.string().min(1).optional()
+  })
+  .strict()
+
+// Collection tools accept selector/attr/type overrides for the data rule.
+const collectionSchema = baseSchema
+  .extend({
+    selector: selectorSchema.optional(),
+    selectorAll: selectorSchema.optional(),
+    attr: z.string().min(1).optional(),
+    type: z.string().min(1).optional()
+  })
+  .strict()
+
+export const markdownInputSchema = contentSchema
+
+export const htmlInputSchema = contentSchema
+
+export const textInputSchema = contentSchema
+
+export const embedInputSchema = baseSchema
+  .extend({
+    maxWidth: z.coerce.number().int().positive().optional(),
+    maxHeight: z.coerce.number().int().positive().optional()
+  })
+  .strict()
+
+export const linksInputSchema = collectionSchema
+
+export const imagesInputSchema = collectionSchema
 
-export const textInputSchema = baseSchema.strict()
+export const videosInputSchema = collectionSchema
+
+export const audiosInputSchema = collectionSchema
+
+export const emailsInputSchema = collectionSchema
+
+export const technologiesInputSchema = baseSchema.strict()
+
+export const lighthouseInputSchema = baseSchema
+  .extend({
+    onlyCategories: z.array(z.string().min(1)).optional(),
+    onlyAudits: z.array(z.string().min(1)).optional(),
+    skipAudits: z.array(z.string().min(1)).optional(),
+    output: z.union([z.string().min(1), z.array(z.string().min(1))]).optional()
+  })
+  .strict()
+
+export const searchInputSchema = z
+  .object({
+    query: z.string().min(1),
+    apiKey: z.string().min(1).optional(),
+    type: z
+      .enum([
+        'search',
+        'news',
+        'images',
+        'videos',
+        'places',
+        'maps',
+        'shopping',
+        'scholar',
+        'patents',
+        'autocomplete'
+      ])
+      .optional(),
+    limit: z.coerce.number().int().positive().optional(),
+    location: z.string().min(1).optional(),
+    period: z.enum(['hour', 'day', 'week', 'month', 'year']).optional()
+  })
+  .strict()
+
+export const functionInputSchema = baseSchema
+  .extend({
+    code: z.string().min(1)
+  })
+  .strict()

package/src/tools/audio.js

@@ -1,17 +1,17 @@
 import { audioInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { register, urlMethod } from './register.js'
 
 export function audio (server) {
   register(
     server,
     'microlink_audio',
     [
-      'Detect and extract playable audio sources from any URL via Microlink.',
+      'Detect the primary playable audio of any public URL via Microlink.',
       'Works with SoundCloud, Spotify, Mixcloud, and other audio platforms.',
-      'The audio URL is in `data.audio.url`. Also returns `type`, `duration`, `size`, `duration_pretty`, and `size_pretty`.',
-      'Combine with `proxy` for sites that require it, or with `meta` to suppress metadata extraction.'
+      'Returns the audio asset: `url`, `type`, `duration`, `size`, `duration_pretty`, `size_pretty`.',
+      'Mirrors the `microlink.audio(url)` library method. For every audio on the page, use `microlink_audios`.'
     ].join(' '),
     audioInputSchema,
-    { audio: true, meta: false }
+    urlMethod('audio')
   )
 }

package/src/tools/audios.js

@@ -0,0 +1,16 @@
+import { audiosInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function audios (server) {
+  register(
+    server,
+    'microlink_audios',
+    [
+      'Collect every audio source (`<audio>`, `<source>`) from any public URL via Microlink.',
+      'Returns an array of absolute, deduped audio URLs.',
+      'Mirrors the `microlink.audios(url)` library method. For the primary playable audio, use `microlink_audio`.'
+    ].join(' '),
+    audiosInputSchema,
+    urlMethod('audios')
+  )
+}

package/src/tools/emails.js

@@ -0,0 +1,16 @@
+import { emailsInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function emails (server) {
+  register(
+    server,
+    'microlink_emails',
+    [
+      'Collect every email address present on any public URL via Microlink.',
+      'Detects addresses from `mailto:` links and plain text alike; returns a deduped array.',
+      'Mirrors the `microlink.emails(url)` library method.'
+    ].join(' '),
+    emailsInputSchema,
+    urlMethod('emails')
+  )
+}

package/src/tools/embed.js

@@ -0,0 +1,17 @@
+import { embedInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function embed (server) {
+  register(
+    server,
+    'microlink_embed',
+    [
+      'Get the oEmbed-style embeddable iframe for any public URL via Microlink (YouTube, Tweet, CodePen, ...).',
+      'Returns `{ html, scripts }` — the markup to embed plus the script URLs it needs.',
+      'Pass `maxWidth` / `maxHeight` to constrain the embed size.',
+      'Mirrors the `microlink.embed(url)` library method.'
+    ].join(' '),
+    embedInputSchema,
+    urlMethod('embed')
+  )
+}

package/src/tools/extract.js

@@ -6,15 +6,13 @@ export function extract (server) {
     server,
     'microlink_extract',
     [
-      'Extract structured metadata from any public URL via Microlink.',
-      'Returns normalized fields: title, description, author, publisher, date, image, logo, lang, and url.',
-      'Use the `data` parameter to scrape custom fields via CSS selectors (selector/selectorAll, attr, type, evaluate).',
-      'Combine with `screenshot`, `pdf`, `video`, `audio`, `insights`, `palette`, `iframe` in a single request.',
-      'For `screenshot`, `pdf`, and `insights`, pass `true` to enable defaults or pass a config object with options; `{}` is treated as `true`.',
-      'Supports device emulation (`device`), custom headers, proxy, JavaScript injection (`scripts`, `modules`, `function`), interaction (`click`, `scroll`), and caching (`ttl`, `staleTtl`, `force`).',
-      'The CDN asset URL for any enabled media feature is in `data.<feature>.url` (e.g. `data.screenshot.url`).'
+      'Scrape custom fields from any public URL via Microlink using MQL data rules.',
+      'Pass `data` with the rules object (selector/selectorAll, attr, type, evaluate; nested rules and arrays supported); returns the extracted `data` object.',
+      'Also supports combining capabilities (`screenshot`, `pdf`, `iframe`, `insights`) and browser controls in the same request.',
+      'Mirrors the `microlink.extract(url, rules)` library method.'
     ].join(' '),
     extractInputSchema,
-    {}
+    (client, { url, data, ...options }) =>
+      client.extract(url, data ?? {}, options)
   )
 }

package/src/tools/function.js

@@ -0,0 +1,16 @@
+import { functionInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function fn (server) {
+  register(
+    server,
+    'microlink_function',
+    [
+      'Run a JavaScript function against any public URL inside Microlink’s server-side browser sandbox.',
+      'Pass `code` as the function source (e.g. "async ({ page }) => page.title()"); it receives `{ page, response, ...args }` and its return value comes back in `value`.',
+      'Also returns `isFulfilled`, `profiling`, and `logging`. Mirrors the `microlink.function(url, code)` library method.'
+    ].join(' '),
+    functionInputSchema,
+    (client, { url, code, ...options }) => client.function(url, code, options)
+  )
+}

package/src/tools/html.js

@@ -0,0 +1,16 @@
+import { htmlInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function html (server) {
+  register(
+    server,
+    'microlink_html',
+    [
+      'Extract the HTML content of any public URL via Microlink.',
+      'Returns the page HTML as a string. Pass `selector` to scope it to part of the page.',
+      'Mirrors the `microlink.html(url)` library method.'
+    ].join(' '),
+    htmlInputSchema,
+    urlMethod('html')
+  )
+}