Link metadata for AI agents
Create a link metadata tool for AI agents with TypeScript. Includes URL fetching, caching, and handling untrusted page content.
Use linkpeek when an agent already has a URL and needs a title, description, preview image, site name, or canonical URL before presenting a link. Keep fetching in trusted server code and return only the metadata the agent needs.
This guide shows a framework-neutral helper for link labels and source cards. linkpeek does not include an agent framework connector or an MCP server.
Titles and descriptions are supplied by the target site. They can be missing, misleading, or unrelated to the full article. Use a separate content retrieval step when an agent needs to read, summarize, or verify a source.
Create a metadata tool
npm install linkpeekimport { preview } from "linkpeek";
export async function inspectLink(url: string) {
const result = await preview(url, {
timeout: 5_000,
maxBytes: 30_000,
});
return {
statusCode: result.statusCode,
url: result.canonicalUrl,
title: result.title?.slice(0, 300) ?? null,
description: result.description?.slice(0, 800) ?? null,
image: result.image,
siteName: result.siteName,
};
}Register this function with the tool mechanism of your agent framework using one required string input named url. It extracts page metadata; it does not execute JavaScript or return article text. Check statusCode before presenting a successful source card: HTML error pages can also contain metadata.
For an MCP integration, your server must register a tool with an input schema and a handler that calls this helper. The MCP tools specification describes this mechanism.
Treat metadata as untrusted input
Page metadata is a prompt injection risk: the remote site controls the titles, descriptions, JSON-LD and everything else. Do not place them in a system or developer prompt, and do not let text inside them change tool permissions or trigger another action.
-
Label tool output as untrusted external content.
-
Return a fixed field set and cap text lengths before adding it to model context.
-
Require separate authorization for browsing, downloading, purchasing, or executing anything referenced by the metadata.
-
Render a hostname-only fallback when extraction fails or the HTTP status is unsuccessful.
Production setup
Keep private-IP access disabled, never forward user cookies or service credentials, rate-limit public callers, cache successful results, and enforce infrastructure egress policy. On Node.js pass resolveHost. Platform fetch owns final DNS resolution, so application-level checks do not replace network controls.
Editor.js
A backend endpoint for the Editor.js link tool (@editorjs/link): fetch the pasted URL's title, description and image safely with linkpeek.
Open Graph parser
Parse or fetch Open Graph, Twitter Card, JSON-LD, favicon and canonical metadata in Node.js and TypeScript with parseHTML() and preview().