Time Doctor

Time Doctor MCP サーバー

Time Doctor の従業員向け時間追跡／生産性監視 API（会社、ユーザー、プロジェクト、タスク、時間の使い方に関する統計情報）を AI アシスタントおよび WYRE Conduit ゲートウェイで利用するための MCP サーバーです。

認証

Time Doctor の現行の公式ドキュメントに記載された API（https://timedoctor.redoc.ly、API Version 1.0.0）では、ユーザーが app.timedoctor.com にログインする際と同じメールアドレスとパスワードで認証します。クライアント ID／シークレットを使った別途のアプリ登録フローはありません。POST /api/1.0/login にメールアドレスとパスワードを送信すると、有効期間が 6 か月の JWT ベアラートークンが返されます（以降のすべての呼び出しで Authorization: JWT {token} を指定します）。このサーバーは認証情報の交換と、認証拒否時の再ログインを内部で処理するため、呼び出し側が指定する必要があるのはメールアドレスとパスワードだけです。

Time Doctor の一部のアカウントではログイン時に TOTP（2FA）コードが必要です。2FA が有効なアカウントは、現在このコネクターではサポートされていません。

設定

.env.example をコピーし、以下の変数を設定します。

環境変数	必須	説明
TIMEDOCTOR_EMAIL	stdio と AUTH_MODE=env の場合	Time Doctor アカウントのメールアドレスです。
TIMEDOCTOR_PASSWORD	stdio と AUTH_MODE=env の場合	Time Doctor アカウントのパスワードです。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http です。
AUTH_MODE	いいえ	gateway（Docker イメージと Compose）または env です。ゲートウェイモードでは、各 /mcp リクエストに X-TimeDoctor-Email と X-TimeDoctor-Password が必要で、TIMEDOCTOR_* へのフォールバックは行いません。env モードでは、S2S 認証に成功した後にのみこれらの環境変数を使用します。未設定の場合は env（stdio およびシングルテナント HTTP）になります。
CONDUIT_S2S_SECRET	HTTP の場合は必須	サービス間シークレットです。値が空、または既知のプレースホルダー（changeme、secret、replace-me、replace-with-a-real-secret およびその他の例示値）の場合、HTTP サーバーはエラーをログに記録して、ゼロ以外の終了コードで終了します。openssl rand -hex 32 で生成してください。Compose はこの値がないと起動しません。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として値を 1 に設定します。プロセスは警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみをバインドします。MCP_HTTP_HOST がループバック以外の場合は起動を拒否します。既知のプレースホルダーシークレットを設定した場合も起動を拒否します。
MCP_HTTP_HOST	いいえ	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定の場合は、従来どおり 0.0.0.0 をバインドします。イメージと Compose はコンテナー内で 0.0.0.0 を設定します。シークレットが設定されていない場合、MCP_ALLOW_INSECURE_DEV=1 により 127.0.0.1 が強制されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。
LOG_LEVEL	いいえ	debug | info（デフォルト）| warn | error です。

/health と /healthz は認証不要のままで、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http かつ CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S が必要です。検証処理は src/s2s-verify.ts の verifyS2sHeader で行います。ヘッダー値は t=<unix seconds>,v1=<hex> です。hex は、CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> のリテラル値に対して計算した HMAC-SHA256（小文字の 16 進数 64 文字）です。タイムスタンプはサーバー時刻との差が 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報を読み取る前に HTTP 401 を返します。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-TimeDoctor-Email: $TIMEDOCTOR_EMAIL" \
  -H "X-TimeDoctor-Password: $TIMEDOCTOR_PASSWORD" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway では、/mcp に X-TimeDoctor-Email と X-TimeDoctor-Password も必要です。これらのヘッダーだけが、そのリクエストで使用する認証情報の取得元です。AUTH_MODE=env でも署名付きの X-Gateway-S2S ヘッダーは必要です。その後、環境変数の TIMEDOCTOR_EMAIL と TIMEDOCTOR_PASSWORD を使用します。

リクエスト制限

