From 76f2de7b19ba14918e15085fdc3ae150d7c6c87d Mon Sep 17 00:00:00 2001 From: Den Delimarsky <53200638+localden@users.noreply.github.com> Date: Fri, 6 Mar 2026 05:45:15 -0800 Subject: [PATCH] Add Security documentation section and SEO improvements (#524) * Add Security docs section, SEO improvements, and doc site enhancements - Add Authorization guide covering per-server and per-tool OAuth patterns - Add CSP & CORS guide extracted from Patterns doc - Group both under a new Security section in the documentation nav - Replace CSP & CORS section in Patterns with cross-reference to new guide - Rename doc site title from package name to 'MCP Apps' - Rename 'Modules' nav section to 'API Documentation' - Ensure Security section appears before API Documentation in TOC - Add SEO plugin with JSON-LD structured data (TechArticle/WebPage) - Add per-page meta descriptions from frontmatter - Add description frontmatter to all documentation pages - Add hostedBaseUrl for sitemap.xml generation and canonical URLs - Normalize document page slugs to lowercase hyphenated format - Update compressed navigation and search index data to match new slugs * Add favicons with light/dark mode support - Download favicons from modelcontextprotocol.io (light + dark variants) - Inject favicon link tags into every page with correct relative paths - Support prefers-color-scheme media queries for light/dark mode - Include apple-touch-icon for iOS - Copy favicon assets to output directory during doc build * Fix HTML sanitization in SEO plugin with proper parser Replace regex-based HTML tag stripping with htmlparser2 for extracting plain-text descriptions from rendered pages. * Add custom theme to align with modelcontextprotocol.io styling - Import Inter and JetBrains Mono fonts (matching MCP site) - Override light mode colors: pure white backgrounds, softer gray borders - Override dark mode colors: match MCP site dark background (#0f1117) - Taller header (3.5rem) with backdrop-blur frosted glass effect - Sidebar: adjusted spacing, font size, and hover/active states - Content: increased line-height (1.6), more heading breathing room - Code blocks: JetBrains Mono, subtle border, more padding - Fix CSS load order: custom.css now loads after theme stylesheets * Align sidebar nav styling with modelcontextprotocol.io - Active item: tinted blue background with blue text (matching MCP's primary-color tinted active state) - Non-active items: muted gray text, subtle hover background - Larger border-radius (0.75rem/rounded-xl) matching MCP sidebar - Group headers: semibold with slight letter spacing - Proper dark mode variants for all states * Fix sidebar active item: dark gray background with bold text * Make sidebar active item more prominent: bolder weight, stronger background * Highlight current page in sidebar nav, normalize code font size Inject a small script via the SEO plugin that marks the active sidebar link with a "current" class (TypeDoc doesn't do this natively for document pages). Uses a MutationObserver since the sidebar is populated asynchronously. Pathname comparison strips .html extensions to support clean-URL servers. Also bumps code/pre font-size from 0.85em to 1em so code snippets match the surrounding body text size. * 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. --- docs/agent-skills.md | 2 + docs/authorization.md | 211 ++++++++++++++++++ docs/csp-cors.md | 64 ++++++ docs/favicons/apple-touch-icon.png | Bin 0 -> 7947 bytes docs/favicons/favicon-16x16.png | Bin 0 -> 298 bytes docs/favicons/favicon-32x32.png | Bin 0 -> 3669 bytes docs/favicons/favicon-dark-16x16.png | Bin 0 -> 298 bytes docs/favicons/favicon-dark-32x32.png | Bin 0 -> 519 bytes docs/favicons/favicon-dark.ico | Bin 0 -> 5166 bytes docs/favicons/favicon.ico | Bin 0 -> 1275 bytes docs/mcp-theme.css | 189 ++++++++++++++++ docs/migrate_from_openai_apps.md | 2 + docs/overview.md | 2 + docs/patterns.md | 59 +---- docs/quickstart.md | 2 + docs/testing-mcp-apps.md | 2 + scripts/typedoc-plugin-mcpstyle.mjs | 53 +++++ scripts/typedoc-plugin-seo.mjs | 315 +++++++++++++++++++++++++++ typedoc.config.mjs | 16 +- 19 files changed, 860 insertions(+), 57 deletions(-) create mode 100644 docs/authorization.md create mode 100644 docs/csp-cors.md create mode 100644 docs/favicons/apple-touch-icon.png create mode 100644 docs/favicons/favicon-16x16.png create mode 100644 docs/favicons/favicon-32x32.png create mode 100644 docs/favicons/favicon-dark-16x16.png create mode 100644 docs/favicons/favicon-dark-32x32.png create mode 100644 docs/favicons/favicon-dark.ico create mode 100644 docs/favicons/favicon.ico create mode 100644 docs/mcp-theme.css create mode 100644 scripts/typedoc-plugin-mcpstyle.mjs create mode 100644 scripts/typedoc-plugin-seo.mjs diff --git a/docs/agent-skills.md b/docs/agent-skills.md index 36e1f98..d27ad71 100644 --- a/docs/agent-skills.md +++ b/docs/agent-skills.md @@ -1,5 +1,7 @@ --- 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. --- # Agent Skills diff --git a/docs/authorization.md b/docs/authorization.md new file mode 100644 index 0000000..59fc26c --- /dev/null +++ b/docs/authorization.md @@ -0,0 +1,211 @@ +--- +title: Authorization +group: Security +description: Learn how to protect MCP App tools with OAuth authorization, including per-server and per-tool auth patterns, token verification, and UI-initiated auth escalation. +--- + +# Authorization + +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 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 obtain authorization. Two well-known endpoints are needed: + +**[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: + +```ts +app.get("/.well-known/oauth-authorization-server", (_req, res) => { + res.json({ + ...oauthMetadata, + client_id_metadata_document_supported: true, + }); +}); +``` + +Setting `client_id_metadata_document_supported: true` tells MCP clients to use CIMD instead of [Dynamic Client Registration](https://modelcontextprotocol.io/specification/latest/basic/authorization#dynamic-client-registration) (DCR). With CIMD, the `client_id` is a URL that serves the client's metadata document, removing the need for a registration endpoint. See [Client Registration Approaches](https://modelcontextprotocol.io/specification/latest/basic/authorization#client-registration-approaches) in the spec for the full list of options and priority order. + +### Token verification + +Verify access tokens as JWTs against the identity provider's JWKS endpoint. The `jose` library handles key fetching and caching: + +```ts +import { createRemoteJWKSet, jwtVerify } from "jose"; + +const JWKS = createRemoteJWKSet(new URL(`${IDP_DOMAIN}/.well-known/jwks.json`)); + +const { payload } = await jwtVerify(token, JWKS, { + issuer: IDP_DOMAIN, +}); +``` + +MCP servers must validate that tokens were issued specifically for them — see [Token Handling](https://modelcontextprotocol.io/specification/latest/basic/authorization#token-handling) and [Access Token Privilege Restriction](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-privilege-restriction) in the spec for the full requirements. + +## Per-server authorization + +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 authorization for those calls. Public tools pass through without a token. + +### How it works + +1. The server maintains a set of tool names that require authorization +2. When a JSON-RPC request arrives at the `/mcp` endpoint, the server inspects the request body to determine if any message is a `tools/call` targeting a protected tool +3. If a protected tool is being called and no valid Bearer token is present, the server returns HTTP `401` with a [`WWW-Authenticate` header](https://modelcontextprotocol.io/specification/latest/basic/authorization#protected-resource-metadata-discovery-requirements) pointing to its [Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) +4. The MCP host (e.g., Claude Desktop) sees the `401`, discovers the authorization server via the metadata URL, runs the [OAuth flow](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-flow-steps) with the user, and retries the request with the acquired token +5. On retry, the server verifies the token, extracts the user identity, and creates a per-request MCP server instance with that auth context +6. Unprotected tools pass through without any token check — they work for everyone + +This design means authorization is enforced at the HTTP boundary (as [required by the spec](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage)), not as a tool-level error. The MCP server itself never sees unauthorized requests for protected tools. + +### Enforcing HTTP 401 + +The [MCP auth specification](https://modelcontextprotocol.io/specification/latest/basic/authorization#access-token-usage) requires protected resources to return HTTP `401` responses — not tool-level errors. + +Start by defining which tools require authorization. Then, in the `/mcp` endpoint handler, inspect the raw JSON-RPC request body, check whether any message targets a protected tool, and either verify the Bearer token or return `401` before the request ever reaches the MCP server: + +```ts +/** Tools that require a valid Bearer token — checked at the HTTP level for proper 401. */ +const PROTECTED_TOOLS = new Set(["get_account_balance", "manage_branch_admin"]); + +app.all("/mcp", async (req, res) => { + // Parse the JSON-RPC body — it may be a single message or a batch + const messages = Array.isArray(req.body) ? req.body : [req.body]; + + // Check if any message is a tools/call for a protected tool + const needsAuth = messages.some( + (msg: any) => + msg?.method === "tools/call" && PROTECTED_TOOLS.has(msg.params?.name), + ); + + // Extract and verify the Bearer token + let authInfo: AuthInfo | undefined; + const authHeader = req.headers.authorization; + + if (authHeader?.startsWith("Bearer ")) { + try { + const token = authHeader.slice(7); + const { payload } = await jwtVerify(token, JWKS, { + issuer: IDP_DOMAIN, + }); + authInfo = { token, sub: payload.sub as string }; + } catch { + if (needsAuth) { + return res + .status(401) + .set( + "WWW-Authenticate", + `Bearer resource_metadata="${resourceMetadataUrl}"`, + ) + .json({ + error: "invalid_token", + error_description: "The access token is invalid", + }); + } + } + } else if (needsAuth) { + return res + .status(401) + .set( + "WWW-Authenticate", + `Bearer resource_metadata="${resourceMetadataUrl}"`, + ) + .json({ + error: "invalid_token", + error_description: "Authorization required", + }); + } + + // Create a per-request MCP server with the auth context. + // authInfo is undefined for public tool calls, populated for + // authenticated requests — tool handlers use it to scope data + // to the authenticated user. + const server = createServer(authInfo); + // ... handle the request with transport +}); +``` + +The `WWW-Authenticate` header includes the [Protected Resource Metadata](https://modelcontextprotocol.io/specification/latest/basic/authorization#authorization-server-location) URL, which tells the client where to discover the authorization server. + +### 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 unauthorized access: + +```ts +registerAppTool( + server, + "get_account_balance", + { + description: "Get account balance", + inputSchema: { accountId: z.string() }, + }, + async ({ accountId }) => { + if (!authInfo) { + return { + isError: true, + content: [ + { + type: "text", + text: "Authorization required to access account data.", + }, + ], + }; + } + + const balance = await getBalance(authInfo.sub, accountId); + return { + content: [{ type: "text", text: `Balance: ${balance}` }], + }; + }, +); +``` + +### UI-initiated auth escalation + +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 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 completes the OAuth flow, the host retries the tool call with the acquired token +5. The protected data appears in the UI + +```tsx +function BranchItem({ branch }: { branch: Branch }) { + const [adminData, setAdminData] = useState(null); + + async function handleManage() { + // This call may trigger the OAuth flow if the user + // hasn't been authorized yet — the host handles it + // transparently. + const result = await app.callServerTool({ + name: "manage_branch_admin", + arguments: { branch_id: branch.id }, + }); + setAdminData(result.structuredContent); + } + + return ( +
+ {branch.name} + + {adminData && } +
+ ); +} +``` + +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. diff --git a/docs/csp-cors.md b/docs/csp-cors.md new file mode 100644 index 0000000..8978ab6 --- /dev/null +++ b/docs/csp-cors.md @@ -0,0 +1,64 @@ +--- +title: CSP and CORS +group: Security +description: Configure Content Security Policy and CORS for MCP Apps that make network requests from sandboxed iframes, including connectDomains, resourceDomains, and stable origin setup. +--- + +# CSP & CORS + +Unlike regular web apps, MCP Apps HTML is served as an MCP resource and runs in a sandboxed iframe with no same-origin server. Any app that makes network requests must configure Content Security Policy (CSP) and possibly CORS. + +**CSP** controls what the _browser_ allows. You must declare _all_ origins in {@link types!McpUiResourceMeta.csp `_meta.ui.csp`} ({@link types!McpUiResourceCsp `McpUiResourceCsp`}) — including `localhost` during development. Declare `connectDomains` for fetch/XHR/WebSocket requests and `resourceDomains` for scripts, stylesheets, images, and fonts. + +**CORS** controls what the _API server_ allows. Public APIs that respond with `Access-Control-Allow-Origin: *` or use API key authentication work without CORS configuration. For APIs that allowlist specific origins, use {@link types!McpUiResourceMeta.domain `_meta.ui.domain`} to give the app a stable origin that the API server can allowlist. The format is host-specific, so check each host's documentation for its supported format. + + +```ts source="../src/server/index.examples.ts#registerAppResource_withDomain" +// Computes a stable origin from an MCP server URL for hosting in Claude. +function computeAppDomainForClaude(mcpServerUrl: string): string { + const hash = crypto + .createHash("sha256") + .update(mcpServerUrl) + .digest("hex") + .slice(0, 32); + return `${hash}.claudemcpcontent.com`; +} + +const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp"); + +registerAppResource( + server, + "Company Dashboard", + "ui://dashboard/view.html", + { + description: "Internal dashboard with company data", + }, + async () => ({ + contents: [ + { + uri: "ui://dashboard/view.html", + mimeType: RESOURCE_MIME_TYPE, + text: dashboardHtml, + _meta: { + ui: { + // CSP: tell browser the app is allowed to make requests + csp: { + connectDomains: ["https://api.example.com"], + }, + // CORS: give app a stable origin for the API server to allowlist + // + // (Public APIs that use `Access-Control-Allow-Origin: *` or API + // key auth don't need this.) + domain: APP_DOMAIN, + }, + }, + }, + ], + }), +); +``` + +Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object. + +> [!NOTE] +> For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`). diff --git a/docs/favicons/apple-touch-icon.png b/docs/favicons/apple-touch-icon.png new file mode 100644 index 0000000000000000000000000000000000000000..2e10abc75b80580abe01aa38757747cc4e7a00e9 GIT binary patch literal 7947 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 literal 0 HcmV?d00001 diff --git a/docs/favicons/favicon-32x32.png b/docs/favicons/favicon-32x32.png new file mode 100644 index 0000000000000000000000000000000000000000..88f78f67cb3f42b3f781a972900d790e864db634 GIT binary patch literal 3669 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 literal 0 HcmV?d00001 diff --git a/docs/favicons/favicon-dark-32x32.png b/docs/favicons/favicon-dark-32x32.png new file mode 100644 index 0000000000000000000000000000000000000000..b861b127be45326f465905220ccc5862fee38e63 GIT binary patch literal 519 zcmV+i0{H!jP)kdg00001b5ch_0Itp) z=>Px$!AV3xRCwBz)xU2|VI0Tt&qbmUB51J~OvF|aKL)WN#BO6iVldcIq=la25%rQmHBRyxGv3sW!8#VZpM`LtscI? zcle4vOG=-y8?VGU<-0#@@IqiShQ%o}?w5HvQ1co4MamCf6^OH#a>-$*y)W}}pynn3 zUYB?|5V6x`{cbyI>0(@>VhX&CKzH+-Z$B_t%@+@h;D9L4l1Rn%AW47rl{ZNBU$N#6 ze%M~xF_zS0@x+PJdQZ}o(WsuT(#lBIB}r%M8H+Y&EInD5`~^_Yri|*+5|jV{002ov JPDHLkV1n(H>azd< literal 0 HcmV?d00001 diff --git a/docs/favicons/favicon-dark.ico b/docs/favicons/favicon-dark.ico new file mode 100644 index 0000000000000000000000000000000000000000..fd1f24d2a262983d60bccd025c547f46b1dd6ca1 GIT binary patch literal 5166 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 Km!l*!-~TTe3wa;_ literal 0 HcmV?d00001 diff --git a/docs/favicons/favicon.ico b/docs/favicons/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..b92e162a311e3dffc3e6b667e85308241af92890 GIT binary patch literal 1275 zcmex=DK+5#0R}-11_uTQW=16jCP7AK zLB{__7;+gHn3$MBPK5&wRyHPPc19Kf21aIPCKgr}pgdTTnURTwft8J2P}tBZkV8n( z$WcTou~1Z5ta0K(6cfOz1(D4Ji~PUEzymajNsw8P!Jffq#iA~zbu+>^CqDn47WJm! zLW_&L#QD&ShI4UAR@)OIM85~TU%2I#^UX^sJH=aN;`M7yZ_`eGn>$fb{w6FWAzkarV!ELiSH{w@GwW@lSTB&q2ncoYu zxVQ5BU4^Nf$s3>iQ!1)|{{D}L#T+4R2e$S5ceLIOUo%BAGH0iI$C-us-~Z|8_z8+G zV6OVz5qq`jez?!>X#d1rE{DGCmt#G1;pTxj36H|ft!EMvLd|b2ER_y?awp~3rMJ30 zbN2NtYkzUg(6UAQL+3TGX~Kr~yb-ge{*j)RSSbEG{`zT#Q@lT>#iw6iUHhKr%p0B7 znlAIbU23Z|u8K-5k+Lu6eOzvK$+mjS$&GP(+h#`Bx=6b9#O|zYdYW{(f8mX<*KFSO zhZTKZVsN^rXyeo0HZQ^zIqDDFnx$&|EPefFvgV2PzDXM=zY|i~xcbtiy)m7RF|HvY zAyE?=0_xQ{HkVh}Ey=U{w`$F2rCp0xEGXaO(_VdT_L&_EJG&L9Zki%LeQW%t<-x6Q zR@}KBI$4c%z5kX;k|IVf4Z#h5Y=?ddT>PyqH8($Mb%NB-yw*N;;qyA(Wm|eX6lO{s zwq&{Iqj37g-&J?smR#!55?OknVD38itmUE)G9-U|-d|d^l;y$k&Wh|KJ6aybZ2CQ6 z|NGZZ8&X3|Ui&?JE}Z%*Z<&|N)T7Dj3cl8yLkK3t?zzYUX>M^#Vvc4vcx+| z{YppBzGE}jyspo9`!YA6bav#D=byqZW`w&Pdu*M^ePh$qIUO!<=ISmu9%(u$tXlP2 zxAS~ynVz?8_F1RGiWKcRFPwTH66g@ h3 { + font-weight: 600; + font-size: 0.875rem; + letter-spacing: 0.01em; +} + +.site-menu { + padding: 1.25rem 0; +} + +@media (prefers-color-scheme: dark) { + .tsd-navigation a { + color: var(--color-text-aside); + } + + .tsd-navigation a:hover:not(.current) { + background-color: rgba(229, 231, 235, 0.05); + color: var(--color-text); + } + + .tsd-navigation a.current { + background-color: rgba(229, 231, 235, 0.15); + color: var(--color-text); + font-weight: 700; + } +} + +:root[data-theme='dark'] .tsd-navigation a { + color: var(--color-text-aside); +} + +:root[data-theme='dark'] .tsd-navigation a:hover:not(.current) { + background-color: rgba(229, 231, 235, 0.05); + color: var(--color-text); +} + +:root[data-theme='dark'] .tsd-navigation a.current { + background-color: rgba(229, 231, 235, 0.15); + color: var(--color-text); + font-weight: 700; +} + +/* ------------------------------------------------------------------ */ +/* Content area */ +/* ------------------------------------------------------------------ */ + +.tsd-typography { + line-height: 1.6; +} + +.tsd-panel.tsd-typography h1 { + margin-top: 0; + padding-bottom: 0.4em; +} + +.tsd-panel.tsd-typography h2 { + margin-top: 2rem; + padding-bottom: 0.3em; +} + +.tsd-panel.tsd-typography h3 { + margin-top: 1.75rem; +} + +/* ------------------------------------------------------------------ */ +/* Code blocks */ +/* ------------------------------------------------------------------ */ + +code, +pre { + font-family: var(--font-family-code); + font-size: 1em; +} + +.tsd-typography pre { + padding: 1rem 1.25rem; + border: 1px solid var(--color-accent); +} + +/* Inline code */ +.tsd-typography code:not(pre code) { + padding: 0.15em 0.35em; + font-size: 1em; +} diff --git a/docs/migrate_from_openai_apps.md b/docs/migrate_from_openai_apps.md index 6f5a1c3..d91281b 100644 --- a/docs/migrate_from_openai_apps.md +++ b/docs/migrate_from_openai_apps.md @@ -1,5 +1,7 @@ --- 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. --- # Migrating from OpenAI Apps SDK to MCP Apps SDK diff --git a/docs/overview.md b/docs/overview.md index 4de6a68..28f5b23 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -1,5 +1,7 @@ --- 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. --- # MCP Apps Overview diff --git a/docs/patterns.md b/docs/patterns.md index 3a6302c..87a6d82 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -1,5 +1,7 @@ --- 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. --- # MCP Apps Patterns @@ -298,62 +300,7 @@ videoEl.src = `data:${content.mimeType!};base64,${content.blob}`; ## Configuring CSP and CORS -Unlike regular web apps, MCP Apps HTML is served as an MCP resource and runs in a sandboxed iframe with no same-origin server. Any app that makes network requests must configure Content Security Policy (CSP) and possibly CORS. - -**CSP** controls what the _browser_ allows. You must declare _all_ origins in {@link types!McpUiResourceMeta.csp `_meta.ui.csp`} ({@link types!McpUiResourceCsp `McpUiResourceCsp`}) — including `localhost` during development. Declare `connectDomains` for fetch/XHR/WebSocket requests and `resourceDomains` for scripts, stylesheets, images, and fonts. - -**CORS** controls what the _API server_ allows. Public APIs that respond with `Access-Control-Allow-Origin: *` or use API key authentication work without CORS configuration. For APIs that allowlist specific origins, use {@link types!McpUiResourceMeta.domain `_meta.ui.domain`} to give the app a stable origin that the API server can allowlist. The format is host-specific, so check each host's documentation for its supported format. - - -```ts source="../src/server/index.examples.ts#registerAppResource_withDomain" -// Computes a stable origin from an MCP server URL for hosting in Claude. -function computeAppDomainForClaude(mcpServerUrl: string): string { - const hash = crypto - .createHash("sha256") - .update(mcpServerUrl) - .digest("hex") - .slice(0, 32); - return `${hash}.claudemcpcontent.com`; -} - -const APP_DOMAIN = computeAppDomainForClaude("https://example.com/mcp"); - -registerAppResource( - server, - "Company Dashboard", - "ui://dashboard/view.html", - { - description: "Internal dashboard with company data", - }, - async () => ({ - contents: [ - { - uri: "ui://dashboard/view.html", - mimeType: RESOURCE_MIME_TYPE, - text: dashboardHtml, - _meta: { - ui: { - // CSP: tell browser the app is allowed to make requests - csp: { - connectDomains: ["https://api.example.com"], - }, - // CORS: give app a stable origin for the API server to allowlist - // - // (Public APIs that use `Access-Control-Allow-Origin: *` or API - // key auth don't need this.) - domain: APP_DOMAIN, - }, - }, - }, - ], - }), -); -``` - -Note that `_meta.ui.csp` and `_meta.ui.domain` are set in the `contents[]` objects returned by the resource read callback, not in `registerAppResource()`'s config object. - -> [!NOTE] -> For full examples that configures CSP, see: [`examples/sheet-music-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/sheet-music-server) (`connectDomains`) and [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/map-server) (`connectDomains` and `resourceDomains`). +See the dedicated [CSP & CORS](./csp-cors.md) guide in the Security section. ## Adapting to host context (theme, styling, fonts, and safe areas) diff --git a/docs/quickstart.md b/docs/quickstart.md index c850f8c..2714d4e 100644 --- a/docs/quickstart.md +++ b/docs/quickstart.md @@ -1,5 +1,7 @@ --- 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. --- # Build Your First MCP App diff --git a/docs/testing-mcp-apps.md b/docs/testing-mcp-apps.md index 6bef13e..df1396c 100644 --- a/docs/testing-mcp-apps.md +++ b/docs/testing-mcp-apps.md @@ -1,5 +1,7 @@ --- 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. --- # Test Your MCP App diff --git a/scripts/typedoc-plugin-mcpstyle.mjs b/scripts/typedoc-plugin-mcpstyle.mjs new file mode 100644 index 0000000..bcd40f7 --- /dev/null +++ b/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( + //, + ); + if (customCssLink) { + page.contents = page.contents.replace(customCssLink[0], ""); + page.contents = page.contents.replace( + "", + customCssLink[0] + "\n", + ); + } + + // 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>/, + `
    • ${group}
    `, + ); + } + + // 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 = ``; + page.contents = page.contents.replace( + "", + currentNavScript + "\n", + ); + }); +} diff --git a/scripts/typedoc-plugin-seo.mjs b/scripts/typedoc-plugin-seo.mjs new file mode 100644 index 0000000..11677e6 --- /dev/null +++ b/scripts/typedoc-plugin-seo.mjs @@ -0,0 +1,315 @@ +/** + * TypeDoc plugin that adds SEO metadata to generated pages. + * + * - 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"; +import fs from "node:fs"; +import path from "node:path"; +import zlib from "node:zlib"; +import * as htmlparser2 from "htmlparser2"; + +const SITE_NAME = "MCP Apps"; + +/** + * Convert a TypeDoc-generated document filename to a lowercase hyphenated slug. + * e.g. "CSP_and_CORS.html" → "csp-and-cors.html" + * "Testing_MCP_Apps.html" → "testing-mcp-apps.html" + * @param {string} filename + * @returns {string} + */ +function toSlug(filename) { + return filename + .replace(/\.html$/, "") + .replace(/_/g, "-") + .toLowerCase() + .concat(".html"); +} + +/** + * Extract a plain-text description from the rendered HTML body. + * Parses the first content paragraph using htmlparser2 and truncates. + * @param {string} html + * @returns {string} + */ +function extractDescription(html) { + // Find the main content area + const contentMatch = html.match( + /
    ([\s\S]*?)<\/div>\s*<\/div>/, + ); + if (!contentMatch) return ""; + + const content = contentMatch[1]; + + // Find first

    that has real content (skip headings, code blocks, lists) + const paragraphs = content.match(/

    ([^<][\s\S]*?)<\/p>/g); + if (!paragraphs) return ""; + + for (const p of paragraphs) { + const text = htmlparser2 + .parseDocument(p) + .children.map((node) => htmlparser2.DomUtils.textContent(node)) + .join("") + .replace(/\s+/g, " ") + .trim(); + + // Skip very short or code-heavy paragraphs + if (text.length > 40) { + return text.length > 160 ? text.slice(0, 157) + "..." : text; + } + } + + return ""; +} + +/** + * Extract the page title from the tag. + * @param {string} html + * @returns {string} + */ +function extractTitle(html) { + const match = html.match(/<title>([^<]+)<\/title>/); + return match ? match[1] : SITE_NAME; +} + +/** + * Determine if a page is a document (guide) or API reference page. + * @param {string} url + * @returns {boolean} + */ +function isDocumentPage(url) { + return url.includes("documents/"); +} + +/** + * Build a JSON-LD structured data object for the page. + * @param {object} options + * @param {string} options.title + * @param {string} options.description + * @param {string} options.url + * @param {boolean} options.isDocument + * @returns {object} + */ +function buildJsonLd({ title, description, url, isDocument }) { + return { + "@context": "https://schema.org", + "@type": isDocument ? "TechArticle" : "WebPage", + name: title, + headline: title, + ...(description && { description }), + ...(url && { url }), + isPartOf: { + "@type": "WebSite", + name: SITE_NAME, + url: "https://apps.extensions.modelcontextprotocol.io/", + }, + }; +} + +/** + * TypeDoc plugin entry point. + * @param {import('typedoc').Application} app + */ +export function load(app) { + const hostedBaseUrl = app.options.getValue("hostedBaseUrl") || ""; + + // --- Per-page: inject JSON-LD, meta descriptions, and favicons --- + app.renderer.on(Renderer.EVENT_END_PAGE, (page) => { + if (!page.contents) return; + + const title = extractTitle(page.contents); + + // Prefer frontmatter description, fall back to auto-extraction + const frontmatterDesc = + page.model?.isDocument?.() && page.model.frontmatter?.description + ? String(page.model.frontmatter.description) + : ""; + const description = frontmatterDesc || extractDescription(page.contents); + const fullUrl = hostedBaseUrl + ? `${hostedBaseUrl.replace(/\/$/, "")}/${page.url}` + : ""; + + // Build JSON-LD + const jsonLd = buildJsonLd({ + title, + description, + url: fullUrl, + isDocument: isDocumentPage(page.url), + }); + + const jsonLdScript = `<script type="application/ld+json">${JSON.stringify(jsonLd)}</script>`; + + // Build meta description tag (replace the generic one if present) + const metaDescription = description + ? `<meta name="description" content="${description.replace(/"/g, """)}"/>` + : ""; + + // Replace existing generic meta description + if (metaDescription) { + page.contents = page.contents.replace( + /<meta name="description" content="Documentation for [^"]*"\/>/, + metaDescription, + ); + } + + // Build favicon tags with correct relative path + const depth = page.url.split("/").length - 1; + const base = depth > 0 ? "../".repeat(depth) : "./"; + const faviconTags = [ + `<link rel="icon" href="${base}favicons/favicon-32x32.png" type="image/png" sizes="32x32" media="(prefers-color-scheme: light)"/>`, + `<link rel="icon" href="${base}favicons/favicon-16x16.png" type="image/png" sizes="16x16" media="(prefers-color-scheme: light)"/>`, + `<link rel="shortcut icon" href="${base}favicons/favicon.ico" type="image/x-icon" media="(prefers-color-scheme: light)"/>`, + `<link rel="icon" href="${base}favicons/favicon-dark-32x32.png" type="image/png" sizes="32x32" media="(prefers-color-scheme: dark)"/>`, + `<link rel="icon" href="${base}favicons/favicon-dark-16x16.png" type="image/png" sizes="16x16" media="(prefers-color-scheme: dark)"/>`, + `<link rel="shortcut icon" href="${base}favicons/favicon-dark.ico" type="image/x-icon" media="(prefers-color-scheme: dark)"/>`, + `<link rel="apple-touch-icon" href="${base}favicons/apple-touch-icon.png" type="image/png" sizes="180x180"/>`, + ].join("\n"); + + // Inject favicons and JSON-LD before </head> + const headInjections = [faviconTags, jsonLdScript] + .filter(Boolean) + .join("\n"); + + page.contents = page.contents.replace( + "</head>", + headInjections + "\n</head>", + ); + }); + + // --- Post-render: copy favicons + rename document slugs --- + app.renderer.on(Renderer.EVENT_END, (event) => { + const outDir = event.outputDirectory; + + // Copy favicons to output directory + const srcFavicons = path.join(path.dirname(outDir), "favicons"); + const destFavicons = path.join(outDir, "favicons"); + if (fs.existsSync(srcFavicons)) { + if (!fs.existsSync(destFavicons)) fs.mkdirSync(destFavicons); + for (const file of fs.readdirSync(srcFavicons)) { + fs.copyFileSync( + path.join(srcFavicons, file), + path.join(destFavicons, file), + ); + } + } + + const docsDir = path.join(outDir, "documents"); + + if (!fs.existsSync(docsDir)) return; + + // Build rename map: old filename → new slug + const renameMap = new Map(); + for (const file of fs.readdirSync(docsDir)) { + if (!file.endsWith(".html")) continue; + const slug = toSlug(file); + if (slug !== file) { + renameMap.set(file, slug); + } + } + + if (renameMap.size === 0) return; + + // Rename the files + for (const [oldName, newName] of renameMap) { + fs.renameSync(path.join(docsDir, oldName), path.join(docsDir, newName)); + } + + // Build link replacement patterns (documents/OldName.html → documents/new-name.html) + const replacements = [...renameMap.entries()].map(([oldName, newName]) => ({ + old: `documents/${oldName}`, + new: `documents/${newName}`, + })); + + // Update all HTML files in the output directory + updateLinksRecursive(outDir, replacements); + + // Update compressed JS data files (navigation + search index) + updateCompressedJsData( + path.join(outDir, "assets", "navigation.js"), + "navigationData", + replacements, + ); + updateCompressedJsData( + path.join(outDir, "assets", "search.js"), + "searchData", + replacements, + ); + + // Update sitemap.xml + const sitemapPath = path.join(outDir, "sitemap.xml"); + if (fs.existsSync(sitemapPath)) { + let sitemap = fs.readFileSync(sitemapPath, "utf8"); + for (const r of replacements) { + sitemap = sitemap.replaceAll(r.old, r.new); + } + fs.writeFileSync(sitemapPath, sitemap); + } + }); +} + +/** + * Decompress a TypeDoc JS data file, replace document slugs, and recompress. + * TypeDoc stores navigation and search data as deflate-compressed base64. + * @param {string} filePath + * @param {string} varName - JS variable name (e.g. "navigationData", "searchData") + * @param {Array<{old: string, new: string}>} replacements + */ +function updateCompressedJsData(filePath, varName, replacements) { + if (!fs.existsSync(filePath)) return; + + let content = fs.readFileSync(filePath, "utf8"); + const pattern = new RegExp(`window\\.${varName} = "(.+)"`); + const match = content.match(pattern); + if (!match) return; + + // Decompress + const buf = Buffer.from(match[1], "base64"); + let json = zlib.inflateSync(buf).toString(); + + // Replace slugs + let changed = false; + for (const r of replacements) { + if (json.includes(r.old)) { + json = json.replaceAll(r.old, r.new); + changed = true; + } + } + + if (!changed) return; + + // Recompress and write + const compressed = zlib.deflateSync(json); + const encoded = compressed.toString("base64"); + content = content.replace(pattern, `window.${varName} = "${encoded}"`); + fs.writeFileSync(filePath, content); +} + +/** + * Recursively update links in all HTML files under a directory. + * @param {string} dir + * @param {Array<{old: string, new: string}>} replacements + */ +function updateLinksRecursive(dir, replacements) { + for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { + const fullPath = path.join(dir, entry.name); + if (entry.isDirectory()) { + updateLinksRecursive(fullPath, replacements); + } else if (entry.name.endsWith(".html") || entry.name.endsWith(".js")) { + let content = fs.readFileSync(fullPath, "utf8"); + let changed = false; + for (const r of replacements) { + if (content.includes(r.old)) { + content = content.replaceAll(r.old, r.new); + changed = true; + } + } + if (changed) { + fs.writeFileSync(fullPath, content); + } + } + } +} diff --git a/typedoc.config.mjs b/typedoc.config.mjs index e71dc29..a97bb29 100644 --- a/typedoc.config.mjs +++ b/typedoc.config.mjs @@ -2,6 +2,7 @@ import { OptionDefaults } from "typedoc"; /** @type {Partial<import('typedoc').TypeDocOptions>} */ const config = { + name: "MCP Apps", readme: "README.md", headings: { readme: false, @@ -13,6 +14,8 @@ const config = { "docs/agent-skills.md", "docs/testing-mcp-apps.md", "docs/patterns.md", + "docs/authorization.md", + "docs/csp-cors.md", "docs/migrate_from_openai_apps.md", ], entryPoints: [ @@ -30,8 +33,9 @@ const config = { jsDocCompatibility: { exampleTag: false, }, - includeVersion: true, + includeVersion: false, categorizeByGroup: true, + groupOrder: ["Getting Started", "Security", "Modules", "*"], navigation: { includeGroups: true, }, @@ -40,13 +44,23 @@ const config = { Specification: "https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx", }, + hostedBaseUrl: "https://apps.extensions.modelcontextprotocol.io/api/", + customCss: "./docs/mcp-theme.css", out: "docs/api", plugin: [ "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", + }, + }, }; export default config;