Skip to content

The open-source app everyone uses to manage agents at work

feat(skills): add MCP integration preparation skill (#11063)

Dottaa71b9cf62840
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;