The MCP server offers 31 tools. Each one is a route of Yore's API under another name, so a tool answers exactly what the site and the yore command get. This page lists them as the server describes them to an assistant.
The envelope
Every answer is one JSON object:
{"yore": 1, "data": { }, "caveats": [ ]}yoreis the contract's number. It goes up when a consumer would have to change.dataholds the answer.caveatsstates the limits on what the answer supports: that a version runs from its first capture to its last, that the archive didn't look in between. An assistant should pass each one on with the answer it belongs to.
A failure carries error in place of data, with a kind, a finer code and a message:
{"yore": 1, "error": {"kind": "not_found", "code": "not_fetched", "message": "no version [9]"}}| Kind | Means |
|---|---|
usage | The request is wrong as asked. Asking again fails the same way. |
auth | No account, or not this account's. |
not_found | The thing doesn't exist as asked. A version that isn't fetched yet answers with the code not_fetched. |
throttled | Too many requests. retry_after says when to ask again. |
archive | The Internet Archive refused or didn't answer. |
internal | Yore failed. |
The order of a plan
A plan goes through plan_create, plan_tree to see what the site holds, plan_update to set paths and languages, plan_read to read the archive's index, plan_pages and plan_tick to choose pages, plan_coverage to see what a run costs, and plan_run. Reading and running happen in the background, so an assistant polls plan_show and plan_coverage.
Plans
status
Who is connected, how many plans the account holds and its caps. Call it first.
plan_list
Every plan of the account: its website, its rules, its state and how many pages it holds.
plan_create
Make a plan for a website. Yore reads the site's sitemaps, today's and the archive's older ones, so plan_tree can show what the site holds; the plan is `reading` until that is done. Name the paths and languages now or later with plan_update, then call plan_read.
Takes hosts (required), name, paths, locales, from, until, density.
plan_show
One plan: its rules, its state (draft, reading, ready, indexing, indexed, running, paused, done, failed) and its counts. While it is busy, `progress` states the step it is on, how much of that is done, and the minutes left at the archive's pace where that sets the wait.
Takes plan (required).
plan_update
Change a plan's rules. On a plan whose index was read, a path or language taken away takes its pages off the plan at once, and one added is read from the archive's index in the background: the plan is `indexing` until it is `indexed`, and its other pages stay. A plan never read needs plan_read.
Takes plan (required), name, paths, locales, from, until, density.
plan_delete
Delete a plan. The captures Yore fetched stay in its shared cache; the plan, its ticks, its exports and its share links go, and that cannot be undone.
Takes plan (required).
plan_tree
What the website holds under one path, as Yore knows it from the sitemaps and the index: each child segment with how many pages lie under it, and the languages the site speaks. Use it to choose paths.
Takes plan (required), host, under, locale.
plan_read
Read the archive's index for the plan's rules: every page its paths name, including pages the site has since removed, and every capture of each. Runs in the background; the plan is `indexing` until it is `indexed`. Costs one request or a few per path and language, and a path read in the last day is not read again. On a plan already read, this is how to learn what the archive captured since.
Takes plan (required).
plan_pages
The pages on a plan, each with whether it is ticked, how many captures and versions it has, its first and last capture, and its removal if the archive shows one.
Takes plan (required), under, locale, ticked, removed, q, sort, limit, page.
plan_tick
Tick pages in or out of a plan. Only ticked pages are fetched, compared and exported. Name the pages by id, by the start of their path, by language, by a part of their address, those removed or redirected, or all of them; filters narrow each other.
Takes plan (required), ticked (required), pages, under, locale, q, removed, all.
plan_coverage
What running the plan costs and how far it is: ticked pages, captures in the window, distinct versions to read, how many are already fetched, how many requests remain, the minutes that takes at the archive's pace, and captures per year. Read it before plan_run.
Takes plan (required).
plan_run
Start fetching the plan's captures from the web archive. Yore fetches each distinct version once, at the archive's pace, taking turns with other plans; then it reads the text, builds the versions and fetches the images. Runs in the background: plan_coverage shows progress.
Takes plan (required).
plan_pause
Stop fetching for a plan. plan_run resumes it.
Takes plan (required).
Reading
page_show
One page: its versions in order, each from its first capture to its last with how many captures prove it, its removal, and its captures per year.
Takes plan (required), page (required).
version_show
One version of a page: its text in sections, the whole text with nothing set aside, the capture it comes from (snapshot URL, UTC time, status, the archive's digest and the SHA-256 of the bytes Yore froze), and its images, each with the date of its own capture.
Takes plan (required), page (required), position (required).
compare
Two versions of one page set against each other, section by section: which sections stayed, changed, came or went, with the text before and after, and how many words were added and removed.
Takes plan (required), page (required), from (required), to (required), whole.
phrase
The life of a sentence: on which pages it stood, from which capture until which, how many captures prove it, the longest stretch the archive did not look, and the first capture without it. Letter case and typographic quotes are ignored. Quote the sentence as the page prints it.
Takes plan (required), q (required), page.
changes
What changed across the plan, by month, newest first: pages that first appeared, pages whose text changed, and pages that were removed or redirected.
Takes plan (required), from, until.
languages
The same page in the site's other languages on one date, each as its own latest capture on or before that date, in sections. Pages are paired by the hreflang links the page itself carries, or by the same path under another language.
Takes plan (required), page (required), at (required).
Evidence
export_make
Make an export of the plan: one zip with every ticked page, each capture the archive holds in the window, each version, the bytes, the texts and the images, and a manifest with the SHA-256 of every file. Built in the background: export_list shows when it is `ready`, with the manifest's own SHA-256. The file is downloaded on the site or with `yore export download`.
Takes plan (required).
export_list
The plan's exports, newest first, each with its state, its size and its manifest's SHA-256.
Takes plan (required).
exhibit_make
Print one comparison as an exhibit: a PDF with the two captures, their addresses in the web archive, their hashes, and every changed section word by word. Answers the PDF's SHA-256; the file is downloaded on the site or with `yore exhibit`.
Takes plan (required), page (required), from (required), to (required), whole.
share_make
Make a link that shows one comparison, read-only, to whoever holds it. Only make one when the user asks to share: the link opens archived text to anyone.
Takes plan (required), page (required), from (required), to (required), whole.
share_list
The plan's share links, each with its address, what it shows and whether it was revoked.
Takes plan (required).
share_revoke
Revoke a share link. It closes for everyone who holds it.
Takes plan (required), token (required).
verify
Whether Yore issued a file with this SHA-256, an export's manifest.json or an exhibit's PDF, and when. It says nothing of what the file holds.
Takes sha256 (required).
Going forward
watch_set
Start or stop watching pages. A watched page is checked once a day with Yore's own client: a change is captured and frozen that day, and the Internet Archive is asked to capture it too.
Takes plan (required), pages (required), watched (required).
watch_list
The pages the plan watches, each with its last check: when, what the site answered, and whether the page was captured, unchanged, changed, removed or blocked.
Takes plan (required).
watch_check
Check one page now with Yore's own client. One request to the site, at most once a minute per page.
Takes plan (required), page (required).
watch_log
Every check of a page, newest first: the ledger only grows.
Takes plan (required), page (required).
Other
plan_resume
Hand a busy plan that went quiet to a worker again. plan_show says `quiet` when a plan is reading, indexing or running and Yore has not heard from its job for 15 minutes: a worker stopped mid-way leaves it so. What was already read is kept. Refused while the plan is still at work.
Takes plan (required).