TimeZest

TimeZest MCP 服务

适用于 TimeZest 排程平台的 MCP（Model Context Protocol）服务。支持 LLM Agent 创建和管理技术人员排程请求，并集成 PSA。

功能

• 🎯 扁平工具列表 - 列出所有工具，可立即调用
• 📅 完整排程流程 - 创建、查看和取消请求
• 🔗 PSA 集成 - 支持 ConnectWise、Autotask、Halo
• 🌍 IANA 时区处理 - 明确管理时区
• 🚀 双触发模式 - PSA 工作流或预约 URL
• 🛡️ 支持网关 - 按请求无状态设计
• 🔍 TQL 筛选 - 支持 TimeZest Query Language
• ✨ 支持 Elicitation - 交互式用户提示
• 📇 交互式排程请求卡片（MCP Apps） - 在 MCP Apps 宿主中，timezest_scheduling_get 会渲染为卡片；默认采用中性色，可通过注入 window.__BRAND__ 或设置 MCP_BRAND_* 环境变量进行品牌定制

快速开始

Docker（推荐）

docker run -it --rm \
  -e TIMEZEST_API_TOKEN=your-api-token \
  ghcr.io/wyre-ai/timezest-mcp:latest

npm

npm install -g @wyre-ai/timezest-mcp
TIMEZEST_API_TOKEN=your-token timezest-mcp

配置

复制 .env.example，并设置以下变量。

环境变量	必需	描述
TIMEZEST_API_TOKEN	适用于 stdio 和 AUTH_MODE=env	TimeZest API 令牌。网关模式不会读取此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
MCP_HTTP_HOST	否	MCP_TRANSPORT=http 时的绑定地址。默认为 127.0.0.1。配置了 CONDUIT_S2S_SECRET 时会遵循此值。容器镜像使用 0.0.0.0。
AUTH_MODE	否	gateway（Docker 镜像和 Compose 默认值）或 env。网关模式要求每个 /mcp 请求都携带 X-Timezest-Api-Token，且绝不会回退到 TIMEZEST_API_TOKEN。env 仅在 S2S 身份验证成功后使用该变量。
CONDUIT_S2S_SECRET	HTTP 必需	服务间密钥。使用 openssl rand -hex 32 生成。如果该值为空或是已知占位符（changeme、your-s2s-secret、secret、placeholder 及类似公开示例），HTTP 服务会记录错误并以非零状态退出。未设置此值时，Compose 不会启动。切勿提交真实值。该值绝不会写入日志。
MCP_ALLOW_INSECURE_DEV	否	仅在本地开发时设为 1，以便在没有 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制执行 X-Gateway-S2S，并会强制将监听地址设为 127.0.0.1，即使 MCP_HTTP_HOST 是范围更广的地址。已知占位符密钥仍会被拒绝。
LOG_LEVEL	否	日志级别：debug、info（默认）、warn、error

/health 无需身份验证，也不会读取凭据。stdio 传输不会使用 CONDUIT_S2S_SECRET。

HTTP 身份验证

设置 MCP_TRANSPORT=http 和 CONDUIT_S2S_SECRET 后，每个 /mcp 请求都必须包含 X-Gateway-S2S。标头值如下：

t=<unix seconds>,v1=<hex hmac-sha256>

v1 是对精确 ASCII 字符串 t=<unix seconds>（与标头中显示的前缀相同）计算出的 HMAC-SHA256 小写十六进制值，密钥为 CONDUIT_S2S_SECRET。时间戳与服务器时钟的偏差不得超过 300 秒。缺少标头或标头无效时会返回 401。密钥绝不会写入日志。

