@microlink/mcp 1.0.0 → 1.1.0

package/README.md

@@ -118,10 +118,10 @@ Once the server is configured, talk to your assistant in plain language. It pick
 
 - *"Take a full-page screenshot of https://example.com in dark mode."* → `microlink_screenshot`
 - *"Generate a Letter-size PDF of https://example.com."* → `microlink_pdf`
-- *"Get the title, description, and image for https://example.com."* → `microlink_meta`
+- *"Get the title, description, and image for https://example.com."* → `microlink_metadata`
 - *"Convert https://news.ycombinator.com to Markdown."* → `microlink_markdown`
 - *"Find the playable video in this YouTube link."* → `microlink_video`
-- *"Run a Lighthouse performance audit on https://example.com."* → `microlink_insights`
+- *"Run a Lighthouse performance audit on https://example.com."* → `microlink_lighthouse`
 - *"Scrape every article title from this page using the `.title` selector."* → `microlink_extract` with `data`
 
 Tools can also be invoked directly. Every tool takes a `url` and returns `structuredContent` (see [Response shape](#response-shape)):
@@ -141,25 +141,27 @@ Tools can also be invoked directly. Every tool takes a `url` and returns `struct
 
 ### Capabilities at a glance
 
-- `microlink_extract`: metadata extraction + custom scraping rules (`data`) + multi-capability composition in one call.
-- `microlink_screenshot`: screenshot generation with element/full-page modes and browser controls.
+Each tool is a thin wrapper over a [`microlink.io`](https://github.com/microlinkhq/microlink/tree/master/packages/core) library method — same inputs, same result, one source of truth.
+
+- `microlink_metadata`: normalized metadata extraction with include/exclude config.
+- `microlink_logo`: brand logo extraction.
+- `microlink_markdown` / `microlink_html` / `microlink_text`: URL to Markdown / HTML / plain text.
+- `microlink_screenshot`: screenshot generation with element/full-page/animated modes and browser controls.
 - `microlink_pdf`: PDF generation with page/layout controls.
-- `microlink_video`: playable video source extraction.
-- `microlink_audio`: playable audio source extraction.
-- `microlink_insights`: Lighthouse + technology detection.
-- `microlink_meta`: normalized metadata extraction with include/exclude config.
-- `microlink_palette`: image palette and contrast color extraction.
-- `microlink_markdown`: URL to Markdown conversion.
-- `microlink_text`: URL to plain text conversion.
+- `microlink_embed`: oEmbed-style embeddable iframe (`{ html, scripts }`).
+- `microlink_video` / `microlink_audio`: primary playable video / audio source.
+- `microlink_links` / `microlink_images` / `microlink_videos` / `microlink_audios` / `microlink_emails`: collect every link / image / video / audio / email on the page.
+- `microlink_technologies`: technology-stack detection (Wappalyzer).
+- `microlink_lighthouse`: Google Lighthouse audit.
+- `microlink_search`: Google as structured data (requires an API key).
+- `microlink_function`: run a JavaScript function in Microlink's server-side browser sandbox.
+- `microlink_extract`: custom scraping rules (`data`) + multi-capability composition in one call.
 - Cross-cutting request capabilities: device/viewport emulation, click/scroll actions, JS/CSS injection, modules, wait conditions, cache controls (`ttl`, `staleTtl`, `force`), retries/timeouts, media mode, headers/proxy, and endpoint/auth routing.
 
 ### Response shape
 
-- All tools (`microlink_extract`, `microlink_screenshot`, `microlink_pdf`, `microlink_video`, `microlink_audio`, `microlink_insights`, `microlink_meta`, `microlink_palette`, `microlink_markdown`, `microlink_text`) return `structuredContent` with:
-  - `endpoint`, `requestUrl`, `finalUrl`, `statusCode`, `responseHeaders`, `microlink`
-  - `microlink` preserves Microlink API JSend payload (`status`, `data`, and error fields like `code`, `id`, `message`, `more`, `report`).
-  - `responseHeaders` includes key cache/rate headers (such as `x-cache-status`, `cf-cache-status`, `cache-control`, `x-rate-limit-*`) when present.
-  - MCP `isError` is set when transport fails or when `microlink.status !== "success"`.
+- 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`.
 
 Parameters labeled `PRO` in the official Microlink docs require a paid plan.
 For compatibility with some MCP clients:
@@ -221,7 +223,7 @@ For `screenshot`, `pdf`, and `insights`, use `true` for defaults or an object fo
 
 ### `microlink_screenshot`
 
-Capture a screenshot of any public URL and receive a permanent CDN asset URL (`data.screenshot.url`).
+Capture a screenshot of any public URL and return the screenshot asset object (`url`, `type`, `width`, `height`, `size`).
 Set `screenshot` to `true` for defaults, or pass `screenshot: { ... }` for options. `screenshot: {}` is treated as `true`.
 
 **Key parameters:**
@@ -266,7 +268,7 @@ Set `screenshot` to `true` for defaults, or pass `screenshot: { ... }` for optio
 
 ### `microlink_pdf`
 
-Generate a PDF of any public URL and receive a permanent CDN asset URL (`data.pdf.url`).
+Generate a PDF of any public URL and return the PDF asset object (`url`, `type`, `size`).
 Set `pdf` to `true` for defaults, or pass `pdf: { ... }` for options. `pdf: {}` is treated as `true`.
 
 **Key parameters:**
@@ -308,7 +310,7 @@ Set `pdf` to `true` for defaults, or pass `pdf: { ... }` for options. `pdf: {}`
 
 ### `microlink_video`
 
-Detect and extract a playable video source from any URL. Returns the video URL in `data.video.url` along with `type`, `duration`, `size`, `width`, `height`, `duration_pretty`, and `size_pretty`.
+Detect and extract a playable video source from any URL. Returns the video asset object: `url`, `type`, `duration`, `size`, `width`, `height`, `duration_pretty`, and `size_pretty`.
 
 Supports YouTube, Vimeo, Twitter/X, TikTok, Instagram, Dailymotion, and hundreds of other platforms.
 
@@ -324,7 +326,7 @@ Supports YouTube, Vimeo, Twitter/X, TikTok, Instagram, Dailymotion, and hundreds
 
 ### `microlink_audio`
 
-Detect and extract a playable audio source from any URL. Returns the audio URL in `data.audio.url` along with `type`, `duration`, `size`, `duration_pretty`, and `size_pretty`.
+Detect and extract a playable audio source from any URL. Returns the audio asset object: `url`, `type`, `duration`, `size`, `duration_pretty`, and `size_pretty`.
 
 Supports SoundCloud, Spotify, Mixcloud, and other audio platforms.
 
@@ -338,29 +340,42 @@ Supports SoundCloud, Spotify, Mixcloud, and other audio platforms.
 
 ---
 
-### `microlink_insights`
+### `microlink_technologies`
+
+Detect the technology stack behind any URL (frameworks, CDNs, analytics, e-commerce, ...) via Wappalyzer. Returns the array of detected technologies.
+
+Mirrors the `microlink.technologies(url)` library method.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | The URL to analyze *(required)* |
+| `apiKey` | `string` | Microlink API key *(optional)* |
+
+---
+
+### `microlink_lighthouse`
+
+Run a Google Lighthouse audit (performance, accessibility, best-practices, SEO) for any URL. Returns the Lighthouse report.
 
-Get web performance and technology-stack insights for any URL.
-Set `insights` to `true` for defaults, or pass `insights: { ... }` for options. `insights: {}` is treated as `true`.
+Mirrors the `microlink.lighthouse(url)` library method.
 
 **Key parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `url` | `string` | The URL to analyze *(required)* |
-| `insights` | `boolean \| object` | Enable default insights (`true`) or provide insights options (`{...}`); `{}` behaves as `true` |
-| `insights.lighthouse` | `boolean \| object` | Run a Lighthouse audit |
-| `insights.lighthouse.output` | `"json" \| "html" \| "csv"` | Report format (default: `"json"`) |
-| `insights.lighthouse.preset` | `string` | Audit preset: `"default"`, `"desktop"`, `"perf"`, `"experimental"`, `"full"`, `"lr-desktop"`, `"lr-mobile"` |
-| `insights.lighthouse.onlyCategories` | `string \| string[]` | Lighthouse category IDs (e.g. `["performance", "accessibility"]`) |
-| `insights.technologies` | `boolean` | Detect tech stack via Wappalyzer |
+| `apiKey` | `string` | Microlink API key *(optional)* |
 
 ---
 
-### `microlink_meta`
+### `microlink_metadata`
 
 Extract normalized metadata from any public URL. Returns: `title`, `description`, `lang`, `author`, `publisher`, `date`, `url`, `image` (with dimensions and file info), and `logo` (publisher favicon).
 
+Mirrors the `microlink.metadata(url)` library method.
+
 **Key parameters:**
 
 | Parameter | Type | Description |
@@ -370,25 +385,39 @@ Extract normalized metadata from any public URL. Returns: `title`, `description`
 
 ---
 
-### `microlink_palette`
+### `microlink_logo`
 
-Extract a color palette from images detected on any public URL. For each image returns: `palette` (hex colors from most to least dominant), `background_color` (optimal WCAG-contrast background), `color` (best overlay color), and `alternative_color`.
+Extract the brand logo of any public URL. Returns the logo asset in `data.logo`: `url`, `type`, `width`, `height`, `size`, and `size_pretty`.
 
-Color data is nested under each image field (e.g. `data.image.palette`). Useful for generating design tokens, theming, or accessibility checks.
+Mirrors the `microlink.logo(url, { square })` library method. Useful for building link previews, favicons, or brand cards.
 
 **Key parameters:**
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
 | `url` | `string` | The URL to analyze *(required)* |
-| `meta` | `boolean \| object` | Control metadata fields returned |
-| `palette` | `boolean` | Enable palette extraction (default: `true`) |
+| `square` | `boolean` | Prefer a square (icon-shaped) logo variant |
 
 ---
 
 ### `microlink_markdown`
 
-Convert any public URL to Markdown. Returns JSON output with Markdown content in `microlink.data.markdown`, useful for extracting readable content from web pages, articles, and documentation.
+Convert any public URL to Markdown. Returns the page content as a Markdown string, useful for extracting readable content from web pages, articles, and documentation.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | The URL to convert *(required)* |
+| `apiKey` | `string` | Microlink API key *(optional)* |
+
+---
+
+### `microlink_html`
+
+Extract the HTML content of any public URL. Returns the page HTML as a string.
+
+Mirrors the `microlink.html(url)` library method.
 
 **Key parameters:**
 
@@ -401,7 +430,7 @@ Convert any public URL to Markdown. Returns JSON output with Markdown content in
 
 ### `microlink_text`
 
-Extract plain text from any public URL. Returns JSON output with plain text content in `microlink.data.text`.
+Extract plain text from any public URL. Returns the readable page text as a string.
 
 **Key parameters:**
 
@@ -412,6 +441,71 @@ Extract plain text from any public URL. Returns JSON output with plain text cont
 
 ---
 
+### `microlink_embed`
+
+Get the oEmbed-style embeddable iframe for any URL (YouTube, Tweet, CodePen, ...). Returns `{ html, scripts }` — the markup plus the script URLs it needs.
+
+Mirrors the `microlink.embed(url)` library method.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | The URL to embed *(required)* |
+| `apiKey` | `string` | Microlink API key *(optional)* |
+
+---
+
+### `microlink_links` / `microlink_images` / `microlink_videos` / `microlink_audios` / `microlink_emails`
+
+Collect every link, image, video source, audio source, or email address on a page. Each returns a clean, absolute, deduped array under `data.links` / `data.images` / `data.videos` / `data.audios` / `data.emails`.
+
+Mirror the `microlink.links(url)` / `.images(url)` / `.videos(url)` / `.audios(url)` / `.emails(url)` library methods. For the single primary playable media, use `microlink_video` / `microlink_audio`.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | The URL to scan *(required)* |
+| `apiKey` | `string` | Microlink API key *(optional)* |
+
+---
+
+### `microlink_search`
+
+Search Google and get structured results (requires an API key). Returns `results` (title, url, description) plus `knowledgeGraph`, `peopleAlsoAsk`, and `relatedSearches` when Google surfaces them.
+
+Mirrors the `microlink.search(query)` library method. Google search operators (`site:`, `filetype:`, quotes, ...) work as-is.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `query` | `string` | The search query *(required)* |
+| `apiKey` | `string` | Microlink API key *(required for this tool)* |
+| `type` | `string` | Vertical: `search` (default), `news`, `images`, `videos`, `places`, `maps`, `shopping`, `scholar`, `patents`, `autocomplete` |
+| `limit` | `number` | Max results |
+| `location` | `string` | Two-letter country code (e.g. `es`) |
+| `period` | `string` | Recency filter: `hour`, `day`, `week`, `month`, `year` |
+
+---
+
+### `microlink_function`
+
+Run a JavaScript function against any public URL inside Microlink's server-side browser sandbox. The function receives `{ page, response, ...args }` and its return value comes back in `value` (plus `isFulfilled`, `profiling`, `logging`).
+
+Mirrors the `microlink.function(url, code)` library method.
+
+**Key parameters:**
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `url` | `string` | The URL to run against *(required)* |
+| `code` | `string` | Function source, e.g. `"async ({ page }) => page.title()"` *(required)* |
+| `apiKey` | `string` | Microlink API key *(optional)* |
+
+---
+
 ## Authentication
 
 Every tool accepts an optional `apiKey` parameter. The key is resolved from these sources in order of priority:

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@microlink/mcp",
   "description": "MCP server for Microlink API",
-  "homepage": "https://github.com/microlinkhq/mcp",
-  "version": "1.0.0",
+  "homepage": "https://github.com/microlinkhq/microlink",
+  "version": "1.1.0",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -10,6 +10,11 @@
   "bin": {
     "microlink-mcp": "./bin/microlink-mcp.js"
   },
+  "author": {
+    "email": "hello@microlink.io",
+    "name": "microlink.io",
+    "url": "https://microlink.io"
+  },
   "contributors": [
     {
       "name": "Joseba",
@@ -21,11 +26,12 @@
     }
   ],
   "repository": {
+    "directory": "packages/mcp",
     "type": "git",
-    "url": "git+https://github.com/microlinkhq/mcp.git"
+    "url": "git+https://github.com/microlinkhq/microlink.git"
   },
   "bugs": {
-    "url": "https://github.com/microlinkhq/mcp/issues"
+    "url": "https://github.com/microlinkhq/microlink/issues"
   },
   "keywords": [
     "api",
@@ -37,25 +43,11 @@
     "server"
   ],
   "dependencies": {
-    "@microlink/mql": "~0.16.1",
+    "@microlink/mql": "0.17.0",
     "@modelcontextprotocol/sdk": "1.29.0",
+    "microlink.io": "0.0.1",
     "zod": "~4.4.3"
   },
-  "devDependencies": {
-    "@commitlint/cli": "latest",
-    "@commitlint/config-conventional": "latest",
-    "ava": "latest",
-    "c8": "latest",
-    "ci-publish": "latest",
-    "conventional-changelog-cli": "latest",
-    "finepack": "latest",
-    "git-authors-cli": "latest",
-    "github-generate-release": "latest",
-    "nano-staged": "latest",
-    "simple-git-hooks": "latest",
-    "standard": "latest",
-    "standard-version": "latest"
-  },
   "engines": {
     "node": ">=20"
   },
@@ -64,41 +56,15 @@
     "scripts",
     "src"
   ],
-  "license": "MIT",
-  "commitlint": {
-    "extends": [
-      "@commitlint/config-conventional"
-    ]
-  },
-  "nano-staged": {
-    "*.js": [
-      "npx @kikobeats/prettier-standard",
-      "standard --fix"
-    ],
-    "package.json": [
-      "finepack"
-    ]
+  "scripts": {
+    "postinstall": "node scripts/postinstall.js",
+    "start": "node src/index.js",
+    "test": "node --test test/*.test.js"
   },
+  "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
-  "simple-git-hooks": {
-    "commit-msg": "npx commitlint --edit",
-    "pre-commit": "npx nano-staged"
-  },
   "type": "module",
-  "scripts": {
-    "contributors": "(git-authors-cli && finepack && git add package.json && git commit -m 'build: contributors' --no-verify) || true",
-    "postinstall": "node scripts/postinstall.js",
-    "postrelease": "pnpm release:tags && pnpm release:github && (ci-publish || pnpm publish --access=public)",
-    "release": "pnpm release:version && pnpm release:changelog && pnpm release:commit && pnpm release:tag",
-    "release:changelog": "conventional-changelog -p conventionalcommits -i CHANGELOG.md -s",
-    "release:commit": "git add package.json CHANGELOG.md && git commit -m \"chore(release): $(node -p \"require('./package.json').version\")\"",
-    "release:github": "github-generate-release",
-    "release:tag": "git tag -a v$(node -p \"require('./package.json').version\") -m \"v$(node -p \"require('./package.json').version\")\"",
-    "release:tags": "git push origin HEAD:master --follow-tags",
-    "release:version": "standard-version --skip.changelog --skip.commit --skip.tag",
-    "start": "node src/index.js",
-    "test": "node --test test/*.test.js"
-  }
-}
+  "gitHead": "b28aa7d6434ac1bb43b084d7e329efec97dab36a"
+}

