0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-10-24 18:19:05 +02:00

Files

T

DottaandPaperclip e34abee670 feat(mcp): connect assistants to a team with user OAuth (#14846 )

## Thinking Path

> - Paperclip gives teams durable tasks, agent execution, budgets, and
approvals.
> - People also use assistants in Codex, Claude, and other MCP clients.
> - Those assistants need a scoped connection that preserves the
person’s permissions and attribution.
> - Delegating a task must not turn the assistant into the assigned
agent.
> - This PR adds opt-in user OAuth, ten first-party tools, browser
consent, and workflow packages.
> - Paid product evals verify the resulting tasks, documents,
attribution, retries, and access boundaries.
> - The team keeps working after the assistant conversation ends.

## Linked Issues or Issue Description

**Problem or motivation**

A person cannot connect an external assistant to an existing team
through browser consent and safely delegate durable work as themselves.

**Proposed solution**

Expose an opt-in `/mcp/paperclip` endpoint with individually described
first-party operations. Bind every connection to a person, client,
company, resource, and scopes. Reuse domain authorization and
scheduling. Package shared team-review, delegation, and follow-up
workflows for OpenAI/Codex and Claude.

**Alternatives considered**

Related PRs #9393 and #12549 cover earlier remote MCP and board-operator
approaches. This change uses user OAuth and a bounded public catalog. It
does not expose a generic executor, operator administration, static
shared board credentials, or external agent execution. Registry listing
work in #9851 is a separate distribution step.

**Roadmap alignment**

This maintainer-requested implementation extends the governed MCP
gateway, activity attribution, durable work products, and hosted
deployment direction in `ROADMAP.md`. It implements the first release of
the saved design plan; external agent participation and granted
third-party tools remain later releases.

## What Changed

- Add MCP 2.0 discovery and task status/comment/document Events on the
same authenticated endpoint. Persist subscriptions and delivery
receipts, verify HTTPS callbacks, sign Standard Webhooks, encrypt
callback material, recheck permissions/Cloud membership, and bound
retries/expiry. Older MCP clients keep their existing tools.
- Add discovery, dynamic client registration, S256 PKCE, resource
validation, rotating refresh tokens, revocation, and company consent.
Store credentials as hashes and recheck membership at execution.
- Add tools for connection identity, agents/projects, task
search/read/create, human comments, documents/deliverables, and
pending-approval links. Preserve current domain permissions and
scheduling.
- Add durable mutation receipts across reconnects. Matching retries
replay results; uncertain outcomes keep the same request ID and require
inspection.
- Add consent and connection-management pages, OAuth log redaction,
shared plugin workflows, and separate OpenAI/Codex and Claude package
outputs.
- Add eight paid Product E2E cases across three models, independent
durable-state grading, usage evidence, cleanup, and report integration.
Add task-document guidance and regenerate the runner capability
inventories.
- Add migrations 0301 and 0302, the dated implementation plan, result
notes, and direct-client setup instructions in `doc/public-mcp.md`.

## Verification

- Merge integration `e180b1948`: resolved conflicts with current master,
preserved both eval registries, regenerated capability catalogs, and
regenerated migrations as 0301/0302 while keeping the original
replay-safe SQL byte-identical. Local migration safety/snapshot tests
(26), MCP/OAuth tests (38), redaction/OpenAPI tests (71), and eval
catalog/grading tests (198) pass. Token and capability gates pass. Full
recursive typecheck passed. Fresh Greptile review is 5/5 with no
unresolved findings. CI is green on this exact head (55 successes, two
intentional skips, one neutral result): one unchanged Cursor sandbox
test timed out at 10 seconds, then passed locally in 856 ms. A single
retry of that failed shard and the aggregate workflow passed. Merge
remains blocked on the repository code-owner approval rule.

Earlier checks passed at `6aa0962d4fb715f2190bb7bb22efacab2e58495d`: 55
successes, two intentional skips and one neutral result. [The earlier CI
run](https://github.com/paperclipai/paperclip/actions/runs/36901592350)
includes all test shards, browser tests, typecheck, build and canary dry
run. Greptile was 5/5 on that commit with no unresolved review threads.
GitHub still requires code-owner review under the repository merge
rules; passing checks do not bypass that approval. Paid source
fingerprints remain separate below and in the dated result note.

- Paid Events qualification passes **3/3**: GPT-5.4 Mini, Claude Haiku
4.5 and Claude Sonnet 4.6. Each uses a real public HTTPS callback,
signature verification and report retrieval in a fresh conversation. A
final Mini regression passes after the quota/status fixes. All evidence
validates. Bounded tunnel startup retries occur before provider calls
and remain visible; failed earlier attempts retain their original
grades.
- The earlier complete seven-case matrix passes **21/21**, with a
separate **3/3** delegation regression. Two preceding matrices also
passed 21/21 each. A complete 24-cell matrix including Events has not
been run. [The dated
results](doc/plans/2026-10-01-public-mcp-paid-eval-results.md) retain
exact source fingerprints, failures, model IDs and partial costs.
- Node 24: repository-wide `pnpm -r typecheck` and `pnpm build` pass
after merging master. Server typecheck passes after the final
quota/status changes. Eval typecheck and all 892 eval-support tests
pass.
- All 33 real MCP/OAuth tests pass. The preceding combined MCP,
redaction, private-address and DNS-rebinding run passed 129 tests; two
later MCP regressions cover quota reuse and unchanged-status
suppression. All 28 adjacent issue-tree/stale-lock route tests pass. CI
then found a null checkout result in the existing concurrent-workspace
path; logging now uses optional status access. All 12 closed-workspace
tests and all 33 MCP tests pass after that correction. The exact-start
event calibration exposed a timestamp gap; scanning now includes the
subscription start, with all 33 MCP tests and server typecheck passing.
These two narrow corrections follow the paid regression.
- A real Core → Cloud → Core authority round trip passes OAuth, MCP 2.0
subscription/delivery, current membership loss, unsubscribe, legacy SDK
tools, refresh and revocation. Its callback transport is a fixture with
independent HMAC verification. The paid Events campaigns separately
prove public HTTPS delivery.
- Earlier component qualification passed UI 7,117 tests, CLI 502, shared
832, skills catalog 20, database 160 and OpenAPI 10. Token gates, module
boundaries, migration order and plugin regeneration passed. CI covers
general/serialized suites, eight browser shards, runner checks,
typecheck, build and canary dry run.
- **Local full-suite limitation:** the earlier monolithic run was not
clean. It encountered overlapping schema rebuilding, Mac database
shared-memory limits and isolated CLI/fixture failures. Targeted reruns
passed. The existing >32 MiB Git filename stress test still hit its
300-second Mac timeout. The additional serialized sweep stopped after 62
passing suites once CI passed. Original failures and partial logs
remain; this PR does not claim a wholly green local monolithic run.
- Local Codex CLI and Claude Code OAuth login and MCP SDK
interoperability were verified. Public-store installation, actual
ChatGPT Work Cloud Events UI, staging HTTPS client behavior and hosted
newcomer provisioning remain release gates.

Enablement is moving to **Settings → Experimental → Assistant
connections (MCP)** in the stacked follow-up
[#14933](https://github.com/paperclipai/paperclip/pull/14933). Merge
both for the intended setup experience. This foundation branch alone
still uses `PAPERCLIP_PUBLIC_MCP_ENABLED=true`. After deployment, set
`PAPERCLIP_PUBLIC_URL` to the authenticated instance's HTTPS origin, and
connect to `/mcp/paperclip`. Select a team and allow writes in browser
consent. Configure an available agent and budget, then delegate and
retrieve results later. For Events, rescan the deployed plugin catalog
in ChatGPT Work Cloud; the host supplies its webhook credentials when
the user asks to watch a task. See [the setup
runbook](doc/public-mcp.md).

## Risks

- Events are at-least-once and may arrive out of order. No replay cursor
is advertised. Clients must refresh finite subscriptions, read current
state and avoid comment feedback loops. Callback material uses the
instance secrets master key; hosted subscriptions require the updated
Cloud broker and are bounded to five minutes/the access proof expiry.
- ChatGPT Work Cloud/dot event UI, plugin rescan and a hosted staging
subscription remain deployment gates. Local signed-webhook and paid
model evidence does not claim those surfaces have been exercised.
- Disabled by default. Merging adds schema and opt-in code; it does not
deploy a public endpoint, publish a store listing, create a team, or
start paid agents.
- Migrations 0301 and 0302 are additive and idempotent. Their SQL is
unchanged from the earlier preview numbers, so hash-aware upgrade
reconciliation preserves prior staging applications. Normal instance
upgrades must apply it before enabling MCP.
- Task creation and comments can schedule paid agent work. Consent and
tool descriptions disclose that effect. Revocation blocks future calls
but does not undo delegated work.
- Public deployments need edge rate limits and credential-safe logging.
Internal dispatch is restricted to the closed catalog and carries a
request-local verified actor.
- Hosted onboarding requires the companion Cloud broker, encryption-key
configuration, and tenant rollout. Self-hosted direct connections can
use this PR alone.
- Store acceptance and agent-mode participation are not claimed.
Checked-in plugin endpoints are development defaults; rebuild packages
for a real deployment before installation.

## Model Used

OpenAI GPT-6 in Codex, with reasoning, tool use, and code execution. A
more specific serving version and context-window size were not exposed
by the session. Paid eval models: `gpt-5.4-mini-2026-03-17`,
`claude-haiku-4-5-20251001`, and `claude-sonnet-4-6`.

## 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 (targeted/component checks;
full local-run limitations are recorded above)
- [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>

2026-10-06 11:48:53 -05:00

30 KiB

Raw Blame History

Capability Capability Contract

This generated contract is a self-contained derivative of the Paperclip skill, its seven references, the Paperclip Evals corpus, and the legacy MCP tool surface. It does not import or contact the Paperclip control plane.

The skill/reference inventory and eval cases are the only normative behavior sources. Paperclip does not use the legacy MCP calls as a production capability surface; all MCP names below are traceability aliases folded into normative eval rows. Their disposition, grants, assertions, and evidence contract are inherited from the target row rather than classified independently.

Baseline Counts

Skill/reference headings: 161
Eval cases: 106 across 16 groups
Total normative rows: 267
Legacy MCP aliases folded into normative rows: 42

Eval group	Cases
hb	5
co	6
st	8
cm	6
se	4
su	4
bl	5
dp	3
ix	9
ap	6
ar	4
er	9
rf	22
mh	4
rs	3
wk	8

Regeneration

pnpm --dir packages/paperclip-runner generate:capability-inventory imports the canonical baselines and rewrites every generated file.
pnpm --dir packages/paperclip-runner check:capability-inventory validates counts, uniqueness, normative dispositions, one-to-one MCP folds, required fields, and generated-file drift without requiring the external eval repository.

Skill / Reference Rows

Legacy MCP Alias Index

This is a compatibility/traceability index, not a tool catalog. “Inherited disposition” is shown only to make the normative target easy to audit.

Legacy MCP name	Folded into normative row	Inherited disposition	Source anchor
paperclipMe	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:290
paperclipInboxLite	eval:hb-inbox-lite-01	control_plane_owned	packages/mcp-server/src/tools.ts:296
paperclipListAgents	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:302
paperclipListSkills	eval:rf-cskill-audit-01	optional_agent_tool	packages/mcp-server/src/tools.ts:308
paperclipGetAgent	eval:rf-api-mgr-heartbeat-01	optional_agent_tool	packages/mcp-server/src/tools.ts:314
paperclipListIssues	eval:se-q-filters-01	optional_agent_tool	packages/mcp-server/src/tools.ts:323
paperclipGetIssue	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:338
paperclipGetHeartbeatContext	eval:hb-context-01	control_plane_owned	packages/mcp-server/src/tools.ts:344
paperclipListComments	eval:se-get-issue-01	optional_agent_tool	packages/mcp-server/src/tools.ts:353
paperclipGetComment	eval:hb-wake-comment-01	control_plane_owned	packages/mcp-server/src/tools.ts:366
paperclipListIssueApprovals	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:373
paperclipListDocuments	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:379
paperclipGetDocument	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:385
paperclipListDocumentRevisions	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:392
paperclipListProjects	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:402
paperclipGetProject	eval:rf-wf-project-setup-01	optional_agent_tool	packages/mcp-server/src/tools.ts:408
paperclipGetIssueWorkspaceRuntime	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:417
paperclipControlIssueWorkspaceServices	eval:rf-iws-start-url-01	optional_agent_tool	packages/mcp-server/src/tools.ts:423
paperclipWaitForIssueWorkspaceService	eval:rf-iws-target-restart-01	optional_agent_tool	packages/mcp-server/src/tools.ts:440
paperclipListGoals	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:466
paperclipGetGoal	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:472
paperclipListApprovals	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:478
paperclipCreateApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:487
paperclipGetApproval	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:496
paperclipGetApprovalIssues	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:502
paperclipListApprovalComments	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:508
paperclipCreateIssue	eval:su-parent-goal-01	optional_agent_tool	packages/mcp-server/src/tools.ts:514
paperclipUpdateIssue	eval:st-done-comment-01	always_agent_tool	packages/mcp-server/src/tools.ts:521
paperclipCheckoutIssue	eval:co-body-contract-01	control_plane_owned	packages/mcp-server/src/tools.ts:528
paperclipReleaseIssue	eval:er-release-01	control_plane_owned	packages/mcp-server/src/tools.ts:540
paperclipAddComment	eval:cm-multiline-01	always_agent_tool	packages/mcp-server/src/tools.ts:546
paperclipSuggestTasks	eval:ix-suggest-tasks-01	always_agent_tool	packages/mcp-server/src/tools.ts:553
paperclipAskUserQuestions	eval:ix-questions-01	always_agent_tool	packages/mcp-server/src/tools.ts:565
paperclipRequestConfirmation	eval:ix-confirmation-plan-01	always_agent_tool	packages/mcp-server/src/tools.ts:577
paperclipRequestCheckboxConfirmation	eval:ix-checkbox-01	always_agent_tool	packages/mcp-server/src/tools.ts:589
paperclipUpsertIssueDocument	eval:dp-plan-doc-01	always_agent_tool	packages/mcp-server/src/tools.ts:601
paperclipRestoreIssueDocumentRevision	eval:dp-base-revision-01	always_agent_tool	packages/mcp-server/src/tools.ts:612
paperclipLinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:627
paperclipUnlinkIssueApproval	eval:ap-board-approval-01	optional_agent_tool	packages/mcp-server/src/tools.ts:636
paperclipApprovalDecision	eval:ap-approval-wake-01	optional_agent_tool	packages/mcp-server/src/tools.ts:646
paperclipAddApprovalComment	eval:ap-approval-deny-01	optional_agent_tool	packages/mcp-server/src/tools.ts:668
paperclipApiRequest	eval:rf-api-404-report-01	optional_agent_tool	packages/mcp-server/src/tools.ts:677

Capability	Primary disposition	Source anchor
skill:skills/paperclip/SKILL.md:paperclip-skill:10	optional_agent_tool	skills/paperclip/SKILL.md:10
skill:skills/paperclip/SKILL.md:terminology:14	optional_agent_tool	skills/paperclip/SKILL.md:14
skill:skills/paperclip/SKILL.md:authentication:20	control_plane_owned	skills/paperclip/SKILL.md:20
skill:skills/paperclip/SKILL.md:conversation-tasks:32	optional_agent_tool	skills/paperclip/SKILL.md:32
skill:skills/paperclip/SKILL.md:server-verified-external-chat-turns:49	control_plane_owned	skills/paperclip/SKILL.md:49
skill:skills/paperclip/SKILL.md:the-heartbeat-procedure:89	optional_agent_tool	skills/paperclip/SKILL.md:89
skill:skills/paperclip/SKILL.md:generated-artifacts-and-work-products:198	always_agent_tool	skills/paperclip/SKILL.md:198
skill:skills/paperclip/SKILL.md:status-quick-guide:246	control_plane_owned	skills/paperclip/SKILL.md:246
skill:skills/paperclip/SKILL.md:monitors-and-watchers-say-only-what-you-actually-scheduled:256	optional_agent_tool	skills/paperclip/SKILL.md:256
skill:skills/paperclip/SKILL.md:delegating-review-tasks:269	always_agent_tool	skills/paperclip/SKILL.md:269
skill:skills/paperclip/SKILL.md:managing-a-user-s-inbox:280	control_plane_owned	skills/paperclip/SKILL.md:280
skill:skills/paperclip/SKILL.md:issue-dependencies-blockers:288	control_plane_owned	skills/paperclip/SKILL.md:288
skill:skills/paperclip/SKILL.md:requesting-board-approval:313	optional_agent_tool	skills/paperclip/SKILL.md:313
skill:skills/paperclip/SKILL.md:issue-thread-interactions:334	optional_agent_tool	skills/paperclip/SKILL.md:334
skill:skills/paperclip/SKILL.md:standalone-decisions:363	optional_agent_tool	skills/paperclip/SKILL.md:363
skill:skills/paperclip/SKILL.md:mcp-tool-approval-gates:467	optional_agent_tool	skills/paperclip/SKILL.md:467
skill:skills/paperclip/SKILL.md:niche-workflow-pointers:509	optional_agent_tool	skills/paperclip/SKILL.md:509
skill:skills/paperclip/SKILL.md:cases:519	optional_agent_tool	skills/paperclip/SKILL.md:519
skill:skills/paperclip/SKILL.md:company-skills-workflow:524	optional_agent_tool	skills/paperclip/SKILL.md:524
skill:skills/paperclip/SKILL.md:routines:535	optional_agent_tool	skills/paperclip/SKILL.md:535
skill:skills/paperclip/SKILL.md:issue-workspace-runtime-controls:546	optional_agent_tool	skills/paperclip/SKILL.md:546
skill:skills/paperclip/SKILL.md:proposing-credentials-safely:553	optional_agent_tool	skills/paperclip/SKILL.md:553
skill:skills/paperclip/SKILL.md:reading-granted-secrets:560	optional_agent_tool	skills/paperclip/SKILL.md:560
skill:skills/paperclip/SKILL.md:critical-rules:586	optional_agent_tool	skills/paperclip/SKILL.md:586
skill:skills/paperclip/SKILL.md:comment-style-required:607	always_agent_tool	skills/paperclip/SKILL.md:607
skill:skills/paperclip/SKILL.md:update:639	optional_agent_tool	skills/paperclip/SKILL.md:639
skill:skills/paperclip/SKILL.md:task-documents-and-deliverables:649	always_agent_tool	skills/paperclip/SKILL.md:649
skill:skills/paperclip/SKILL.md:planning-required-when-planning-requested:663	optional_agent_tool	skills/paperclip/SKILL.md:663
skill:skills/paperclip/SKILL.md:key-endpoints-hot-routes:694	optional_agent_tool	skills/paperclip/SKILL.md:694
skill:skills/paperclip/SKILL.md:searching-issues:723	optional_agent_tool	skills/paperclip/SKILL.md:723
skill:skills/paperclip/SKILL.md:full-reference:733	optional_agent_tool	skills/paperclip/SKILL.md:733
skill:skills/paperclip/SKILL.md:conversational-confirmation-answers:737	always_agent_tool	skills/paperclip/SKILL.md:737
skill:skills/paperclip/references/api-reference.md:paperclip-api-reference:1	optional_agent_tool	skills/paperclip/references/api-reference.md:1
skill:skills/paperclip/references/api-reference.md:response-schemas:9	optional_agent_tool	skills/paperclip/references/api-reference.md:9
skill:skills/paperclip/references/api-reference.md:agent-record-get-api-agents-me-or-get-api-agents-agentid:11	optional_agent_tool	skills/paperclip/references/api-reference.md:11
skill:skills/paperclip/references/api-reference.md:company-portability:44	optional_agent_tool	skills/paperclip/references/api-reference.md:44
skill:skills/paperclip/references/api-reference.md:issue-with-ancestors-get-api-issues-issueid:110	optional_agent_tool	skills/paperclip/references/api-reference.md:110
skill:skills/paperclip/references/api-reference.md:issue-update-response-patch-api-issues-issueid:196	optional_agent_tool	skills/paperclip/references/api-reference.md:196
skill:skills/paperclip/references/api-reference.md:blocker-diagnostics-get-api-issues-issueid-diagnostics-blockers:238	control_plane_owned	skills/paperclip/references/api-reference.md:238
skill:skills/paperclip/references/api-reference.md:wake-diagnostics-get-api-issues-issueid-diagnostics-wakes:277	control_plane_owned	skills/paperclip/references/api-reference.md:277

30 KiB Raw Blame History