crisphive

Crisphive MCP

Crisphive API 的官方 MCP（Model Context Protocol）服务 （Crisphive API）——面向现场运营的 Agent 式 AI 调度 基础设施。

让 AI Agent（Claude、ChatGPT、Gemini、Cursor 或任何 MCP 客户端）根据 位置、技能和实时空闲情况匹配客户与企业的日程，并为工作安排团队路线：工作预订与预约 调度、工单跟踪、来自实时派遣与调度引擎的空闲情况、客户（CRM）同步、服务目录、 技术人员与团队名册、地理服务区域和车队 ——适用于暖通空调、水管、电气、清洁、家电维修和物业维护等行业及家庭服务。调度基于约束条件， 由确定性求解器完成：Agent 负责对话，求解器负责决策——输入相同，计划始终相同，不会让大模型 猜测日历安排。托管的远程服务；无需安装或运行任何内容（此仓库包含文档和注册表清单）。

https://api.crisphive.com/mcp

首先试试这些

连接（chsk_test_ 沙盒密钥即可），然后将以下任一提示词直接粘贴到你的 Agent 中：

1. 创建工作——“安排明天在 145 Laurier Ave W 为 Marie Tremblay 提供 2 小时的暖通空调服务， 电话号码为 613-555-0142。” （createCustomer → listJobRequestBookingWindows → createJobRequest → quoteJobRequest → confirmJobRequest）
2. 插入紧急任务——“现在在 99 Bank St 为 David Okafor 安排紧急水管维修 （613-555-0198）——给我看看哪些任务会被重新安排。” （listEmergencyCandidates → previewEmergencyReschedule → commitEmergencyReschedule）
3. 每日概览——“概述我明天的日程，并标记所有有风险的事项。” （listJobRequests → getTechnicianSchedule） . 病假替补——“Dmitri 请了明天的病假——重新安排他的工作，但不要改动任何客户的预约。” （previewAbsenceResolve → commitAbsenceResolve）

Crisphive 的每个目录页面和文档页面都展示相同的提示词，因此你在此处看到的内容 就是各处完全一致的首次使用体验。

→ 完整概览、工具表格和一键连接：https://crisphive.com/claude

要求

任何支持通过 Streamable HTTP 使用远程服务的 MCP 客户端均可使用—— claude.ai、Claude Desktop、Claude Code、ChatGPT、Gemini CLI、Cursor、VS Code、 Windsurf、Cline、Zed、LM Studio 等。

安装

claude.ai / Claude Desktop（OAuth——无需密钥）

设置 → 连接器 → 添加自定义连接器，粘贴 https://api.crisphive.com/mcp。当同意页面打开时，以 Crisphive 企业所有者身份登录。 （自定义连接器需要支持该功能的 Claude 计划。）

Claude Code

# OAuth (you'll be prompted to authorize in the browser)
claude mcp add --transport http crisphive https://api.crisphive.com/mcp

# or with an API key (sandbox key shown — safe to experiment)
claude mcp add --transport http crisphive https://api.crisphive.com/mcp \
  --header "Authorization: Bearer chsk_test_YOUR_KEY"

Cursor

或者添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "crisphive": { "url": "https://api.crisphive.com/mcp" }
  }
}

VS Code

code --add-mcp '{"name":"crisphive","url":"https://api.crisphive.com/mcp"}'

ChatGPT

设置 → 连接器（开发者模式）→ 使用 URL https://api.crisphive.com/mcp 添加 MCP 服务（OAuth）。

Gemini CLI

添加到 ~/.gemini/settings.json（注意：Gemini CLI 对 Streamable HTTP 服务使用 httpUrl）：

{
  "mcpServers": {
    "crisphive": {
      "httpUrl": "https://api.crisphive.com/mcp",
      "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" }
    }
  }
}

其他 MCP 客户端（Windsurf、Cline、Zed、LM Studio 等）

大多数客户端都接受标准的远程服务配置格式：

{
  "mcpServers": {
    "crisphive": {
      "url": "https://api.crisphive.com/mcp",
      "headers": { "Authorization": "Bearer chsk_test_YOUR_KEY" }
    }
  }
}

只有少数客户端的 URL 字段名称有所不同：

客户端	配置文件	URL 字段
Cline / Roo Code	cline_mcp_settings.json	url
Windsurf	~/.codeium/windsurf/mcp_config.json	serverUrl
Gemini CLI	~/.gemini/settings.json	httpUrl
Zed	settings.json → context_servers	url

