Documentation: bring docs up to date after the endpoint, MCP server and npm publish

[deanleigh]

Documentation to bring up to date after 6-7 Aug 2026

Everything below follows from shipping the create-from-source endpoint, the MCP
server, and npm publication. All docs work happens in .worktrees/docs/,
never the main working directory.

What shipped

	Registry	Version
Umbraco.Community.UpDoc	NuGet	17.5.3.6
@umtemplates/updoc-mcp	npm	0.1.0

Issues closed: #41, #132, #138. Also #134 (Swagger doc), #137 (import facts),
#140, #145, #146, #147.

New pages needed

MCP server reference

Nothing documents it. Should cover: what it is, installing via npx, the two
tools and their arguments, that documents are created as drafts, and that
Umbraco's own tools come from Umbraco's server rather than this one.

Note chaining is off by default (UMBRACO_MCP_CHAIN=true restores it) and why:
a fresh install otherwise hangs while npx downloads mcp-dev, and every Umbraco
tool appears twice for anyone running both servers.

The API

41 endpoints, all now describing their responses. Worth a page covering the
Swagger document at /umbraco/swagger/updoc/swagger.json, that errors are
ProblemDetails (RFC 7807), and create-from-source in particular.

Existing pages to update

• article-mcp-server/index.md — says the tool "is not yet published to
  npm". It is. Also worth adding what the pre-publish dry run caught, since that
  is the most transferable part for another package author.
• usage.md — describes the backoffice flow only. Should mention documents
  can now be created through the API.
• backend/index.md — lists backend files; several are new
  (DocumentCreationService, MappingApplicationService, ValueCoercion,
  MarkdownStripper, SectionLookupBuilder, MediaFilePathResolver,
  MarkdownConversionService, CreateFromSourceController,
  UpDocControllerBase).
• frontend/index.md — create-from-source.ts is new and shared by both
  entry points.
• source-files/ — 54 pages exist. CLAUDE.md requires a page per source
  file, so the new C# and TS files above need one each, plus sidebar entries in
  docs/astro.config.mjs.

Worth recording somewhere

Three things learned that would help another package author, and are not
obvious:

1. The CLI does not validate tool output and calls handlers directly,
   bypassing registerTool. Two list-workflows bugs shipped because --call
   printed fine. Only a real MCP client catches them.
2. yargs is a runtime dependency even though nothing imports it — the SDK
   loads it dynamically for --call and --list-tools. Moving it to
   devDependencies makes both flags silently do nothing.
3. Markdig and marked produce byte-identical HTML for the markdown UpDoc
   generates. Measured, not assumed.

Message for Phil

Short note that it is published, both halves, with the npm link. The article
already covers the reasoning.

[deanleigh]

Done and deployed.

Two new pages

• The UpDoc API — Swagger document, ProblemDetails errors, create-from-source in full
• The MCP server — installing via npx, the two tools, running alongside Umbraco's own server, and why chaining is off

Ten source-file pages, each carrying the reasoning rather than restating the signature:

CreateFromSourceController, UpDocControllerBase, DocumentCreationService, MappingApplicationService, SectionLookupBuilder, ValueCoercion, MarkdownStripper, MarkdownConversionService, MediaFilePathResolver, and create-from-source.ts.

Updated: backend/index.md, frontend/index.md, usage.md (a third option, since creating a document no longer needs the backoffice), and the sidebar.

The three lessons from the issue are recorded where someone would actually meet them: the CLI's blind spot on the MCP page, yargs in the article's dry-run section, and the Markdig measurement on MarkdownConversionService.

111 pages build, no broken links, no local paths.