Authenticated MCP access for unpublished GitBook spaces (drafts & change requests) + write operations

[BenWehrbeinGK]

Feature Request: Authenticated MCP access for unpublished GitBook spaces (drafts & change requests) + write operations

Summary

Enable a secure, authenticated Model Context Protocol (MCP) capability for private/unpublished GitBook spaces and content, with read access to drafts and change requests, and write operations to (a) generate new change requests, and (b) (low priority) create new spaces. This unlocks AI‑assisted authoring, review automations, and agent workflows before publication, while preserving GitBook’s governance and privacy controls.

Problem

GitBook’s current MCP servers expose read‑only access to published sites. Teams increasingly run AI agents (Copilot/Claude/IDE MCP clients) during pre‑publish phases—editing, reviewing, and staging content. Without an authenticated MCP path to unpublished content:

• Agents cannot reason over draft pages, open change requests, or review pre‑merge diffs.
• Automated authoring pipelines must fall back to bespoke API calls, fragmenting tooling and losing MCP’s standardization.
• Review workflows remain manual and slower, despite existing API coverage.

Proposal

Introduce an Org/Site/Space‑scoped, token‑based MCP server that:

1. Reads unpublished content
   • Pages in draft (live or locked edit mode)
   • Change requests (metadata + document body; selected formats: document and markdown)
   • CR comments (threaded discussion for review context)
2. Generates new change requests
   • Tools to create CRs with subject/description, attach initial content (markdown or document JSON), and set reviewers
   • Optional automation hooks: labels/tags, default merge rules, and status transitions (draft → open)
3. (Low priority) Creates new spaces
   • Space scaffolding: title, visibility (private/visitor-auth/in-collection), default levels/roles
   • Optional: initial page tree bootstrap

MCP Tooling Sketch (HTTP transport)

• list_spaces, get_space, search_unpublished_content
• get_change_requests, get_change_request, get_change_request_comments
• create_change_request, update_change_request, submit_change_request
• create_space (low priority)
• get_page_draft, upsert_page_draft (read/write within CR scope)
• diff_to_main (server computes CR vs. main content, returns structured diff)

Authentication & Authorization

• Bearer tokens (PAT or OAuth) with explicit, minimal scopes:
  • mcp:read:drafts, mcp:read:change-requests
  • mcp:write:change-requests, mcp:write:spaces (optional)
• Scope mapping to existing Org/Space permissions (role checks for edit, review, create).
• Audit logs: each MCP tool invocation recorded with actor, scope, space/page/CR IDs, and diff.

Governance & Safety

• Default deny outside assigned scopes; CR writes limited to designated spaces.
• Rate limits independent of public MCP, with back‑pressure for large orgs.
• Data residency & privacy: server respects site visibility (private, visitor-auth, in-collection) and does not surface analytics/user data.

API Alignment

• Tools should internally compose existing REST endpoints for:
  • Change Requests (list/get/create/update/comments)
  • Spaces (create/get/update)
• Content payload formats: document (canonical) and markdown (authoring convenience).
• Returned URLs: include app and location for deep‑linking.

Representative Use Cases

• Agent‑assisted drafting: an MCP client proposes edits to onboarding docs, opens a CR with candidate markdown, and requests reviewers.
• Pre‑publish QA: agents analyze draft pages for broken links, terminology drift, and code block linting; comments posted directly to CR threads.
• Release preparation: generate CRs that bundle page changes for a version, attach diffs, and orchestrate review/merge.