From a71b9cf6284020e3cabbc0f7916ec8dcb7c4cc7b Mon Sep 17 00:00:00 2001 From: Dotta <34892728+cryppadotta@users.noreply.github.com> Date: Fri, 7 Aug 2026 15:40:11 -0500 Subject: [PATCH] feat(skills): add MCP integration preparation skill (#11063) ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The Skills Store lets a company find and install reusable agent procedures > - The MCP integration preparation procedure existed outside the app catalog > - Paperclip users could not find or install that procedure from the product > - This pull request adds the procedure as an optional software development skill > - The skill keeps research, human approval, and connector delivery as separate gates > - The benefit is a repeatable and governed path from vendor research to one connector pull request ## Linked Issues or Issue Description **What existing behavior does this improve?** The app-shipped Skills Store can install optional skills, but it does not include the MCP integration preparation workflow from `paperclip-content`. **Subsystem affected** `packages/skills-catalog`. **Current behavior** An agent must know where the external workflow lives. The agent cannot find or install it from the Paperclip skills catalog. **Proposed behavior** The optional catalog includes `prepare-mcp-integration`. The installed skill directs agents through cited research, a research-only content pull request, an exact-revision human gate, and one Paperclip connector pull request per approved connection. **Reason and benefit** This change makes the existing integration and connector playbooks available as one installable Paperclip workflow. It also prevents agents from starting connector code before the research gate is approved. **Breaking changes** None. The skill is optional and markdown-only. Related source work: paperclipai/paperclip-content#13. ## What Changed - Add the optional `prepare-mcp-integration` catalog skill under software development - Add Paperclip catalog metadata for roles, requirements, tags, and trust classification - Add a worked Notion MCP research-gate example - Regenerate the checked-in catalog manifest - Add the new key to the shipped optional skill test ## Verification - `pnpm --filter @paperclipai/skills-catalog build:manifest` - `pnpm --filter @paperclipai/skills-catalog validate` - `pnpm --filter @paperclipai/skills-catalog test` - Confirm the generated catalog contains `paperclipai/optional/software-development/prepare-mcp-integration` - Confirm the trust level is `markdown_only` and compatibility is `compatible` ## Risks - Low risk. This change adds one optional markdown-only catalog entry. - The workflow can become stale if the two upstream playbooks change. The skill requires agents to read the current playbooks before each phase and to update upstream rules when reusable specifications change. ## Model Used OpenAI Codex with GPT-5.4, reasoning mode, shell tool use, and code editing. ## 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 --- .../prepare-mcp-integration/SKILL.md | 210 ++++++++++++++++++ .../examples/notion-mcp-research-gate.md | 43 ++++ .../skills-catalog/generated/catalog.json | 55 ++++- .../src/shipped-catalog.test.ts | 1 + 4 files changed, 305 insertions(+), 4 deletions(-) create mode 100644 packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/SKILL.md create mode 100644 packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/examples/notion-mcp-research-gate.md diff --git a/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/SKILL.md b/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/SKILL.md new file mode 100644 index 0000000000..a7ba10b3e0 --- /dev/null +++ b/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/SKILL.md @@ -0,0 +1,210 @@ +--- +name: prepare-mcp-integration +description: > + Prepare MCP/vendor integrations through cited research, a content PR, + exact-revision human approval, and one governed Paperclip connector PR per + approved connection. Use for new integration research and delivery; not for + ad hoc connector coding that bypasses the playbooks. +key: paperclipai/optional/software-development/prepare-mcp-integration +recommendedForRoles: + - engineer + - product-manager + - researcher +tags: + - mcp + - integrations + - connectors + - research + - github + - human-approval +requires: + - git + - gh + - curl +--- + +# Prepare MCP Integration + +Take an input link or vendor brief through two separate phases: a reviewable +research PR in `paperclip-content`, then connector implementation in Paperclip +App only after a human accepts the exact research revision and connection set. + +## Preserve These Boundaries + +- Treat `paperclip-content/integrations/README.md` as the research contract and + `paperclip-content/integrations/skills/integration-harness/SKILL.md` as its + entrypoint. Reference and run them; do not copy their schemas, templates, + state machines, reconciliation rules, or internal gates into this skill. +- Treat `paperclip/doc/connections/CONNECTOR-PLAYBOOK.md` on the implementation + target branch as the connector contract. Follow it end to end; do not + substitute remembered behavior or the examples in this skill. +- Finish Phase A with a research-only PR. Do not create an App implementation + branch, task, or code change before the research gate is accepted. +- Bind acceptance to one research PR head SHA and an explicit connection set. + Acceptance does not cover later commits or additional connections. +- Create one Paperclip App PR per approved connection. Shared prerequisite + infrastructure or broad playbook corrections may use separate prerequisite + PRs; never combine distinct connections into one connector PR. +- Keep vendor credentials in approved secret storage. Never put secrets in + briefs, catalog files, issue text, plans, fixtures, screenshots, logs, branch + names, commits, or PRs. + +## Preflight + +1. Load the current Paperclip skill for checkout, comments, interactions, + durable state, and final disposition. Load the standard PR-preparation skill + (`prepare-paperclip-pr` for Paperclip agents) before opening any PR. +2. Resolve the input URL(s), vendor/platform, intended MCP endpoint or API, + target repositories and branches, and the Paperclip issue that owns the + work. Ask only when these cannot be determined safely from the brief. +3. Fetch both repositories and record the target commit hashes. Read the + canonical files from those target commits, not from a possibly stale working + tree. Refresh and reread them again immediately before Phase B. +4. Inventory existing integration catalog entities, open PRs, branches, and + current AppDefinitions/connectors before creating anything. Match by + meaning, not title or slug. +5. Determine whether the input describes one connection or several. A + connection has one coherent credential owner, endpoint/transport, resource + boundary, and independently reviewable action catalog. Record the proposed + split early and refine it as evidence arrives. +6. Prefer official vendor documentation, protocol/RFC sources, safe live + probes, and current Paperclip code. Use third-party sources only to find or + qualify primary evidence. Record every factual claim with URL and access + date; mark unresolved facts explicitly instead of guessing. + +Do not mutate a vendor account, register a client, grant consent, or invoke a +write tool merely to research it. A safe unauthenticated metadata probe is +allowed when it does not change vendor state. Route credential- or +browser-dependent validation through an explicit QA task when it becomes +necessary. + +## Keep The Run Resumable + +Maintain one concise checkpoint in the Paperclip issue or an issue document: + +- current phase and owning next action; +- input links and target repository commits; +- research PR URL and exact head SHA; +- proposed and accepted connection sets; +- research-gate interaction and accepted target revision; +- one branch, PR URL/head, and verification summary per connection; +- prerequisite/playbook PRs and remaining blockers. + +On every restart, reconcile this state with files, branches, PRs, reviews, and +interactions before creating anything. Reuse semantic matches. Never duplicate +catalog entities, regress terminal pipeline phases, reuse stale acceptance, or +open a second PR for the same connection accidentally. + +## Phase A: Research In paperclip-content + +1. Create an isolated worktree and branch from the refreshed content target. + Preserve unrelated local changes. +2. Intake the supplied links or brief through the integration harness. Let the + harness load its sibling skills for discovery, feature research, proposal + reconciliation, user stories, UI planning, implementation planning, + examples, and docs briefing. Obey every internal human gate in + `integrations/README.md`; the final research gate below does not replace + them. +3. Build the complete reviewable OKF/planning package required by the current + pipeline. For MCP work, make the evidence sufficient to decide: + - official endpoint and transport; + - auth mode, credential ownership, scopes, discovery and DCR behavior; + - endpoint-precedence and redirect-origin constraints; + - token lifetime, rotation, refresh, revocation, and re-auth behavior; + - tool inventory, action risk, resource filters, account/tier/pricing + constraints, administrator setup, and validation needs; + - exact service involvement and system boundaries in Paperclip. +4. Ground every Paperclip-surface claim in the maintained surface map and + current App code. Reconcile before creating, update required indexes/logs, + and preserve lineage, timestamps, immutable slugs, and absorbing phases as + required by the research contract. +5. Open one research-only PR to `paperclip-content`. Include the full planning + package and any tightly coupled content-playbook correction, but no + Paperclip App implementation. +6. Run focused validation and the required PR workflow. Do not present the gate + until checks are green, Greptile is 5/5, all actionable review comments are + resolved, and the recorded PR head still matches the reviewed head. + +## Gate Research Before Building + +1. Create or update a dedicated issue document that names: + - the research PR URL and exact head SHA; + - the content and App source commits used for research; + - the proposed connection set and why each item is independent; + - known limitations, prerequisites, and deferred questions. +2. Create a Paperclip `request_confirmation` interaction targeted at that issue + document's latest revision. Use a revision-specific idempotency key and a + `wake_assignee` continuation policy so either acceptance or rejection wakes + the assignee. Ask the reviewer to include revision notes when rejecting. +3. Put the issue in `in_review` and stop. Do not prepare App worktrees or code + while the interaction is pending. +4. On rejection, use the interaction response and any revision notes to revise + Phase A only and present a new revision. If the research PR head, gate + document, or connection set changes, withdraw/supersede the old confirmation + and request a fresh one. +5. On acceptance, verify that the response still targets the latest gate + revision and recorded PR head. Implement only the accepted connections. + +## Phase B: Implement In Paperclip App + +Refresh the App target branch, reread the current Connector Playbook, and record +its commit before writing code. For each accepted connection: + +1. Create one isolated worktree, branch, and PR. Reconcile against current + AppDefinitions and connector code first. +2. Follow the Connector Playbook's current decisions for catalog entry versus + plugin, reuse path, AppDefinition, transport, credential refs, resource + filters, action catalog, governance, wizard behavior, health/catalog, + availability, revocation, audit, and validation. +3. Derive OAuth behavior from evidence. In particular, do not ship a complete + authorization/token endpoint pair for a discovery-capable MCP vendor unless + it is intentionally authoritative: current broker precedence can make that + pair bypass stored endpoints, challenge hints, and RFC discovery. Probe DCR + and redirect constraints safely, reuse registered clients, and cover token + rotation/terminal refresh failures when the vendor requires them. +4. Add the connection documentation mandated by the current playbook, + including the service-involvement statement, a sequence diagram with exact + auth/discovery/registration/callback endpoints, and step-by-step + administrator setup. +5. Add focused automated tests and the production-like validation hook for + connect, catalog discovery, an allowed read, an ask-first write, a + denied/quarantined action, revoke, and audit. Include negative company, + actor, resource, and changed-schema cases where applicable. +6. Use a first-class QA child issue only when real credentials, vendor consent, + or browser evidence cannot be completed safely by the implementing agent. + Link it as a blocker and give QA exact, secret-safe steps and expected + evidence. +7. Run the standard PR-preparation workflow for this connector PR. Do not hand + it back for merge until focused verification passes, all required checks are + green, Greptile is 5/5, and every actionable comment is resolved. + +Complete and report each connection independently. Failure or review delay on +one connection must not cause another connection to be bundled into its PR. + +## Feed New Rules Upstream + +At both phases, compare new evidence with the two canonical playbooks. + +- Record vendor-specific facts in that vendor's catalog artifacts, manifest, + docs, and tests. +- When evidence changes a reusable schema, gate, template, auth rule, risk + policy, documentation standard, or validation rule, update the owning + upstream playbook/skill/template and add regression coverage where possible. +- Include a narrow, tightly coupled correction in the relevant research or + connector PR. Use a separate prerequisite PR when the correction affects + several connectors, changes shared infrastructure, or would obscure the + one-connection review. +- Rebase/reconcile dependent work and rerun affected planning and verification + after the correction. If the accepted research PR or connection set changes, + repeat the research gate. +- Never knowingly leave implementation, tests, and the owning playbook + inconsistent. + +## Finish + +Before marking the issue done, report the exact research PR and head, accepted +gate revision, every connector/prerequisite PR and head, focused verification, +CI/review state, and any upstream playbook changes. Leave the issue `in_review` +only for a real pending interaction/reviewer/monitor path, `blocked` only for a +named owner and concrete unblock action, and `done` only when every approved +connection has a merge-ready PR and no required follow-up remains on the issue. diff --git a/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/examples/notion-mcp-research-gate.md b/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/examples/notion-mcp-research-gate.md new file mode 100644 index 0000000000..8abdfb1f00 --- /dev/null +++ b/packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/examples/notion-mcp-research-gate.md @@ -0,0 +1,43 @@ +# Example: Research and Gate a Notion MCP Connection + +## Input + +> Research Notion's hosted MCP server and prepare it for Paperclip. Start from +> the vendor documentation URL. Do not build the connector until I approve the +> research. + +## Application + +1. Read the current `paperclip-content/integrations/README.md` and integration + harness from the content target commit. +2. Research the official Notion MCP, OAuth, scopes, tools, limits, and admin + setup. Record URLs and access dates, and mark unknowns rather than guessing. +3. Reconcile existing Notion integration artifacts and open PRs before adding + or changing catalog content. +4. Open a research-only `paperclip-content` PR containing the planning package + required by the integrations playbook. +5. Record the research PR head SHA and proposed connection set in an issue + document, then request confirmation against that exact revision. +6. Stop with the issue in review. No Paperclip App branch exists yet. + +## Gate Output + +```text +Research PR: https://github.com/paperclipai/paperclip-content/pull/123 +Research head: 0123456789abcdef0123456789abcdef01234567 +Content source: 89abcdef0123456789abcdef0123456789abcdef +App source: fedcba9876543210fedcba9876543210fedcba98 +Proposed connection set: +- notion-mcp: one OAuth credential owner, hosted MCP endpoint, and independently + reviewable Notion action catalog +Known limitations: +- Production OAuth consent still requires credentialed QA after approval. +Next action: +- Human confirms or rejects this exact research revision. +``` + +After acceptance, create one isolated Paperclip App worktree and PR for +`notion-mcp`, reread the current Connector Playbook, and follow its current +implementation and validation requirements. If research reveals a reusable +OAuth or documentation rule, update the owning upstream playbook in the +appropriate PR before declaring the connector merge-ready. diff --git a/packages/skills-catalog/generated/catalog.json b/packages/skills-catalog/generated/catalog.json index 9456225a9e..ad63e17569 100644 --- a/packages/skills-catalog/generated/catalog.json +++ b/packages/skills-catalog/generated/catalog.json @@ -2,7 +2,7 @@ "schemaVersion": 1, "packageName": "@paperclipai/skills-catalog", "packageVersion": "0.3.1", - "generatedAt": "2026-07-28T22:35:25.645Z", + "generatedAt": "2026-08-07T20:30:29.973Z", "skills": [ { "id": "paperclipai:bundled:docs:doc-maintenance", @@ -102,11 +102,11 @@ { "path": "SKILL.md", "kind": "skill", - "sizeBytes": 11837, - "sha256": "86d6e382c32c626213b46c010cc7fc1ec460821a8c777cfa5b8e86fa9d6a86b2" + "sizeBytes": 12028, + "sha256": "083d5fa8dc43c3ce7747e89c1afb6f6f42d0603a31808bffc5f8e56735f2d865" } ], - "contentHash": "sha256:1c7a82cd9638a1d845b238032da3ff4ad80c5b6a87dca46082f501fa4583db55" + "contentHash": "sha256:f2592d81f616628a3eba92636616424f2eed82ec22bb504240a58f6be115e407" }, { "id": "paperclipai:bundled:paperclip-operations:status-card-query", @@ -1113,6 +1113,53 @@ "path": "skills/last30days", "url": "https://github.com/mvanhorn/last30days-skill/tree/v3.3.0/skills/last30days" } + }, + { + "id": "paperclipai:optional:software-development:prepare-mcp-integration", + "key": "paperclipai/optional/software-development/prepare-mcp-integration", + "kind": "optional", + "category": "software-development", + "slug": "prepare-mcp-integration", + "name": "prepare-mcp-integration", + "description": "Prepare MCP/vendor integrations through cited research, a content PR, exact-revision human approval, and one governed Paperclip connector PR per approved connection. Use for new integration research and delivery; not for ad hoc connector coding that bypasses the playbooks.", + "path": "catalog/optional/software-development/prepare-mcp-integration", + "entrypoint": "SKILL.md", + "trustLevel": "markdown_only", + "compatibility": "compatible", + "defaultInstall": false, + "recommendedForRoles": [ + "engineer", + "product-manager", + "researcher" + ], + "requires": [ + "git", + "gh", + "curl" + ], + "tags": [ + "mcp", + "integrations", + "connectors", + "research", + "github", + "human-approval" + ], + "files": [ + { + "path": "SKILL.md", + "kind": "skill", + "sizeBytes": 11183, + "sha256": "452386be3aa5e2988dc9d72f288f469975da766626a25c48017877963c533781" + }, + { + "path": "examples/notion-mcp-research-gate.md", + "kind": "markdown", + "sizeBytes": 1900, + "sha256": "944b13ac67c06c65643eb236e856f1479106749861535648d29334f84cf1b50b" + } + ], + "contentHash": "sha256:4dbb76624e0fd5502fa10a9168f77214c5020899838af887e77a1617a0a00c31" } ] } diff --git a/packages/skills-catalog/src/shipped-catalog.test.ts b/packages/skills-catalog/src/shipped-catalog.test.ts index 2c9211f695..5069d5600b 100644 --- a/packages/skills-catalog/src/shipped-catalog.test.ts +++ b/packages/skills-catalog/src/shipped-catalog.test.ts @@ -24,6 +24,7 @@ const EXPECTED_OPTIONAL_KEYS = [ "paperclipai/optional/finance/ramp", "paperclipai/optional/product/design-critique", "paperclipai/optional/research/last30days", + "paperclipai/optional/software-development/prepare-mcp-integration", ]; const MAX_FRONTMATTER_DESCRIPTION_LENGTH = 300;