temporal-mcp

temporal-mcp

あなたのモデルは微積分を知っていますが、今日が何日かは知りません。それを解決しましょう。

temporal-mcp は、小規模な Model Context Protocol サーバーで、LLM エージェントがターンとターンの間の時間を把握できるようにします。ツールは 2 つ、数百行のコード、標準ライブラリ + mcp + platformdirs。それだけです。

問題

午後 11 時に新しいチャットを始めると、モデルが「おはようございます」と言います。3 週間後に会話を再開すると、モデルは時間が経っていないかのように、文の途中から話を続けます。「今日の状況」を尋ねると、昨日の状況が返ってきます。それとも先週の火曜日の状況かもしれません。

LLM には壁時計がありません。最後のユーザーメッセージがいつだったか、日付が変わったか、これが新しいスレッドなのか、長い間隔を空けて再開したスレッドなのかもわかりません。たいていの場合、これは問題になりません。ですが、ときにはエージェントが冷凍睡眠から目覚めたばかりのように聞こえることがあります。

解決策

スレッドごとに永続化される最終確認時刻のログを、2 つの MCP ツールとして公開します。

• temporal_tick — ユーザーのターンごとに 1 回呼び出します。モデルが読み取れる形式で、「前のメッセージから 14 分経過、日付の変更なし、タイムゾーンは MDT」 と返します。
• temporal_peek — 同じ情報を返しますが、状態は更新しません。ターンを始めたことにせず、間隔だけを確認したい場合に使います。

以上です。時間は存在します。モデルもそれを知っておくべきです。

10 秒で試す

curl -s -X POST https://temporal-mcp.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(uuidgen)" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"temporal_tick",
        "arguments":{"thread_key":"try-it","tz_offset_minutes":-360,"tz_name":"MDT"}}}' \
| python3 -c 'import sys,json; print(json.load(sys.stdin)["result"]["content"][0]["text"])'

次のように表示されます。

[temporal] Wed May 13, 10:42 AM MDT | fresh thread (no prior history)
{...JSON payload...}

2 回実行すると、2 回目の応答に間隔が表示されます。明日実行すると、day rollover: yes が返ります。それがすべてです。

得られるもの

すべての tick は、人が読めるヘッダーと JSON ペイロードを返します。

[temporal] Wed May 13, 9:42 AM MDT | last prompt 14m ago (Wed 9:28 AM)

{"thread_key": "mcp:abc123", "now": 1747158120.0, "prev": 1747157280.0,
 "delta_sec": 840, "day_rollover": false, "fresh_thread": false,
 "tz_name": "MDT", "tz_offset_sec": -21600, "available": true, "error": ""}

ヘッダーはモデル用です。JSON はコード用です。day_rollover を使って何か面白いこと（異なる挨拶をする、コンテキストを再読み込みする、「今日の項目」を再計算するなど）をしたい場合や、delta_sec を使って何かをしたい場合（関連性を減衰させる、再開されたセッションを検出する、アイドル状態のスレッドにフラグを付けるなど）に利用できます。

使い方は 2 通り

1. ホステッドエンドポイント — claude.ai、ChatGPT、モバイル

claude.ai のウェブ版、ChatGPT、または リモート MCP サーバーを必要とするその他のサービスを使う場合は、コネクタの接続先を次のように設定します。

https://temporal-mcp.dev/mcp

認証方法は、クライアントの UI で利用できる項目に応じて 2 通りあります。

A. OAuth 2.0（claude.ai と ChatGPT のカスタムコネクタ）

claude.ai と ChatGPT のカスタムコネクタ UI は、どちらも Client ID と Client Secret による OAuth 2.0 を必要とします。ホステッドエンドポイントは完全な OAuth プロバイダーです。https://temporal-mcp.dev/connect にアクセスし、OAuth 認証情報を生成をクリックしてください。新しい client_id と client_secret のペアが一度だけ表示されます。それをクライアントのコネクタ設定に貼り付けます。これで登録は完了です。

