timezest-mcp

⏰ TimeZest MCP 服务

通过模型上下文协议（MCP），将 TimeZest 排期数据直接接入 Claude。使用自然语言实时查询预约、生成工程师简报，以及管理与工单关联的排期。

注册表 ID： io.github.sagarkalra-tech/timezest-mcp

---

🌟 为什么选择 TimeZest MCP？

如果你管理的团队使用 TimeZest 和 ConnectWise，一定深有体会：在不同标签页间切换、手动检查谁已预约、追踪尚未安排的排期请求，还要交叉核对工单编号。

这个 MCP 服务可将 Claude 变成一名排期助手，能够：

• 🗓️ 按工程师分组，提供今日已确认预约的晨间简报
• 🔍 按工单编号查找预约——只需说“查找工单 #964400 的预约”
• ⏳ 找出需要跟进的长期未安排请求
• 📊 生成团队的排期汇总统计
• 🕐 为全球 MSP 团队提供时区准确的报告

---

🚀 30 秒快速开始

前提条件

• Node.js 20+ — 在此下载
• TimeZest API 密钥 — 在 TimeZest → Settings → API 中获取

选项 1：Claude Desktop（推荐）

将以下内容添加到 Claude Desktop 配置文件中：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "timezest": {
      "command": "npx",
      "args": ["-y", "timezest-mcp@latest"],
      "env": {
        "TIMEZEST_API_KEY": "your-timezest-api-key-here"
      }
    }
  }
}

重启 Claude Desktop。完成。

选项 2：Claude Code CLI

claude mcp add-json timezest-mcp '{
  "command": "npx",
  "args": ["-y", "timezest-mcp@latest"],
  "env": {
    "TIMEZEST_API_KEY": "your-timezest-api-key-here"
  }
}'

选项 3：VS Code（Copilot）

添加到 .vscode/settings.json 或用户设置中：

{
  "mcp": {
    "servers": {
      "timezest": {
        "command": "npx",
        "args": ["-y", "timezest-mcp@latest"],
        "env": {
          "TIMEZEST_API_KEY": "your-timezest-api-key-here"
        }
      }
    }
  }
}

---

🛠️ 可用工具

该服务提供 8 个专用工具，供 Claude 调用：

工具	描述	关键参数
get_todays_appointments	晨间简报——按工程师分组的今日已确认预约，以及待处理的未安排请求	timezone
list_appointments	查询任意日期范围，可选用筛选条件	start_date、end_date、engineer_name、status
get_engineer_schedule	指定工程师的所有即将到来的预约，按时间排序	engineer_name、days_ahead、include_pending
list_pending_requests	未安排的邀请（已发送/新建），并按小时/天追踪时长	days_back、engineer_name、older_than_hours
find_appointment_by_ticket	查找与 ConnectWise 工单编号关联的预约	ticket_number（例如 964400 或 #964400）
get_appointment_types	列出 TimeZest 中配置的所有预约类型定义	—
get_appointment_stats	汇总：按状态、按工程师统计的数量，今日工作量，最早的待处理项	days_back、days_forward
list_cancelled_appointments	已取消的请求及其用于重新预约的排期 URL	days_back、engineer_name

---

💬 示例提示词

连接后，只需用自然语言与 Claude 对话：

"Who are my top engineers today and what are they booked for?"

"Find any TimeZest requests for ticket #964400."

"Give me a morning briefing of today's confirmed vs. unbooked requests."

"Show me all pending scheduling requests older than 48 hours."

"What's the scheduling volume breakdown for the last two weeks?"

"Pull up Sarah's schedule for the next 5 days."

"List all cancelled appointments from last week — any we should rebook?"

---

⚙️ 配置

环境变量	必需	默认值	用途
TIMEZEST_API_KEY	是	—	你的 TimeZest Bearer 令牌（Settings → API）
TIMEZEST_DEFAULT_TZ	否	America/Chicago	用于本地化显示字符串的默认 IANA 时区
TIMEZEST_WINDOW_DAYS_BACK	否	14	向前回溯多少天获取排期请求
TIMEZEST_WINDOW_DAYS_FORWARD	否	30	向后延伸多少天获取排期请求

