feat(skills): add MCP integration preparation skill

Co-Authored-By: Paperclip <noreply@paperclip.ing>

packages/skills-catalog/catalog/optional/software-development/prepare-mcp-integration/SKILL.md

@@ -0,0 +1,208 @@
+---
+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
+   continuation policy that wakes the assignee after acceptance or rejection.
+3. Put the issue in `in_review` and stop. Do not prepare App worktrees or code
+   while the interaction is pending.
+4. On rejection, 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.

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.

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:16:25.784Z",
   "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": 11048,
+          "sha256": "7cf22c853e368317f2a1c8659fd45042073cd492254495b9a079c14962f10f58"
+        },
+        {
+          "path": "examples/notion-mcp-research-gate.md",
+          "kind": "markdown",
+          "sizeBytes": 1900,
+          "sha256": "944b13ac67c06c65643eb236e856f1479106749861535648d29334f84cf1b50b"
+        }
+      ],
+      "contentHash": "sha256:d73cd59d3d06ee0dad72bfb7bb1535f71db33ba267418b36fbd124734cad2a71"
     }
   ]
 }

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;