FencePost

Good Previews Make Good Neighbors

FencePost Reference

How FencePost checks link previews, which sites it can capture and how to use its API and MCP tools. The API supports all three tools; MCP supports checking links and generating previews.

Open Graph Tags

Open Graph is a set of <meta> tags, first defined by Facebook in 2010, that describe a page to the apps that build link previews: Slack, Teams, LinkedIn, iMessage and most chat and social apps. Without them, an app guesses, and often shows only the page's title or a stray image from the page.

<meta property="og:site_name" content="Classroom Booking">
<meta property="og:title" content="Reserve a Classroom - Classroom Booking">
<meta property="og:description" content="Find a room for a review session or a guest talk, with the seats and screens you need.">
<meta property="og:url" content="https://www.cmu.edu/classrooms/reserve.html">
<meta property="og:type" content="website">
<meta property="og:image" content="https://www.cmu.edu/classrooms/images/preview.jpg">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Classroom Booking's home page: Reserve a Classroom, beside a photo of a classroom.">
<meta name="twitter:card" content="summary_large_image">
TagWhat It Is
og:title, og:descriptionThe bold title and the line under it.
og:image, og:image:altThe picture, 1200 × 630 pixels, and its description for screen readers.
og:urlThe page's preferred address, which apps use instead of the exact link someone pasted.
og:site_nameThe site's name, which some apps show with the title.
twitter:cardsummary_large_image asks for the large picture instead of a thumbnail.

The Web Kilt's Link Previews / Open Graph page has the full guidance, including how to add the tags in a CMS or an app.

Approved Sites

FencePost works with any public page on cmu.edu or one of its subdomains, and on these sites run by Carnegie Mellon groups:

GroupSite
AB Techabtech.org and its subdomains
Activities Boardactivitiesboard.org and its subdomains
Carnegie Tech Radio Clubw3vc.org and its subdomains
CMU Buggy Alumni Associationcmubuggy.org and its subdomains
CMU Webcmu-web.github.io
Employee Perksmerichar.org and its subdomains
Pittsburgh Supercomputing Centerpsc.edu and its subdomains
Robotics Clubroboclub.org and its subdomains
Scotch'n'Soda Theatrescotchnsoda.org and its subdomains
ScottyLabsscottylabs.org and its subdomains
ScottyLabs (TartanHacks)tartanhacks.com and its subdomains
Spring Carnival Committeespringcarnival.org and its subdomains
The Tartanthetartan.org and its subdomains
WRCTwrct.org and its subdomains

To add a site that isn't on cmu.edu, use the Request a Domain form. FencePost sees only what anyone on the public internet can: it doesn't sign in, and it can't reach pages that work only on campus. For those, upload a screenshot in Generate a Preview.

API

Each endpoint takes JSON and answers with JSON. Images come back as base64; nothing is stored.

RequestBodyResponse
POST /api/checkurl, and article: true for a news story or postWhat a share would show (title, description, siteName, image, imageAlt) and findings, each pass, fix or note
POST /api/previewurl and the preview fieldsThe 1200 × 630 pixel JPEG (image), its title, description and the tags for the page's head
POST /api/screenshoturl and kind: card (the default) or phoneIts width, height and title, and images: the screenshot as WebP, PNG and JPEG, each with its format, type, file name, bytes and base64 image

To try it from a terminal, send a page's address with curl. This example checks the Web Kilt's home page:

curl -s https://fencepost.andrew.cmu.edu/api/check -H 'Content-Type: application/json' -d '{"url": "https://webkilt.andrew.cmu.edu/"}'

FencePost follows the redirect to /0/ and answers with what a share would show, then a finding for each check. Shortened, the answer looks like this:

