DottaandPaperclip
3ce8d976a9
## Thinking Path > - Paperclip connects agents to external tools through saved accounts and per-action permissions. > - Notebook exposes artifact management through an ordinary remote MCP server with OAuth. > - A private pilot needs a hidden, default-off catalog and execution gate. > - Local file publishing belongs to Notebook, which can accept bounded file bytes through ordinary MCP tools. > - Paperclip therefore needs the connector registration and generic availability checks, with no file-transfer architecture. ## Linked Issues or Issue Description **Subsystem affected** Apps catalog, experimental feature metadata, connection setup, and connector availability. **Problem or motivation** Users need to connect Notebook as their Cloud account, assign its tools to agents, and retain Paperclip's normal Allowed / Ask first / Off rules. The private pilot must remain hidden until an operator enables it. Notebook should own its upload protocol and local publishing script. **Proposed solution** Register a personal remote MCP OAuth connection at Notebook's canonical endpoint. Reuse existing OAuth discovery, credential storage, refresh, reconnect, and removal. Enforce availability through generic catalog feature metadata and saved application identity. Keep Notebook's standalone uploader in its own service repository; it calls the ordinary gateway and receives no saved OAuth credential. **Alternatives considered** A gallery-only filter permits retained tools and deep links while disabled. A shared workspace publisher and private upload-ticket transport add runtime behavior that a normal MCP connector does not require. Notebook can receive file bytes directly through its own tools instead. **Roadmap alignment** This extends Connected Apps and supports Artifacts and Work Products. ROADMAP.md and related PRs were checked. This PR is standalone on master. The separate OAuth lifecycle and file-transfer proposals (#17085 and #17086) are closed and are not dependencies. ## What Changed - Register Notebook's personal MCP OAuth method, canonical endpoint, scopes, catalog metadata, and branding. - Declare managed `enablePaperclipNotebook` with false defaults and no user-facing settings toggle or staging opt-in. - Use generic availability metadata for gallery/setup, retained connection identity, OAuth completion, health, tool/context discovery, and dispatch. Resources/prompts recheck before credentials, including retained handles. Removal remains available while disabled. - Resolve catalog application identity from the saved application key, so editable connection labels cannot bypass the hidden gate. - Select a method's sole supported credential kind when no kind is supplied. - Keep UI changes to metadata-driven availability and existing setup/reconnect controls. - Document Notebook's service-owned upload script, inline publication, ordinary action policies, and credential behavior. - Add ordinary MCP OAuth, assignment, action-policy, disabled-state, settings, and catalog tests. No workspace contribution registry, private transfer endpoint, native publisher, Runner file-reader change, or Paperclip CLI upload command is included. The entire native-runtime and CLI trees match master. Upload code lives in `paperclip-cloud/notebook/`. ## Verification Source head: `65ef741e4f476c67425b57d2fb2d6d4c00e99b06`, directly on master `53732c811bb69655eb43d3d12f2063ae4ca5ad67`. The diff is 42 files. Shared execution changes only enforce generic catalog availability; tool access also resolves saved application identity and the sole supported credential kind. Neither module contains Notebook upload logic. - Catalog/shared/settings/UI suites: 592 tests passed across 12 files. Shared/server/UI typechecks passed using installed compilers. - Fresh real PostgreSQL generic MCP suite: 84/84 passed at final source; server typecheck and module boundaries pass. Coverage includes personal OAuth, ordinary refresh/reconnect, assignments, Allowed / Ask first / Off, hidden feature enforcement, and local credential removal. Four new resources/prompts cases failed against the prior code and pass after filtering saved application identity and rechecking before credentials. They prove missing/relabelled setup markers and stale eligibility cannot dispatch or read secrets while disabled; an ordinary provider remains available with the flag off. - The full tool-access service suite passed 463/464 cases. One unchanged Google Workspace `slides.write` case timed out at 15 seconds; it passed on one isolated retry without source or timeout changes. Its exact test block matches master. The cause is not established; final-head CI must qualify the complete suite. - Maps, module boundaries, token gates, and whitespace checks passed. Byte comparisons confirm the former transfer/runtime/CLI surfaces match master. - Fresh exact-head Greptile is 5/5 with zero unresolved findings after an exhaustive feedback audit. Current-head CI workflow [39625691137](https://github.com/paperclipai/paperclip/actions/runs/39625691137) succeeded, including both required checks (`ci / verify`, `ci / e2e`), Build, and browser E2E. Supplementary security/advisory scan status is recorded in the PR Checks panel and qualification receipt; prior-head scans are not counted. The superseded `4bd7af9b2e` completed CI successfully, but Greptile found the valid resources/prompts availability gap described above. It was fixed, replied to, and resolved; earlier-head results do not qualify this revision. Preserved environment failures: the first socket-restricted UI/route run had 93 listener setup failures, and the same 93 cases passed with local-socket access. The package-manager launcher could not fetch its signature metadata; installed compilers passed without dependency or configuration changes. The full service timeout and isolated retry remain recorded separately. The superseded `585e870e73` CI also failed an unchanged agent-chat project-plan revision assertion after task creation; the complete spec and relevant runtime sources match master, and a same-master prior run passed. Its cause is not established. Logs are preserved; no test or timeout was weakened and no old-head rerun was requested. The subsequent heads run full CI independently; no prior-head pass substitutes for current qualification. The Notebook uploader requires a separate service release. This public PR adds no uploader runtime to Paperclip and claims no newly deployed browser/agent acceptance. The Notebook-owned upload path is qualified separately. Code-owner review remains required before merge. ## Risks - The feature flag gates the curated connector; it does not create a Notebook service-side team allowlist or block arbitrary standard MCP URLs. - Publishing, sharing, and deletion retain the existing assignment and action-policy boundaries. - The hidden feature must be checked for retained tools and saved identity, including when connection labels change. - Disconnect removes local credentials. It does not revoke the remote Notebook authorization; the owner can revoke it in Notebook. - Ordinary refresh uses the existing client. A lost response after refresh-token rotation can require reconnect. - The standalone Notebook script and its bounded upload tools must ship together in the Notebook service before that documented convenience path is available. - No database schema, workflow, lockfile, shared transfer, or Runner change is included. No merge, deployment, or rollout is performed by this update. ## Model Used OpenAI GPT-6 in Codex, with reasoning, repository inspection, code execution, and tool use. The runtime did not expose a more specific model ID or context-window size. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
5.7 KiB
Paperclip Notebook
Paperclip Notebook uses the existing remote HTTP MCP connection, authorization-code OAuth with PKCE, Dynamic Client Registration, and instance credential vault. Hosted and self-hosted Paperclip use the same connection protocol; Cloud broker enrollment is unnecessary. Cloud authenticates the person, while Notebook owns pages, reader policies, deployments, and its resource-specific OAuth grants.
Connection and rollout
The curated connection uses https://notebook.paperclip.app/mcp. It is hidden
behind the default-off enablePaperclipNotebook flag, with no Settings toggle,
including developer mode. Operators can enable it through managed configuration
(features.enablePaperclipNotebook: true); self-hosted operators can use the
existing instance experimental-settings API. Cloud tenants cannot self-enable
this hidden flag, including through staging tenant opt-ins.
Catalog metadata and the saved application identity govern availability. While disabled, setup, discovery, reconnect, OAuth completion, and curated Notebook calls are denied. Local removal and grant revocation remain available. This rollout gate does not blacklist independent generic remote MCP endpoints.
The personal connection requests notebook:read, notebook:write,
notebook:share, and notebook:delete. Sharing includes publishing a page
publicly in Explore. Notebook enforces ownership and reader policy; Paperclip
continues to enforce current agent assignment and Allowed / Ask first / Off
controls. Connection labels use the normal catalog name. Reconnect preserves
assignments and action restrictions.
Publishing local files
A remote MCP server cannot read an agent-local filesystem path. Ordinary MCP
clients can use notebook_publish for inline UTF-8 or base64 content up to 1 MiB
decoded. Clients that upload directly can continue to use the existing scoped
S3-ticket protocol; upload URLs are temporary authority and must not be logged.
For a local file or built directory, Notebook provides a standalone Node.js
script. It is owned and served by Notebook; Paperclip adds no publishing CLI
command, native runtime tool, private transfer channel, or credential flow.
The script requires a Notebook release advertising uploadLimits through
notebook_get_account and supporting notebook_begin_upload with
transport: "mcp" plus notebook_upload_chunk. The script and these tools must
be deployed together; this source addition does not establish that deployment.
Run it only in an approved agent shell that already has PAPERCLIP_API_URL,
PAPERCLIP_API_KEY, and PAPERCLIP_RUN_ID. These are the existing Paperclip run
credentials, not Notebook credentials. It creates no login or API key. Download
and inspect the trusted script before running it:
curl --fail --silent --show-error --proto '=https' \
https://notebook.paperclip.app/client/publish.mjs \
-o /tmp/paperclip-notebook-publish.mjs
node /tmp/paperclip-notebook-publish.mjs ./dist \
--connection CONNECTION_ID --title "Weekly report" \
--idempotency-key weekly-report-build
Build client applications before publishing. Use --entry-file and --spa
when needed. Updates require --page-id and --expected-version. The script
reads only the selected local source under the shell's existing filesystem
authority. It rejects symbolic links, nonregular files, noncanonical paths, and advertised
size/file limits before publication mutations, then verifies declared content
again before sending chunks.
Agents without those shell credentials or filesystem access use the ordinary
MCP tools available to their runtime; the script grants neither authority.
The script opens an ordinary run-bound tool gateway session and sends every
operation through /api/tool-gateway/tools/call on the selected connection.
Notebook OAuth credentials remain in Paperclip's vault. File bytes travel as
bounded base64 tool arguments under normal gateway handling, not through signed
upload URLs or a private data channel. Notebook verifies chunk identity,
checksums, ownership, scopes, and the original upload window before publication.
If an action requires approval, stop and wait for the normal task approval.
Rerun with the same publication key and unchanged files after approval or a lost
response; Notebook reports the missing chunk indexes so completed chunks are
not repeated. Off actions, removed assignments, disabled connections, and the
rollout gate continue to prevent dispatch. Throttles are honored within a
bounded attempt. Uploads expire after 15 minutes; an expired upload requires a
new publication key. A validating operation is not a working link: use
notebook_get_operation until Notebook reports success and the effective audience.
Verification and limits
The connection fixtures exercise personal OAuth, registration, PKCE/resource binding, tool discovery, assignment, refresh, reconnect policy preservation, and local removal. Uploader tests use real local files and controlled HTTP services; final acceptance must additionally exercise the ordinary authenticated Paperclip gateway against Notebook. These checks do not establish deployed hosted/self-hosted browser acceptance or maximum-path AWS publication. Notebook advertises accepted upload limits; clients do not infer its S3 key layout.
Removing a connection disables local use and clears saved credentials through Paperclip's existing removal flow. It does not automatically revoke Notebook's remote authorization; revoke that separately in Notebook's Connected apps. Automatic upstream revocation, account-email labels, and custom rotating-refresh response recovery remain deferred. A lost refresh response may require reconnecting.
Notebook artwork uses the repository's first-party Paperclip mark, with fixed light and dark variants for the connector icon renderer.