@42a/ael

Framework-agnostic core of the 42a Agentic Enablement Layer (AEL) — make any site readable and usable by AI agents:

• Markdown page variants — every page served as a frontmatter markdown document via ?format=markdown, <path>.md, or Accept: text/markdown negotiation.
• /llms.txt + /llms-full.txt — spec-conformant agent index of your key pages.
• MCP server — a stateless Model Context Protocol endpoint (JSON-RPC 2.0 over plain HTTP POST, protocol 2025-06-18) with read-only tools: get_site_info, search_content, get_page, list_recent_posts, list_categories — plus all four /.well-known/mcp* discovery documents.
• 42a connect — optional pairing with 42a for GEO vitals and agent-traffic analytics.

Every feature is a WHATWG (Request) => Promise<Response> handler, so it runs anywhere fetch-standard requests exist (Node ≥ 18.17, edge runtimes, workers).

Use a framework adapter instead of this package directly when one exists: @42a/ael-next (Next.js App Router), @42a/ael-astro (Astro). For WordPress, use the 42a AEL WordPress plugin.

Direct usage (any fetch-standard server)

import { createAel } from "@42a/ael";

const ael = createAel({ siteUrl: "https://example.com" });

// In your request handling:
const response = await ael.handle(request); // null when not an AEL path

Content model

By default the self-render provider enumerates pages from your sitemap and converts your own rendered HTML to markdown — zero config. For higher fidelity, implement ContentProvider (getSiteInfo, listPages, getPage, search, optional listCollections) against your CMS, or compose with mergeProviders(primary, fallback) / staticProvider(pages).

Config highlights

createAel({
  siteUrl: "https://example.com",       // required, canonical origin
  siteName, description, language,       // metadata (else derived from homepage)
  provider,                              // ContentProvider (default: self-render)
  markdown: { contentSelector: "#main", urlStyle: "query" | "suffix" },
  llms: { maxFullItems: 50, maxFullBytes: 2_000_000 },
  mcp: { endpointPath: "/api/mcp", tools: [/* custom McpToolDefinition */] },
  cache,                                 // KV impl (default: in-memory per instance)
  telemetry: false,                      // opt-in usage reporting to 42a
});

CLI

npx @42a/ael doctor [url]     # probe a site's agent layer: markdown, llms.txt, MCP, robots
npx @42a/ael connect          # connect the site to 42a — mints FORTYTWOA_SITE_TOKEN

connect opens the 42a pairing page, exchanges the code for a site token, and prints the one env var to add (FORTYTWOA_SITE_TOKEN). After the next deploy your adapter serves /.well-known/42a.json and 42a verifies the domain automatically — no meta tags, no layout edits.

Telemetry

Off by default; nothing leaves the site unless connected AND telemetry: true. When enabled, in-memory delta counters (markdown hits, llms.txt hits, MCP requests/tool calls) flush fire-and-forget; counts are approximate lower bounds on serverless.