@microlink/mcp 1.0.0

package/src/microlink-client.js

@@ -0,0 +1,239 @@
+import mql from '@microlink/mql'
+
+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
+  }
+
+  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}`
+  }
+
+  return FREE_QUOTA_EXCEEDED_HINT
+}
+
+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
+  }
+
+  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)
+
+  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)
+    }
+  }
+}
+
+export function asToolResult (result) {
+  const output = {
+    endpoint: result.endpoint,
+    requestUrl: result.requestUrl,
+    finalUrl: result.finalUrl,
+    statusCode: result.statusCode,
+    responseHeaders: result.headers,
+    microlink: result.body
+  }
+
+  const isMicrolinkError = result.body?.status && result.body.status !== 'success'
+  const isError = !result.ok || isMicrolinkError
+
+  return {
+    isError,
+    structuredContent: output,
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(output, null, 2)
+      }
+    ]
+  }
+}

package/src/schemas.js

@@ -0,0 +1,271 @@
+import { z } from 'zod'
+
+const stringOrStringArraySchema = z.union([z.string(), z.array(z.string()).min(1)])
+const stringOrNumberSchema = z.union([z.string(), z.number()])
+
+function coerceJsonObjectString (value) {
+  if (typeof value !== 'string') {
+    return value
+  }
+
+  const input = value.trim()
+  if (input.length < 2 || !input.startsWith('{') || !input.endsWith('}')) {
+    return value
+  }
+
+  try {
+    const parsed = JSON.parse(input)
+    if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      return parsed
+    }
+  } catch {
+    // Keep original value and let schema validation surface the error.
+  }
+
+  return value
+}
+
+function coerceBooleanString (value) {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase()
+    if (normalized === 'true') return true
+    if (normalized === 'false') return false
+  }
+
+  return 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 proxySchema = objectLikeSchema(
+  z.union([z.string().min(1), z.object({}).catchall(z.unknown())])
+)
+
+// 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(),
+      attr: z.string().min(1).optional(),
+      type: z.string().min(1).optional(),
+      evaluate: z.string().min(1).optional(),
+      data: z.record(z.string(), z.unknown()).optional()
+    })
+    .catchall(z.unknown())
+)
+
+// 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 viewportSchema = objectLikeSchema(
+  z
+    .object({
+      width: z.number().positive().optional(),
+      height: z.number().positive().optional(),
+      deviceScaleFactor: z.number().positive().optional(),
+      isMobile: booleanSchema.optional(),
+      hasTouch: booleanSchema.optional(),
+      isLandscape: booleanSchema.optional()
+    })
+    .strict()
+)
+
+const screenshotOverlaySchema = objectLikeSchema(
+  z
+    .object({
+      browser: z.enum(['light', 'dark']).optional(),
+      background: z.string().min(1).optional()
+    })
+    .strict()
+)
+
+export const screenshotConfigSchema = objectLikeSchema(
+  z
+    .object({
+      codeScheme: z.string().min(1).optional(),
+      element: z.string().min(1).optional(),
+      fullPage: booleanSchema.optional(),
+      omitBackground: booleanSchema.optional(),
+      overlay: screenshotOverlaySchema.optional(),
+      type: z.enum(['jpeg', 'png']).optional()
+    })
+    .strict()
+)
+
+const pdfMarginSchema = objectLikeSchema(
+  z.union([
+    z.string().min(1),
+    z
+      .object({
+        top: z.string().min(1).optional(),
+        bottom: z.string().min(1).optional(),
+        left: z.string().min(1).optional(),
+        right: z.string().min(1).optional()
+      })
+      .strict()
+  ])
+)
+
+export const pdfConfigSchema = objectLikeSchema(
+  z
+    .object({
+      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(),
+      pageRanges: z.string().min(1).optional(),
+      scale: z.number().min(0.1).max(2).optional(),
+      width: z.string().min(1).optional()
+    })
+    .strict()
+)
+
+const lighthouseOutputSchema = z.enum(['json', 'html', 'csv'])
+const lighthousePresetSchema = z.enum(['default', 'desktop', 'experimental', 'full', 'lr-desktop', 'lr-mobile', 'perf'])
+
+const lighthouseConfigSchema = objectLikeSchema(
+  z
+    .object({
+      output: lighthouseOutputSchema.optional(),
+      onlyCategories: stringOrStringArraySchema.optional(),
+      preset: lighthousePresetSchema.optional()
+    })
+    .catchall(z.unknown())
+)
+
+export const insightsConfigSchema = objectLikeSchema(
+  z
+    .object({
+      lighthouse: z.union([booleanSchema, lighthouseConfigSchema]).optional(),
+      technologies: booleanSchema.optional()
+    })
+    .strict()
+)
+
+export const metaConfigSchema = objectLikeSchema(
+  z
+    .object({
+      author: booleanSchema.optional(),
+      date: booleanSchema.optional(),
+      description: booleanSchema.optional(),
+      image: booleanSchema.optional(),
+      lang: booleanSchema.optional(),
+      logo: booleanSchema.optional(),
+      publisher: booleanSchema.optional(),
+      title: booleanSchema.optional(),
+      url: booleanSchema.optional()
+    })
+    .strict()
+)
+
+const baseSchema = z.object({
+  url: z.string().url(),
+  apiKey: z.string().min(1).optional()
+})
+
+const fullShape = {
+  embed: z.string().min(1).optional(),
+  function: z.string().min(1).optional(),
+  iframe: toggledObjectSchema.optional(),
+  meta: z.union([booleanSchema, metaConfigSchema]).optional(),
+  palette: booleanSchema.optional(),
+  ping: toggledObjectSchema.optional()
+}
+
+const visualSchema = {
+  adblock: booleanSchema.optional(),
+  animations: booleanSchema.optional(),
+  click: stringOrStringArraySchema.optional(),
+  colorScheme: z.enum(['no-preference', 'light', 'dark']).optional(),
+  data: objectLikeSchema(z.record(z.string(), dataRuleSchema)).optional(),
+  device: z.string().min(1).optional(),
+  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(),
+  javascript: booleanSchema.optional(),
+  mediaType: z.enum(['screen', 'print']).optional(),
+  modules: stringOrStringArraySchema.optional(),
+  prerender: z.union([z.literal('auto'), booleanSchema]).optional(),
+  proxy: proxySchema.optional(),
+  retry: z.number().int().nonnegative().optional(),
+  scripts: stringOrStringArraySchema.optional(),
+  scroll: z.string().min(1).optional(),
+  staleTtl: z.union([z.string(), z.number(), booleanSchema]).optional(),
+  styles: stringOrStringArraySchema.optional(),
+  timeout: stringOrNumberSchema.optional(),
+  ttl: stringOrNumberSchema.optional(),
+  viewport: viewportSchema.optional(),
+  waitForSelector: z.string().min(1).optional(),
+  waitForTimeout: stringOrNumberSchema.optional(),
+  waitUntil: z.union([waitUntilEventSchema, z.array(waitUntilEventSchema).min(1)]).optional()
+}
+
+export const extractInputSchema = baseSchema
+  .extend(fullShape)
+  .extend(visualSchema)
+  .extend({
+    audio: booleanSchema.optional(),
+    video: booleanSchema.optional(),
+    pdf: z.union([booleanSchema, pdfConfigSchema]).optional(),
+    screenshot: z.union([booleanSchema, screenshotConfigSchema]).optional(),
+    insights: z.union([booleanSchema, insightsConfigSchema]).optional()
+  })
+  .strict()
+
+export const screenshotInputSchema = baseSchema
+  .extend(visualSchema)
+  .extend({
+    screenshot: z.union([booleanSchema, screenshotConfigSchema]).optional()
+  })
+  .strict()
+
+export const pdfInputSchema = baseSchema
+  .extend(visualSchema)
+  .extend({
+    pdf: z.union([booleanSchema, pdfConfigSchema]).optional()
+  })
+  .strict()
+
+export const insightsInputSchema = baseSchema
+  .extend({
+    insights: z.union([booleanSchema, insightsConfigSchema]).optional()
+  })
+  .strict()
+
+export const audioInputSchema = baseSchema
+  .extend({
+    proxy: proxySchema.optional(),
+    meta: z.union([booleanSchema, metaConfigSchema]).optional(),
+    audio: booleanSchema.optional()
+  })
+  .strict()
+
+export const videoInputSchema = baseSchema
+  .extend({
+    proxy: proxySchema.optional(),
+    meta: z.union([booleanSchema, metaConfigSchema]).optional(),
+    video: booleanSchema.optional()
+  })
+  .strict()
+
+export const paletteInputSchema = baseSchema
+  .extend({
+    meta: z.union([booleanSchema, metaConfigSchema]).optional(),
+    palette: booleanSchema.optional()
+  })
+  .strict()
+
+export const metaInputSchema = baseSchema
+  .extend({
+    meta: z.union([booleanSchema, metaConfigSchema]).optional()
+  })
+  .strict()
+
+export const markdownInputSchema = baseSchema.strict()
+
+export const textInputSchema = baseSchema.strict()

package/src/tools/audio.js

@@ -0,0 +1,17 @@
+import { audioInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function audio (server) {
+  register(
+    server,
+    'microlink_audio',
+    [
+      'Detect and extract playable audio sources from any 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.'
+    ].join(' '),
+    audioInputSchema,
+    { audio: true, meta: false }
+  )
+}

package/src/tools/extract.js

@@ -0,0 +1,20 @@
+import { extractInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function extract (server) {
+  register(
+    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`).'
+    ].join(' '),
+    extractInputSchema,
+    {}
+  )
+}

