feat(cli): add page-actions mcp-auth flag to docs.yml

[devin-ai-integration]

Description

Exposes the config flag for authenticated MCP (fern-platform#13712). An SSO/password-protected docs site opts into the authed MCP endpoint (/_mcp/authed/server) and its OAuth metadata documents with:

page-actions:
  options:
    mcp-auth: true

Defaults to false, so nothing changes for existing sites. mcp-auth follows the existing mcp flag's plumbing (docs-yml definition → DocsYmlSchemas raw schema → generated api/serialization types → parseDocsConfiguration → convertPageActions), and the FDR write is conditional (...(mcpAuth ? { mcpAuth: true } : {})) so publishes only carry the field when it's on.

Changes Made

• fern/apis/docs-yml/definition/docs.yml: document mcp-auth on PageActionOptions.
• packages/cli/configuration: raw "mcp-auth" key, generated mcpAuth api type + core.serialization.property("mcp-auth", …), mcpAuth: boolean on ParsedPageActionsConfig.
• packages/cli/configuration-loader: mcpAuth: pageActions.options?.mcpAuth ?? false.
• packages/cli/docs-resolver: write mcpAuth through to FDR.
• Unreleased changelog entry (feat).

Testing

• Unit tests added/updated — existing skills-page-action.test.ts fixture updated; docs-resolver + configuration-loader suites pass (14 files / 107 tests).
• Manual testing completed — end-to-end publish with mcp-auth: true is pending fern-platform#13712 landing, since the authed endpoint only exists there.

Link to Devin session: https://app.devin.ai/sessions/612b7bdf03ae4384be9d05684646b722

---

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[nitpickybot]

AI Review Summary

Straightforward flag plumbing for page-actions.options.mcp-auth through the docs.yml schema, parsed config, and FDR write. Naming and default handling follow the existing mcp conventions. Two things worth verifying: whether the FDR SDK type actually declares mcpAuth yet (the conditional spread will hide a mismatch), and the interaction when mcp: false but mcp-auth: true.

• 🟡 1 warning(s)
• 🔵 1 suggestion(s)

[nitpickybot]

🟡 warning

Spreading a conditional object literal bypasses TypeScript's excess-property checking, so this compiles even if CjsFdrSdk.docs.v1.commons.PageActionOptions doesn't declare mcpAuth yet (the PR notes fern-platform#13712 hasn't landed). Confirm the pinned FDR SDK version actually has the field — otherwise this silently publishes a key the server ignores, and a future rename/typo won't be caught either.

[nitpickybot]

🔵 suggestion

What happens with mcp: false + mcp-auth: true? Today that publishes { mcp: false, mcpAuth: true }, which is contradictory. Either gate mcpAuth on mcp being enabled here, or document that the authed endpoint is independent of the public one.

[devin-ai-integration]

Devin Review found 1 potential issue.

View 1 additional finding in Devin Review.

[devin-ai-integration]

🔴 Docs sites that turn on the new authenticated-MCP setting fail to build

The new mcp-auth setting is accepted by the internal parser ("mcp-auth": z.boolean().optional() at packages/cli/configuration/src/docs-yml/DocsYmlSchemas.ts:380) but was never added to the checked-in validation files the CLI uses first, so any site that sets it is rejected outright.

Impact: Users who add the new option to their docs configuration get a hard "Failed to parse docs.yml" error and cannot build or publish their site at all.

JSON-schema validation runs before parsing and forbids unknown keys

packages/cli/workspace/loader/src/loadDocsWorkspace.ts:81 validates the raw docs.yml against the generated packages/cli/workspace/loader/src/docs-yml.schema.json via validateAgainstJsonSchema and throws a CliError when validation fails (packages/cli/workspace/loader/src/loadDocsWorkspace.ts:110-114).

The docs.PageActionOptions definition in both generated schemas (docs-yml.schema.json:4487 region and the copy under packages/cli/workspace/loader/src/) still lists only copy-page, view-as-markdown, ask-ai, chatgpt, claude, claude-code, cursor, mcp, vscode, custom, skills and ends with "additionalProperties": false. Ajv is compiled with allErrors: true and no removeAdditional, so mcp-auth: true produces an additionalProperties error → Unexpected property 'mcp-auth'.

These two JSON schemas are generated from fern/apis/docs-yml/definition/docs.yml by pnpm docs-yml:jsonschema (see package.json:68), and CI enforces that they are regenerated and committed (.github/workflows/ci.yml:172-180). The previous mcp flag addition included the regenerated schemas; this PR does not.

Prompt for agents

The PR adds the new `mcp-auth` page-action option to the docs-yml Fern definition, the zod raw schema, generated api/serialization types, the parsed config, and the FDR write, but the two checked-in generated JSON schemas were not regenerated: docs-yml.schema.json at the repo root and packages/cli/workspace/loader/src/docs-yml.schema.json. The CLI validates docs.yml against the latter in packages/cli/workspace/loader/src/loadDocsWorkspace.ts before any parsing, and the docs.PageActionOptions definition there has "additionalProperties": false, so a docs.yml containing page-actions.options.mcp-auth is rejected with an 'Unexpected property' parse error, making the feature unusable. CI also enforces that these files match regeneration output (.github/workflows/ci.yml runs `pnpm jsonschema` and fails on any git diff). Fix by running `pnpm docs-yml:jsonschema` and committing the regenerated schema files.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

Confirmed and fixed — docs.PageActionOptions has "additionalProperties": false, so mcp-auth would have been rejected by loadDocsWorkspace's JSON-schema validation before parsing. Ran pnpm docs-yml:jsonschema and committed both regenerated schemas.

[github-actions]

Docs Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-07T04:38:17Z).

Fixture	main	PR	Delta
docs	250.5s (n=5)	222.6s (35 versions)	-27.9s (-11.1%)

Docs generation runs fern generate --docs --preview end-to-end against the benchmark fixture with 35 API versions (each version: markdown processing + OpenAPI-to-IR + FDR upload).
Delta is computed against the nightly baseline on main.
Baseline from nightly run(s) on main (latest: 2026-08-07T04:38:17Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-07 18:52 UTC

[github-actions]

SDK Generation Benchmark Results

Comparing PR branch against median of 5 nightly run(s) on main (latest: 2026-08-07T04:38:17Z).

Full benchmark table (click to expand)

Generator	Spec	main (generator)	main (E2E)	PR (generator)	Delta
csharp-sdk	square	89s (n=5)	N/A	62s	-27s (-30.3%)
go-sdk	square	147s (n=5)	303s (n=5)	126s	-21s (-14.3%)
java-sdk	square	219s (n=5)	273s (n=5)	218s	-1s (-0.5%)
php-sdk	square	81s (n=5)	N/A	45s	-36s (-44.4%)
python-sdk	square	147s (n=5)	263s (n=5)	105s	-42s (-28.6%)
ruby-sdk-v2	square	110s (n=5)	148s (n=5)	89s	-21s (-19.1%)
rust-sdk	square	221s (n=5)	225s (n=5)	214s	-7s (-3.2%)
swift-sdk	square	62s (n=5)	453s (n=5)	45s	-17s (-27.4%)
ts-sdk	square	177s (n=5)	181s (n=5)	96s	-81s (-45.8%)

main (generator): generator-only time via --skip-scripts (includes Docker image build, container startup, IR parsing, and code generation — this is the same Docker-based flow customers use via fern generate). main (E2E): full customer-observable time including build/test scripts (nightly baseline, informational). Delta is computed against generator-only baseline.
⚠️ = generation exited with a non-zero exit code (timing may not reflect a successful run).
Baseline from nightly runs on main (latest: 2026-08-07T04:38:17Z). Trigger benchmark-baseline to refresh.
Last updated: 2026-08-07 18:53 UTC