feat(pages): partial page editing without resending whole pages

[glazperle]

The problem

BookStack's API only supports full replacement of page content. PUT /api/pages/{id} takes a complete html or markdown body, and there is no PATCH endpoint.

For an LLM client this is expensive. Changing one paragraph of a long page means reading the whole page, reproducing it verbatim with the change applied, and sending all of it back. The content passes through the model twice, and correctness depends on the model copying thousands of tokens without a single slip.

The repo already documents the workaround, in bookstack_pages_update's own description:

markdown replaces the whole page, so to append you must resend the existing content plus the addition - read the page first.

This PR moves that read-modify-write cycle into the server, so a client sends only the fragment it wants changed.

Existing behaviour is unchanged. bookstack_pages_update still replaces the whole content field. bookstack_pages_read without any of the new options returns the same object it always did, and there is a test asserting that by object identity.

What's added

Tool	Purpose
bookstack_pages_edit	Literal find-and-replace. Each edit swaps an old_string for a new_string, applied in order.
bookstack_pages_append	Insert at the end of the page, at the end of a named section, or immediately after a section heading.
bookstack_pages_outline	Heading structure: level, exact text, character offset, section size, plus the page's editor type. Returns no content.

bookstack_pages_read gains grep, case_sensitive, context, max_matches, offset, length and metadata_only, so a large page can be searched or read in windows. grep searches the stored source, not the rendered output, which is what makes a returned excerpt usable as an old_string anchor without modification.

A typical sequence on a large page:

// 1. What sections exist, and how big are they?
{ "tool": "bookstack_pages_outline", "arguments": { "id": 12 } }

// 2. Get an exact anchor without loading the page
{ "tool": "bookstack_pages_read",
  "arguments": { "id": 12, "grep": "retention period", "context": 300 } }

// 3. Rehearse. Nothing is written.
{ "tool": "bookstack_pages_edit",
  "arguments": { "id": 12, "dry_run": true,
    "edits": [{ "old_string": "retention period of 6 months",
                "new_string": "retention period of 24 months" }] } }

// 4. Apply, refusing the write if the page changed meanwhile
{ "tool": "bookstack_pages_edit",
  "arguments": { "id": 12, "expected_updated_at": "2026-08-17T09:12:44.000000Z",
    "edits": [{ "old_string": "retention period of 6 months",
                "new_string": "retention period of 24 months" }] } }

Two rules about which field to patch

Both live in src/utils/page-content.ts and both have direct test coverage.

Markdown pages (editor === 'markdown') are patched and written through markdown. Writing html to a markdown page changes its editor type, and the API provides no way to change it back.

Every other page is patched against raw_html, the stored source, and never against html, the rendered output. html has page includes already resolved, so writing a patched copy of it back would replace every {{@42}} include with a frozen snapshot of its target. An anchor taken from the rendered output would also fail to match on write.

Guards

These target the mistakes an LLM client makes in practice, not malicious input.

An old_string must match exactly once. If it matches more often the edit is refused instead of applied to the first hit, and the error includes the first few matches with surrounding context. replace_all is available for a rename that legitimately repeats.

If an anchor is not found, the error reports whether the same text exists with different whitespace, and includes the actual bytes. This is the most frequent failure we saw in practice: a model reproduces a sentence with collapsed whitespace because that is how it reads on screen. Reporting only "not found" gives it nothing to act on.

dry_run applies the edits in memory and reports what would change. No request reaches BookStack.

expected_updated_at is an optimistic lock against the page's updated_at. Without it, a concurrent edit by someone else is silently overwritten.

A result smaller than half the original is refused unless allow_shrink is set. This catches an anchor whose closing text occurs earlier than the author expected, which would otherwise delete most of the document.

After a write, the page is read again and the written fragments are looked for in normalised text. BookStack regenerates heading anchors and injects id attributes on save, so the bytes returned differ from the bytes sent and a byte comparison would report every successful write as a failure. A fragment that cannot be found yields verified: false instead of an exception, because the write did happen and the client needs both facts.

None of these tools return page content in their responses. Each write creates a BookStack revision, so an applied edit can still be rolled back from the UI.

Error mapping

