Panteon Timeline MCP Server 🚀

FastMCP で構築された MCP (Model Context Protocol) サーバーで、AI アシスタント (Antigravity、Claude Desktop、Cursor など) が Panteon Timeline (https://timeline.panteon.no) からリアルタイムのタスクデータと会話履歴を直接取得できるようにします。

✨ 機能

• Issue ID の抽出: https://timeline.panteon.no/tasks#/list/15033/edit/5461 のような URL 形式を自動的に解析し、直接の issue ID (5461) も受け付けます。

• 2 段階 API 解決: ブラウザ拡張機能のロジックを踏襲し、外部の issue ID (5461) を API 1 経由で Panteon の内部 task_id に解決し、その後 API 2 経由で完全な会話タイムラインを取得します。

• AI 最適化フォーマット: AI による分析、要約、返信作成に適した構造化 XML/Markdown コンテキスト (<task_title>、<task_description>、<conversation_history>) を提供します。

• 柔軟な認証: .env ファイル設定またはツール呼び出しごとのパラメータを介して、JWT Bearer トークンまたは Cookie ヘッダーをサポートします。

Related MCP server: ProofHub MCP Server

🛠️ インストールとセットアップ

1. 依存関係のインストール

Python 3.10+ がインストールされていることを確認し、プロジェクトの仮想環境を作成または再利用して、そこに依存関係をインストールします:

cd timeline-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

2. 認証の設定

timeline.panteon.no から保護されたデータを取得するには、MCP サーバーがログイン済みブラウザセッションからの認証トークンを必要とします。

1. .env.example を .env にコピーします:

   cp .env.example .env

2. Google Chrome を開き、https://timeline.panteon.no にログインします。

3. Chrome DevTools (F12 または Ctrl+Shift+I) を開き、Network タブに移動します。

4. タイムラインのタスクページを更新するか、任意の操作を行います。

5. api/ で始まる任意のリクエスト (例: taskbyissue/... または timeline) をクリックします。

6. Request Headers の下で、Authorization の値 (Bearer プレフィックスを除く) または生の Cookie ヘッダー文字列をコピーします。

7. それを .env ファイルに貼り付けます:

   PANTEON_BEARER_TOKEN=eyJ...
   # OR
   PANTEON_COOKIE=...

🤖 MCP クライアントの設定

Claude Desktop / Antigravity / Cursor の場合

MCP サーバー設定ファイル (例: claude_desktop_config.json) に次の設定を追加します:

{
  "mcpServers": {
    "timeline-mcp": {
      "command": "/home/harpalsinh.solanki@hs.local/projects/panteon/timeline-mcp/.venv/bin/python",
      "args": [
        "/home/harpalsinh.solanki@hs.local/projects/panteon/timeline-mcp/server.py"
      ],
      "env": {
        "PANTEON_BEARER_TOKEN": "your_jwt_token_here"
      }
    }
  }
}

Codex の場合

Codex は config.toml から MCP サーバーを読み取ります。グローバル設定の場合は ~/.codex/config.toml に、プロジェクトスコープの設定の場合はこのリポジトリ内の .codex/config.toml にこれを追加します:

[mcp_servers.timeline_mcp]
command = "/home/harpalsinh.solanki@hs.local/projects/panteon/timeline-mcp/.venv/bin/python"
args = ["/home/harpalsinh.solanki@hs.local/projects/panteon/timeline-mcp/server.py"]
cwd = "/home/harpalsinh.solanki@hs.local/projects/panteon/timeline-mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120

cwd をこのリポジトリに設定すると、python-dotenv が .env を自動的に読み込みます。代わりにシェルから資格情報を渡す場合は、次を追加します:

env_vars = ["PANTEON_BEARER_TOKEN", "PANTEON_COOKIE", "PANTEON_TIMELINE_DIR"]

設定を保存したら、Codex を再起動し、Codex TUI で /mcp を実行して timeline_mcp がアクティブであることを確認します。

🧰 利用可能なツール

get_task_conversation

タスクを完全に取得します — 説明本文とコメント会話全体 — 埋め込まれたすべての画像を含み、マークダウンファイルに書き込みます。

• 引数:

  • issue_identifier (str) — 例: "https://timeline.panteon.no/tasks#/list/15033/edit/5461" または "5461"。裸の数値 ID または /edit/<id> を含む URL である必要があります。

  • bearer_token / cookie (str, 任意) — 呼び出しごとに .env の資格情報を上書きします。

  • inline (bool, デフォルト false) — true の場合、保存に加えて完全なタスクマークダウンが戻り値に追加されます。ローカルファイルシステムのパスを読み取れないクライアント向けに使用します。

• 副作用: timeline/<issue_id>/task.md (タイトル、メタデータ、説明、コメント) を書き込みます。保存されたファイルは MCP リソースとして timeline://<issue_id>/task.md でも公開されるため、クライアントは取得後に MCP 経由で完全なコンテンツを読み取ることができます。

• 空のタスク: 説明とコメントの両方が空の場合、MCP クライアントが引き出し (elicitation) をサポートしていれば、ツールは任意のユーザー提供コンテキストを要求します。受け入れられた入力は ## User-Provided Context の下に保存されます。サポートされていないクライアントは通常のプレースホルダー出力を保持します。

• 戻り値: issue ID、タイトル、ステータス、保存されたファイルパスを含む短い人間が読める要約文字列 — 例:

  Issue #4117 — Label print
  Status:     open
  Saved to:   /abs/path/timeline/4117/task.md

  タスク本文全体、コメント会話全体、およびすべての画像 URL が保存されたファイルに書き込まれます。そのファイルを読むと完全なコンテンツにアクセスできます。

コメントに埋め込まれた画像 URL (markdown ![](…) または HTML <img>) は、絶対的な https://timeline.panteon.no/... URL に解決されます。画像以外の添付リンク (例: .csv) は除外されます。

出力場所

ファイルは <base>/timeline/<issue_id>/task.md に書き込まれます。ここで <base> は次のとおりです:

1. PANTEON_TIMELINE_DIR 環境変数 (設定されている場合。この MCP は duell-admin プロジェクトルートを指すように設定されています)。それ以外の場合は

2. 現在の作業ディレクトリ。

💻 コマンドラインでの使用

同じフェッチロジックは、fetch_task.py を介してシェルから利用できます (資格情報は .env から取得されます):

# By numeric ID or full URL
.venv/bin/python fetch_task.py 5461
.venv/bin/python fetch_task.py "https://timeline.panteon.no/tasks#/list/15033/edit/5461"

# Also print the rendered markdown to stdout
.venv/bin/python fetch_task.py 5461 --print

# Write under a specific project root instead of PANTEON_TIMELINE_DIR / cwd
.venv/bin/python fetch_task.py 5461 --base-dir /path/to/project

🧪 開発とテスト

# Install dev dependencies (adds pytest)
.venv/bin/python -m pip install -r requirements-dev.txt

# Run the unit tests — no network or credentials required
.venv/bin/python -m pytest

テストは tests/ にあり、純粋な解析/レンダリングヘルパーと認証エラー処理 (モックされた HTTP セッション経由) をカバーしています。