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;