timezest-mcp

⏰ TimeZest MCP サーバー

Model Context Protocol（MCP）を通じて、TimeZest のスケジュールデータを Claude に直接取り込めます。 リアルタイムの予約検索、エンジニア向けブリーフィング、チケットに紐づいたスケジュール管理を、すべて自然言語で行えます。

レジストリ ID： io.github.sagarkalra-tech/timezest-mcp

---

🌟 TimeZest MCP を選ぶ理由

ConnectWise と連携する TimeZest を使うチームを管理している方なら、タブを切り替えたり、誰が予約済みかを手動で確認したり、未予約のスケジュール依頼を追跡したり、チケット番号と照合したりする手間をご存じでしょう。

この 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"
        }
      }
    }
  }
}

---

🛠️ 利用可能なツール

このサーバーは、Claude が呼び出せる8 種類の専用ツールを公開します。

ツール	説明	主なパラメーター
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. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feat/my-feature）
3. 変更を加え、テストが通ることを確認します（npm test）
4. プルリクエストを送信します

データフロー、コンポーネント設計、変換ロジックの詳細については、ARCHITECTURE.md をご覧ください。

---

📄 ライセンス

MIT © 2026 Sagar Kalra