メールアドレス、パスワード、アカウント情報は不要です。認証情報のペア自体が ID になります。保存するのはシークレットの SHA-256 ハッシュのみなので、平文を目にすることはありません。新しいタイムラインを始めたいときは、いつでも新しいペアを生成できます。

Claude.ai の設定： Settings → Connectors → Add custom connector を選択します。URL は https://temporal-mcp.dev/mcp です。Client ID と Client Secret を貼り付けて接続します。自動承認フローで元のページに戻ると、claude.ai がコードをトークンと交換します。これで完了です。

ChatGPT の設定： 同様に、Settings → Connectors → Custom MCP を選択します。同じ URL と認証情報を使います。

B. ベアラートークンをそのまま使用（Cursor、Cline、Claude Desktop、Zed、Claude Code）

クライアントがカスタム HTTP ヘッダーに対応している場合（ほとんどが対応しています）、OAuth は使わず、任意の不透明な文字列をベアラートークンとして送信できます。

Authorization: Bearer <any opaque string you choose>

UUID、パスフレーズなど、何でも選べます。保存前に SHA-256 ハッシュ化するため、認証情報自体が ID になるという点は OAuth フローと同じですが、手間はかかりません。これは手順が最も少ない従来の方法で、カスタムヘッダーを設定できるクライアントならどれでも使えます。

C. URL に埋め込むトークン（xAI、Grok、URL しか使えない場合）

クライアントのコネクター UI に URL フィールドしかなく、ヘッダー、認証、OAuth がない場合は、トークンをパスに直接埋め込みます。

https://temporal-mcp.dev/mcp/<any opaque string you choose>

パス形式が削除される場合は、クエリパラメーターとして指定することもできます。

https://temporal-mcp.dev/mcp?token=<any opaque string you choose>

SHA-256 ハッシュ化も、同じ ID モデルも変わりません。URL に埋め込んだトークンは、ヘッダートークンより漏えいしやすいため（プロキシログ、リファラー）、この方法はデフォルトではなく、実用的な代替手段です。ただし、私たちのモデルにおける脅威はデータの露出ではなく、「誰かがあなたのタイムラインを進めること」です。URL が記録されるべきでない場所に記録された疑いがある場合は、いつでも新しいランダム文字列を選んでローテーションしてください。

いずれの方法でも

登録不要です。メールアドレスも個人を特定できる情報（PII）も必要ありません。ホスト型エンドポイントは無料で、認証情報ごとに毎分 60 リクエストに制限されています。それを超える場合は、セルフホストしてください（以下を参照）。

2. ローカル stdio — Claude Desktop、Cursor、Cline、Zed、Claude Code

デスクトップ／IDE の MCP クライアントでは、Python パッケージを pip install し、ローカルで実行します。ネットワーク往復はなく、状態はディスク上に保存され、認証も不要です。

pip install temporal-mcp

Python 3.9 以降。Linux、macOS、Windows に対応しています。

stdio として実行します。

temporal-mcp        # or: python -m temporal_mcp

Claude Desktop

{
  "mcpServers": {
    "temporal": {
      "command": "temporal-mcp"
    }
  }
}

Cursor／Cline／その他 MCP stdio に対応するクライアント

同様に、クライアントの接続先として temporal-mcp コマンドを指定します。

リモートエンドポイントをセルフホストする（Cloudflare Workers）

temporal-mcp.dev のホスト型エンドポイントは、D1 をバックエンドとする Cloudflare Workers 上で動作しています。プライバシー、スケール、または大規模な製品の一部として提供するために独自のインスタンスを用意する場合、デプロイに必要なファイルはすべて workers/ にあります。

cd workers
npm install
npx wrangler login
npx wrangler d1 create temporal_mcp           # creates the database
# Paste the printed database_id into wrangler.toml
npx wrangler d1 migrations apply temporal_mcp --remote
npx wrangler deploy

無料枠で、毎日約 10 万リクエストを永久に利用できます。匿名トラフィックを拒否するには、[vars] で REQUIRE_AUTH=true を設定してください。Worker は約 400 行の TypeScript で構成され、独自の単体テストもあります（workers/test/）。

ツール

temporal_tick

