/pipedrive-setup

name: pipedrive-setup
description: "Connect Pipedrive CRM for a live pipeline view and confirm-gated deal updates. Use when the user says 'connect Pipedrive', 'link my CRM', 'sync my pipeline with Pipedrive'. Not for pipeline analysis without a CRM; use `pipeline-health`. Not for reconciling an already-connected CRM; use `pipeline-sync`."
integration:
  id: pipedrive
  name: Pipedrive
  mcp_server: pipedrive-mcp
  auth: api_key
  enhances:
    - skill: pipeline-sync
      capability: "Live pipeline view + drift reconciliation against your local pipeline tracker"
    - skill: week-review
      capability: "Reconciles deal numbers (stage/value/probability) against the CRM"
    - skill: meeting-prep
      capability: "Pulls live deal context (stage, value, last activity) for the company"
    - skill: process-meetings
      capability: "Offers to push meeting outcomes as deal notes/activities after you confirm"
    - skill: daily-plan
      capability: "Surfaces focus deals with stale activity or overdue next actions"
  new_capabilities:
    - name: Confirm-gated CRM writes
      trigger: "Dex drafts a note/activity/field change, shows the payload, writes only on your OK"
  sync:
    direction: bidirectional
    entities: deals, notes, activities

Pipedrive Setup

Connect your Pipedrive CRM to Dex. This gives Dex a **live view of your pipeline** and the ability to **push notes, activities and field updates into the deals you're working on**, always after showing you exactly what it will send.

Design (read this: it shapes the setup)

• **Hybrid source of truth.** Pipedrive owns the canonical *numbers* (stage, value, probability, close date, owner, activities). Your local pipeline tracker note (default `04-Projects/Pipeline_Tracker.md`, configurable via `tracker_path` in `System/integrations/pipedrive.yaml`) keeps the *strategy* (per-deal narrative, coverage, positioning) and **defines the focus list**: the deals you're actively working drive which Pipedrive deals Dex syncs.
• **Confirm every write.** Nothing is written to the CRM without Dex showing you the exact payload first (the write tools support `dry_run` previews).
• **Creation is opt-in.** By default Dex can only annotate and update deals that already exist. If you want Dex to be able to *create* deals or organisations, that is a separate, deliberate switch (`writes.allow_create`), because many CRMs are shared with colleagues.
• **Scope = your focus list**, mapped deal-by-deal in `/pipeline-sync`. There is no blanket auto-sync of the whole organisation.

What This Enables

• **`/pipeline-sync`**: "show me my pipeline", reconcile live CRM numbers against your tracker, flag drift, push confirmed updates.
• **`/week-review`**: reconcile sub-step surfaces deal-number drift.
• **`/meeting-prep`**: live deal context for a deal-linked company.
• **`/process-meetings`**: offers to push meeting outcomes to the deal (confirmed).
• **`/daily-plan`**: read-only nudge on stale/overdue focus deals.

Privacy & Security

• Your access token is stored in the **macOS Keychain** (service `dex-pipedrive`) on a Mac, or in the gitignored vault-root `.env` file (`PIPEDRIVE_API_TOKEN=...`) on other systems. It is **never committed**.
• Non-secret settings (your Pipedrive domain, stage/owner mappings) live in `System/integrations/pipedrive.yaml`.
• The token is **never** placed in `.mcp.json` or `config.yaml` (both are committed to git).
• Every write is confirm-gated. Dex uses `dry_run` previews so you always see the payload before it sends.

When to Run

• User types `/pipedrive-setup`
• User asks to connect Pipedrive / their CRM
• User wants a live pipeline view in Dex
• During `/integrate-mcp` if Pipedrive is mentioned

---

Setup Flow

> Throughout this flow, **Dex performs every file action for the user**. They only ever paste their token into the chat; Dex does the rest.

Step 1: Check if Already Connected

1. Read `System/integrations/config.yaml` -> `pipedrive.enabled`. 2. If `true`, run `pipedrive_status()`. If it returns `connected: true`, jump to **Reconfiguration**. 3. Otherwise continue to Step 2.

Step 2: Explain What We're Setting Up

Say:

**Let's connect Pipedrive to Dex.**

You'll get a live view of your pipeline, and Dex can push notes / activities /
field updates into your deals, always showing you exactly what it'll send first.

Your local pipeline tracker stays the home of your strategy and focus list.
Pipedrive becomes the source of truth for the deal *numbers*.

**What you'll need:**
- Your Pipedrive personal API token (I'll show you where)
- About 3 minutes

**Ready?**

Wait for confirmation.

Step 3: Get the API Token + Domain

Guide the user:

To get your Pipedrive API token:

1. In Pipedrive, click your profile (top right) -> **Personal preferences**
2. Open the **API** tab
3. Copy **Your personal API token**

Also tell me your Pipedrive web address, the bit before .pipedrive.com
(e.g. if you log in at https://yourcompany.pipedrive.com, the domain is "yourcompany").

Capture:

• `api_token`: validate non-empty (Pipedrive tokens are ~40-character hexadecimal).
• `company_domain`: the subdomain only.

Step 4: Store the Token Securely

**On macOS**, store it in the Keychain (service `dex-pipedrive`, account `api`) as a small JSON blob so the domain travels with it:

security add-generic-password -U -s dex-pipedrive -a api \
  -w '{"api_token": "<token>", "company_domain": "<domain>"}'

**On other systems** (or if the Keychain write fails), append to the gitignored vault-root `.env` file instead:

PIPEDRIVE_API_TOKEN=<token>

Then `chmod 600 .env` and confirm it is gitignored (`git check-ignore .env` should echo the path). Never ask the user to edit files themselves.

Step 5: Register the MCP Server (idempotent)

Check `.mcp.json` for a `pipedrive-mcp` entry under `mcpServers`. If missing, add (note: **VAULT_PATH only, no token**), substituting the real v