• HTTP リクエスト本文は 256 KiB（262144 バイト）までです。X-Gateway-S2S のチェック（およびゲートウェイモードでは認証情報ヘッダーのチェック）を通過した後、Content-Length が上限を超えていると、JSON-RPC エラーとともに 413 が返されます。Content-Length のない本文は、MCP SDK トランスポートによって制限されます。未認証のリクエストには、引き続き最初に 401 が返されます。
• tools/call の引数は 10,000 要素までです（すべての配列項目とオブジェクトキーを、階層の深さにかかわらず数えます）。上限を超える入力には、固定メッセージ「Tool input exceeds the maximum of 10000 elements」を含む isError ツール結果が返され、ディスパッチされることはありません。

これらの制限は、CVE-2026-111768 / GHSA-46jr-4wx8-v453（検証中のメモリ枯渇）および GHSA-f897-62hf-6gxq（リクエスト本文／バッチの上限がない問題）に対処するものです。

ツール

会社

• timedoctor_list_companies - 認証済みユーザーが所有または管理する会社（ワークスペース）。
• timedoctor_get_company - ID で指定した単一の会社。

ユーザー

• timedoctor_list_users - ユーザーの一覧。会社で絞り込み、メールアドレス／名前でフィルタリングできます。
• timedoctor_get_user - ID で指定した単一のユーザー。
• timedoctor_check_invitation - メールアドレスに対する会社の招待が存在するかどうか（読み取り専用）。

プロジェクト

• timedoctor_list_projects - 会社内のプロジェクト。
• timedoctor_get_project - ID で指定した単一のプロジェクト。

タスク

• timedoctor_list_tasks - 会社内のタスク。プロジェクト、名前、またはオープン／クローズ状態でフィルタリングできます。
• timedoctor_get_task - ID で指定した単一のタスク。

アクティビティ／統計

• timedoctor_get_worklog - 指定した期間内における、ユーザーまたは会社の詳細な作業セッションログ（開始時刻、時間、タスク／プロジェクト、モード）。
• timedoctor_get_timeuse_stats - 指定した期間内における、ユーザーまたは会社の集計済み生産性統計（アプリケーション／カテゴリごとの時間、生産的／非生産的）。

対象範囲

これは、時間記録の監督に関する MSP の中核的なワークフロー、つまり「誰の時間がどこで記録されているか」と「時間がどのように配分されているか」をカバーする v1／MVP の機能範囲です。現時点では、ファイル（スクリーンキャスト／スクリーンショット）、カテゴリ、作業スケジュール（優先度の低い管理設定）、ユーザーの招待／作成／削除を行うすべての変更操作、および「ログイン」ユーザーなりすましエンドポイントは明示的に対象外です（実際にセキュリティ上の影響が大きい機能です）。需要があれば、後続の対応として追加できます。

開発

npm install
npm run build
npm test
npm run lint   # tsc --noEmit

# HTTP refuses to start until CONDUIT_S2S_SECRET is set
CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" npm run start:http

# Local HTTP only, without a service-to-service secret (binds 127.0.0.1)
MCP_ALLOW_INSECURE_DEV=1 MCP_HTTP_HOST=127.0.0.1 npm run start:http

Docker

イメージはコンテナ内で 0.0.0.0（MCP_HTTP_HOST）をリッスンし、デフォルトでは AUTH_MODE=gateway を使用します。ポートをループバックに公開し、実際の S2S シークレットを渡してください。ゲートウェイモードでは、Time Doctor の認証情報はリクエストごとにヘッダーとして渡され、環境変数からは読み込まれません。

docker build -t timedoctor-mcp .
docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -p 127.0.0.1:8080:8080 \
  timedoctor-mcp

CONDUIT_S2S_SECRET が設定されていない場合、Compose は起動を拒否します。ゲートウェイサービスは AUTH_MODE=gateway を設定し、TIMEDOCTOR_EMAIL または TIMEDOCTOR_PASSWORD を注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナント HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、TIMEDOCTOR_EMAIL と TIMEDOCTOR_PASSWORD を使用します。これは上記のゲートウェイ Compose サービスとは別の構成です。

docker run \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=env \
  -e [email protected] \
  -e TIMEDOCTOR_PASSWORD=your-password \
  -p 127.0.0.1:8080:8080 \
  timedoctor-mcp

シークレットを使用しないローカル HTTP は、開発専用です。127.0.0.1 にバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST（イメージのデフォルトである 0.0.0.0 を含む）を指定すると、起動時に終了します。

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 npm run start:http