用途：pipedrive-mcp-server 是一个 MCP 服务器，用于将 Pipedrive CRM 接入 AI 助手（如 Claude Desktop、Claude Code 或任何 MCP 客户端），让用户能通过自然语言查询、创建和更新 CRM 数据。
主要能力：
- 完整 CRM 操作：覆盖交易（deals）、联系人（persons）、组织（organizations）、活动（activities）、产品、项目、任务、线索、笔记和邮件。
- 邮件分析：可访问邮件线程和消息，用于互动分析。
- 字段发现：将自定义字段的哈希码映射为可读名称。
- 管道管理：列出管道、阶段和用户。
- 分页支持：基于游标的分页，适用于大数据集。
- 错误处理：提供清晰、可操作的错误消息。
- 工具数量：共 155 个工具，经过契约测试，对标 Pipedrive OpenAPI v2 规范，确保工具不会偏离文档化 API。
- 实时烟雾验证：对真实 Pipedrive 账户进行工具面广泛测试。
使用方式：
- 最快设置：运行 npx … init 引导式安装器，按提示操作。该安装器会打开 Pipedrive API 令牌页面，实时验证密钥，并为你的客户端（Claude Desktop、Claude Code、Cursor、Windsurf 或 VS Code）生成可用的 MCP 配置。
- 手动设置：在 .mcp.json 中添加配置，使用 scoped 包名 @ckalima/pipedrive-mcp-server，并设置环境变量 PIPEDRIVE_API_KEY。
- 获取 API 密钥：登录 Pipedrive，进入 Settings > Personal preferences > API，复制 40 字符的 API 密钥。
- 环境变量：通过 PIPEDRIVE_MODE 设置能力模式（read-only、safe-write（默认）、full）。full 模式可启用破坏性工具（表格中标记为 🔒），否则返回 DESTRUCTIVE_DISABLED 错误；超出当前模式的工具返回 MODE_RESTRICTED 错误。
- 向后兼容：当 PIPEDRIVE_MODE 未设置时，模式由旧标志 PIPEDRIVE_ENABLE_DESTRUCTIVE 推导（true → full，否则 safe-write）。未识别的 PIPEDRIVE_MODE 值回退为 read-only。
能力模式：
- read-only：推荐首次设置和代理评估使用，只读。
- safe-write（默认）：读取 + 非破坏性写入。
- full：启用所有工具，包括破坏性操作（删除、转换等不可逆写入）。 服务器会从 tools/list 中隐藏超出模式的工具，并在调度器层面拒绝直接调用，确保模式是真实保证而非 UI 提示。每个工具还带有 MCP 注解（readOnlyHint / destructiveHint / idempotentHint），以便策略感知客户端区分读、写、删。
适用场景：
- 通过 AI 助手直接管理 Pipedrive CRM 数据，例如：
- "显示价值超过 $10,000 的开放交易"
- "创建名为 'Acme Contract' 的价值 $50,000 的交易"
- "查找 TechCorp 的所有联系人"
- "列出我收件箱中最近的邮件线程"
- "交易定义了哪些自定义字段？"
限制：
- 传输方式目前仅支持 STDIO（计划支持 Streamable HTTP）。
- 认证通过 Pipedrive API 密钥，匹配本地/自托管层级；尚无托管 OAuth 方案。
- API 版本：v2-first，v1 仅用于无 v2 等价的能力（笔记、邮件、用户、线索 CRUD）。Pipedrive 正在逐步淘汰 v1，部分 v1 端点计划于 2025-12-31 终止，完整 v1 日落预计在 2026-07-31 左右。
- 部分工具需要 Growth+ 计划（标记为 ⭑）。
- 破坏性操作默认关闭，需显式设置 PIPEDRIVE_MODE=full。
- 服务器仅通过 STDIO 运行，无网络监听；API 令牌从环境读取且从不记录；破坏性操作默认关闭；CRM 工具输出被结构化标记为不可信（作为建议性缓解措施，非保证）。
- 连接账户检查：启动时执行一次 GET /v1/users/me，超时 10 秒，不阻塞启动；首次工具响应后可能附加一次性连接块，包含 company_id、verified 和嵌套在 untrusted_display 下的 company_name、user_email 等。
许可：MIT 许可，通过 npm 构建溯源发布。
