Pullpush

PullPush MCP —连接任意两个 API 并保持同步

这是 PullPush.ai 的官方 MCP 服务——一个集成平台，可连接电商商店、仓库、市场平台、ERP 和 POS 系统，并让它们之间的库存水平、订单和商品保持同步。

此服务让 AI Agent（Claude、Cursor 或任何支持 Model Context Protocol 的工具）端到端地构建、运行和监控这些集成：连接两个系统、安全预览同步，并切换到正式运行——无需人工点击仪表板。

Agent 为什么喜欢它

• 运行时确定，不在关键路径中使用大模型。 AI 会在构建时提供帮助（生成连接器、建议字段映射）；同步引擎本身可预测、有版本控制且可观测。
• 默认安全。 新工作流以影子模式（只读）启动。pullpush.sync action:"preview" 会在写入任何内容前显示结构化的源与目标差异。
• 凭据绝不会接触你的设备或环境变量。 连接密钥在创建时立即在服务端使用信封加密（AES-256-GCM，每租户独立密钥）进行加密。
• 自描述。 get-started MCP 提示词会引导你从零开始构建可用的集成；pullpush:// 资源提供工具目录、快速入门和 Agent 指南——无需预先介绍。
• 错误信息结构化且可执行。 失败时会返回 {code, suggestion, suggestedTool, retryable}——Agent 始终知道下一步该做什么。
• 服务级可靠性。 熔断器、按键有序投递、幂等性、带重试的死信队列、指数退避。

60 秒内试用——无需注册

curl -X POST https://api.pullpush.ai/api/sandbox

返回一个免费的 48 小时沙盒租户：包含 API 密钥、可直接粘贴的 MCP 配置，以及两个预先接入的演示连接，其库存数据刻意设置为不一致——因此你第一次运行 pullpush.sync action:"preview" 时，就能看到真实的规范化差异（数量不符、缺失商品、同步一致的行）。沙盒到期后会自动删除——也可以保留它： POST /api/sandbox/claim（Bearer = 沙盒密钥，{"email": "..."}）会将其转换为持久的免费租户，并保留你构建的所有内容。

快速入门

直接连接托管端点。这是最稳健的选项——设备上无需运行任何内容，因此没有进程会崩溃或变得过时：

{
  "mcpServers": {
    "pullpush": {
      "type": "streamable-http",
      "url": "https://api.pullpush.ai/mcp",
      "headers": { "Authorization": "Bearer <your-api-key>" }
    }
  }
}

将其添加到 ~/.cursor/mcp.json（Cursor）、Claude Desktop 的配置，或客户端的 MCP 配置中。

仅支持 stdio 的客户端

将此软件包用作连接同一端点的本地 stdio 代理。安装一次固定版本，然后运行二进制文件——不要使用 npx ...@latest，因为每次客户端启动服务时，它都会重新解析软件包（并需要网络连接）：

npm i -g [email protected]

{
  "mcpServers": {
    "pullpush": {
      "command": "kaduno-pullpush-mcp",
      "env": { "PULLPUSH_API_KEY": "<your-api-key>" }
    }
  }
}

代理不会因 API 无法访问而退出：它会启动并响应客户端，同时在后台建立连接（采用指数退避，并遵循 Retry-After）。网络短暂中断或 API 重启后，它会重新连接；离线期间，工具调用会返回可重试的“正在重新连接”错误，且不会更改任何内容。工具目录会缓存在磁盘上，因此即使 API 停机时重启，仍会列出你的工具。

然后让 Agent 运行 get-started 提示词——它会引导你完成整个流程： 浏览连接器目录 → 创建并测试连接 → 建议字段映射 → 以影子模式创建工作流 → 预览差异 → 切换到正式运行。

获取 API 密钥

如需临时密钥，请使用上方的沙盒。如需持久租户：

1. 免费注册（1 个连接，每月 1,000 个事件——无需银行卡）
2. 管理面板 → 设置 → API 密钥
3. 创建具有所需作用域（租户、组织或管理员）的密钥

工具

涵盖完整集成生命周期的 48 个工具（30 个显式工具，以及 18 个领域路由器中的 188 个操作）。显式工具均有单独命名；领域路由器通过 action 参数接受多种操作。

连接

• pullpush.connection.create — 创建并配置与外部系统（Shopify、WooCommerce、Linnworks、Xero、HubSpot 等 20 多种系统）的连接
• pullpush.connection.test — 测试实时连接凭据；返回运行状况指标和故障次数
• pullpush.connection — 列出、获取、更新、删除和配置连接（路由器，支持的操作：list、get、update、delete、health、config）

流

• pullpush.flow.create — 配置源→目标同步管道，包含触发器、映射和规范数据模型
• pullpush.flow.dryRun — 对流经转换/筛选的事件进行试运行，不执行传送；返回映射后的载荷
• pullpush.flow.natural — 根据自然语言描述创建流；提出映射方案并以影子模式创建
• pullpush.flow — 列出、获取、更新、暂停/恢复、删除流并查看传送历史记录（路由器）

同步与对账

• pullpush.sync.reconcile — 对账并传送：比较源与目标的差异，然后传送更改并显示每项进度
• pullpush.sync — 预览差异、创建数据快照、检查单个键、扫描目录、诊断未匹配的 SKU、管理基线（路由器，支持的操作：preview、snapshot、inspect、reconcile、scan、reset-baseline、baseline.history、baseline.rollback、channel-cache、unmatched）

字段映射

