# Site blueprint

> How macanderson.com is built to be read by people and by AI agents, and how to build a site like it. Markdown twins, llms.txt, an MCP server, a guarded assistant, and an installable app.

Canonical page: https://macanderson.com/blueprint

This site is written for two kinds of readers: people, and the AI agents that read the web for them. Every choice below serves one of them, and most serve both. Copy any of it.

## Every page has a markdown twin

Add `.md` to any address and you get the same page as plain markdown. A request that sends `Accept: text/markdown` gets the markdown version at the normal address. Agents read markdown faster and more accurately than a page full of layout, and each twin names its canonical page so search engines know which one to rank.

## llms.txt and llms-full.txt

[/llms.txt](/llms.txt) is a short map of the site in the [llms.txt format](https://llmstxt.org): who Mac is, then a link and a one-line description for every page. [/llms-full.txt](/llms-full.txt) holds the whole site in one file, so an agent can load all of it in one request.

## An MCP server

The site runs a [Model Context Protocol](https://modelcontextprotocol.io) server at `https://macanderson.com/mcp`. It is read-only and needs no key. Its tools search the site, read any page as markdown, list the field manual and research, and return Mac's profile and GitHub activity. To add it to Claude Code:

```sh
claude mcp add --transport http macanderson https://macanderson.com/mcp
```

In browsers that support WebMCP, the page also registers its tools with the browser, so an agent in the tab can search and open pages without scraping them.

## Structured data on every page

Each page carries schema.org data that says what it is. The home page describes Mac as a `Person` with his profiles. The field manual is a `Book` whose parts are chapters. Each part and essay is a `TechArticle` that lists its cited sources. Search engines and agents read these facts directly instead of guessing them from the layout.

## A guarded assistant

The assistant answers questions about Mac and his work. It follows the method the field manual teaches: decide in code what code can decide, and spend the model last.

1. Code finds the passages first. A keyword index (BM25) ranks passages from the site's own pages before any model call. The same question always gets the same passages.
2. The model sees only those passages, under a fixed token budget. It is told to answer from them and to say so when they do not cover the question.
3. Every answer lists its sources, so you can check it.
4. Limits sit in code, not in the prompt. Each question has a length cap. Each network address has a request limit. The whole site has a daily cap, and Vercel BotID screens out automated traffic. The assistant has no tools that write anything.
5. When the model is unavailable or a limit is reached, the assistant still answers with the best matching passages and links.

## An installable app

The site is a progressive web app. On a phone, add it to your home screen and it opens full screen with its own icon. A service worker keeps the pages you have read available offline.

## Fast by default

Pages are built ahead of time and served as static files. The only code that runs on a server is the assistant, the subscribe form, and the MCP endpoint. Fonts load from the same domain. Animations use the browser's own scroll and view timelines, and they stop when your device asks for reduced motion.

## Build your own

You need three things: your writing in plain files, a build step that turns them into pages and markdown twins, and a short list of facts about you that every page can reuse. Start with llms.txt and the markdown twins. They take an afternoon and help every agent that reads your site. Add the MCP server and the assistant when you have enough writing for them to search.