mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-27 02:44:50 +01:00
DottaandPaperclip
3db2e6bdd2
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - Governed MCP access spans contracts, runtime enforcement, adapters, UI surfaces, and operator verification > - The parity reference PR #9534 is too large for effective automated or human review > - The feature therefore needs a linear stack whose individual diffs stay below the 100-file review limit > - This pull request is split 8/8 and focuses on end-to-end coverage, operator docs, evals, and release notes > - The benefit is a standalone, testable review boundary while preserving byte-for-byte parity at the top of the stack ## Linked Issues or Issue Description - Related parity reference: #9534 - Problem: The complete stack needs discoverable browser scenarios, operator guidance, threat modeling, eval coverage, and a parity proof before merge. - Proposed solution: Adds MCP user-story and Smoke Lab e2e suites, docs/evals/release notes, the skill update, and the root e2e driver script registration. - Alternatives considered: keeping #9534 as one 403-file review, or rewriting the feature to manufacture seams; both were rejected in favor of path extraction plus compile-driven boundary moves. - Roadmap alignment: this advances the existing governed MCP/tool-access work already represented by #9534; it does not introduce a separate roadmap initiative. - Stack position: base branch is `pap10341-split/07-ui-apps-activation`. - Merge policy: merge bottom-up, in order, only after the complete eight-PR stack has been reviewed and the top-of-stack parity gate remains empty. - Requested review: QA for flag audit and e2e/browser acceptance; Greptile on every PR. ## What Changed - Adds MCP user-story and Smoke Lab e2e suites, docs/evals/release notes, the skill update, and the root e2e driver script registration. - Keeps this PR below 100 changed files and independently typecheckable. - Preserves the final tree from #9534 when combined with the other seven stack levels. ## Verification - `pnpm typecheck` - `node --check scripts/e2e-mcp-user-stories.mjs` - `pnpm exec playwright test --config tests/e2e/playwright.config.ts --list` — 43 tests discovered - `git diff pap10341-split/08-e2e-docs 6b40e3876d9297105d4ec306e47e46d351c86172` — empty (0 bytes) ## Risks - Browser suites depend on runtime services and environment setup; this PR validates discovery locally while QA owns full flag-on/flag-off execution. - Stack risk: merging out of order can expose incomplete layers; mitigate by following the documented bottom-up merge policy. - Parity risk: later edits to an intermediate branch can drift from #9534; mitigate by re-running the empty top-of-stack diff before merge. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, exact model ID `gpt-5.4`; runtime-managed context window; medium reasoning with repository, shell, Git, GitHub CLI, and code-execution tools enabled. ## 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] Internal references are omitted except the execution-plan link explicitly required for this coordinated split stack - [x] My branch name describes the change 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 - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge ## Stack Coordination - Internal execution plan: [PAP-13874](/PAP/issues/PAP-13874#document-plan) - Parity reference: #9534 - Stack: #9556 → #9557 → #9558 → #9559 → #9560 → #9561 → #9562 → #9563 - Merge bottom-up only after full-stack review and an empty parity diff at #9563. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
118 lines
5.5 KiB
Markdown
118 lines
5.5 KiB
Markdown
# Apps, Connections, and Integrations
|
|
|
|
Audience: internal engineers and product contributors working on integrations.
|
|
|
|
Post-read action: classify a new integration request, pick the right Paperclip
|
|
layer to change, and avoid creating a parallel connection framework.
|
|
|
|
## Decision Record
|
|
|
|
Board decisions from [PAP-13211](/PAP/issues/PAP-13211) make the Apps v2
|
|
substrate on the PAP-10341 branch canonical:
|
|
|
|
- **D1: Apps v2 is the substrate.** The active model is
|
|
`tool_applications`, `tool_connections`, catalog entries, profiles, policy
|
|
rules, action requests, gateway sessions, audit events, and runtime slots.
|
|
Connections v1 is retired as an implementation path.
|
|
- **D2: one vault, brokered projections.** Durable third-party credentials live
|
|
in `company_secrets` as secret refs. Adapter config, plugin config, harness
|
|
credential files, and run environments may receive only brokered or projected
|
|
credentials.
|
|
- **D3: the vocabulary and three-door IA are product law.** The default product
|
|
doors are Apps, Connections, and Review. Protocol and operator-depth concepts
|
|
live behind Developer or Advanced surfaces.
|
|
- **D4: unification lands on PAP-10341.** Pages, CircleBack-style harness MCP
|
|
OAuth, provider gallery work, and plugin-provided integrations converge on
|
|
this branch instead of spawning new integration substrates.
|
|
- **D5: inbound stays thin.** External clients that call Paperclip use scoped
|
|
Paperclip tokens and existing profiles/rules. They do not get a separate
|
|
permission model.
|
|
|
|
## Canonical Object Model
|
|
|
|
Use **connection** as the unifying noun. A connection is four things:
|
|
|
|
1. A stored credential reference.
|
|
2. A capability catalog.
|
|
3. A governance layer.
|
|
4. An audit trail.
|
|
|
|
Everything else is an axis on that object:
|
|
|
|
| Axis | Values | It answers |
|
|
| --- | --- | --- |
|
|
| Direction | outbound, inbound | Who is the client? |
|
|
| Transport | MCP, native REST/OpenAPI, OAuth app install, webhook | How do bytes move? |
|
|
| Auth mode | OAuth, API key/PAT, app installation, none | What does the secret represent? |
|
|
| Credential owner | company, user, run | Whose identity acts? |
|
|
| Packaging | catalog entry, plugin, skill | How does it ship? |
|
|
|
|
MCP is a transport, not a product category. "Install the Discord app",
|
|
"connect Google Drive", and "add an MCP endpoint" all produce governed
|
|
connections with different transport/auth values.
|
|
|
|
## Layer Stack
|
|
|
|
When you are unsure where a change belongs, place it on the narrowest layer that
|
|
solves the problem:
|
|
|
|
| Layer | Owns | Examples |
|
|
| --- | --- | --- |
|
|
| Surface | user-facing Apps, Connections, Review, Developer/Advanced screens | gallery cards, setup wizard, review queue |
|
|
| Governance | profiles, bindings, allow/ask-first/block rules, quarantine, audit | read-only profile, ask-first write policy |
|
|
| Capability | action catalogs, schemas, risk classes, changed-tool review | `search_issues`, `create_comment`, schema hash |
|
|
| Credential | `company_secrets`, OAuth broker, credential resolver, token broker | Slack bot token ref, Google OAuth refresh token ref |
|
|
| Identity | actor attribution and token exchange | board user, agent run, first-party service identity |
|
|
| Transport | how the external system is reached | remote HTTP MCP, local stdio, REST/OpenAPI, webhook |
|
|
|
|
The agent should not hold a durable provider credential. It should hold a
|
|
Paperclip run/session token; the server or broker resolves the connection,
|
|
checks governance, invokes the provider, and writes audit.
|
|
|
|
## Packaging Rule
|
|
|
|
Default to a **catalog entry** when an integration can be described as metadata:
|
|
manifest, auth config, action catalog, resource filters, and policy defaults.
|
|
|
|
Use a **plugin** only when the integration needs product code such as custom UI
|
|
pages, its own tables, workers, migrations, routines, or specialized ingestion.
|
|
A plugin may bundle catalog entries, but it must not bypass the connection,
|
|
profile, policy, credential, and audit model.
|
|
|
|
Use a **skill** for agent instructions. Skills may use connections; they must
|
|
not own durable tokens.
|
|
|
|
## Canonical Docs
|
|
|
|
- [Glossary](./GLOSSARY.md) defines product and internal terms.
|
|
- [Security threat model](./SECURITY-THREAT-MODEL.md) harvests the keeper from
|
|
[PAP-2359](/PAP/issues/PAP-2359) and maps it onto Apps v2.
|
|
- [First-30 matrix](./FIRST-30-MATRIX.md) harvests the keeper from
|
|
[PAP-2432](/PAP/issues/PAP-2432) and is the source matrix for connector
|
|
playbook work.
|
|
- [Connector playbook](./CONNECTOR-PLAYBOOK.md) is the repeatable template for
|
|
adding a vendor as a catalog entry on Apps v2.
|
|
- [MCP access governance](../MCP-ACCESS-GOVERNANCE.md) remains the operator
|
|
runbook for the current gateway, profile, policy, approval, runtime, and audit
|
|
APIs.
|
|
|
|
## Migration Notes
|
|
|
|
Connections v1 contributed useful policy, UX, and rollout thinking, but its
|
|
implementation branch is no longer the target. When you see old tickets or code
|
|
using `connections`, `connection_grants`, or a provider-directory mental model,
|
|
translate the intent into Apps v2:
|
|
|
|
| Connections v1 intent | Apps v2 home |
|
|
| --- | --- |
|
|
| Provider directory | Apps gallery / `tool_applications` |
|
|
| Configured provider instance | Connection / `tool_connections` |
|
|
| Grant allowlist | Profiles, profile bindings, policies |
|
|
| Resource filters | Policy/profile conditions plus provider config |
|
|
| Tool broker | Tool gateway and runtime supervisor |
|
|
| Connection UX tail | Apps, Connections, Review, Developer/Advanced IA |
|
|
|
|
Do not add new work to the retired v1 branch. If an old ticket still describes a
|
|
valid product gap, retarget it to an active Apps v2 issue or close it as
|
|
superseded with a link to the replacement.
|