wiki-formant 0.67.0 → 0.70.0

package/README.md

@@ -79,7 +79,7 @@ const view = await categoryView({ tree, taxonomy, pages: store }, 'ecosystem', s
 
 ## Wiki read tools
 
-`wikiReadTools` is the read half of a wiki's MCP server over its store and tree: `search_wiki`, `get_page`, `get_pages`, `list_pages`, `get_categories`, `get_recent_changes` and `get_full_corpus`. `searchWiki` is the same rows for an app's plain-GET `?q=` and its search page, so the three never disagree.
+`wikiReadTools` is the read half of a wiki's MCP server over its store and tree: `search_wiki`, `get_page`, `get_pages`, `list_pages`, `get_categories`, `get_recent_changes`, `get_full_corpus` and `get_page_history`. `searchWiki` is the same rows for an app's plain-GET `?q=` and its search page, so the three never disagree.
 
 ```ts
 import { wikiReadTools, searchWiki } from 'wiki-formant/wiki-tools';
@@ -90,6 +90,8 @@ const { items, total } = await searchWiki(reading, 'validators', { page: 1, size
 ```
 
 - Every row carries `path`, which every read tool takes back, and `chars` where the page's text was read. A pasted URL resolves, with `pathPrefix` stripped; a category's path reads its hub article; a miss names the nearest pages.
+- Every row carries the page `id` too, which a `pageList` block takes. `get_page` with `blocks: true` returns the stored blocks, the page `id`, its whole metadata and `version`: what an edit starts from. `forEdit` adds what the app's write tool takes beside them, and `authors` names each revision's author in `get_page_history`.
+- `text` should be the serializer the page's markdown twin uses, and `resolve` the resolver its page uses to fill what is read live (a page list's pages): `get_page`, `get_pages` and the default corpus read text through both, so a page reads the same over MCP as at its twin, which `twinParity` checks.
 - `privateHidden` closes the back office to every tool; without it a hidden page is unlisted but readable by path, as its URL is.
 - `metadata`, `label`, `corpus`, `noMatch` and `skills` are the app's: what a row adds, how a category is named, the sections its llms-full.txt is made of, what an empty search says, and the A2A skills.
 - Writes stay with each app, because who may write is the one thing no two of them agree on.
@@ -248,6 +250,16 @@ process.exit(t.summary());
 
 What stays in your repo is fixtures: which tools you expect, what a good answer from each looks like, and which text surfaces you publish. `payloadBudget` weighs every listed call **and** every read-only tool that takes no required arguments, because the one tool nobody thought to list is the one that answers with 3.3 MB; pass a per-call `maxBytes` for a bulk-export tool that is deliberately large. It also asserts that a JSON answer arrived with `structuredContent`.
 
