Panteon Timeline MCP 服务器 🚀

一个基于 FastMCP 构建的 MCP（模型上下文协议）服务器，使 AI 助手（Antigravity、Claude Desktop、Cursor 等）能够直接从 Panteon Timeline（https://timeline.panteon.no）获取实时任务数据和对话历史。

✨ 功能特性

• 提取问题 ID：自动解析类似 https://timeline.panteon.no/tasks#/list/15033/edit/5461 的 URL 格式，或直接接受问题 ID（5461）。

• 两步 API 解析：镜像浏览器扩展逻辑，先通过 API 1 将外部问题 ID（5461）解析为 Panteon 内部的 task_id，再通过 API 2 获取完整的对话时间线。

• AI 优化格式：提供结构化的 XML/Markdown 上下文（<task_title>、<task_description>、<conversation_history>），可直接用于 AI 分析、摘要和回复草拟。

• 灵活的认证方式：支持通过 .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。如果你更倾向于从 shell 传入凭据，请添加：

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

保存配置后，重启 Codex 并在 Codex TUI 中运行 /mcp 以确认 timeline_mcp 已激活。

🧰 可用工具

get_task_conversation

完整获取一个任务——包括其描述正文 和 全部评论对话——以及嵌入在任意位置的每张图片，并将其写入一个 markdown 文件。

• 参数：

  • issue_identifier（字符串）——例如 "https://timeline.panteon.no/tasks#/list/15033/edit/5461" 或 "5461"。必须是纯数字 ID 或包含 /edit/<id> 的 URL。

  • bearer_token / cookie（字符串，可选）——在单次调用中覆盖 .env 中的凭据。

  • inline（布尔值，默认 false）——当为 true 时，完整的任务 markdown 会附加到返回值中，同时也会保存到文件。适用于无法读取本地文件系统路径的客户端。

• 副作用：写入 timeline/<issue_id>/task.md（标题、元数据、描述、评论）。保存的文件也会作为 MCP 资源 暴露在 timeline://<issue_id>/task.md，因此客户端可以在获取后通过 MCP 读取完整内容。

• 空任务：当描述和评论均为空时，如果 MCP 客户端支持引导式输入，该工具会请求可选的用户提供上下文。接受的输入会保存在 ## 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. 当前工作目录。

💻 命令行用法

相同的获取逻辑可通过 shell 中的 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 会话）。