Split styling into dedicated plugin, fix auth terminology, improve breadcrumbs

Extract CSS cascade fix, breadcrumb labels, and sidebar nav highlighting
from the SEO plugin into a new typedoc-plugin-mcpstyle.mjs to keep
concerns separated.

Fix authorization doc: use "authorization" consistently instead of mixing
with "authentication", link to MCP spec and RFC 9728 for Protected
Resource Metadata, remove redundant spec link paragraph.

Rename "Documents" nav section to "Getting Started" and add explicit
group frontmatter to all doc pages. Breadcrumbs now show the section
name instead of duplicating the page title.

Author: localden

docs/agent-skills.md

@@ -1,5 +1,6 @@
 ---
 title: Agent Skills
+group: Getting Started
 description: Use Agent Skills to build, migrate, and extend MCP Apps with AI coding agents. Install skills that scaffold new apps, convert OpenAI Apps, and add UI to existing servers.
 ---
 

docs/authorization.md

@@ -6,24 +6,20 @@ description: Learn how to protect MCP App tools with OAuth authorization, includ
 
 # Authorization
 
-MCP Apps can protect tools behind OAuth authorization. There are two approaches:
+MCP Apps can protect tools behind OAuth-based authorization, as defined in the [MCP specification](https://modelcontextprotocol.io/specification/latest/basic/authorization). There are two approaches:
 
-- **Per-server authorization** — The entire MCP server requires authentication at connection time. Every request must include a valid token, regardless of which tool is being called. This is the simpler model when all tools are sensitive.
-- **Per-tool authorization** — Only specific tools require authentication. Public tools work without a token, and the OAuth flow is triggered only when the user calls a protected tool. This lets you mix public and protected tools in the same server.
-
-Both approaches use the same underlying mechanism: HTTP `401` responses with [Protected Resource Metadata](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-location). The difference is _when_ the `401` is returned — on every unauthenticated request, or only when a protected tool is called.
-
-For the full protocol specification — including OAuth 2.1 requirements, discovery mechanisms, client registration approaches, token handling, and security considerations — see the [MCP Authorization specification](https://modelcontextprotocol.io/specification/latest/basic/authorization).
+- **Per-server authorization** — The entire MCP server requires authorization at connection time. Every request must include a valid token, regardless of which tool is being called. This is the simpler model when all tools are sensitive.
+- **Per-tool authorization** — Only specific tools require authorization. Public tools work without a token, and the OAuth flow is triggered only when the user calls a protected tool. This lets you mix public and protected tools in the same server.
 
 ## Shared setup
 
 Regardless of which approach you choose, you need OAuth discovery metadata and token verification. These are the same for both.
 
 ### OAuth discovery metadata
 
-The MCP specification requires servers to implement [authorization server discovery](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-discovery) so clients know how to authenticate. Two well-known endpoints are needed:
+The MCP specification requires servers to implement [authorization server discovery](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-discovery) so clients know how to obtain authorization. Two well-known endpoints are needed:
 
-**Protected Resource Metadata** (`/.well-known/oauth-protected-resource`) — tells clients where to find the Authorization Server. The MCP SDK's `mcpAuthRouter` handles this automatically.
+**[Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728)** (`/.well-known/oauth-protected-resource`) — describes the resource server and identifies which authorization server(s) can issue tokens for it. The MCP SDK's `mcpAuthRouter` handles this automatically.
 
 **Authorization Server Metadata** (`/.well-known/oauth-authorization-server`) — advertises the authorization and token endpoints, supported scopes, and whether [Client ID Metadata Documents](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-id-metadata-documents) (CIMD) is supported:
 
@@ -56,13 +52,13 @@ MCP servers must validate that tokens were issued specifically for them — see
 
 ## Per-server authorization
 
-With per-server authorization, every request to the `/mcp` endpoint must include a valid Bearer token. Any unauthenticated request receives HTTP `401`, and the host must complete the OAuth flow before the client can use any tools. This is the right choice when all tools are sensitive and there's no value in allowing unauthenticated access.
+With per-server authorization, every request to the `/mcp` endpoint must include a valid Bearer token. Any unauthorized request receives HTTP `401`, and the host must complete the OAuth flow before the client can use any tools. This is the right choice when all tools are sensitive and there's no value in allowing unauthorized access.
 
 The TypeScript MCP SDK supports this out of the box via `mcpAuthRouter` and `ProxyOAuthServerProvider` — no custom HTTP handler logic is needed. See the [MCP SDK documentation](https://github.com/modelcontextprotocol/typescript-sdk) for setup details.
 
 ## Per-tool authorization
 
-With per-tool authorization, the `/mcp` endpoint handler inspects the raw JSON-RPC request body, checks whether any message targets a protected tool, and only enforces authentication for those calls. Public tools pass through without a token.
+With per-tool authorization, the `/mcp` endpoint handler inspects the raw JSON-RPC request body, checks whether any message targets a protected tool, and only enforces authorization for those calls. Public tools pass through without a token.
 
 ### How it works
 
@@ -146,7 +142,7 @@ The `WWW-Authenticate` header includes the [Protected Resource Metadata](https:/
 
 ### Defence-in-depth in tool handlers
 
-Even though the HTTP layer enforces authorization, protected tool handlers should also verify `authInfo` as a defence-in-depth measure. If the HTTP layer is misconfigured or bypassed, the tool handler catches it:
+Even though the HTTP layer enforces authorization, protected tool handlers should also verify `authInfo` as a defence-in-depth measure. If the HTTP layer is misconfigured or bypassed, the tool handler catches unauthorized access:
 
 ```ts
 registerAppTool(
@@ -163,7 +159,7 @@ registerAppTool(
         content: [
           {
             type: "text",
-            text: "Authentication required to access account data.",
+            text: "Authorization required to access account data.",
           },
         ],
       };
@@ -179,12 +175,12 @@ registerAppTool(
 
 ### UI-initiated auth escalation
 
-A powerful pattern is mixing public and protected tools in the same app. The app loads with public data (no auth required), and authentication is triggered only when the user performs a protected action. This is a practical application of the [step-up authorization flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#step-up-authorization-flow) described in the spec:
+A powerful pattern is mixing public and protected tools in the same app. The app loads with public data (no authorization required), and the OAuth flow is triggered only when the user performs a protected action. This is a practical application of the [step-up authorization flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#step-up-authorization-flow) described in the spec:
 
-1. A public tool (e.g., `manage_branch`) loads the UI with unauthenticated data
+1. A public tool (e.g., `manage_branch`) loads the UI without requiring authorization
 2. The user clicks a button that calls a protected tool via `app.callServerTool()`
 3. The MCP host receives HTTP `401` and automatically runs the OAuth flow
-4. After the user authenticates, the host retries the tool call with the new token
+4. After the user completes the OAuth flow, the host retries the tool call with the acquired token
 5. The protected data appears in the UI
 
 ```tsx
@@ -193,7 +189,7 @@ function BranchItem({ branch }: { branch: Branch }) {
 
   async function handleManage() {
     // This call may trigger the OAuth flow if the user
-    // hasn't authenticated yet — the host handles it
+    // hasn't been authorized yet — the host handles it
     // transparently.
     const result = await app.callServerTool({
       name: "manage_branch_admin",
@@ -212,4 +208,4 @@ function BranchItem({ branch }: { branch: Branch }) {
 }
 ```
 
-This pattern keeps the initial experience fast (no login wall) while securing sensitive operations behind authentication. The host manages the entire OAuth flow — the app code simply calls the tool and handles the result.
+This pattern keeps the initial experience fast (no login wall) while securing sensitive operations behind authorization. The host manages the entire OAuth flow — the app code simply calls the tool and handles the result.

docs/migrate_from_openai_apps.md

@@ -1,5 +1,6 @@
 ---
 title: Migrate OpenAI App
+group: Getting Started
 description: Migrate from the OpenAI Apps SDK to MCP Apps SDK with concept mapping tables, API equivalents, and complete before/after code examples.
 ---
 

docs/overview.md

@@ -1,5 +1,6 @@
 ---
 title: Overview
+group: Getting Started
 description: MCP Apps extends the Model Context Protocol to let MCP servers deliver interactive UIs — charts, forms, dashboards — rendered securely in iframes inside any compliant host.
 ---
 

docs/patterns.md

@@ -1,5 +1,6 @@
 ---
 title: Patterns
+group: Getting Started
 description: Common patterns and recipes for building MCP Apps — polling, chunked data, binary resources, theming, fullscreen, model context, state persistence, and more.
 ---
 

docs/quickstart.md

@@ -1,5 +1,6 @@
 ---
 title: Quickstart
+group: Getting Started
 description: Build your first MCP App step by step — create an MCP server with an interactive View that renders inside Claude Desktop and other MCP hosts.
 ---
 

docs/testing-mcp-apps.md

@@ -1,5 +1,6 @@
 ---
 title: Testing MCP Apps
+group: Getting Started
 description: Test MCP Apps locally with the basic-host reference implementation or in production hosts like Claude.ai and VS Code.
 ---
 

scripts/typedoc-plugin-mcpstyle.mjs

@@ -0,0 +1,53 @@
+/**
+ * TypeDoc plugin that applies MCP-specific styling tweaks.
+ *
+ * - Moves custom.css to load last so overrides win the cascade
+ * - Replaces breadcrumbs with the document group name (e.g. "Security")
+ * - Marks the current sidebar nav link for CSS highlighting
+ */
+
+import { Renderer } from "typedoc";
+
+/**
+ * TypeDoc plugin entry point.
+ * @param {import('typedoc').Application} app
+ */
+export function load(app) {
+  app.renderer.on(Renderer.EVENT_END_PAGE, (page) => {
+    if (!page.contents) return;
+
+    // Move custom.css to load after all theme stylesheets so overrides win the cascade
+    const customCssLink = page.contents.match(
+      /<link rel="stylesheet" href="[^"]*custom\.css"\/>/,
+    );
+    if (customCssLink) {
+      page.contents = page.contents.replace(customCssLink[0], "");
+      page.contents = page.contents.replace(
+        "</head>",
+        customCssLink[0] + "\n</head>",
+      );
+    }
+
+    // For document pages, replace the breadcrumb with the group name
+    // (e.g. "Security", "Getting Started"). The page title is in the H1.
+    if (page.model?.isDocument?.() && page.model.frontmatter?.group) {
+      const group = String(page.model.frontmatter.group);
+      page.contents = page.contents.replace(
+        /<ul class="tsd-breadcrumb"[^>]*>.*?<\/ul>/,
+        `<ul class="tsd-breadcrumb" aria-label="Breadcrumb"><li><span>${group}</span></li></ul>`,
+      );
+    }
+
+    // Inject script to mark the current sidebar nav link with a "current" class.
+    // TypeDoc does not natively add this class for document pages.
+    // The sidebar is populated asynchronously from compressed navigation data,
+    // so we use a MutationObserver to detect when links appear.
+    // Pathname comparison strips trailing slashes and .html extensions to handle
+    // servers with clean-URL mode (e.g. `serve` drops .html).
+    const currentNavScript = `<script>(function(){function norm(s){return s.replace(/\\/$/,"").replace(/\\.html$/,"");}function mark(){var p=norm(location.pathname);var links=document.querySelectorAll(".site-menu .tsd-navigation a[href]");for(var i=0;i<links.length;i++){var h=norm(new URL(links[i].href,location.href).pathname);if(h===p){links[i].classList.add("current");return true;}}return false;}function init(){if(!mark()){var c=document.getElementById("tsd-nav-container");if(c){new MutationObserver(function(m,o){if(mark())o.disconnect();}).observe(c,{childList:true,subtree:true});}}}if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",init);}else{init();}})();</script>`;
+    page.contents = page.contents.replace(
+      "</body>",
+      currentNavScript + "\n</body>",
+    );
+  });
+}

scripts/typedoc-plugin-seo.mjs

@@ -4,6 +4,7 @@
  * - Normalizes document page filenames to lowercase-hyphenated slugs
  * - Injects JSON-LD (TechArticle / WebPage) structured data for search crawlers
  * - Adds per-page meta description tags extracted from page content
+ * - Copies favicons to the output directory
  */
 
 import { Renderer } from "typedoc";
@@ -116,7 +117,7 @@ function buildJsonLd({ title, description, url, isDocument }) {
 export function load(app) {
   const hostedBaseUrl = app.options.getValue("hostedBaseUrl") || "";
 
-  // --- Per-page: inject JSON-LD and meta descriptions ---
+  // --- Per-page: inject JSON-LD, meta descriptions, and favicons ---
   app.renderer.on(Renderer.EVENT_END_PAGE, (page) => {
     if (!page.contents) return;
 
@@ -168,39 +169,15 @@ export function load(app) {
       `<link rel="apple-touch-icon" href="${base}favicons/apple-touch-icon.png" type="image/png" sizes="180x180"/>`,
     ].join("\n");
 
-    // Move custom.css to load after all theme stylesheets so overrides win the cascade
-    const customCssLink = page.contents.match(
-      /<link rel="stylesheet" href="[^"]*custom\.css"\/>/,
-    );
-    if (customCssLink) {
-      page.contents = page.contents.replace(customCssLink[0], "");
-    }
-
-    // Inject favicons, relocated custom CSS, and JSON-LD before </head>
-    const headInjections = [
-      faviconTags,
-      customCssLink ? customCssLink[0] : "",
-      jsonLdScript,
-    ]
+    // Inject favicons and JSON-LD before </head>
+    const headInjections = [faviconTags, jsonLdScript]
       .filter(Boolean)
       .join("\n");
 
     page.contents = page.contents.replace(
       "</head>",
       headInjections + "\n</head>",
     );
-
-    // Inject script to mark the current sidebar nav link with a "current" class.
-    // TypeDoc does not natively add this class for document pages.
-    // The sidebar is populated asynchronously from compressed navigation data,
-    // so we use a MutationObserver to detect when links appear.
-    // Pathname comparison strips trailing slashes and .html extensions to handle
-    // servers with clean-URL mode (e.g. `serve` drops .html).
-    const currentNavScript = `<script>(function(){function norm(s){return s.replace(/\\/$/,"").replace(/\\.html$/,"");}function mark(){var p=norm(location.pathname);var links=document.querySelectorAll(".site-menu .tsd-navigation a[href]");for(var i=0;i<links.length;i++){var h=norm(new URL(links[i].href,location.href).pathname);if(h===p){links[i].classList.add("current");return true;}}return false;}function init(){if(!mark()){var c=document.getElementById("tsd-nav-container");if(c){new MutationObserver(function(m,o){if(mark())o.disconnect();}).observe(c,{childList:true,subtree:true});}}}if(document.readyState==="loading"){document.addEventListener("DOMContentLoaded",init);}else{init();}})();</script>`;
-    page.contents = page.contents.replace(
-      "</body>",
-      currentNavScript + "\n</body>",
-    );
   });
 
   // --- Post-render: copy favicons + rename document slugs ---

typedoc.config.mjs

@@ -35,7 +35,7 @@ const config = {
   },
   includeVersion: false,
   categorizeByGroup: true,
-  groupOrder: ["Documents", "Security", "Modules", "*"],
+  groupOrder: ["Getting Started", "Security", "Modules", "*"],
   navigation: {
     includeGroups: true,
   },
@@ -51,11 +51,13 @@ const config = {
     "typedoc-github-theme",
     "./scripts/typedoc-plugin-fix-mermaid-entities.mjs",
     "./scripts/typedoc-plugin-seo.mjs",
+    "./scripts/typedoc-plugin-mcpstyle.mjs",
     "@boneskull/typedoc-plugin-mermaid",
   ],
   ignoredHighlightLanguages: ["mermaid"],
   locales: {
     en: {
+      kind_plural_document: "Getting Started",
       kind_plural_module: "API Documentation",
     },
   },