+The drift checks hold an MCP server to what its own site does, so a tool cannot describe, accept or return something the site does not:
+
+- `manifestParity(t, { writeAuth? })`: `/.well-known/mcp.json` is `tools/list` tool for tool, names the endpoint under test, and states write auth only where a write tool is listed (both ways, given `writeAuth`).
+- `rowParity(t, label, mcp, rest)`: a tool's answer and the GET API's or `?q=` page's are identical, and not both empty.
+- `twinParity(t, label, twinUrl, text)`: a read tool's text is the page's markdown twin, past its frontmatter and the title line.
+- `editReadChecks(t, { path, rows?, validate?, endpoint? })`: rows carry page ids, `get_page` with `blocks: true` returns blocks the site's own `validate` accepts and a version, and `get_page_history`'s newest revision is that version.
+- `roundTrip(t, label, { read, write })`: what a read tool hands out, the write tool takes back unchanged, and the next read matches.
+- `openapiWriteParity(t, [[path, method, tool], …])`: every field an OpenAPI write documents, the matching tool takes.
+- `rolaOriginCheck(t)`: a challenge tool's ROLA recipe names the origin under test.
+
 `standardVersionSources(t, openapiPaths)` is the `versionCoherence` map every S10 surface serves — both agent-card paths, `mcp.json`, the server card and each path the OpenAPI document answers at — so a suite names only the paths it adds. `t.rpcAt(endpoint, …)` and `t.callAt` drive a second MCP endpoint on the same surface with the same backoff, User-Agent and tally.
 
 ```ts

package/dist/conformance.d.ts

@@ -193,3 +193,70 @@ export declare function payloadBudget(t: Tester, calls: ReadonlyArray<{
  * every unnamed crawler is telling two different stories to the same caller.
  */
 export declare function robotsChecks(t: Tester, paths: readonly string[]): Promise<void>;
+/**
+ * `/.well-known/mcp.json` is `tools/list`, tool for tool, names the endpoint
+ * under test, and states write auth only where the server lists a write tool.
+ *
+ * Both lists are `toolCard` projections, so anything short of equality is a
+ * manifest built from something other than the server's own tools. Pass
+ * `writeAuth` where the server's writes take a credential the manifest should
+ * describe, and the check runs both ways.
+ */
+export declare function manifestParity(t: Tester, opts?: {
+    url?: string;
+    writeAuth?: boolean;
+}): Promise<void>;
+/**
+ * Two surfaces answering one question answer it identically: a tool's rows and
+ * the GET API's, a tool's search and the `?q=` page's. Two empty answers are
+ * not agreement, so an empty one fails.
+ */
+export declare function rowParity(t: Tester, label: string, mcp: unknown, rest: unknown): void;
+/**
+ * A page reads the same over MCP as at its markdown twin: the tool's text is
+ * the twin's body, after the frontmatter, and after the `# Title` line the twin
+ * adds where the page's own blocks open with no h1.
+ */
+export declare function twinParity(t: Tester, label: string, twinUrl: string, content: string): Promise<void>;
+/**
+ * What an edit starts from, on any server built on the wiki read tools: rows
+ * carry the id a pageList block takes, `get_page` with `blocks: true` returns
+ * the stored blocks and the version a save takes as its base, and the history's
+ * newest revision is that version. `validate` is the site's own block check,
+ * so blocks the tool hands out are blocks the site's write takes back.
+ */
+export declare function editReadChecks(t: Tester, opts: {
+    path: string;
+    endpoint?: string;
+    rows?: ReadonlyArray<{
+        id?: unknown;
+    }>;
+    validate?: (blocks: unknown[]) => true | string;
+    label?: string;
+}): Promise<void>;
+/**
+ * What a read tool hands out, a write tool takes back unchanged, and the page
+ * reads the same after: the read's shape is the write's. `write` gets the read
+ * as it came; `read` is called again after.
+ */
+export declare function roundTrip(t: Tester, label: string, io: {
+    read: () => Promise<unknown>;
+    write: (value: unknown) => Promise<Rpc>;
+}): Promise<void>;
+/**
+ * Every field a REST write documents, the matching tool takes. An edit tool
+ * missing the version field the editor sends overwrites whatever landed between
+ * an agent's read and its write. `ops` pairs an OpenAPI path and method with
+ * the tool that does the same write.
+ */
+export declare function openapiWriteParity(t: Tester, ops: ReadonlyArray<readonly [path: string, method: string, tool: string]>, specUrl?: string): Promise<void>;
+/**
+ * The ROLA recipe a challenge tool hands out names the origin the verifier
+ * checks: the origin under test. One that named the canonical site while the
+ * verifier read another variable failed every signature off that site.
+ */
+export declare function rolaOriginCheck(t: Tester, opts?: {
+    origin?: string;
+    endpoint?: string;
+    tool?: string;
+}): Promise<void>;

package/dist/conformance.js

@@ -468,3 +468,128 @@ export async function robotsChecks(t, paths) {
         t.check(`robots allows ${path}`, !match || match.allow, match ? `${match.allow ? 'Allow' : 'Disallow'}: ${match.path}` : 'no matching rule');
     }
 }
