Correct six MCP doc errors that disagree with the code #461

Summary

Six fixes correct the MCP docs and context7.json where they disagree with the shipped code. The code is right in each case.

Parent: #230.

Fixes

1. Heading-level rule, half stated.
   • docs/mcp/reference.md:86 says a new heading must be "deeper than the section heading". apps/hocuspocus.server/API.md:1052 says a heading "at or above the target heading's level is refused". Neither names the next-heading limit.
   • The code also refuses a heading shallower than the next heading: apps/hocuspocus.server/src/modules/document-content/domain/sections.ts:59. The tool description (modules/mcp/tools/documentTools.ts:360) and CHANGELOG.md:33-35 already say so.
   • Fix, docs/mcp/reference.md:86: "- A new heading must be deeper than the section heading and no shallower than the next heading, and it can go only at the end of the section. Anywhere else, it would move the blocks after it into a new subsection."
   • Fix, API.md:1052: "- In edit_blocks, a heading at or above the target heading's level is refused, and so is a heading above the next heading's level. Either would move the following subsections under a new parent. A deeper heading may go only at the end of the section; anywhere else it would move the blocks after it into a new subsection."
2. Server instructions, under-described.
   • API.md:1068 says the instructions name only create_document. docs/mcp/reference.md:95 also leaves out read_document.
   • INSTRUCTIONS in modules/mcp/http/serverFactory.ts:12 names create_document, read_document, replace_text and edit_blocks.
   • Fix, API.md:1068: replace "They name create_document for a new document." with "They name create_document for a new document. To change one, they name read_document first, then replace_text and edit_blocks."
   • Fix, docs/mcp/reference.md:95: replace "To change one, they name replace_text and edit_blocks." with "To change one, they name read_document first, then replace_text and edit_blocks."
3. Garbled CHANGELOG list.

   • apps/hocuspocus.server/CHANGELOG.md:36-38 reads "inside one paragraph, never the name of an attached file, list item or table cell". It seems to say replace_text never edits list items or table cells.

   • The code allows both (documentTools.ts:441).

   • Fix: the entry is under [Unreleased], so edit it in place. Lines 36-38 become:

       `replace_text` changes one exact piece of text inside one paragraph, list
       item or table cell, never the name of an attached file, and keeps its
       formatting. Neither touches the
     

4. Wrong confirm label.
   • docs/mcp/README.md:122 says "Choose Disconnect again to confirm".
   • The confirm button reads "Disconnect app" (apps/webapp/src/components/settings/openDisconnectAppConfirm.tsx:12).
   • Fix: "Choose Disconnect app to confirm."
5. ALLOWED_ORIGINS and the MCP Origin gate.
   • apps/hocuspocus.server/ENV.md:60 says "In production, falls back to [APP_URL] when empty. Dev allows any origin." Both hold for CORS only.
   • The fallback applies in every environment (src/config/env.ts:84). The /api/mcp Origin gate uses the list in every environment too (src/index.ts:137, modules/mcp/http/controller.ts:37-44). So a browser-based MCP client gets 403 in dev unless its origin is listed. API.md:1023 is already correct.
   • Fix: the Notes cell becomes "CORS allowlist and the /api/mcp Origin gate list. When empty, it falls back to [APP_URL]. CORS ignores the list in dev and allows any origin. The Origin gate uses it in every environment, dev included."
6. context7.json:44 is out of date.
   • It tells AI assistants: "docs.plus has no AI features, no tracked changes and no page layout. Do not generate examples implying any of them exist." The MCP connector now lets AI apps read and edit documents.
   • Maintainer ruling, 2026-10-07: "docs.plus has no AI model inside the editor, no tracked changes and no page layout. AI apps such as Claude and ChatGPT connect through the docs.plus MCP connector (see docs/mcp). Do not generate examples implying an in-editor AI, tracked changes or page layout."
   • Write the ruled text as two rules items, with the ruled words in the ruled order. Context7 caps each item at 255 characters (AGENTS.md:384), and the ruled text is 261 as one item. A longer item fails the claim.
     • Item 1 (178 characters): "docs.plus has no AI model inside the editor, no tracked changes and no page layout. AI apps such as Claude and ChatGPT connect through the docs.plus MCP connector (see docs/mcp)."
     • Item 2 (82 characters): "Do not generate examples implying an in-editor AI, tracked changes or page layout."

Out of scope

• PUBLIC_RESTAPI_URL and APP_URL for self-hosters: Tell self-hosters to set APP_URL, because email and connected-app links use it #337.
• The Supabase gate wording in docs/mcp/reference.md:26: Confirm the password-token hook is on, and correct the connected-app docs #441.

Acceptance criteria

• docs/mcp/reference.md:86 and API.md:1052 state the next-heading limit.
• docs/mcp/reference.md:95 and API.md:1068 name create_document, read_document, replace_text and edit_blocks.
• The [Unreleased] entry in apps/hocuspocus.server/CHANGELOG.md says replace_text works in a paragraph, list item or table cell.
• docs/mcp/README.md names the confirm button Disconnect app.
• The ALLOWED_ORIGINS row in ENV.md says the [APP_URL] fallback holds everywhere, and the /api/mcp Origin gate uses the list in dev too.
• context7.json carries the ruled text as two rules items, and no rules item is longer than 255 characters.

Verify

• From the repo root, grep -rn "deeper than the section heading,\|Disconnect\*\* again\|Dev allows any origin\|no AI features" docs apps/hocuspocus.server/*.md context7.json prints nothing. On main it prints the four lines that fixes 1, 4, 5 and 6 change.
• bun -e "console.log(Math.max(...require('./context7.json').rules.map(r => r.length)))" prints 255 or less.
• After the merge, the maintainer presses Refresh at https://context7.com/docs-plus/docs.plus. Context7 does not re-crawl on push.