仅支持 stdio 的客户端可以通过 mcp-remote桥接：

{
  "mcpServers": {
    "crisphive": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.crisphive.com/mcp"]
    }
  }
}

本地服务（npm — @crisphive/mcp）

本仓库还提供了一个轻量的本地 stdio 服务：包含相同的 67 个工具 （名称和架构相同，均根据与托管端点相同的 /v1 OpenAPI 规范生成），每次调用都会使用你的密钥向 Crisphive API 发起 HTTPS 请求。本地不会运行任何业务逻辑。

{
  "mcpServers": {
    "crisphive": {
      "command": "npx",
      "args": ["-y", "@crisphive/mcp"],
      "env": { "CRISPHIVE_API_KEY": "chsk_test_YOUR_KEY" }
    }
  }
}

环境变量：

变量	必需	含义
CRISPHIVE_API_KEY	调用工具时需要	chsk_live_… = 生产数据，chsk_test_… = 隔离的沙盒。请在控制面板中创建密钥（Developers → API keys）。
CRISPHIVE_BASE_URL	否	API 源地址覆盖值（默认值为 https://api.crisphive.com）。

如果客户端支持，请优先使用托管的远程服务（https://api.crisphive.com/mcp）——支持 OAuth，无需处理密钥，并始终保持最新。本地软件包适用于仅支持 stdio 的客户端和可自托管的部署。

在此仓库中开发：npm ci && npm test。工具注册表 （src/tools.generated.json）由程序生成——npm run generate 会根据实时规范刷新它；如果注册表与 /v1 不一致，CI 就会失败。

身份验证

每个请求都使用作为 bearer token 发送的 API 密钥进行身份验证。请在 Crisphive 商业控制面板中创建密钥。密钥前缀决定数据环境：

• chsk_live_… → 实时（生产）数据
• chsk_test_… → 沙盒（隔离的测试）数据

从环境中读取密钥——切勿将密钥提交到代码库。

密钥会过期。 创建密钥时会选择其有效期——默认为 30 天，最长为 365 天；密钥的有效期在其生命周期内固定，之后无法延长。如需续期，请创建第二个密钥，将你的 Agent 指向该密钥，然后撤销第一个密钥：企业可以同时持有多个有效密钥，因此切换过程不会中断服务，也无需使用特殊端点（AWS 对访问密钥记录的流程也是如此）。从控制面板或密钥 API 中读取 expires_at，并安排切换。过期的密钥会返回 API_KEY_EXPIRED，这与 API_KEY_INVALID 不同，因此你可以分别针对错过续期和密钥撤销设置提醒。

密钥到期前 7 天（OAuth 连接为 14 天），Crisphive 会向企业所有者发送电子邮件，因此密钥过期不应让人措手不及——但邮件会发给企业，不一定会发给你，所以请自行跟踪 expires_at。如果密钥的有效期特意设置为少于 7 天，就不会收到提前通知；创建密钥时已会收到通知。

MCP 端点还支持面向终端用户连接器（claude.ai、ChatGPT 等）的 OAuth 2.1：企业所有者在授权页面上为你的 Agent 授权，无需处理任何密钥。符合规范的 MCP 客户端会自动完成整个流程——发现、动态客户端注册、授权码 + PKCE。完整流程、范围和令牌有效期： docs/integration.md。

工具

共 67 个工具，每个工具对应公开 /v1 API 中的一项操作，名称与 SDK 方法相同（listCustomers、createJobRequest 等），并基于同一份 OpenAPI 规范生成，因此 REST 和 MCP 始终保持一致。完整参考： docs/tools.md。