• pullpush.mapping.suggest — AI 根据源样本向目标结构提出字段映射；返回映射、置信度和预览
• pullpush.mapping.validate — 根据源和目标架构验证映射配置
• pullpush.mapping.compare — 并排比较两个映射
• pullpush.mapping.explain — 逐步说明映射如何转换数据
• pullpush.mapping.diff — 比较两个映射版本的差异，查看更改内容
• pullpush.mapping.get — 获取流当前的映射配置、源字段和目标字段

诊断

• pullpush.explain — 诊断流、连接或传送失败的原因；收集错误、识别模式并建议修复方法
• pullpush.diagnose.recent — 扫描所有流中的近期故障；返回按优先级排序的问题列表
• pullpush.ask — 根据租户故障和异常解答自然语言运维问题

连接器编写

• pullpush.connector.generate — 由 AI 生成 TypeScript 连接器代码、进行类型检查和测试，并完成注册
• pullpush.connector — 列出、获取、更新和管理连接器定义（路由器）

数据操作

• pullpush.data.push — 将文件数据（CSV、JSON、XML）推送到连接
• pullpush.import — 基于文件的数据导入操作（路由器）
• pullpush.export — 定时导出管道：创建、列出、更新、删除、测试、运行（路由器）
• pullpush.canonical — 检查和管理规范数据模型（路由器）

影子模式与安全性

• pullpush.shadow — 在正式上线前以只读方式运行集成；比较影子模式与实时结果（路由器）

批量操作

• pullpush.batch.test — 并行测试多个连接
• pullpush.batch.status — 获取所有流的状态矩阵
• pullpush.batch.setup — 一次调用完成设置：在一个操作中创建连接和流并进行测试
• pullpush.batch — 多流批量操作和主动报告（路由器）

运维与健康状况

• pullpush.health.overview — 租户健康状况仪表板：连接、流程、故障、积压、交付率、异常
• pullpush.health.mcp — MCP 服务健康状况：数据库、已注册工具、运行时间
• pullpush.ops — 异常检测、死信恢复、运维监控（路由器）

工作流

• pullpush.workflow.create — 创建包含触发器和步骤 DAG 的多步骤工作流
• pullpush.workflow.trigger — 根据现有事件手动触发一次工作流运行
• pullpush.workflow — 列出、获取和管理工作流（路由器）

集成与市场

• pullpush.integration.create — 创建集成，将流程/工作流归入同一名称下
• pullpush.integration — 列出和管理集成（路由器）
• pullpush.marketplace.install — 将市场条目安装到你的租户
• pullpush.marketplace — 浏览和管理市场连接器（路由器）
• pullpush.destination.provision — 在目标 API 上配置自定义字段（例如 HubSpot 属性）

管理

• pullpush.tenant — 租户管理：列出、获取、创建、更新（路由器）
• pullpush.billing — 订阅和用量管理（路由器）
• pullpush.partner — 合作伙伴计划运营（路由器）
• pullpush.backup — 备份与恢复操作（路由器）
• pullpush.feedback — 提交有关 MCP 工具质量或缺失功能的反馈

完整工具参考：pullpush.ai/docs/mcp

环境变量

变量	必需	默认值	说明
PULLPUSH_API_KEY	是	—	你的 PullPush API 密钥
PULLPUSH_API_URL	否	https://api.pullpush.ai	API 基础 URL（可覆盖，用于可自托管部署）
PULLPUSH_CACHE_DIR	否	OS 缓存目录	工具目录的缓存位置
PULLPUSH_TIMEOUT_MS	否	55000	工具调用在代理返回超时错误前允许等待的时间

身份验证范围

范围	访问权限
租户密钥	你所在租户的连接、流程、同步和诊断信息
组织密钥	组织中的所有租户（只读或读写）
管理员密钥	完整平台访问权限（账单、合作伙伴、所有租户）

工具会自动限定访问范围：租户密钥无法查看其他租户的数据。

功能

• 连接故障时也不会崩溃：即使 API 不可用也会启动，自动重新连接， 同时提供缓存的工具目录
• 自动刷新：工具目录每 5 分钟刷新一次——无需重启即可显示服务端新增的工具 （仅当目录确实发生变化时才会通知客户端）
• 离线快速入门：内置的 pullpush://docs/quickstart-local 资源无需网络即可使用
• 未知工具时重试：找不到工具时自动刷新目录
• 清晰的错误消息：说明身份验证失败、网络问题和版本不匹配

文档

• 入门指南 — 5 分钟完成首次集成
• MCP 指南 — 完整工具参考和客户端设置
• 影子模式 · 预览与协调 · 安全
• llms.txt — 机器可读的产品摘要
• 机器可读的集成目录
• MCP 注册表条目：ai.pullpush/pullpush-mcp

另有提供：pullpush-mcp-dev

对于连接器作者、平台管理员和内部开发者， pullpush-mcp-dev 提供以下额外工具：

• AI 驱动的连接器生成与组合
• 规范架构管理
• 市场发布
• 账单与合作伙伴管理
• 跨所有租户的批量操作

开发

git clone https://github.com/Kaduno-systems/pullpush-mcp.git
cd pullpush-mcp
npm install
npm run dev    # Run from source via tsx
npm run build  # Compile with tsup

此仓库是 MCP 客户端软件包的已发布镜像；平台本身在私有 monorepo 中开发。欢迎在此处或通过 [email protected] 提交问题和提问。

许可证

MIT

开发

开发工作在 PullPush 平台 monorepo 中进行；Kaduno-systems/pullpush-mcp 仓库是每个版本的已发布镜像。欢迎在那里提交问题；代码变更通过 monorepo 提交。