Panteon Timeline MCP Server 🚀

FastMCP로 구축된 MCP(Model Context Protocol) 서버로, AI 어시스턴트(Antigravity, Claude Desktop, Cursor 등)가 Panteon Timeline(https://timeline.panteon.no)에서 실시간 작업 데이터와 대화 기록을 직접 가져올 수 있게 해줍니다.

✨ 주요 기능

• 이슈 ID 추출: https://timeline.panteon.no/tasks#/list/15033/edit/5461 같은 URL 형식을 자동으로 파싱하거나, 직접 이슈 ID(5461)를 입력받습니다.

• 2단계 API 해석: 브라우저 확장 프로그램 로직을 그대로 반영하여, API 1을 통해 외부 이슈 ID(5461)를 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 아래에 저장되며, 지원하지 않는 클라이언트는 일반적인 플레이스홀더 출력을 유지합니다.

• 반환 값: 이슈 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/에 있으며, 순수 파싱/렌더링 헬퍼와 인증 오류 처리를(mock HTTP 세션을 통해) 다룹니다.