Panteon Timeline MCP Server 🚀

Un servidor MCP (Model Context Protocol) construido con FastMCP que permite a los asistentes de IA (Antigravity, Claude Desktop, Cursor, etc.) obtener datos de tareas en tiempo real y el historial de conversaciones directamente desde Panteon Timeline (https://timeline.panteon.no).

✨ Características

• Extraer Issue ID: Analiza automáticamente formatos de URL como https://timeline.panteon.no/tasks#/list/15033/edit/5461 o acepta IDs de issue directos (5461).

• Resolución de API en dos pasos: Replica la lógica de la extensión del navegador resolviendo el ID de issue externo (5461) al task_id interno de Panteon mediante la API 1, y luego obteniendo el historial completo de la conversación mediante la API 2.

• Formato optimizado para IA: Proporciona contexto estructurado XML/Markdown (<task_title>, <task_description>, <conversation_history>) listo para el análisis, el resumen y la redacción de respuestas por parte de la IA.

• Autenticación flexible: Admite tokens JWT Bearer o cabeceras Cookie mediante la configuración del archivo .env o parámetros por llamada de herramienta.

Related MCP server: Rytnow MCP Server

🛠️ Instalación y configuración

1. Instalar dependencias

Asegúrate de tener Python 3.10+ instalado y, a continuación, crea o reutiliza el virtualenv del proyecto e instala las dependencias en él:

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

2. Configurar la autenticación

Para obtener datos protegidos de timeline.panteon.no, el servidor MCP necesita un token de autenticación de tu sesión iniciada en el navegador.

1. Copia .env.example a .env:

   cp .env.example .env

2. Abre Google Chrome e inicia sesión en https://timeline.panteon.no.

3. Abre Chrome DevTools (F12 o Ctrl+Shift+I) -> ve a la pestaña Network.

4. Actualiza la página de tareas de timeline o realiza cualquier acción.

5. Haz clic en cualquier petición que empiece por api/ (p. ej., taskbyissue/... o timeline).

6. En Request Headers, copia el valor de Authorization (sin el prefijo Bearer ) o la cadena sin procesar de la cabecera Cookie.

7. Pégalo en tu archivo .env:

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

🤖 Configurar los clientes MCP

Para Claude Desktop / Antigravity / Cursor

Añade la siguiente configuración al archivo de configuración de tu servidor MCP (p. ej., 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"
      }
    }
  }
}

Para Codex

Codex lee los servidores MCP desde config.toml. Añade esto a ~/.codex/config.toml para una configuración global, o a .codex/config.toml dentro de este repositorio para una configuración a nivel de proyecto:

[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

Con cwd establecido en este repositorio, python-dotenv carga .env automáticamente. Si prefieres pasar las credenciales desde la shell en su lugar, añade:

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

Después de guardar la configuración, reinicia Codex y ejecuta /mcp en la TUI de Codex para confirmar que timeline_mcp está activo.

🧰 Herramientas disponibles

get_task_conversation

Obtiene una tarea completa — su cuerpo de descripción y toda la conversación de comentarios — incluida cada imagen incrustada en cualquier parte, y la escribe en un archivo markdown.

• Argumentos:

  • issue_identifier (str) — p. ej. "https://timeline.panteon.no/tasks#/list/15033/edit/5461" o "5461". Debe ser un ID numérico simple o una URL que contenga /edit/<id>.

  • bearer_token / cookie (str, opcional) — sobrescribe las credenciales de .env por llamada.

  • inline (bool, por defecto false) — cuando es true, el markdown completo de la tarea se añade al valor de retorno además de guardarse. Usa esto para clientes que no puedan leer la ruta local del sistema de archivos.

• Efecto secundario: escribe timeline/<issue_id>/task.md (título, metadatos, descripción, comentarios). El archivo guardado también se expone como recurso MCP en timeline://<issue_id>/task.md, de modo que los clientes pueden leer el contenido completo a través de MCP después de una obtención.

• Tareas vacías: cuando tanto la descripción como los comentarios están vacíos, la herramienta solicita contexto opcional proporcionado por el usuario si el cliente MCP admite la elicitación. La entrada aceptada se guarda en ## User-Provided Context; los clientes que no lo admiten mantienen la salida de marcador de posición normal.

• Devuelve una cadena de resumen breve y legible con el ID de issue, el título, el estado y la ruta del archivo guardado, por ejemplo:

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

  El cuerpo completo de la tarea, toda la conversación de comentarios y cada URL de imagen se escriben en el archivo guardado. Lee ese archivo para acceder al contenido completo.

Las URL de imágenes incrustadas en los comentarios (markdown ![](…) o HTML <img>) se resuelven a URL absolutas https://timeline.panteon.no/.... Los enlaces de adjuntos que no son imágenes (p. ej. .csv) se excluyen.

Ubicación de la salida

El archivo se escribe en <base>/timeline/<issue_id>/task.md, donde <base> es:

1. La variable de entorno PANTEON_TIMELINE_DIR, si está definida (este MCP está configurado con ella apuntando a la raíz del proyecto duell-admin); en caso contrario,

2. el directorio de trabajo actual.

💻 Uso desde la línea de comandos

La misma lógica de obtención está disponible desde la shell mediante fetch_task.py (las credenciales provienen de .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

🧪 Desarrollo y pruebas

# 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

Las pruebas están en tests/ y cubren los helpers puros de análisis y renderizado, además del manejo de errores de autenticación (mediante una sesión HTTP simulada).