分组	工具
客户（CRM 同步，完整 CRUD）	listCustomers · createCustomer · getCustomer · updateCustomer · deleteCustomer
预约（创建和跟踪）	createJobRequest · listJobRequests · getJobRequest · getJobRequestTimeline · listJobRequestBookingWindows · listJobRequestChanges
目录（读取）	listJobTypes · getJobType · listSkills · listSkillCategories · listSkillsByCategory · listServiceAreas · getServiceArea
目录管理（导入同步）	createJobType · updateJobType · deleteJobType · createSkillCategory · deleteSkillCategory · createSkill · updateSkill · deleteSkill · createServiceArea · updateServiceArea · deleteServiceArea · createVehicle · updateVehicle · deleteVehicle
团队和车队（读取）	listTechnicians · getTechnician · listVehicles · getVehicle
团队名册管理（HR 系统同步）	listAssignableGroups · createTechnician · updateTechnician · deleteTechnician · replaceTechnicianBuddies · replaceTechnicianLeads · replaceTechnicianVehicles · replaceTechnicianServiceAreas · replaceTechnicianSkills · listTechnicianSkills
匹配和排程（只读，由引擎计算）	listMatchingSlots · listCrewCandidates · getTechnicianSchedule · listNearbyTechnicians
排程操作（调整排程）	quoteJobRequest · confirmJobRequest · bookAndConfirmJobRequest · previewJobRequestMove · commitJobRequestMove
优先级和紧急调度（P0–P3、SLA、级联）	updateJobPriority · listEmergencyCandidates · previewEmergencyReschedule · commitEmergencyReschedule
缺勤处理（病假电话通知——为技术人员全天的工作重新安排人员）	previewAbsenceResolve · commitAbsenceResolve
技术人员休假（记录病假／休假、读取现有休假，并在他们返岗时删除记录）	createTechnicianTimeOff · listTechnicianTimeOff · deleteTechnicianTimeOff
Webhook（REST-hook 触发器：订阅／取消订阅）	listWebhookEventTypes · createWebhookEndpoint · deleteWebhookEndpoint

典型 Agent 工作流：

listSkills / listJobTypes                → discover reference IDs
createCustomer                           → { customer_id }
listJobRequestBookingWindows             → offer only the returned windows
createJobRequest                         → booking created
quoteJobRequest → confirmJobRequest      → scheduled (auto or forced technician)
   (quote answers 409 JOB_REQUEST_QUOTE_NOT_SCHEDULABLE when the customer
    would see no slot — agree a new time, or resend with force: true)
getJobRequest / listJobRequestChanges    → track status

电话通话或自动化的一次调用工作流（语音 Agent：连接到 https://api.crisphive.com/mcp?profile=voice，以使用精简的工具集）：

listCustomers (phone: "+16135550188")    → is the caller already a customer?
bookAndConfirmJobRequest                 → booked + scheduled, or confirmed:false + refusal
                                           (the job then waits in the coordinator's queue)

紧急情况（P0）工作流：

createJobRequest (priority: "p0") → quoteJobRequest
listEmergencyCandidates                  → ranked techs + crew_recommendation
previewEmergencyReschedule               → what moves (or reassigns)
commitEmergencyReschedule                → inserted + auto-confirmed
   (or preview with an inline `job` probe, then bookAndConfirmJobRequest
    with priority p0 + emergency{dispatch: "now"} books and commits in one call)

病假电话通知工作流（技术人员无法出勤——在不变更时间的情况下，为其排班中的每项工作重新安排人员）：

previewAbsenceResolve                    → who takes each job; nothing written
createTechnicianTimeOff                  → record the sick day (lands pending — enough for the commit)
commitAbsenceResolve                     → apply exactly the previewed plan, all-or-nothing

分页

列表工具接受 page / limit，并返回 meta 对象（total、 count、per_page、current_page、total_pages）。

幂等性

创建／提交工具（createCustomer、createTechnician、createJobRequest、 confirmJobRequest、commitJobRequestMove、commitEmergencyReschedule、commitAbsenceResolve） 接受 idempotency_key 参数，确保重试不会创建重复项——重试时传入相同的值。

错误

每个工具都会返回 Crisphive 响应封装（以文本和 structuredContent 形式）：成功时 error_code 为 0，失败时则为稳定的字符串（CUSTOMER_NOT_FOUND、API_KEY_INVALID 等）。请根据错误代码进行判断，切勿匹配错误消息字符串。

文档

• 文档：https://docs.crisphive.com
• MCP：https://docs.crisphive.com/mcp
• API 参考：https://docs.crisphive.com/technical-reference
• Webhook：https://docs.crisphive.com/webhook
• AI 相关（OpenAPI 规范和助手引导配置）：https://docs.crisphive.com/for-ai
• 客户端集成指南：docs/integration.md
• 工具参考：docs/tools.md

隐私与支持

• 隐私政策： https://crisphive.com/privacy-policy — Crisphive 仅处理可通过 API 访问的业务数据（客户、预约、技术人员、车队），以提供本服务；不会出售个人信息。只要账户处于活跃状态，数据就会被保留，并且仅在必要时与服务提供商/子处理商共享。通过 MCP 连接的 Agent 代表授权企业行事，其访问范围仅限于该企业的数据、环境（正式环境或沙盒）及已授予的权限。
• 支持： [email protected]

许可证

MIT