@tickernelz/paperclip-pro-skills-catalog 2026.925.0

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

@@ -0,0 +1,230 @@
+---
+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.
+
+## Default Connection Experience
+
+- Request the broadest vendor permissions and scopes the connection can
+  support by default. Operators should not have to predict every future tool
+  they may need during setup. Enforce safe use after connection through
+  Paperclip's action catalog, resource boundaries, ask-first policies,
+  quarantine, and audit controls.
+- Keep the default wizard limited to the minimum information needed to create
+  a working connection: connection identity, authentication, and any
+  unavoidable tenant or resource boundary. Put optional scope reduction,
+  feature groups, individual tool filters, response modes, transport tuning,
+  and other expert controls behind one collapsed **Advanced** disclosure.
+- Give advanced controls working broad defaults so an operator can finish
+  setup without opening them. When a provider truly requires an explicit
+  advanced choice, document the exception and explain it in plain language
+  instead of exposing protocol details by default.
+- Treat vendor permission breadth and Paperclip execution governance as
+  separate layers. Do not reduce requested vendor permissions merely to stand
+  in for missing action review, approval, quarantine, or audit policy.
+
+## 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.

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