TimeZest

TimeZest MCP サーバー

TimeZest スケジューリングプラットフォーム向けの MCP（Model Context Protocol）サーバーです。LLM エージェントが PSA と連携して、技術者のスケジューリングリクエストを作成・管理できます。

機能

• 🎯 フラットなツールリスト - すべてのツールが一覧表示され、すぐに呼び出せます
• 📅 スケジューリングの全ライフサイクル - リクエストの作成、表示、キャンセル
• 🔗 PSA 連携 - ConnectWise、Autotask、Halo に対応
• 🌍 IANA タイムゾーン処理 - タイムゾーンを明示的に管理
• 🚀 2 種類のトリガーモード - PSA ワークフローまたは予約 URL
• 🛡️ ゲートウェイ対応 - リクエストごとにステートレスな設計
• 🔍 TQL フィルタリング - TimeZest Query Language に対応
• ✨ エリシテーション対応 - 対話形式のユーザープロンプト
• 📇 インタラクティブなスケジューリングリクエストカード（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	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として 1 を正確に設定してください。プロセスは警告を記録し、X-Gateway-S2S を必須とせず、MCP_HTTP_HOST により広いアドレスが指定されていても、リスナーを 127.0.0.1 に固定します。既知のプレースホルダーシークレットは引き続き拒否されます。
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>（ヘッダーに表示されるものと同じプレフィックス）を、CONDUIT_S2S_SECRET を鍵として HMAC-SHA256 で計算し、小文字の 16 進数で表した値です。タイムスタンプはサーバー時刻から 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 - 接続ステータスと利用可能なツールを表示

エージェント

• timezest_agents_list - 個々の技術者を一覧表示
• timezest_agents_get - エージェントの詳細を取得

チーム

• timezest_teams_list - チームを一覧表示（ラウンドロビン方式のスケジュール設定）
• timezest_teams_get - チームの詳細を取得

予約タイプ

• timezest_appointment_types_list - 利用可能なサービスの種類を一覧表示
• timezest_appointment_types_get - 予約タイプの詳細を取得

リソース

• timezest_resources_list - すべてのリソースを一覧表示（エージェント＋チーム）

スケジュール設定（コアドメイン）

• 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 Query Language の例：

# 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 ゲートウェイモードでは、ポートをループバックインターフェースに公開し、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 のみにバインドされ、警告がログに記録されます。ループバック以外の 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 Gateway

このサーバーは、以下の機能を備えた WYRE MCP Gateway 向けに設計されています。

• リクエストごとのサーバーインスタンス（ステートレス）
• すべての /mcp リクエストでの X-Gateway-S2S 署名（HTTP 認証を参照）
• ゲートウェイモードでの X-Timezest-Api-Token 認証情報の注入。TIMEZEST_API_TOKEN へのフォールバックはありません
• 構造化されたエラーレスポンス
• フラットなツール一覧（移動先の状態なしで利用可能）

API の対応状況

TimeZest API	対応状況	備考
エージェント	✅ 一覧、取得	個々の技術者
チーム	✅ 一覧、取得	ラウンドロビン方式のスケジュール設定
予約タイプ	✅ 一覧、取得	サービスタイプの定義
リソース	✅ 一覧	エージェントとチームを統合
スケジュールリクエスト	✅ CRUD	中核となるスケジュール機能
TQL フィルタリング	✅ すべてのエンドポイント	TimeZest クエリ言語
PSA 連携	✅ すべてのシステム	ConnectWise、Autotask、Halo
Webhook	❌ 該当なし	TimeZest は webhook を提供していません

コントリビューション

開発ガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

Apache 2.0 — 詳細は LICENSE ファイルをご覧ください。

リンク

• TimeZest API ドキュメント
• TimeZest ヘルプセンター
• MCP プロトコル
• WYRE Technology