+// ---- drift: what the MCP server says against what the site does -----------
+//
+// Each app had written these against its own surfaces after an audit found its
+// MCP server describing, accepting or returning something its site did not:
+// an edit tool without the version guard the editor sends, page reads that
+// flattened what the markdown twin kept, a manifest stating write auth on a
+// deployment with no writes. The same check, once per app, is how the checks
+// themselves drift, so they live here beside the transport they test.
+/** A JSON value that says nothing: comparing two of them proves nothing. */
+const vacuous = (v) => v == null || (Array.isArray(v) ? v.length === 0 : typeof v === 'object' && Object.keys(v).length === 0);
+/** Where two JSON values first part, for a check's note. */
+const firstDifference = (a, b) => {
+    const [x, y] = [JSON.stringify(a) ?? 'undefined', JSON.stringify(b) ?? 'undefined'];
+    let i = 0;
+    while (i < x.length && x[i] === y[i])
+        i++;
+    return `at char ${i}: MCP …${x.slice(Math.max(0, i - 20), i + 40)}… vs …${y.slice(Math.max(0, i - 20), i + 40)}…`;
+};
+/**
+ * `/.well-known/mcp.json` is `tools/list`, tool for tool, names the endpoint
+ * under test, and states write auth only where the server lists a write tool.
+ *
+ * Both lists are `toolCard` projections, so anything short of equality is a
+ * manifest built from something other than the server's own tools. Pass
+ * `writeAuth` where the server's writes take a credential the manifest should
+ * describe, and the check runs both ways.
+ */
+export async function manifestParity(t, opts = {}) {
+    const manifest = (await (await fetch(opts.url ?? `${t.base}/.well-known/mcp.json`)).json());
+    const listed = (await t.rpc('tools/list')).result?.tools ?? [];
+    const names = (xs) => xs.map(x => x.name).sort().join(' ');
+    const same = JSON.stringify(manifest.tools) === JSON.stringify(listed);
+    t.check('mcp.json is tools/list', same && listed.length > 0, same ? `${listed.length} tools` : names(manifest.tools ?? []) === names(listed) ? firstDifference(manifest.tools, listed) : `mcp.json: ${names(manifest.tools ?? [])} | tools/list: ${names(listed)}`);
+    // By path: the manifest names the canonical origin, and a run against a dev server is not it.
+    const path = (u) => (u ? new URL(u, t.base).pathname : '');
+    t.check('mcp.json names the endpoint', path(manifest.mcp?.endpoint) === path(t.endpoint), `${manifest.mcp?.endpoint}`);
+    const writes = listed.filter(x => x.annotations?.readOnlyHint === false).length;
+    const states = !!manifest.auth?.writes;
+    t.check('mcp.json write auth', (!states || writes > 0) && (opts.writeAuth === undefined || states === opts.writeAuth), `auth.writes ${states ? 'stated' : 'absent'}, ${writes} write tools listed${opts.writeAuth === undefined ? '' : `, expected ${opts.writeAuth ? 'stated' : 'absent'}`}`);
+}
+/**
+ * Two surfaces answering one question answer it identically: a tool's rows and
+ * the GET API's, a tool's search and the `?q=` page's. Two empty answers are
+ * not agreement, so an empty one fails.
+ */
+export function rowParity(t, label, mcp, rest) {
+    const same = JSON.stringify(mcp) === JSON.stringify(rest);
+    t.check(label, same && !vacuous(mcp), vacuous(mcp) ? 'nothing to compare: the MCP answer is empty' : same ? 'identical' : firstDifference(mcp, rest));
+}
+/**
+ * A page reads the same over MCP as at its markdown twin: the tool's text is
+ * the twin's body, after the frontmatter, and after the `# Title` line the twin
+ * adds where the page's own blocks open with no h1.
+ */
+export async function twinParity(t, label, twinUrl, content) {
+    const url = twinUrl.startsWith('http') ? twinUrl : `${t.base}/${twinUrl.replace(/^\//, '')}`;
+    const res = await fetch(url);
+    let body = (await res.text()).replace(/^---\n[\s\S]*?\n---\n+/, '').trim();
+    const text = content.trim();
+    if (!text.startsWith('# '))
+        body = body.replace(/^# [^\n]*\n+/, '');
+    t.check(label, res.ok && !!text && body === text, !res.ok ? `${res.status} ${url}` : !text ? 'nothing to compare: the MCP text is empty' : body === text ? `${text.length} chars` : firstDifference(text, body));
+}
+/**
+ * What an edit starts from, on any server built on the wiki read tools: rows
+ * carry the id a pageList block takes, `get_page` with `blocks: true` returns
+ * the stored blocks and the version a save takes as its base, and the history's
+ * newest revision is that version. `validate` is the site's own block check,
+ * so blocks the tool hands out are blocks the site's write takes back.
+ */
+export async function editReadChecks(t, opts) {
+    const endpoint = opts.endpoint ?? t.endpoint;
+    const label = (s) => (opts.label ? `[${opts.label}] ${s}` : s);
+    if (opts.rows) {
+        const rows = opts.rows;
+        t.check(label('rows carry the page id'), rows.length > 0 && rows.every(r => typeof r.id === 'string' && r.id.length > 0), `${rows.length} rows, first id=${String(rows[0]?.id)}`);
+    }
+    const page = t.payload(await t.callAt(endpoint, 'get_page', { path: opts.path, blocks: true }));
+    const blocks = Array.isArray(page?.content) ? page.content : null;
+    const verdict = blocks && opts.validate ? opts.validate(blocks) : true;
+    t.check(label('get_page(blocks)'), !!page?.id && !!page.version && !!blocks && typeof page.metadata === 'object' && verdict === true, !blocks ? `no block array: ${JSON.stringify(page).slice(0, 80)}` : verdict !== true ? `the site's block check refuses them: ${verdict}` : `${blocks.length} blocks, v${page.version}`);
+    const history = t.payload(await t.callAt(endpoint, 'get_page_history', { path: opts.path, limit: 3 }));
+    const newest = history?.revisions?.[0];
+    t.check(label('get_page_history'), !!newest?.id && newest.version === history.currentVersion && newest.version === page?.version && 'author' in newest, `${history?.revisions?.length ?? 0} revisions, newest v${newest?.version} of v${history?.currentVersion}, page v${page?.version}`);
+}
+/**
+ * What a read tool hands out, a write tool takes back unchanged, and the page
+ * reads the same after: the read's shape is the write's. `write` gets the read
+ * as it came; `read` is called again after.
+ */
+export async function roundTrip(t, label, io) {
+    const before = await io.read();
+    const wrote = await io.write(before);
+    const after = await io.read();
+    const failed = wrote.error ? `-${wrote.error.code} ${wrote.error.message}` : wrote.result?.isError ? String(t.payload(wrote)).slice(0, 100) : '';
+    t.check(label, !vacuous(before) && !failed && JSON.stringify(after) === JSON.stringify(before), vacuous(before) ? 'nothing to compare: the read is empty' : failed ? `the write refused its own read: ${failed}` : JSON.stringify(after) === JSON.stringify(before) ? 'unchanged' : firstDifference(after, before));
+}
+/**
+ * Every field a REST write documents, the matching tool takes. An edit tool
+ * missing the version field the editor sends overwrites whatever landed between
+ * an agent's read and its write. `ops` pairs an OpenAPI path and method with
+ * the tool that does the same write.
+ */
+export async function openapiWriteParity(t, ops, specUrl = `${t.base}/.well-known/openapi.json`) {
+    const spec = (await (await fetch(specUrl)).json());
+    const tools = (await t.rpc('tools/list')).result?.tools ?? [];
+    for (const [path, method, tool] of ops) {
+        const content = spec.paths?.[path]?.[method.toLowerCase()]?.requestBody?.content ?? {};
+        const fields = [...new Set(Object.values(content).flatMap(c => Object.keys(c.schema?.properties ?? {})))];
+        const props = Object.keys(tools.find(x => x.name === tool)?.inputSchema?.properties ?? {});
+        const missing = fields.filter(f => !props.includes(f));
+        t.check(`${tool} takes ${method.toUpperCase()} ${path}`, fields.length > 0 && missing.length === 0, !fields.length ? `the spec documents no body for ${method.toUpperCase()} ${path}` : missing.length ? `missing: ${missing.join(', ')}` : `${fields.length} fields`);
+    }
+}
+/**
+ * The ROLA recipe a challenge tool hands out names the origin the verifier
+ * checks: the origin under test. One that named the canonical site while the
+ * verifier read another variable failed every signature off that site.
+ */
+export async function rolaOriginCheck(t, opts = {}) {
+    const origin = opts.origin ?? new URL(t.base).origin;
+    const answer = t.payload(await t.callAt(opts.endpoint ?? t.endpoint, opts.tool ?? 'get_challenge'));
+    const message = answer?.sign?.message ?? '';
+    t.check('ROLA recipe names this origin', message.includes(`"${origin}"`), `expects "${origin}" in: …${message.slice(-90)}`);
+}

package/dist/mcp.d.ts

@@ -34,13 +34,34 @@ export declare const MCP_META: {
     readonly serverInfo: "io.modelcontextprotocol/serverInfo";
 };
 import { type RateLimitOptions } from './rate-limit.js';
+/**
+ * JSON Schema as far as a tool's parameters go. Open past the named keywords,
+ * because an array's items may be a whole block type, which a narrower shape
+ * made every app type as `{ type: 'object' }` and leave the rest unsaid.
+ */
+export type JsonSchema = {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    description?: string;
+    enum?: readonly (string | number)[];
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    required?: readonly string[];
+    minimum?: number;
+    maximum?: number;
+    [keyword: string]: unknown;
+};
 export type ToolParam = {
     type: 'string' | 'number' | 'boolean' | 'array' | 'object';
     description: string;
     enum?: string[];
-    items?: {
-        type?: 'string' | 'number' | 'object';
-    };
+    items?: JsonSchema;
+    /**
+     * Bounds a client can read before it calls. The handler still clamps (an
+     * argument out of range comes back adjusted, not refused), so these state the
+     * clamp rather than enforce it.
+     */
+    minimum?: number;
+    maximum?: number;
 };
 export type ToolSchema = {
     type: 'object';

package/dist/mcp.js

@@ -233,7 +233,7 @@ function validateArgs(tool, args) {
             // No `items` means strings. Items with no one type (a `oneOf` of shapes,
             // as a zod union emits) are the tool's own to check: read as strings, every
             // well-formed call was refused.
-            const itemType = spec.items ? spec.items.type : 'string';
+            const itemType = spec.items ? (spec.items.type === 'integer' ? 'number' : spec.items.type) : 'string';
             if (actual !== 'array') {
                 problems.push(`Parameter "${key}" must be an array${itemType ? ` of ${itemType}s` : ''}; received ${actual} (${JSON.stringify(value)}).`);
             }

package/dist/wiki-tools.d.ts

@@ -1,9 +1,9 @@
 import { type McpTool } from './mcp.js';
 import { type CorpusSection } from './corpus.js';
 import { type WikiNode, type WikiTree } from './tree.js';
-import type { WikiStore, WikiPageListing, PageMetadata } from './store.js';
+import type { WikiStore, WikiPageListing, WikiPageRow, PageMetadata } from './store.js';
 import type { DiffBlock } from './revisions.js';
-type ToolName = 'search_wiki' | 'get_page' | 'get_pages' | 'list_pages' | 'get_categories' | 'get_recent_changes' | 'get_full_corpus';
+type ToolName = 'search_wiki' | 'get_page' | 'get_pages' | 'list_pages' | 'get_categories' | 'get_recent_changes' | 'get_full_corpus' | 'get_page_history';
 export interface WikiToolsOptions<B extends DiffBlock> {
     store: WikiStore<B>;
     tree: WikiTree<WikiNode>;
@@ -11,6 +11,13 @@ export interface WikiToolsOptions<B extends DiffBlock> {
     url: (tagPath: string, slug: string) => string;
     /** A page's blocks as plain prose: what `get_page` returns and `chars` counts. */
     text: (blocks: B[]) => string;
+    /**
+     * A page's blocks with what is read live filled in, such as a page list's
+     * pages: the resolver the app's page and markdown twin use. `get_page`,
+     * `get_pages` and the default corpus read their text through it, so a list
+     * reads there as it does on the twin rather than as its stored placeholder.
+     */
+    resolve?: (blocks: B[]) => Promise<B[]>;
     /** The wiki as the descriptions name it: "the Radix Wiki", "this DAO's wiki". */
     noun: string;
     /** The corpus document's heading. */
@@ -19,6 +26,10 @@ export interface WikiToolsOptions<B extends DiffBlock> {
     pathPrefix?: string;
     /** Back-office pages are private here, not merely unlisted: no tool reads one. */
     privateHidden?: boolean;
+    /** What `get_page` with `blocks: true` adds for the app's write tool, such as fields it keeps inside metadata. */
+    forEdit?: (page: WikiPageRow<B>) => Record<string, unknown>;
+    /** Display names by user id, for `get_page_history`. Without it a revision names no author. */
+    authors?: (ids: string[]) => Promise<Map<string, string>>;
     /** What a listing row adds from the page's metadata, or null for nothing. */
     metadata?: (tagPath: string, metadata: PageMetadata) => Record<string, unknown> | null;
     /** A category's name as the tree lists it. Defaults to the node's `name`. */
@@ -32,7 +43,7 @@ export interface WikiToolsOptions<B extends DiffBlock> {
 }
 /** A read tool: the package's always say whether they write. */
 export type WikiTool = McpTool & Required<Pick<McpTool, 'title' | 'annotations'>>;
-type Rowable<B> = Pick<WikiPageListing, 'title' | 'tagPath' | 'slug' | 'snippet' | 'metadata' | 'updatedAt' | 'lastVerifiedAt'> & {
+type Rowable<B> = Pick<WikiPageListing, 'id' | 'title' | 'tagPath' | 'slug' | 'snippet' | 'metadata' | 'updatedAt' | 'lastVerifiedAt'> & {
     content?: B[];
 };
 /** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
@@ -42,6 +53,7 @@ declare const rowFor: <B extends DiffBlock>(o: Pick<WikiToolsOptions<B>, "url" |
     snippet: string;
     updatedAt: string;
     chars?: number | undefined;
+    id: string;
     title: string;
     path: string;
     url: string;

package/dist/wiki-tools.js

@@ -21,12 +21,19 @@ import { openingText } from './text.js';
 const MAX_BATCH_PATHS = 20;
 const READ = { readOnlyHint: true, idempotentHint: true, openWorldHint: false };
 const pathOf = (tagPath, slug) => wikiPath(tagPath, slug).slice(1);
+/** How a single-page tool takes its page. */
+const ADDRESS = {
+    path: { type: 'string', description: 'The page\'s whole path, e.g. "developers/scrypto/blueprints". Preferred over tagPath + slug.' },
+    tagPath: { type: 'string', description: 'Tag path only ("" for a top-level page). Ignored when `path` is set.' },
+    slug: { type: 'string', description: 'Page slug. Ignored when `path` is set.' },
+};
 /** Whether a tag path is closed to these tools: a back office the wiki keeps private. */
 const offFor = (o) => (tagPath) => !!tagPath && !!o.privateHidden && o.store.isHidden(tagPath);
 /** The row every listing returns: search, list, recent changes, and the app's own `?q=` twin. */
 const rowFor = (o) => (p) => {
     const meta = o.metadata?.(p.tagPath, (p.metadata ?? {}));
     return {
+        id: p.id,
         title: p.title,
         path: pathOf(p.tagPath, p.slug),
         url: o.url(p.tagPath, p.slug),
@@ -68,21 +75,38 @@ export function wikiReadTools(o) {
         const page = (await store.get(t.tagPath, t.slug)) ?? (await store.get(pathOf(t.tagPath, t.slug), ''));
         return page && !off(page.tagPath) ? page : null;
     };
-    const full = (page) => ({
+    /** The page a call names by `path` or `tagPath` + `slug`; a miss names the nearest pages, so a wrong guess is fixed in one retry. */
+    const named = async (r) => {
+        const raw = r.str('path');
+        const t = raw ? target(raw) : { tagPath: r.str('tagPath'), slug: r.str('slug') };
+        if (!t?.slug)
+            throw new McpToolError('Pass either `path` ("tag/path/slug") or `slug` (with optional `tagPath`).');
+        const page = await read(t);
+        if (page)
+            return page;
+        const near = await store.search(t.slug.replace(/-/g, ' '), { take: 5 });
+        throw new McpToolError(`No page at path "${pathOf(t.tagPath, t.slug)}".`, {
+            didYouMean: near.items.filter(p => !off(p.tagPath)).map(p => ({ path: pathOf(p.tagPath, p.slug), title: p.title })),
+            hint: 'Paths are exact. Use search_wiki for a keyword, or list_pages with the tagPath to enumerate the branch.',
+        });
+    };
+    /** Blocks as the page shows them. */
+    const shown = (blocks) => (o.resolve ? o.resolve(blocks) : Promise.resolve(blocks));
+    const head = (page) => ({
         ...summary({ ...page, snippet: describe(openingText(page.content)) }),
         version: page.version,
-        content: o.text(page.content),
     });
+    const full = async (page) => ({ ...head(page), content: o.text(await shown(page.content)) });
     const sections = async (tagPath) => {
         if (o.corpus)
             return o.corpus(tagPath);
         const pages = (await store.corpus())
             .filter(p => !(p.tagPath === '' && p.slug === '') && (!tagPath || p.tagPath === tagPath || p.tagPath.startsWith(`${tagPath}/`)))
             .sort((a, b) => b.updatedAt.getTime() - a.updatedAt.getTime());
-        return pages.map(p => {
+        return Promise.all(pages.map(async (p) => {
             const path = pathOf(p.tagPath, p.slug);
-            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(p.content)}` };
-        });
+            return { path, tagPath: p.tagPath, section: `## ${p.title}\n\nPath: ${path}\nURL: ${o.url(p.tagPath, p.slug)}\nUpdated: ${isoDate(p.updatedAt)}\n\n${o.text(await shown(p.content))}` };
+        }));
     };
     const tools = [
         {
@@ -100,8 +124,8 @@ export function wikiReadTools(o) {
                 properties: {
                     query: { type: 'string', description: 'Search term, matched against page titles and body text' },
                     tagPath: { type: 'string', description: 'Only pages at this tag path, e.g. a path from get_categories' },
-                    page: { type: 'number', description: '1-based page number (default 1)' },
-                    pageSize: { type: 'number', description: 'Results per page (default 20, max 50)' },
+                    page: { type: 'number', description: '1-based page number (default 1)', minimum: 1 },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 50)', minimum: 1, maximum: 50 },
                 },
                 required: ['query'],
             },
@@ -129,31 +153,23 @@ export function wikiReadTools(o) {
             description: `One page of ${noun} in full: its text, version, update date and metadata. ` +
                 'Address it by `path` ("tag/path/slug", exactly the `path` or `url` a listing returns), or by `tagPath` + `slug`; a category\'s own path reads its hub article. Not a title. ' +
                 'For 2 to 20 pages call get_pages, one round trip rather than N. A miss names the nearest pages, so a wrong guess is fixed in one retry. ' +
-                'A page\'s URL with `.md` appended is its markdown.',
+                'A page\'s URL with `.md` appended is its markdown. ' +
+                'With `blocks: true`, `content` is the stored block array, ids and all, beside the page `id` and its whole `metadata`: read a page this way before editing it, and send its `version` back as the edit\'s baseVersion.',
             inputSchema: {
                 type: 'object',
                 properties: {
-                    path: { type: 'string', description: 'The page\'s whole path, e.g. "developers/scrypto/blueprints". Preferred over tagPath + slug.' },
-                    tagPath: { type: 'string', description: 'Tag path only ("" for a top-level page). Ignored when `path` is set.' },
-                    slug: { type: 'string', description: 'Page slug. Ignored when `path` is set.' },
+                    ...ADDRESS,
+                    blocks: { type: 'boolean', description: 'Return the stored blocks rather than prose, for an edit' },
                 },
                 requireOneOf: ['path', 'slug'],
             },
             handler: async (args) => {
                 const r = readArgs(args);
-                const raw = r.str('path');
-                const t = raw ? target(raw) : { tagPath: r.str('tagPath'), slug: r.str('slug') };
-                if (!t?.slug)
-                    throw new McpToolError('Pass either `path` ("tag/path/slug") or `slug` (with optional `tagPath`).');
-                const page = await read(t);
-                if (!page) {
-                    const near = await store.search(t.slug.replace(/-/g, ' '), { take: 5 });
-                    throw new McpToolError(`No page at path "${pathOf(t.tagPath, t.slug)}".`, {
-                        didYouMean: near.items.filter(p => !off(p.tagPath)).map(p => ({ path: pathOf(p.tagPath, p.slug), title: p.title })),
-                        hint: 'Paths are exact. Use search_wiki for a keyword, or list_pages with the tagPath to enumerate the branch.',
-                    });
-                }
-                return withAdjustments(r, full(page));
+                const page = await named(r);
+                if (!r.bool('blocks'))
+                    return withAdjustments(r, await full(page));
+                // Stored, not resolved: what an edit sends back is what was stored.
+                return withAdjustments(r, { ...head(page), id: page.id, content: page.content, metadata: page.metadata, ...o.forEdit?.(page) });
             },
         },
         {
@@ -167,7 +183,7 @@ export function wikiReadTools(o) {
                 type: 'object',
                 properties: {
                     paths: { type: 'array', items: { type: 'string' }, description: `Page paths, 1 to ${MAX_BATCH_PATHS} per call` },
-                    maxChars: { type: 'number', description: 'Total characters across the pages returned (default 250000, max 1000000)' },
+                    maxChars: { type: 'number', description: 'Total characters across the pages returned (default 250000, max 1000000)', minimum: 1_000, maximum: 1_000_000 },
                 },
                 required: ['paths'],
             },
@@ -194,7 +210,7 @@ export function wikiReadTools(o) {
                         missing.push(input);
                         continue;
                     }
-                    const row = full(page);
+                    const row = await full(page);
                     // At least one page always comes back, so one oversized page can still be read.
                     if (pages.length && used + row.content.length > maxChars) {
                         omitted.push({ path: row.path, chars: row.content.length });
@@ -228,8 +244,8 @@ export function wikiReadTools(o) {
                 properties: {
                     tagPath: { type: 'string', description: 'The branch to list, e.g. a path from get_categories. Includes its descendants.' },
                     sort: { type: 'string', enum: ['title', 'updatedAt'], description: 'Sort order (default "updatedAt", newest first)' },
-                    page: { type: 'number', description: '1-based page number (default 1)' },
-                    pageSize: { type: 'number', description: 'Results per page (default 20, max 100)' },
+                    page: { type: 'number', description: '1-based page number (default 1)', minimum: 1 },
+                    pageSize: { type: 'number', description: 'Results per page (default 20, max 100)', minimum: 1, maximum: 100 },
                 },
             },
             handler: async (args) => {
@@ -285,8 +301,8 @@ export function wikiReadTools(o) {
             inputSchema: {
                 type: 'object',
                 properties: {
-                    days: { type: 'number', description: 'Look back this many days (default 7, max 30)' },
-                    limit: { type: 'number', description: 'Most pages returned (default 20, max 50)' },
+                    days: { type: 'number', description: 'Look back this many days (default 7, max 30)', minimum: 1, maximum: 30 },
+                    limit: { type: 'number', description: 'Most pages returned (default 20, max 50)', minimum: 1, maximum: 50 },
                 },
             },
             handler: async (args) => {
@@ -320,8 +336,8 @@ export function wikiReadTools(o) {
                 properties: {
                     sizeOnly: { type: 'boolean', description: 'Sizes and breakdowns only, no document. Do this before the first real pull.' },
                     tagPath: { type: 'string', description: 'One branch and its descendants. Omit for everything.' },
-                    maxChars: { type: 'number', description: `Character budget for \`document\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max})` },
-                    skip: { type: 'number', description: 'Resume from this page index: the `nextSkip` of the previous truncated call (default 0)' },
+                    maxChars: { type: 'number', description: `Character budget for \`document\` (default ${CORPUS_BUDGET.default}, max ${CORPUS_BUDGET.max})`, minimum: CORPUS_BUDGET.min, maximum: CORPUS_BUDGET.max },
+                    skip: { type: 'number', description: 'Resume from this page index: the `nextSkip` of the previous truncated call (default 0)', minimum: 0 },
                 },
             },
             handler: async (args) => {
@@ -337,6 +353,33 @@ export function wikiReadTools(o) {
                 return withAdjustments(r, { scope: o.corpusTitle, ...(tagPath ? { tagPath } : {}), ...slice });
             },
         },
+        {
+            name: 'get_page_history',
+            title: 'Page history',
+            annotations: READ,
+            description: `A page's revisions in ${noun}, newest first: each one's \`id\`, version, change type, message, date and the blocks it changed. ` +
+                'Address the page as get_page does. A revision `id` is what a restore takes, where this server has one. Defaults: limit 20 (max 100).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    ...ADDRESS,
+                    limit: { type: 'number', description: 'Most revisions returned (default 20, max 100)', minimum: 1, maximum: 100 },
+                },
+                requireOneOf: ['path', 'slug'],
+            },
+            handler: async (args) => {
+                const r = readArgs(args);
+                const page = await named(r);
+                const revisions = await store.history(page.id, { limit: r.num('limit', 20, 1, 100) });
+                const names = o.authors && await o.authors([...new Set(revisions.flatMap(v => v.authorId ? [v.authorId] : []))]);
+                return withAdjustments(r, {
+                    path: pathOf(page.tagPath, page.slug),
+                    url: o.url(page.tagPath, page.slug),
+                    currentVersion: page.version,
+                    revisions: revisions.map(({ pageId: _, authorId, ...v }) => ({ ...v, ...(names ? { author: (authorId && names.get(authorId)) || null } : {}) })),
+                });
+            },
+        },
     ];
     return tools.map(t => (o.skills?.[t.name] ? { ...t, skill: o.skills[t.name] } : t));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wiki-formant",
-  "version": "0.67.0",
+  "version": "0.70.0",
   "description": "The portable half of a wiki: derived taxonomy and facet controls, a version-negotiating MCP transport, markdown twins, block rendering, a rich-text editor engine, conditional-GET plumbing, and the headers and CSP every origin sends.",
   "type": "module",
   "license": "MIT",