@microlink/mcp 2.4.0 → 2.5.0

package/README.md

@@ -161,9 +161,11 @@ 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://...", ...] }`.
+- Every tool also declares an MCP `outputSchema` describing its `structuredContent.data`, mirroring the TypeScript types shipped by the library (`Asset`, `Metadata`, `Embed`, `FunctionResult`, ...), so MCP clients get machine-readable result contracts. Error results are exempt from output validation. Fields that can legitimately be absent are nullable (for example `logo` when no brand logo is detected, or `markdown` when the selector matches nothing).
+- Tools are annotated `readOnlyHint: true` since they only fetch and transform public URLs. The exception is `microlink_function`, which executes user-supplied code and is not annotated read-only.
 - 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.
+Parameters that require a paid plan are labeled `PRO` in their own schema descriptions, mirroring the official Microlink docs.
 For compatibility with some MCP clients:
 - boolean parameters also accept the strings `"true"` and `"false"` and are normalized before validation.
 - parameters that accept objects also accept JSON stringified objects (for example, `screenshot: "{\"overlay\":{\"browser\":\"dark\"}}"`).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@microlink/mcp",
   "description": "MCP server for Microlink API",
   "homepage": "https://github.com/microlinkhq/microlink",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js"
@@ -45,7 +45,7 @@
   "dependencies": {
     "@microlink/mql": "0.19.0",
     "@modelcontextprotocol/sdk": "1.30.0",
-    "microlink.io": "0.10.3",
+    "microlink.io": "0.10.4",
     "zod": "~4.4.3"
   },
   "engines": {
@@ -59,12 +59,13 @@
   "scripts": {
     "postinstall": "node scripts/postinstall.js",
     "start": "node src/index.js",
-    "test": "node --test test/*.test.js"
+    "test": "node --test test/*.test.js",
+    "test:live": "LIVE=1 node --test test/live.test.js"
   },
   "license": "MIT",
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "gitHead": "de05659e0fe9d49ba25643efbcb9914d5332ca91"
+  "gitHead": "69d1f76ff2dcbfb56cccd86a17da9c719e398301"
 }

package/src/index.js

@@ -8,14 +8,25 @@ import { tools } from './tools/index.js'
 const require = createRequire(import.meta.url)
 const { version: pkgVersion } = require('../package.json')
 
+const DEFAULT_INSTRUCTIONS = [
+  'Turn any public URL into screenshots, PDFs, metadata, readable content (Markdown, HTML or plain text), media sources, technology stacks, Lighthouse audits, Google search results or custom-scraped fields.',
+  'Always pass full URLs including the protocol.',
+  'Without an API key, requests use the free endpoint (50 requests/day); pass apiKey or set MICROLINK_API_KEY for PRO.',
+  'On failure, read the error message and the hint/reason fields and adjust the request instead of retrying blindly.'
+].join(' ')
+
 export function createMicrolinkServer ({
   name = 'microlink-mcp-server',
-  version = pkgVersion
+  version = pkgVersion,
+  instructions = DEFAULT_INSTRUCTIONS
 } = {}) {
-  const server = new McpServer({
-    name,
-    version
-  })
+  const server = new McpServer(
+    {
+      name,
+      version
+    },
+    { instructions }
+  )
 
   tools(server)
 

package/src/microlink-client.js

@@ -32,19 +32,22 @@ export function resolveApiKey (inputApiKey, headerApiKey) {
   )
 }
 
-// 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
+const isPlainObject = value =>
+  value !== null && typeof value === 'object' && !Array.isArray(value)
+
+function toToolResponse (isError, field, value) {
   return {
-    isError: false,
-    structuredContent: { data },
-    content: [{ type: 'text', text: JSON.stringify(data, null, 2) }]
+    isError,
+    structuredContent: { [field]: value },
+    content: [{ type: 'text', text: JSON.stringify(value, null, 2) }]
   }
 }
 
-const isPlainObject = value =>
-  value !== null && typeof value === 'object' && !Array.isArray(value)
+// 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) {
+  return toToolResponse(false, 'data', value ?? null)
+}
 
 // The API wraps some failures in a generic top-level message ("The request
 // has been not processed…"), while the specific cause travels in `data`
