Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
devin-ai-integration wants to merge 3 commits into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
011bb5d
feat(cli): add page-actions mcp-auth flag to docs.yml
cadesark Aug 7, 2026
0f7b1ea
chore(cli): regenerate docs-yml json schemas for mcp-auth
cadesark Aug 7, 2026
58f92e5
chore(cli): regenerate fern-yml json schema for mcp-auth
cadesark Aug 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions fern/apis/docs-yml/definition/docs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -462,6 +462,15 @@ types:
discovering the endpoint would cause confusion.

@default: true
mcp-auth:
type: optional<boolean>
docs: |
Opts this docs site into the authenticated MCP endpoint (`/_mcp/authed/server`) and its
OAuth metadata documents, letting MCP clients log in through the site's existing SSO or
password auth and receive results scoped to that user's roles. Only applies to docs sites
that have authentication configured; the public MCP endpoint is unaffected.

@default: false
vscode:
type: optional<boolean>
docs: |
Expand Down
5 changes: 5 additions & 0 deletions packages/cli/cli/changes/unreleased/add-mcp-auth-page-action.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
- summary: |
Add `page-actions.options.mcp-auth` to `docs.yml`, which opts an authenticated docs site into
the authenticated MCP endpoint (`/_mcp/authed/server`) so MCP clients can log in over OAuth
through the site's existing SSO or password auth. Defaults to `false`.
type: feat
1 change: 1 addition & 0 deletions packages/cli/configuration-loader/src/docs-yml/parseDocsConfiguration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -446,6 +446,7 @@ function convertPageActions(
cursor: pageActions.options?.cursor ?? true,
claudeCode: pageActions.options?.claudeCode ?? true,
mcp: pageActions.options?.mcp ?? true,
mcpAuth: pageActions.options?.mcpAuth ?? false,
vscode: pageActions.options?.vscode ?? false,
custom: (pageActions.options?.custom ?? []).map((action) =>
convertCustomPageAction(action, absoluteFilepathToDocsConfig)
Expand Down
1 change: 1 addition & 0 deletions packages/cli/configuration/src/docs-yml/DocsYmlSchemas.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -377,6 +377,7 @@ export const PageActionOptions = z.object({
claude: z.boolean().optional(),
cursor: z.boolean().optional(),
mcp: z.boolean().optional(),
"mcp-auth": z.boolean().optional(),

@devin-ai-integration devin-ai-integration Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔴 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.
Open in Devin Review

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

@devin-ai-integration devin-ai-integration Bot Aug 7, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

vscode: z.boolean().optional(),
custom: z.array(CustomPageAction).optional()
});
Expand Down
1 change: 1 addition & 0 deletions packages/cli/configuration/src/docs-yml/ParsedDocsConfiguration.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ export interface ParsedPageActionsConfig {
claudeCode: boolean;
vscode: boolean;
mcp: boolean;
mcpAuth: boolean;
custom: ParsedCustomPageAction[];
skills: CjsFdrSdk.docs.v1.commons.PageActionOptions["skills"];
};
Expand Down
9 changes: 9 additions & 0 deletions .../cli/configuration/src/docs-yml/schemas/sdk/api/resources/docs/types/PageActionOptions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,15 @@ export interface PageActionOptions {
* @default: true
*/
mcp?: boolean;
/**
* Opts this docs site into the authenticated MCP endpoint (`/_mcp/authed/server`) and its
* OAuth metadata documents, letting MCP clients log in through the site's existing SSO or
* password auth and receive results scoped to that user's roles. Only applies to docs sites
* that have authentication configured; the public MCP endpoint is unaffected.
*
* @default: false
*/
mcpAuth?: boolean;
/**
* When enabled, displays an "Open in VS Code" button that allows users to open the page content in Visual Studio Code for editing and development.
*
Expand Down
2 changes: 2 additions & 0 deletions ...guration/src/docs-yml/schemas/sdk/serialization/resources/docs/types/PageActionOptions.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,7 @@ export const PageActionOptions: core.serialization.ObjectSchema<
claudeCode: core.serialization.property("claude-code", core.serialization.boolean().optional()),
cursor: core.serialization.boolean().optional(),
mcp: core.serialization.boolean().optional(),
mcpAuth: core.serialization.property("mcp-auth", core.serialization.boolean().optional()),
vscode: core.serialization.boolean().optional(),
custom: core.serialization.list(CustomPageAction).optional(),
skills: SkillsPageActionConfig.optional(),
Expand All @@ -33,6 +34,7 @@ export declare namespace PageActionOptions {
"claude-code"?: boolean | null;
cursor?: boolean | null;
mcp?: boolean | null;
"mcp-auth"?: boolean | null;
vscode?: boolean | null;
custom?: CustomPageAction.Raw[] | null;
skills?: SkillsPageActionConfig.Raw | null;
Expand Down
1 change: 1 addition & 0 deletions packages/cli/docs-resolver/src/DocsDefinitionResolver.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2816,6 +2816,7 @@ export class DocsDefinitionResolver {
claudeCode: this.parsedDocsConfig.pageActions.options.claudeCode,
vscode: this.parsedDocsConfig.pageActions.options.vscode,
...(!this.parsedDocsConfig.pageActions.options.mcp ? { mcp: false } : {}),
...(this.parsedDocsConfig.pageActions.options.mcpAuth ? { mcpAuth: true } : {}),

@nitpickybot nitpickybot Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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 nitpickybot Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 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.

custom: this.parsedDocsConfig.pageActions.options.custom.map((customAction) => ({
title: customAction.title,
subtitle: customAction.subtitle,
Expand Down
1 change: 1 addition & 0 deletions packages/cli/docs-resolver/src/__test__/skills-page-action.test.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,7 @@ function makeParsedPageActions(
claudeCode: true,
vscode: false,
mcp: true,
mcpAuth: false,
custom: [],
skills
}
Expand Down
Loading