prepare-mcp-integration skill

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

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-content/integrations/README.md as the research contract and

target branch as the connector contract. Follow it end to end; do not substitute remembered behavior or the examples in this skill.

• Treat paperclip/doc/connections/CONNECTOR-PLAYBOOK.md on the implementation

branch, task, or code change before the research gate is accepted.

• Finish Phase A with a research-only PR. Do not create an App implementation

Acceptance does not cover later commits or additional connections.

• Bind acceptance to one research PR head SHA and an explicit connection set.

infrastructure or broad playbook corrections may use separate prerequisite PRs; never combine distinct connections into one connector PR.

• Create one Paperclip App PR per approved connection. Shared prerequisite

briefs, catalog files, issue text, plans, fixtures, screenshots, logs, branch names, commits, or PRs.

• Keep vendor credentials in approved secret storage. Never put secrets in

Default Connection Experience

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.

• Request the broadest vendor permissions and scopes the connection can

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.

• Keep the default wizard limited to the minimum information needed to create

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.

• Give advanced controls working broad defaults so an operator can finish

separate layers. Do not reduce requested vendor permissions merely to stand in for missing action review, approval, quarantine, or audit policy.

• Treat vendor permission breadth and Paperclip execution governance as

Preflight

durable state, and final disposition. Load the standard PR-preparation skill (prepare-paperclip-pr for Paperclip agents) before opening any PR.

1. Load the current Paperclip skill for checkout, comments, interactions,

target repositories and branches, and the Paperclip issue that owns the work. Ask only when these cannot be determined safely from the brief.

1. Resolve the input URL(s), vendor/platform, intended MCP endpoint or API,

canonical files from those target commits, not from a possibly stale working tree. Refresh and reread them again immediately before Phase B.

1. Fetch both repositories and record the target commit hashes. Read the

current AppDefinitions/connectors before creating anything. Match by meaning, not title or slug.

1. Inventory existing integration catalog entities, open PRs, branches, and

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.

1. Determine whether the input describes one connection or several. A

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.

1. Prefer official vendor documentation, protocol/RFC sources, safe live

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

Preserve unrelated local changes.

1. Create an isolated worktree and branch from the refreshed content target.

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.

1. Intake the supplied links or brief through the integration harness. Let the

pipeline. For MCP work, make the evidence sufficient to decide:

1. Build the complete reviewable OKF/planning package required by the current

constraints, administrator setup, and validation needs;

• 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

• exact service involvement and system boundaries in Paperclip.

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.

1. Ground every Paperclip-surface claim in the maintained surface map and

package and any tightly coupled content-playbook correction, but no Paperclip App implementation.

1. Open one research-only PR to paperclip-content. Include the full planning

until checks are green, Greptile is 5/5, all actionable review comments are resolved, and the recorded PR head still matches the reviewed head.

1. Run focused validation and the required PR workflow. Do not present the gate

Gate Research Before Building

1. Create or update a dedicated issue document that names: