Marginalia

Inspiration

Every AI reading tool today is a chat box beside the text: ask, get a smooth answer, move on. That smoothness is the enemy of understanding — and it never knows what you already know. Two of my own projects had already designed the fix twice without a surface for it: an expand-and-annotate reader in an open-source LaTeX research environment, and "annotated reading versions" of papers in a learning system I'm building around evidence-gated mastery. The missing piece was a way for an agent to work inside the reading, live, while I read. WebMCP is exactly that piece.

The name is a homage to the oldest form of this idea: marginalia — commentary written in the margins of a text, never in the text.

What it does

Marginalia is a reader where a human and their agent work on the same page. The page holds the document, your marks, and your own notes; the agent brings what it knows about you; WebMCP tools are where the two meet. No tool can write to the source. The agent lives in the margin.

Open a paper, an article, or a docs page. Tell your agent what you already know — it records that as proposed knowledge you confirm with a tap — and the document reshapes around you: sections you've mastered fold to a stub with a reason, sections you haven't get expansions, glosses, [figures,] and connections to your own notes. Density isn't a global dial; it's a function of what you know about the concepts in each section. An expert in one domain and a novice in another is the normal case.

Three layers, never merged, each toggleable: source (immutable), you (your marks), agent (its artifacts — attributed, reasoned, removable, with one button to remove them all). Switch the agent layer off and you are looking at the untouched text.

The demo reads across a century: Rutherford's 1911 scattering paper (public domain), a 2025 Curious Kids essay from The Conversation on where atoms come from (CC BY-ND — and the layer rule is ND-compliance by construction: the text is byte-identical, everything else is margin), and Chrome's own WebMCP documentation (CC BY 4.0), which the agent annotates using the very tools registered on the page it's reading.

How we built it

Vanilla ES modules, no build step, one static page deployed on Netlify. Page state is a single frozen-source / mutable-margin store; every WebMCP tool validates its input and then calls the store, so the rules are enforced in code, not in a prompt.

Tools registered via the WebMCP imperative API: get_reading_state, get_section_text, get_knowledge, upsert_knowledge, set_section_depth, annotate, search_notes, insert_figure [adjust to what shipped]. Every tool returns structured errors with a next_step written in coach voice for the agent to relay ("hiding a section requires a confirmed knowledge entry — ask the reader to confirm first"). [Your notes never leave the browser: drop a folder of Markdown and the agent queries a client-side index through search_notes.] [Math renders with KaTeX in both source and margin.] [SVG figures pass a sanitizer before rendering.]

Two rules do most of the work: the layer rule (there is no write-to-source tool — enforcement by absence) and the pending-reshape rule (the agent never reshapes the section you are currently reading; changes land as pending and apply when you arrive). The document never moves under you.

Why WebMCP and not an MCP server: the state that matters — the document, the click you just made, your notes, the artifacts already in the margin — is page state you are editing live. A server can't see it; the page can, and hands it to the agent on the next call. And the layer rule is only enforceable where the tools live: a page can simply not register a write tool. A prompt can be argued out of; a missing function cannot.

Challenges we ran into

Building against a protocol that is a week old, in a few hours, with a team of one human orchestrating several coding agents in parallel: one file per lane, an integrator merging, "tested" meaning a screenshot in the PR. [Getting tools visible in the ChatGPT in-app browser vs. the Chrome inspector extension — the API surface is still moving, so we register on both names and log which one took.] Licensing was its own design problem: the demo content had to be legally copyable into a public repo and shown on video, which is how a 1911 paper, a CC BY-ND essay and CC BY docs ended up sharing a stage.

Accomplishments that we're proud of

A document that visibly reshapes as you say what you know — with a reason under every fold. An ethical constraint (AI never writes into human text) that is also a technical guarantee and, incidentally, what makes CC BY-ND content legal to read this way. Honest states everywhere: refusals explain themselves, "no notes loaded" is a state, not an error.

What we learned

The interesting WebMCP apps aren't the ones where the agent fills in forms. They're the ones where the page holds something the agent can't have — here, the reader's live behaviour and their own archive — and the tool schema encodes a relationship: the agent proposes, the page referees, the human decides.

What's next for Marginalia

Integration with knowledge bases, memory systems and testing.

Built With

• css3
• html5
• javascript
• webmcp