package/scripts/postinstall.js

@@ -1,5 +1,6 @@
 const WIDTH = 74
 
+// eslint-disable-next-line no-control-regex
 const ANSI_PATTERN = /\u001b\[[0-9;]*m/g
 const hasColor = process.stdout.isTTY && process.env.NO_COLOR === undefined
 
@@ -39,10 +40,16 @@ const lines = [
   borderLine(),
   contentLine(`${colors.bold}MICROLINK MCP${colors.reset}`),
   contentLine(),
-  contentLine(`${colors.bold}Free plan:${colors.reset} 50 requests/day included.`),
+  contentLine(
+    `${colors.bold}Free plan:${colors.reset} 50 requests/day included.`
+  ),
   contentLine(`${colors.yellow}Need more or unlimited usage?${colors.reset}`),
-  contentLine(`Get an API key at ${colors.green}https://microlink.io/#pricing${colors.reset}`),
-  contentLine(`${colors.gray}Tip:${colors.reset} set MICROLINK_API_KEY in your MCP server env.`),
+  contentLine(
+    `Get an API key at ${colors.green}https://microlink.io/#pricing${colors.reset}`
+  ),
+  contentLine(
+    `${colors.gray}Tip:${colors.reset} set MICROLINK_API_KEY in your MCP server env.`
+  ),
   borderLine()
 ]
 

package/src/index.js

@@ -8,7 +8,10 @@ import { tools } from './tools/index.js'
 const require = createRequire(import.meta.url)
 const { version: pkgVersion } = require('../package.json')
 
-export function createMicrolinkServer ({ name = 'microlink-mcp-server', version = pkgVersion } = {}) {
+export function createMicrolinkServer ({
+  name = 'microlink-mcp-server',
+  version = pkgVersion
+} = {}) {
   const server = new McpServer({
     name,
     version