Skip to content

feat(mcp): expose the drive docs surface as MCP tools #1641

Description

@newhoggy

Summary

ADR-0076 §12 defers MCP tools for the Docs surface,
following the CLI-first deferral ADR-0070 §9, ADR-0071 §11 and ADR-0073 §12
already set. This is the Docs counterpart of #1614 (Sheets), and should
probably be picked up alongside or after it — they share every design
question and the answers should match.

The CLI surface shipped in #1628 and #1639: drive docs info/read (ungated)
and drive docs replace/append/create (gated on docs-write).

What should be easy

The read tools mirror drive_sheets_info/drive_sheets_read almost exactly.
src/mcp/drive_tools.rs already has the shape, and the engines return typed
outcomes that serialize cleanly.

What needs a decision

Should the mutating verbs be exposed at all? #1614 faces the same question
for Sheets, and the answer should be the same for both — it is a decision
about the MCP surface, not about Docs.

Two properties make it safer here than it might look, both worth stating in
whatever decision gets made:

  • The gate cannot be bypassed by an MCP caller. FilesApi's mutating
    methods and DocsApi::batch_update are pub(in crate::drive), so a tool
    handler physically cannot call them without going through a gated engine.
    That is a compile-time property, not a convention.
  • Logging cannot be bypassed either. record_attempt lives inside the
    engine rather than the CLI layer, specifically so a future MCP caller still
    produces a drivemutation record — including for a Blocked outcome, which
    makes zero API calls.

And one that makes it harder:

  • --dry-run has no natural MCP analogue. A tool call is not a shell
    invocation the user inspects before running. Either the preview becomes a
    separate tool, or the mutating tools are exposed without one — which
    changes the safety story ADR-0076 §7 relies on.

Also worth settling

  • Whether is_stale_revision's outcome needs a distinct machine-readable
    shape, so an agent can tell "re-run this" from "this was wrong".
  • Whether the occurrence-count estimate should be surfaced at all, given
    ADR-0076 §7 makes it display-only and explicitly non-authoritative — an
    agent is more likely than a human to treat a number as a fact.

Refs #1615, #1628, #1639, #1614, ADR-0076 §12

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions