mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-22 16:51:28 +02: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>
73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# Connections Glossary
|
|
|
|
Audience: engineers, designers, and agents writing integration code, plans, or
|
|
product copy on the Apps v2 substrate.
|
|
|
|
Source: the accepted vocabulary table from the [PAP-13211](/PAP/issues/PAP-13211)
|
|
plan. Treat these definitions as product law when translating old Connections
|
|
v1, plugin, skill, MCP, and gateway language onto Apps v2.
|
|
|
|
## Canonical Vocabulary
|
|
|
|
| Term | Definition | It is NOT |
|
|
| --- | --- | --- |
|
|
| App | Catalog entry for an external or first-party system: metadata, supported transports, auth modes, and action catalog. The unit of the store. | A running thing; a plugin. |
|
|
| Connection | A configured, credentialed instance of an app for this company, possibly per-user account. Carries status and health. | A plugin install; an MCP server config file. |
|
|
| Action / Tool | One invokable capability of a connection, risk-classified and quarantined when new or changed. | A free-form shell command or permission grant. |
|
|
| Profile | Curated allowlist of actions bound to a scope such as company, project, agent, routine, or issue. | A permission system of its own. |
|
|
| Rule | Allow, ask-first, or block per action. Ask-first lands in the Review queue. | A profile or catalog entry. |
|
|
| Gateway | Named inbound MCP endpoint exposing curated connections/tools to external clients under a scoped bearer token. Reuses profiles and rules. | A new permission model. |
|
|
| Plugin | Code extension package: workers, UI, migrations. May declare apps/providers and provision skills. Packaging, not governance. | An integration per se. |
|
|
| Skill | Instructions an agent follows. May use connections; must not own tokens. | A token store. |
|
|
| MCP | A wire protocol; one transport apps may support. | A product category. |
|
|
| Broker | The run-time service that turns a stored credential plus a grant into a short-lived, downscoped, attributed token. | A vault or a permission model. |
|
|
|
|
## Product Copy Defaults
|
|
|
|
Use these words in prosumer surfaces:
|
|
|
|
- app
|
|
- connect
|
|
- connection
|
|
- allowed
|
|
- ask-first
|
|
- review
|
|
|
|
Keep protocol and implementation terms behind Developer or Advanced surfaces:
|
|
|
|
- MCP
|
|
- stdio
|
|
- gateway
|
|
- plugin
|
|
- manifest
|
|
- DCR
|
|
- PKCE
|
|
- schema hash
|
|
- bearer token
|
|
- secret ref
|
|
|
|
## Apps v2 Object Mapping
|
|
|
|
| Vocabulary term | Apps v2 object or surface |
|
|
| --- | --- |
|
|
| App | `tool_applications`, provider gallery cards, app detail metadata. |
|
|
| Connection | `tool_connections`, connection detail status/health, setup/configure flows. |
|
|
| Action / Tool | Catalog entries discovered from MCP/OpenAPI/vendor wrappers. |
|
|
| Profile | Access profiles and bindings. |
|
|
| Rule | Policy rules such as allow, ask-first, block, rate limit, and trust rules. |
|
|
| Gateway | Inbound MCP gateway sessions and scoped client tokens. |
|
|
| Plugin | Extension packaging that may declare apps but does not bypass governance. |
|
|
| Skill | Agent instruction package that calls governed connections through Paperclip. |
|
|
| MCP | Transport option for apps and gateways. |
|
|
| Broker | Credential resolver/token broker path over `company_secrets`. |
|
|
|
|
## Translation Rules
|
|
|
|
- MCP is a transport, not the information architecture.
|
|
- A plugin may bundle an app, but governance always flows through the connection,
|
|
profile, rule, broker, and audit model.
|
|
- A skill may use Slack, Google Drive, Ramp, or another vendor, but the durable
|
|
credential belongs in `company_secrets` and is reached through a connection.
|
|
- Inbound clients use scoped Paperclip auth; outbound vendor calls use the Apps
|
|
v2 connection governance stack.
|