---

🏗️ 架构

┌─────────────────────────────────────────────────────────────────┐
│                        MCP CLIENT (Claude)                      │
│        Desktop App  •  Claude Code CLI  •  IDE Plugin           │
└──────────────────────────┬──────────────────────────────────────┘
                           │ Stdio (JSON-RPC)
┌──────────────────────────▼──────────────────────────────────────┐
│                     TIMEZEST MCP SERVER                         │
│                                                                 │
│  ┌──────────────┐  ┌──────────────┐                             │
│  │ Tool Handler │  │  MCP SDK     │  (index.ts)                 │
│  │ (8 Tools)    │  │  Registry    │                             │
│  └──────┬───────┘  └──────────────┘                             │
│         │                                                       │
│  ┌──────▼────────────────────────────────────────────────────┐  │
│  │                 TIMEZEST API CLIENT                        │  │
│  │  Pagination • Retry Logic • Rate Limit Management         │  │
│  └──────────────────────┬────────────────────────────────────┘  │
│                         │ (client.ts)                            │
│  ┌──────────────────────▼────────────────────────────────────┐  │
│  │               DATA TRANSFORMATION LAYER                    │  │
│  │  Timezone Math • Engineer Mapping • Ticket Linking         │  │
│  └────────────────────────────────────────────────────────────┘  │
│                         │ (utils/)                               │
└─────────────────────────┼────────────────────────────────────────┘
                          │ HTTPS / REST
┌─────────────────────────▼──────────────────────────────────────┐
│                      TIMEZEST API (v1)                          │
│       Scheduling Requests • Appointment Types • Resources       │
└─────────────────────────────────────────────────────────────────┘

关键设计决策

• 只读：有意保持只读，不会修改您的日程数据
• 弹性客户端：采用指数退避机制，并自动支持针对 429/5xx 错误的 Retry-After 标头
• 深度分页：递归抓取所有页面（每批 50 项），以构建完整数据集
• 时区精度：将 Unix 时间戳转换为严格的 ISO 格式，并使用 IANA 时区标识符生成本地化显示字符串
• 工程师解析：采用“最高置信度”搜索，先检查 scheduled_agents，再回退到 resources
• 预热缓存：首次获取预约类型后会将其缓存，以减少 API 开销

---

🧪 测试

此服务附带全面的 Vitest 测试套件，包含 3 个文件中的 22 项测试：

测试文件	测试数量	覆盖范围
transform.test.ts	8	工程师解析、工单提取、时区转换、优雅处理缺失字段
filter.test.ts	6	不区分大小写的部分匹配、团队名称匹配、日期范围筛选
client.test.ts	8	预约类型缓存、分页、429/5xx 错误重试、4xx 错误不重试

所有测试均使用模拟的 API 响应——不会调用实时 API，也不需要密钥。

npm test            # Single run
npm run test:watch  # Re-runs on file save

---

🔒 安全与可信度

• NPM 来源证明：每个版本均通过 GitHub Actions OIDC 进行加密签名
• CI/CD 流水线：在标记版本时自动构建 → 测试 → 发布（无需手动执行 npm publish）
• CI 中不使用密钥：测试无需 API 密钥，使用模拟响应即可完全确定性地运行
• Node.js 版本矩阵：已在 Node 20（LTS）和 22（Current）上测试

---

📦 分发渠道

渠道	链接
NPM	timezest-mcp
MCP Registry	io.github.sagarkalra-tech/timezest-mcp
GitHub	sagarkalra-tech/TimeZest-MCP

---

🤝 参与贡献

1. Fork 此代码仓库
2. 创建功能分支（git checkout -b feat/my-feature）
3. 修改代码并确保测试通过（npm test）
4. 提交拉取请求

请参阅 ARCHITECTURE.md，深入了解数据流、组件设计和转换逻辑。

---

📄 许可证

MIT © 2026 Sagar Kalra