feat(mcp): route MCP writes through the suggestion-review layer (AGENT-2)#142
Merged
Conversation
MCP write tools that MUTATE existing content (append_to_page, append_blocks, update_block, set_kit_value, set_db_cell) now persist a reviewable StoredSuggestion by default instead of mutating the page/database directly, using the same review layer + kind/target/payload mapping as the in-app agent (packages/server/src/ai/agent.ts). Nothing an MCP client writes lands until a human accepts it in the review pane. A trusted deployment restores direct mutation via allowDirectEdits (OpenBookMcpOptions), wired from the OPENBOOK_MCP_ALLOW_DIRECT_EDITS env flag in bin.ts — a deployment/config decision, never a tool argument the client can set. Pure creation tools (create_page, create_artifact_page, create_database_row) stay immediate: creation is non-destructive and the review model has no target page / suggestion kind for a not-yet-existing page, matching the agent's rule. Adds scripts/suggestions.test.mts (default=suggestion + flag=direct) and updates the e2e catalogue to assert the new reviewable-by-default behavior. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KFk2T9k3p7ghCjdzMfkA5w
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The
@book.dev/mcpserver's mutating write tools now persist reviewable suggestions by default (matching the in-app agentpackages/server/src/ai/agent.ts), instead of mutating pages/db directly. Board: AGENT-2 (Epic: Agent-first-class).Write tools re-routed → suggestion kind:
append_to_page/append_blocks→insert(applyKindappend_blocks)update_block→replace-textset_kit_value→replace-textset_db_cell→set-cellSuggestions are created via
DataClient.createSuggestion(POST/api/pages/:id/suggestions); a newrecordSuggestionhelper builds{pageId, authorKind:'ai', authorName:'MCP client', kind, target, before, after, payload{applyKind,summary}}so MCP-authored edits replay through the same accept/apply bridge as agent suggestions. Payload/target mappings mirroragent.ts.Opt-out (deployment-level, by design)
allowDirectEditsonOpenBookMcpOptions, wired from envOPENBOOK_MCP_ALLOW_DIRECT_EDITSinbin.ts. Deliberately a deployment/config flag, not a tool argument — an untrusted client cannot opt itself out of review.Design call for security review to bless
The 3 pure-creation tools (
create_page,create_artifact_page,create_database_row) stay immediate, NOT suggestions: the review model has nokindfor "create" (closed set: replace-text/set-cell/insert/delete/set-theme) and no existing host page to attach a suggestion to. This matchesagent.ts's own rule ("creation is non-destructive → applies immediately") and the parity acceptance criterion. Gating creation too would require new suggestion-machinery kinds (out of scope; possible follow-up).Security posture after this change
By default an external MCP client cannot silently mutate existing page text/blocks/kit inputs/db cells — every such write becomes a queued
StoredSuggestion(author "MCP client") requiring human acceptance. It can still create new pages/rows (non-destructive) and read/search. Only a deployment settingOPENBOOK_MCP_ALLOW_DIRECT_EDITSrestores direct writes.Tests
New
packages/mcp/scripts/suggestions.test.mts(16 checks: default=suggestion + no mutation + agent-parity payload; flag=direct mutation; creation stays immediate). Updatedscripts/e2e.mts(43 checks). Fullpnpm verifyexit 0 in-worktree (build:libs, typecheck, lint, mcp 16, server e2e 251, mcp e2e 43).Scope: entirely within
packages/mcp.