@microlink/mcp 1.0.0 → 1.1.0

package/src/tools/images.js

@@ -0,0 +1,16 @@
+import { imagesInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function images (server) {
+  register(
+    server,
+    'microlink_images',
+    [
+      'Collect every image (`<img src>`) from any public URL via Microlink.',
+      'Returns an array of absolute, deduped image URLs. Pass `selectorAll` to scope the collection.',
+      'Mirrors the `microlink.images(url)` library method.'
+    ].join(' '),
+    imagesInputSchema,
+    urlMethod('images')
+  )
+}

package/src/tools/index.js

@@ -1,23 +1,43 @@
 import { audio } from './audio.js'
+import { audios } from './audios.js'
+import { emails } from './emails.js'
+import { embed } from './embed.js'
 import { extract } from './extract.js'
-import { insights } from './insights.js'
+import { fn } from './function.js'
+import { html } from './html.js'
+import { images } from './images.js'
+import { lighthouse } from './lighthouse.js'
+import { links } from './links.js'
+import { logo } from './logo.js'
 import { markdown } from './markdown.js'
-import { meta } from './meta.js'
-import { palette } from './palette.js'
+import { metadata } from './metadata.js'
 import { pdf } from './pdf.js'
 import { screenshot } from './screenshot.js'
+import { search } from './search.js'
+import { technologies } from './technologies.js'
 import { text } from './text.js'
 import { video } from './video.js'
+import { videos } from './videos.js'
 
 export function tools (server) {
-  extract(server)
+  metadata(server)
+  logo(server)
+  markdown(server)
+  html(server)
+  text(server)
   screenshot(server)
   pdf(server)
+  embed(server)
   video(server)
   audio(server)
-  insights(server)
-  meta(server)
-  palette(server)
-  markdown(server)
-  text(server)
+  links(server)
+  images(server)
+  videos(server)
+  audios(server)
+  emails(server)
+  technologies(server)
+  lighthouse(server)
+  search(server)
+  fn(server)
+  extract(server)
 }

package/src/tools/lighthouse.js

@@ -0,0 +1,16 @@
+import { lighthouseInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function lighthouse (server) {
+  register(
+    server,
+    'microlink_lighthouse',
+    [
+      'Run a Google Lighthouse audit (performance, accessibility, best-practices, SEO) for any public URL via Microlink.',
+      'Returns the Lighthouse report.',
+      'Mirrors the `microlink.lighthouse(url)` library method.'
+    ].join(' '),
+    lighthouseInputSchema,
+    urlMethod('lighthouse')
+  )
+}

package/src/tools/links.js

@@ -0,0 +1,16 @@
+import { linksInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function links (server) {
+  register(
+    server,
+    'microlink_links',
+    [
+      'Collect every link (`<a href>`) from any public URL via Microlink.',
+      'Returns an array of absolute, deduped URLs. Pass `selectorAll` to scope the collection.',
+      'Mirrors the `microlink.links(url)` library method.'
+    ].join(' '),
+    linksInputSchema,
+    urlMethod('links')
+  )
+}

package/src/tools/logo.js

@@ -0,0 +1,17 @@
+import { logoInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function logo (server) {
+  register(
+    server,
+    'microlink_logo',
+    [
+      'Extract the brand logo of any public URL via Microlink.',
+      'Returns the logo asset: `url`, `type`, `width`, `height`, `size`, and `size_pretty`.',
+      'Pass `square: true` to prefer a square (icon-shaped) variant.',
+      'Mirrors the `microlink.logo(url, { square })` library method.'
+    ].join(' '),
+    logoInputSchema,
+    urlMethod('logo')
+  )
+}

package/src/tools/markdown.js

@@ -1,5 +1,5 @@
 import { markdownInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { register, urlMethod } from './register.js'
 
 export function markdown (server) {
   register(
@@ -7,10 +7,10 @@ export function markdown (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.'
+      'Returns the page content as a Markdown string. Pass `selector` to scope it to part of the page.',
+      'Mirrors the `microlink.markdown(url)` library method.'
     ].join(' '),
     markdownInputSchema,
-    { data: { markdown: { attr: 'markdown' } }, meta: false }
+    urlMethod('markdown')
   )
 }

package/src/tools/metadata.js

@@ -0,0 +1,17 @@
+import { metadataInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function metadata (server) {
+  register(
+    server,
+    'microlink_metadata',
+    [
+      'Extract normalized metadata from any public URL via Microlink.',
+      'Returns the metadata object: `title`, `description`, `lang`, `author`, `publisher`, `date`, `url`, `image` (with dimensions and file info), and `logo`.',
+      'Pass `meta: false` to skip extraction, or a config object to include/exclude fields (e.g. `{ logo: true, title: true }`).',
+      'Mirrors the `microlink.metadata(url)` library method.'
+    ].join(' '),
+    metadataInputSchema,
+    urlMethod('metadata')
+  )
+}

package/src/tools/pdf.js

@@ -1,23 +1,18 @@
 import { pdfInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { capabilityMethod, 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`.',
+      'Generate a PDF of any public URL via Microlink and return the asset object (`url`, `type`, `size`, ...) with a permanent CDN 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.'
+      'Use `pdf.format` ("A4" default, "Letter", "Legal", ...), `pdf.landscape`, `pdf.margin` (string or top/bottom/left/right object), `pdf.scale` (0.1-2.0), `pdf.pageRanges` ("1-5"), or `pdf.width`/`pdf.height`.',
+      'Combine with `styles`, `scripts`, `modules`, `mediaType`, `waitForSelector`, and `waitUntil` for full control.',
+      'Mirrors the `microlink.pdf(url, options)` library method.'
     ].join(' '),
     pdfInputSchema,
-    { pdf: true, meta: false }
+    capabilityMethod('pdf', 'pdf')
   )
 }

package/src/tools/register.js

@@ -1,4 +1,9 @@
-import { asToolResult, callMicrolink } from '../microlink-client.js'
+import {
+  asErrorResult,
+  asToolResult,
+  client,
+  resolveApiKey
+} from '../microlink-client.js'
 
 function getHeaderValueCaseInsensitive (headers, headerName) {
   if (!headers || typeof headers !== 'object') {
@@ -9,11 +14,7 @@ function getHeaderValueCaseInsensitive (headers, headerName) {
 
   for (const [key, value] of Object.entries(headers)) {
     if (key.toLowerCase() === lookup) {
-      if (Array.isArray(value)) {
-        return value[0]
-      }
-
-      return value
+      return Array.isArray(value) ? value[0] : value
     }
   }
 
@@ -26,33 +27,44 @@ function getApiKeyFromRequestHeaders (headers) {
   if (typeof authorization === 'string') {
     const match = /^Bearer\s+(.+)$/i.exec(authorization.trim())
     const bearerToken = match?.[1]?.trim()
-
-    if (bearerToken) {
-      return bearerToken
-    }
+    if (bearerToken) return bearerToken
   }
 
   const xApiKey = getHeaderValueCaseInsensitive(headers, 'x-api-key')
   if (typeof xApiKey === 'string') {
     const token = xApiKey.trim()
-    if (token) {
-      return token
-    }
+    if (token) return token
   }
 
   return undefined
 }
 
-export function register (server, name, description, inputSchema, forcedFlags) {
+// Common shape: a tool that maps to `client.<method>(url, options)`.
+export function urlMethod (method) {
+  return (client, { url, ...options }) => client[method](url, options)
+}
+
+// Capability tools nest their config under a key (e.g. `screenshot: { ... }`)
+// to match the Microlink API surface; the library takes a flat options bag, so
+// flatten the config back out before calling it.
+export function capabilityMethod (method, key) {
+  return (client, { url, [key]: config, ...rest }) => {
+    const options =
+      config !== null && typeof config === 'object'
+        ? { ...config, ...rest }
+        : rest
+    return client[method](url, options)
+  }
+}
+
+export function register (server, name, description, inputSchema, invoke) {
   server.registerTool(
     name,
-    {
-      description,
-      inputSchema
-    },
+    { description, inputSchema },
     async (args, extra) => {
-      const parsedArgs = inputSchema.safeParse(args)
-      if (!parsedArgs.success) {
+      const parsed = inputSchema.safeParse(args)
+
+      if (!parsed.success) {
         return {
           isError: true,
           content: [
@@ -61,7 +73,7 @@ export function register (server, name, description, inputSchema, forcedFlags) {
               text: JSON.stringify(
                 {
                   message: 'Input validation failed.',
-                  issues: parsedArgs.error.issues
+                  issues: parsed.error.issues
                 },
                 null,
                 2
@@ -72,38 +84,16 @@ export function register (server, name, description, inputSchema, forcedFlags) {
       }
 
       try {
-        const headerApiKey = getApiKeyFromRequestHeaders(extra?.requestInfo?.headers)
-        const params =
-          parsedArgs.data.apiKey || !headerApiKey
-            ? parsedArgs.data
-            : {
-                ...parsedArgs.data,
-                apiKey: headerApiKey
-              }
-
-        const result = await callMicrolink({
-          params,
-          forcedFlags
-        })
+        const headerApiKey = getApiKeyFromRequestHeaders(
+          extra?.requestInfo?.headers
+        )
+        const apiKey = resolveApiKey(parsed.data.apiKey, headerApiKey)
+        const params = apiKey ? { ...parsed.data, apiKey } : parsed.data
 
-        return asToolResult(result)
+        const value = await invoke(client, params)
+        return asToolResult(value)
       } catch (error) {
-        return {
-          isError: true,
-          content: [
-            {
-              type: 'text',
-              text: JSON.stringify(
-                {
-                  message: 'Microlink request failed before receiving an API response.',
-                  error: error instanceof Error ? error.message : String(error)
-                },
-                null,
-                2
-              )
-            }
-          ]
-        }
+        return asErrorResult(error)
       }
     }
   )

package/src/tools/screenshot.js

@@ -1,23 +1,20 @@
 import { screenshotInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { capabilityMethod, register } from './register.js'
 
 export function screenshot (server) {
   register(
     server,
     'microlink_screenshot',
     [
-      'Capture a screenshot of any public URL via Microlink and return a permanent CDN asset URL.',
-      'The screenshot URL is in `data.screenshot.url`.',
+      'Capture a screenshot of any public URL via Microlink and return the asset object (`url`, `type`, `width`, `height`, `size`, ...) with a permanent CDN URL.',
       'Pass `screenshot: true` for defaults or `screenshot: { ... }` for options; `screenshot: {}` is treated as `true`.',
-      'Use `screenshot.fullPage` to capture the entire scrollable page.',
-      'Use `screenshot.element` (CSS selector) to capture a specific DOM element.',
-      'Use `screenshot.type` to choose output format: "jpeg" (default "png").',
-      'Use `screenshot.omitBackground` to remove the white background (useful with transparent PNGs).',
-      'Use `screenshot.overlay` to add a browser chrome overlay with `browser` ("light"|"dark") and `background` (CSS color or gradient).',
-      'Use `screenshot.codeScheme` to set the syntax-highlighting theme for code pages (e.g. "dracula", "atom-dark").',
-      'Combine with `device`, `viewport`, `click`, `scroll`, `styles`, `scripts`, `modules`, `waitForSelector`, `waitForTimeout`, `waitUntil`, `colorScheme`, and `mediaType` for full browser control.'
+      'Use `screenshot.fullPage` to capture the whole scrollable page.',
+      'Use `screenshot.animated` to capture an animated screenshot (GIF/MP4) instead of a still image.',
+      'Use `screenshot.element` (CSS selector) to capture a specific element, `screenshot.type` for format ("jpeg", default "png"), `screenshot.omitBackground` for transparency, `screenshot.overlay` for browser chrome, `screenshot.palette` to also extract dominant colors, or `screenshot.codeScheme` to theme code pages.',
+      'Combine with `device`, `viewport`, `click`, `scroll`, `styles`, `scripts`, `modules`, `waitForSelector`, `waitForTimeout`, `waitUntil`, `colorScheme`, and `mediaType`.',
+      'Mirrors the `microlink.screenshot(url, options)` library method.'
     ].join(' '),
     screenshotInputSchema,
-    { screenshot: true, meta: false }
+    capabilityMethod('screenshot', 'screenshot')
   )
 }

package/src/tools/search.js

@@ -0,0 +1,17 @@
+import { searchInputSchema } from '../schemas.js'
+import { register } from './register.js'
+
+export function search (server) {
+  register(
+    server,
+    'microlink_search',
+    [
+      'Search Google and get structured results via Microlink (requires an API key).',
+      'Returns `results` (title, url, description) plus `knowledgeGraph`, `peopleAlsoAsk`, and `relatedSearches` when available.',
+      'Use `type` for a vertical ("search" default, "news", "images", "videos", "places", "maps", "shopping", "scholar", "patents", "autocomplete"), and `limit` / `location` / `period` to refine.',
+      'Google search operators (`site:`, `filetype:`, quotes, ...) work as-is. Mirrors the `microlink.search(query)` library method.'
+    ].join(' '),
+    searchInputSchema,
+    (client, { query, ...options }) => client.search(query, options)
+  )
+}

package/src/tools/technologies.js

@@ -0,0 +1,16 @@
+import { technologiesInputSchema } from '../schemas.js'
+import { register, urlMethod } from './register.js'
+
+export function technologies (server) {
+  register(
+    server,
+    'microlink_technologies',
+    [
+      'Detect the technology stack behind any public URL via Microlink (Wappalyzer).',
+      'Returns an array of detected technologies (frameworks, CDNs, analytics, e-commerce, etc.).',
+      'Mirrors the `microlink.technologies(url)` library method.'
+    ].join(' '),
+    technologiesInputSchema,
+    urlMethod('technologies')
+  )
+}

package/src/tools/text.js

@@ -1,16 +1,16 @@
 import { textInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { register, urlMethod } from './register.js'
 
 export function text (server) {
   register(
     server,
     'microlink_text',
     [
-      'Extract plain text from any public URL via Microlink.',
-      'Returns JSON output with plain text content under `data.text`.',
-      'Useful for getting raw text content from web pages.'
+      'Extract the plain text of any public URL via Microlink.',
+      'Returns the readable page text as a string. Pass `selector` to scope it to part of the page.',
+      'Mirrors the `microlink.text(url)` library method.'
     ].join(' '),
     textInputSchema,
-    { data: { text: { attr: 'text' } }, meta: false }
+    urlMethod('text')
   )
 }

package/src/tools/video.js

@@ -1,17 +1,17 @@
 import { videoInputSchema } from '../schemas.js'
-import { register } from './register.js'
+import { register, urlMethod } from './register.js'
 
 export function video (server) {
   register(
     server,
     'microlink_video',
     [
-      'Detect and extract playable video sources from any URL via Microlink.',
-      'Works with YouTube, Vimeo, Twitter/X, TikTok, Instagram, Dailymotion, and hundreds of other platforms.',
-      'The video URL is in `data.video.url`. Also returns `type`, `duration`, `size`, `width`, `height`, `duration_pretty`, and `size_pretty`.',
-      'Combine with `proxy` for sites that require it, or with `meta` to suppress metadata extraction.'
+      'Detect the primary playable video of any public URL via Microlink.',
+      'Works with YouTube, Vimeo, Twitter/X, TikTok, Instagram, and hundreds of other platforms.',
+      'Returns the video asset: `url`, `type`, `duration`, `size`, `width`, `height`, `duration_pretty`, `size_pretty`.',
+      'Mirrors the `microlink.video(url)` library method. For every video on the page, use `microlink_videos`.'
     ].join(' '),
     videoInputSchema,
-    { video: true, meta: false }
+    urlMethod('video')
   )
 }

package/src/tools/videos.js

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

package/src/tools/insights.js

@@ -1,21 +0,0 @@
-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/meta.js

@@ -1,17 +0,0 @@
-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

@@ -1,17 +0,0 @@
-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 }
-  )
-}