t=$(date +%s)
sig=$(printf 't=%s' "$t" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
# X-Gateway-S2S: t=$t,v1=$sig

在 AUTH_MODE=gateway 模式下，/mcp 还要求提供 X-Timezest-Api-Token。该标头是此请求唯一的凭据来源。缺少标头时会返回 401，且服务器不会回退到 TIMEZEST_API_TOKEN。

工具

以下每个工具都已列出，可立即调用——无需先进入某个域。分组仅用于文档说明。

从 2.x 升级？ timezest_navigate 和 timezest_back 已移除。 没有替代工具：直接调用域工具即可，因为现在所有工具都已预先列出。以前会先调用 timezest_navigate({domain: "agents"})，再调用 timezest_agents_list 的客户端， 现在只需调用 timezest_agents_list——timezest_scheduling_list 等其他工具也一样。 timezest_status 仍然可用，现在会报告可用工具，而不是显示可进入的菜单。

状态

• timezest_status - 显示连接状态和可用工具

Agent

• timezest_agents_list - 列出各位技术人员
• timezest_agents_get - 获取 Agent 详情

团队

• timezest_teams_list - 列出团队（轮询排程）
• timezest_teams_get - 获取团队详情

预约类型

• timezest_appointment_types_list - 列出可用的服务类型
• timezest_appointment_types_get - 获取预约类型详情

资源

• timezest_resources_list - 列出所有资源（Agent + 团队）

排程（核心域）

• timezest_scheduling_list - 列出排程请求
• timezest_scheduling_get - 获取请求详情
• timezest_scheduling_create_request - 创建新请求（关键工具）
• timezest_scheduling_cancel - 取消请求

使用示例

查看可用内容

User: "What can TimeZest do?"
Tools: timezest_status

创建排程请求

User: "Book a technician for server repair at Customer Corp tomorrow"
Tools: timezest_scheduling_create_request({
  "appointmentTypeId": "repair-onsite",
  "triggerMode": "pod",
  "endUser": {
    "name": "John Doe",
    "company": "Customer Corp",
    "email": "[email protected]"
  },
  "timeRange": {
    "earliestDate": "2024-02-01",
    "earliestTime": "09:00",
    "latestDate": "2024-02-01", 
    "latestTime": "17:00",
    "timezone": "America/New_York"
  },
  "associatedEntities": [
    {"type": "connectwise", "id": "12345", "number": "T20240001"}
  ]
})

PSA 集成

将排程请求关联到 PSA 工单：

{
  "associatedEntities": [
    {"type": "connectwise", "id": "12345", "number": "T20240001"},
    {"type": "autotask", "id": "67890"},
    {"type": "halo", "id": "11111"}
  ]
}

触发模式

• pod：触发已配置的 PSA 工作流（创建日历条目、更新工单）
• generate_url：返回供客户使用的可分享预约 URL

TQL 筛选

TimeZest 查询语言示例：

# Active agents in IT department
filter: "active:true AND department:\"IT Support\""

# Recent scheduling requests
filter: "createdAt:>=2024-01-01 AND status:pending"

# Specific customer requests  
filter: "endUser.company:\"Important Customer\""

时区处理

**重要：**务必明确指定 IANA 时区。TimeZest 会按照指定时区解释排程时间窗口。

{
  "timeRange": {
    "earliestDate": "2024-02-01",
    "earliestTime": "09:00", 
    "timezone": "America/New_York"  // ✅ Required
  }
}

开发

本地设置

# Clone and install
git clone https://github.com/WYRE-AI/timezest-mcp.git
cd timezest-mcp
npm install

# Development with file dependency (replace before publish)
# Edit package.json: "@wyre-technology/node-timezest": "file:../node-timezest"

# Build and test
npm run build
npm test

# Run locally
TIMEZEST_API_TOKEN=your-token npm run dev

Docker 开发

镜像设置了 AUTH_MODE=gateway 和 MCP_HTTP_HOST=0.0.0.0。Stdio（在设置 MCP_TRANSPORT=http 前为镜像默认值）仍会读取 TIMEZEST_API_TOKEN，且不会使用 CONDUIT_S2S_SECRET。

# Build image
docker build -t timezest-mcp --build-arg NODE_AUTH_TOKEN=$GITHUB_TOKEN .

# Stdio
docker run -it --rm \
  -e TIMEZEST_API_TOKEN=your-token \
  -e LOG_LEVEL=debug \
  timezest-mcp

HTTP 网关模式会在 loopback 地址上发布端口，并传递 S2S 密钥。TimeZest 令牌会随每个请求通过 X-Timezest-Api-Token 传入；不会从环境变量中读取。使用 openssl rand -hex 32 生成密钥——changeme 或 your-s2s-secret 等示例占位值会被拒绝。

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker run --rm \
  -e MCP_TRANSPORT=http \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  timezest-mcp

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动。网关服务会设置 AUTH_MODE=gateway，且不会注入 TIMEZEST_API_TOKEN 或 env_file：

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

单租户 HTTP（AUTH_MODE=env）仍要求提供 S2S 密钥，然后使用 TIMEZEST_API_TOKEN：

docker run --rm \
  -e MCP_TRANSPORT=http \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e TIMEZEST_API_TOKEN=your-token \
  -p 127.0.0.1:8080:8080 \
  timezest-mcp

不提供密钥的本地 HTTP 仅用于开发。它只绑定到 127.0.0.1，并会记录警告。非 loopback 的 MCP_HTTP_HOST 会被覆盖：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run dev

MCP 集成

Claude Desktop

将以下内容添加到 MCP 设置中：

{
  "mcpServers": {
    "timezest": {
      "command": "npx",
      "args": ["@wyre-ai/timezest-mcp"],
      "env": {
        "TIMEZEST_API_TOKEN": "your-api-token"
      }
    }
  }
}

WYRE 网关

此服务专为 WYRE MCP Gateway 设计，具备以下特性：

• 每个请求都会创建独立的服务实例（无状态）
• 每个 /mcp 请求都会使用 X-Gateway-S2S 签名（参见HTTP 身份验证）
• 网关模式下通过 X-Timezest-Api-Token 注入凭据，不回退使用 TIMEZEST_API_TOKEN
• 结构化错误响应
• 扁平工具列表（无需进入任何导航状态）

API 覆盖情况

TimeZest API	覆盖情况	备注
Agents	✅ 列表、获取	单个技术人员
Teams	✅ 列表、获取	轮流调度
Appointment Types	✅ 列表、获取	服务类型定义
Resources	✅ 列表	统一的 Agents + Teams
Scheduling Requests	✅ CRUD	核心调度功能
TQL Filtering	✅ 所有端点	TimeZest 查询语言
PSA Integration	✅ 所有系统	ConnectWise、Autotask、Halo
Webhooks	❌ 不适用	TimeZest 不提供 Webhook

贡献

开发指南请参阅 CONTRIBUTING.md。

许可证

Apache 2.0，详情请参阅 LICENSE 文件。

链接

• TimeZest API 文档
• TimeZest 帮助中心
• MCP 协议
• WYRE Technology