スレッドの時計を進め、スナップショットを返します。ユーザーの各ターンにつき 1 回呼び出してください。

フィールド	型	備考
thread_key	文字列、省略可	安定した会話／セッション ID です。claude.ai の Web 版では会話 ID、Cursor ではウィンドウ／ワークスペース ID を指定します。それ以外の場合は、呼び出し元で安定して使用できる任意の文字列を指定してください。省略すると、ホスト名と cwd のハッシュがデフォルトで使われます。ローカルテストには問題ありませんが、複数のスレッドを提供する用途には適しません。
client_id	文字列、省略可	名前空間タグ（例："caweb"、"cursor"）です。デフォルトは "mcp" です。共有状態でスレッドが衝突しないよう、クライアントごとに異なるタグを使用してください。

temporal_peek

読み取り専用です。同じ形式ですが、状態は進めません。経過時間の差分だけを確認したいものの、この呼び出しが「ユーザーの各ターンにつき 1 回」という標準イベントではない場合に使用してください。

状態

スレッドごとの最終確認状態は、次の場所に保存されます。

プラットフォーム	パス
Linux	~/.local/share/temporal-mcp/state.json
macOS	~/Library/Application Support/temporal-mcp/state.json
Windows	%LOCALAPPDATA%\temporal-mcp\state.json

TEMPORAL_MCP_STATE_DIR=/some/path で上書きできます。

状態の書き込みは POSIX では flock によって安全に行われ、os.replace によってアトミックに置き換えられるため、同じ状態ディレクトリを参照する複数のエージェントが互いの状態を破損させることはありません。（Windows ではプロセス内ロックにフォールバックします。単一の MCP サーバーには問題ありませんが、プロセス間の競合には対応していません。）

メンテナンス

python -m temporal_mcp gc        # prune threads > 30d idle
python -m temporal_mcp gc 7      # prune threads > 7d idle

意図的に MCP ツールとしては公開していません。「最後に話したのはいつか」という自分の記憶をモデルが整理できると、いずれ必ず、最悪のタイミングで実行してしまうためです。必要であれば cron から実行してください。

設計メモ（詳しく知りたい方向け）

• スレッドキーの名前空間は {client_id}:{key} です。サーフェスごとに一意の client_id を割り当て、claude.ai のウェブ版のスレッドが、同じ状態ディレクトリを 共有するローカルの Cursor セッションと衝突しないようにしてください。

• 失敗は正直に報告します。 状態ファイルを読み取れない場合、またはロックが タイムアウトした場合、スナップショットは available: false と error フィールドを返し、 ヘッダーには gap: unknown と表示されます。新しいスレッドだと黙って偽ることは ありません。すべてのターンが新しいとモデルが判断すると、いつまでも「おはようございます」と 言い続けることになります。

• ウォッチドッグ。 tick() は、停止した状態の読み取りがフックの実行時間を ブロックしないよう、タイムアウトを 100 ms に設定してデーモンスレッドで実行されます。 タイムアウトすると、上記の正直な失敗スナップショットが返されます。

• 0.1 では HTTP トランスポートなし。 Stdio のみです。Claude Desktop、Cursor、 その他の主要な MCP クライアントが実際に使用している方式だからです。需要があれば、 0.2 で HTTP/SSE を追加できます。

ロードマップ

• 0.2 — オプションの HTTP/SSE トランスポート、Mcp-Session-Id などからの会話 ID の 自動解決、タイムゾーンの上書き設定
• 0.3 — オプトインの「長時間の中断」しきい値（N 時間を超えると resume: true フラグを 返す）。これにより、エージェントは自分で時間を計算せずに、再開したセッションを 判別できます。

ライセンス

MIT。［LICENSE］(LICENSE) を参照してください。

作者

Garret Sutherland / MirrorEthic LLC が開発しました。 より大規模な認知メッシュプロジェクトの時間レイヤーから抽出したもので、 独立したパッケージにする価値があるほど、このプリミティブは重要な役割を担っていました。

---

_{mcp-name: io.github.MirrorEthic/temporal-mcp}