PageContentError and PageStaleError are mapped in ErrorHandler.handleError() rather than at the tool, so McpError stays confined to src/utils/errors.ts and the tool classes keep throwing plain errors.

PageContentError maps to InvalidParams. Each case describes something about the caller's input, and the details object carries what the client needs to correct itself: available section names, ambiguous matches, or the whitespace-tolerant match. The generic branch would report these as InternalError and discard details.

PageStaleError maps to InvalidRequest and is a separate class for that reason. The arguments were valid and the page moved, so the correct client response is to re-read and retry, not to change the anchor.

Contract and tests

MCPSchemaNode gains minItems and maxItems, so the published lower bound on the edits array matches the zod rule, the way minLength already pairs with z.string().min(n).

New schemas use z.strictObject and the shared entityId. id is part of the schema and the handler destructures the validated object.

tests/unit/id-schema-contract.test.ts gains 7 integer classifications and 3 tool bases. One judgement call worth flagging: context publishes minimum: 1. I first wrote a practical floor of about 20, but the exact-minimum rule in that test would then need a fifth category for a single property. The bound that matters there is the maximum, which is what stops a grep from returning the whole page.

tests/unit/page-content.test.ts (33 tests) covers the pure helpers, both field-selection rules, and every diagnostic.

tests/unit/pages.test.ts (19 tests) drives the handlers against a recording client with the real ValidationHandler. These tools depend on schema defaults and on strictObject rejecting unknown keys, so a stubbed validator would test a contract that does not ship. The assertions cover which field is written, that nothing is written when a guard fires, and that responses contain no page content.

Tool count 56 to 59 in tests/transport/tools.test.ts, tests/transport/stdio.test.ts, README, docs/ and docker-compose.yml.

bunx tsc --noEmit clean, bunx biome check . clean, bun test 297 passing (integration suites skip without a live BookStack).

Notes for review

This has been running against a live BookStack 26.05.2 instance in a fork for a while. Every guard above exists because the corresponding mistake happened first.

src/utils/page-content.ts has no client and no I/O, so the field-selection rules and the diagnostics are testable in isolation.

Happy to split this if you prefer smaller pieces: the helpers plus the pages_read options are independently useful, with the three tools as a second PR. Also happy to change naming, parameter shapes or descriptions.

🤖 Generated with Claude Code

[pnocera]

Requesting changes before merge. I reviewed the current head (402782f) and found three blockers:

1. BLOCKER [contract-drift] — unbounded grep result (src/utils/page-content.ts:325-356; src/tools/pages.ts:375-400): an allowed regex such as [\s\S]* puts the complete stored page in matches[0].match. context and max_matches do not bound a single match, contradicting the narrowed-read/large-page contract. Use a safe bounded query design: cap each match and aggregate output, return offset/length/truncation metadata for oversize matches, and either constrain regex syntax or use a safe regex engine. Add regression coverage for whole-document and pathological patterns.

2. BLOCKER [correctness] — expected_updated_at is a preflight, not an optimistic lock (src/tools/pages.ts:761-766, 904-909, 1038-1047, followed by an unconditional PUT at 1066): another writer can update after getPage() but before the PUT, and this request overwrites it. Implement an atomic upstream conditional update if BookStack supports one and integration-test the race; otherwise rename/re-document this as best-effort stale detection and remove the no-overwrite guarantee.

3. BLOCKER [correctness] — deletions falsely report verified (src/tools/pages.ts:793-800; src/utils/page-content.ts:275-285): edit verification passes new_string; for deletion it is empty, and containsNormalized(..., "") always returns true. An unchanged reread after a deletion can therefore return verified: true. Model required-present and required-absent expectations separately, then add the unchanged-reread deletion regression.

I ran bun run typecheck plus the two new unit suites (52 passing); their current coverage does not exercise these cases. Please push a focused fix set to this PR, then request re-review.

[pnocera]

Resolved the requested correctness issues on the PR branch and gated the final head.

Validation:

• bun test: 538 passed, 5 configured Docker smoke skips, 0 failed
• bun run typecheck
• Claude implementation review (round 4): GO; durable artifact records its non-blocking residual risks.