@@ -53,7 +56,7 @@ const isPlainObject = value =>
 // auxiliary strings in `data`.
 const GENERIC_API_MESSAGE = 'The request has been not processed.'
 
-export function asErrorResult (error) {
+function toErrorPayload (error) {
   const isMql = error instanceof MicrolinkError
   const statusCode = isMql ? error.statusCode : undefined
   const description = isMql ? error.description : undefined
@@ -99,9 +102,16 @@ export function asErrorResult (error) {
     payload.hint = FREE_QUOTA_EXCEEDED_HINT
   }
 
-  return {
-    isError: true,
-    structuredContent: { error: payload },
-    content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }]
-  }
+  return payload
+}
+
+export function asErrorResult (error) {
+  const payload =
+    isPlainObject(error) &&
+    !(error instanceof Error) &&
+    typeof error.message === 'string'
+      ? error
+      : toErrorPayload(error)
+
+  return toToolResponse(true, 'error', payload)
 }

package/src/schemas.js

@@ -214,6 +214,9 @@ export const metaConfigSchema = objectLikeSchema(
     .strict()
 )
 
+const optionalApiKey = description =>
+  z.string().min(1).optional().describe(description)
+
 const baseSchema = z.object({
   url: z
     .string()
@@ -221,13 +224,9 @@ const baseSchema = z.object({
     .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.'
-    )
+  apiKey: optionalApiKey(
+    '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 = {
@@ -426,13 +425,9 @@ export const searchInputSchema = z
       .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.'
-      ),
+    apiKey: optionalApiKey(
+      'Microlink API key. Required for this tool: Google search runs on the PRO endpoint.'
+    ),
     type: z
       .enum([
         'search',

package/src/tools/extract.js

@@ -7,7 +7,7 @@ export function extract (server) {
     'microlink_extract',
     [
       '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.',
+      'Pass `data` with the rules object (selector/selectorAll, attr, type, evaluate; nested rules and arrays supported); returns the extracted `data` object. By default no page metadata is included; pass `meta: true` to also get the default metadata.',
       'Also supports combining capabilities (`screenshot`, `pdf`, `iframe`, `insights`) and browser controls in the same request.',
       'Mirrors the `microlink.extract(url, rules)` library method.'
     ].join(' '),

package/src/tools/register.js

@@ -54,6 +54,30 @@ export const INTERACTIVE_ANNOTATIONS = {
   openWorldHint: true
 }
 
+// Human-friendly titles shown by MCP clients for each tool.
+const TITLES = {
+  metadata: 'Metadata',
+  logo: 'Logo',
+  markdown: 'Markdown',
+  html: 'HTML',
+  text: 'Plain text',
+  screenshot: 'Screenshot',
+  pdf: 'PDF',
+  embed: 'Embed',
+  video: 'Video',
+  audio: 'Audio',
+  links: 'Links',
+  images: 'Images',
+  videos: 'Videos',
+  audios: 'Audios',
+  emails: 'Emails',
+  technologies: 'Technologies',
+  lighthouse: 'Lighthouse',
+  search: 'Google search',
+  function: 'Function',
+  extract: 'Extract'
+}
+
 // Common shape: a tool that maps to `client.<method>(url, options)`.
 export function urlMethod (method) {
   return (client, { url, ...options }) => client[method](url, options)
@@ -86,23 +110,19 @@ export function register (
   const key = name.replace(/^microlink_/, '')
   const dataSchema = outputSchemas[key]
   const outputSchema = dataSchema ? { data: dataSchema } : undefined
+  const title = TITLES[key]
 
   server.registerTool(
     name,
-    { description, inputSchema, outputSchema, annotations },
+    { title, description, inputSchema, outputSchema, annotations },
     async (args, extra) => {
       const parsed = inputSchema.safeParse(args)
 
       if (!parsed.success) {
-        const payload = {
+        return asErrorResult({
           message: 'Input validation failed.',
           issues: parsed.error.issues
-        }
-        return {
-          isError: true,
-          structuredContent: { error: payload },
-          content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }]
-        }
+        })
       }
 
       try {