package/src/tools/index.js

@@ -0,0 +1,23 @@
+import { audio } from './audio.js'
+import { extract } from './extract.js'
+import { insights } from './insights.js'
+import { markdown } from './markdown.js'
+import { meta } from './meta.js'
+import { palette } from './palette.js'
+import { pdf } from './pdf.js'
+import { screenshot } from './screenshot.js'
+import { text } from './text.js'
+import { video } from './video.js'
+
+export function tools (server) {
+  extract(server)
+  screenshot(server)
+  pdf(server)
+  video(server)
+  audio(server)
+  insights(server)
+  meta(server)
+  palette(server)
+  markdown(server)
+  text(server)
+}

package/src/tools/insights.js

@@ -0,0 +1,21 @@
+import { insightsInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function insights (server) {
+  register(
+    server,
+    'microlink_insights',
+    [
+      'Get web performance and technology-stack insights for any URL via Microlink.',
+      'Pass `insights: true` for defaults or `insights: { ... }` for options; `insights: {}` is treated as `true`.',
+      'Use `insights.lighthouse` (true or config object) for a Lighthouse performance audit.',
+      '  - `insights.lighthouse.output`: report format — "json" (default), "html", or "csv".',
+      '  - `insights.lighthouse.preset`: "default", "desktop", "perf", "experimental", "full", "lr-desktop", "lr-mobile".',
+      '  - `insights.lighthouse.onlyCategories`: array of category IDs to include (e.g. ["performance", "accessibility"]).',
+      'Use `insights.technologies` (true) to detect the technology stack (frameworks, CDNs, analytics, etc.) via Wappalyzer.',
+      'Both can be combined in a single request.'
+    ].join(' '),
+    insightsInputSchema,
+    { insights: true, meta: false }
+  )
+}

package/src/tools/markdown.js

@@ -0,0 +1,16 @@
+import { markdownInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function markdown (server) {
+  register(
+    server,
+    'microlink_markdown',
+    [
+      'Convert any public URL to Markdown via Microlink.',
+      'Returns JSON output with Markdown content under `data.markdown`.',
+      'Useful for extracting readable content from web pages, articles, and documentation.'
+    ].join(' '),
+    markdownInputSchema,
+    { data: { markdown: { attr: 'markdown' } }, meta: false }
+  )
+}

package/src/tools/meta.js

@@ -0,0 +1,17 @@
+import { metaInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function meta (server) {
+  register(
+    server,
+    'microlink_meta',
+    [
+      'Extract normalized metadata from any public URL via Microlink.',
+      'Returns: `title`, `description`, `lang`, `author`, `publisher`, `date`, `url`, `image` (with dimensions and file info), and `logo` (publisher favicon).',
+      'Pass `meta: false` to skip metadata extraction entirely — useful when you only need a screenshot or video and want a faster response.',
+      'Pass a config object to include or exclude specific fields: `{ logo: true, title: true }` returns only those fields; `{ image: false }` returns everything except image.'
+    ].join(' '),
+    metaInputSchema,
+    { meta: true }
+  )
+}

package/src/tools/palette.js

@@ -0,0 +1,17 @@
+import { paletteInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function palette (server) {
+  register(
+    server,
+    'microlink_palette',
+    [
+      'Extract a color palette from images detected on any public URL via Microlink.',
+      'For each image, returns: `palette` (hex colors from most to least dominant), `background_color` (optimal WCAG-contrast background), `color` (best overlay color for the background), and `alternative_color` (secondary overlay color).',
+      'Color data is nested under each image field in the response (e.g. `data.image.palette`, `data.image.background_color`).',
+      'Useful for generating design tokens, theming, or accessibility checks from real page images.'
+    ].join(' '),
+    paletteInputSchema,
+    { palette: true, meta: true }
+  )
+}

package/src/tools/pdf.js

@@ -0,0 +1,23 @@
+import { pdfInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function pdf (server) {
+  register(
+    server,
+    'microlink_pdf',
+    [
+      'Generate a PDF of any public URL via Microlink and return a permanent CDN asset URL.',
+      'The PDF URL is in `data.pdf.url`.',
+      'Pass `pdf: true` for defaults or `pdf: { ... }` for options; `pdf: {}` is treated as `true`.',
+      'Use `pdf.format` to set paper size: "A4" (default), "Letter", "Legal", "Tabloid", "Ledger", "A0"–"A6".',
+      'Use `pdf.landscape` to switch to landscape orientation.',
+      'Use `pdf.margin` to set page margins as a string ("0.35cm") or object with top/bottom/left/right.',
+      'Use `pdf.scale` to scale the page (0.1–2.0).',
+      'Use `pdf.pageRanges` to select specific pages (e.g. "1-5").',
+      'Use `pdf.width` and `pdf.height` for custom dimensions (overrides format).',
+      'Combine with `styles`, `scripts`, `modules`, `mediaType`, `waitForSelector`, and `waitUntil` for full control.'
+    ].join(' '),
+    pdfInputSchema,
+    { pdf: true, meta: false }
+  )
+}