{
  "url": "https://webkilt.andrew.cmu.edu/0/",
  "title": "Carnegie Mellon Web Kilt",
  "siteName": "Carnegie Mellon Web Kilt",
  "image": { "url": "https://webkilt.andrew.cmu.edu/0/images/preview.jpg", "width": 1200, "height": 630 },
  "findings": [
    { "key": "title", "status": "pass", "text": "The title is \"Carnegie Mellon Web Kilt\"." },
    …
  ]
}

Preview Fields

FieldWhat It Does
urlThe page, on a site FencePost captures. Required.
titleUp to 100 characters. Blank uses the page's own title; required with a screenshot.
descriptionUp to 220 characters. Blank uses the page's own description.
siteThe site's name, up to 60 characters.
imagePathWhere you'll save the image; the tags point to it. Default /images/preview.jpg.
screenshotA base64 PNG, JPEG or WebP under 8 MB, used instead of a capture, for a page behind a sign-in.

MCP Server

Connect an AI agent to FencePost's MCP server with these settings:

ConnectionValue
Server Namefencepost
Endpointhttps://fencepost.andrew.cmu.edu/mcp
TransportStreamable HTTP, without sign-in

It offers these tools:

ToolInputResult
get_guideNo argumentsThe preview rules, the approved domains and the fields
check_linkurlThe same as POST /api/check
generate_previewurl and the preview fieldsThe JPEG as an image, with the tags and where to save it

Screenshots are only on the page and the API. A failure returns a tool result marked isError with the same message the API gives.

WordPress Plugin

FencePost Link Previews, a WordPress plugin, makes each page's preview image for you. About a minute after a page or post is published or updated, it sends the page's address and the site's name to POST /api/preview, saves the image in the media library and uses it for that page. A featured image always wins.

  • It works with what the site already has: the Forbes & Moreword theme, Yoast SEO, Rank Math, All in One SEO and SEOPress. With none of them, it writes the image tags itself.
  • Pages must be public and on cmu.edu or an approved site. When FencePost can't capture one, the Link Preview column in Pages and Posts says why.
  • To make a new one now, select Make a New Preview under the page's title in Pages or Posts.

Download fencepost-wordpress.zip and upload it in Plugins › Add New Plugin › Upload Plugin, or install it with WP-CLI:

wp plugin install https://github.com/cmu-web/cmu-web-fencepost/releases/latest/download/fencepost-wordpress.zip --activate

Errors

StatusMeaningWhat to Check
400FencePost can't use that request.The address (a full https:// address), the field lengths and the screenshot's type and size.
403The site isn't one FencePost captures.See Approved Sites.
429Two captures are already running.Wait a moment and try again.
502The page answered with an error.The page itself; a 401 or 403 from it means a sign-in, so upload a screenshot instead. A response with "code": "bot-check" is a Cloudflare bot check; see Sites Behind Cloudflare.
504The site took too long to answer.Try again; if it keeps happening, upload a screenshot.
500Something went wrong in FencePost.Try again; if it keeps happening, report it on GitHub with a made-up example.

Every error is JSON with an error message written for the person using the page, so it can be shown as is.

Sites Behind Cloudflare

Some sites use Cloudflare's bot protection, which answers anything that isn't a full browser with a challenge page instead of the site. FencePost can't get past it, and says so. Apps such as Slack and LinkedIn are usually let through as known bots, so the site's real previews may be fine; FencePost just can't see them.

If you manage the site's Cloudflare settings, let FencePost through with a custom rule:

  1. In the Cloudflare dashboard, open the site's domain, then go to Security › WAF › Custom rules and create a rule.
  2. Match FencePost by its address: IP Source Address equals 128.2.24.46. Its requests also say FencePost/1.0 in their user agent, but anyone can send that, so match the address.
  3. Choose the action Skip, pick the bot protection the site uses, and deploy the rule.

Cloudflare's free Bot Fight Mode can't be skipped by a rule, according to Cloudflare's documentation. A site that uses it would have to turn it off for FencePost to see its pages. Until then, generate the preview from your own screenshot in Generate a Preview.