0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-08 21:03:51 +02:00

Files

T

DottaandPaperclip 3db2e6bdd2 feat(mcp) [split 8/8]: add e2e coverage and operator docs (#9563 )

## 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>

2026-07-14 15:48:57 -05:00

3.5 KiB

Raw Blame History

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 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.

3.5 KiB Raw Blame History