planka-v2-mcp

Un servidor especializado del Protocolo de Contexto de Modelo (MCP) que permite a los LLMs (como Claude en Cursor) interactuar con tableros kanban de Planka v2.x.

GitHub

Documentación

📋 Servidor MCP de Planka Kanban (v2.x)

Un servidor Model Context Protocol (MCP) listo para producción que permite a asistentes de codificación con IA y agentes autónomos (como Claude, Cursor y Antigravity) interactuar sin problemas con tableros kanban de Planka v2.x.

Soporta tanto CLI Local (Stdio) como Servidor HTTP Remoto con Server-Sent Events (SSE) con Aislamiento de Usuarios Multi-Tenant.

✨ Características Principales

🌐 Arquitectura de Doble Transporte: Ejecútalo localmente vía stdio (para aplicaciones de escritorio como Cursor y Claude Desktop) o como un servicio HTTP de alto rendimiento vía sse (para web, agentes en la nube y microservicios centralizados).
👥 Credenciales Multi-Tenant por Llamada: En modo HTTP SSE, cada usuario puede pasar sus propias credenciales de Planka al conectarse. Las acciones, tarjetas, comentarios y finalizaciones de tareas se atribuyen a cada usuario respectivo en Planka.
📂 Jerarquía de Listas de Tareas (Planka v2.x): Soporte nativo para Listas de Tareas como contenedores principales dentro de las tarjetas.
⚡ Flujos de Trabajo Automatizados para Tarjetas: workflow_action integrado en mcp_kanban_card_manager que permite transiciones de estado en una sola llamada (start_working, mark_completed, move_to_testing, move_to_done) con comentarios automáticos y resolución de tareas.
⏱️ Seguimiento de Tiempo (Cronómetro): Inicia, detén, reinicia y consulta cronómetros de tarjetas registrados directamente en Planka.
👤 Resolución Inteligente de Miembros: Asigna usuarios por email o username sin necesidad de buscar su ID de usuario interno previamente.
🗂️ Herramientas de Gestión Consolidadas: Las herramientas se agrupan en gestores lógicos para respetar los límites de herramientas de los LLM (el límite de 40 herramientas de Cursor) mientras se expone la funcionalidad completa de la API.
🐳 Listo para Docker y GHCR: Imagen multi-etapa contenerizada publicada automáticamente en GitHub Container Registry (ghcr.io).
🛡️ Seguridad Empresarial: Protección contra traversal de rutas, protecciones SSRF, saneamiento de IDs, renovación transparente de tokens en 401 y seguridad opcional de puerta de enlace con token Bearer (MCP_API_KEY).

🛠️ Resumen de Herramientas MCP

Todas las operaciones se agrupan en 8 Herramientas de Gestión Consolidadas:

Nombre de la Herramienta	Acciones Clave	Descripción
`mcp_kanban_project_board_manager`	`get_projects`, `create_project`, `get_boards`, `create_board`, `get_board_summary`, `get_project_summary`	Gestiona proyectos y tableros con estadísticas agregadas.
`mcp_kanban_card_manager`	`get_all`, `create`, `update`, `move`, `duplicate`, `delete`, `workflow_action`	Gestiona tarjetas y automatiza las progresiones de estado del flujo de trabajo.
`mcp_kanban_stopwatch`	`start`, `stop`, `get`, `reset`	Realiza seguimiento y registra el tiempo de trabajo en las tarjetas.
`mcp_kanban_task_list_manager`	`get_all`, `create`, `get_one`, `update`, `delete`	Gestiona los contenedores de Listas de Tareas de Planka v2.0 dentro de las tarjetas.
`mcp_kanban_task_manager`	`get_all`, `create`, `batch_create`, `update`, `complete_task`, `delete`	Gestiona listas de verificación y tareas dentro de las listas de tareas.
`mcp_kanban_comment_manager`	`get_all`, `create`, `update`, `delete`	Publica comentarios de auditoría y discusiones en las tarjetas.
`mcp_kanban_label_manager`	`get_all`, `create`, `update`, `delete`, `add_to_card`, `remove_from_card`	Gestiona las taxonomías de etiquetas de los tableros con más de 10 colores estándar de Planka.
`mcp_kanban_card_membership_manager`	`get_all`, `create`, `delete`, `get_users`	Asigna y desasigna miembros con resolución automática de correo electrónico/nombre de usuario.

🚀 Primeros Pasos

1. Requisitos Previos

Una instancia de Planka v2.x en ejecución accesible a través de la red.
Una cuenta de usuario o cuenta de bot de servicio en Planka.

2. Modo Local: Stdio (Cursor, Claude Desktop, Antigravity)

En modo local, el servidor MCP se conecta a través de entrada/salida estándar (stdio).

Configuración con `npx` (Recomendado)

Añade la definición del servidor al archivo de configuración de tu cliente (por ejemplo, claude_desktop_config.json o Configuración de Cursor):

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": ["-y", "@navyatec/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password",
        "PLANKA_IGNORE_SSL": "false"
      }
    }
  }
}

Configuración de Fuente Local

{
  "mcpServers": {
    "planka-mcp": {
      "command": "node",
      "args": ["/path/to/kanban-mcp/dist/index.js"],
      "env": {
        "PLANKA_BASE_URL": "https://your-planka-instance.com",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-secure-password"
      }
    }
  }
}

3. Modo Remoto: HTTP Server-Sent Events (SSE)

Ejecuta el servidor como un demonio HTTP centralizado para servir a agentes remotos, plataformas en la nube o múltiples desarrolladores concurrentes.

Iniciando el Servidor SSE

# Start directly via npx
npx -y @navyatec/planka-v2-mcp --transport sse --port 3000

# Or using environment variables
export MCP_TRANSPORT=sse
export PORT=3000
export MCP_API_KEY=my-secret-gateway-key # (Optional) Requires Bearer token to access MCP
node dist/index.js

👥 Credenciales Multi-Tenant por Llamada

Cuando se ejecuta en modo SSE, no necesitas almacenar credenciales de usuario en el .env del servidor. En su lugar, cada cliente envía sus propias credenciales durante el handshake de conexión SSE.

Opción A: Mediante Cabeceras HTTP (GET /sse)

GET /sse HTTP/1.1
Host: your-mcp-server:3000
X-Planka-Email: developer@yourdomain.com
X-Planka-Password: secretPassword
X-Planka-Base-Url: https://planka.yourdomain.com

(También soporta Authorization: Basic <base64(email:password)> estándar).

Opción B: Mediante Parámetros de Consulta en la URL (GET /sse) (Ideal para clientes de navegador y EventSource estándar)

http://your-mcp-server:3000/sse?email=developer@yourdomain.com&password=secretPassword&baseUrl=https://planka.yourdomain.com

Endpoints y Protocolos

El servidor soporta nativamente tanto el moderno Transporte HTTP Streamable como el Transporte SSE Legado:

POST /sse, POST /mcp, POST /: Handshake HTTP Streamable y llamadas JSON-RPC con gestión de sesión mediante cabecera Mcp-Session-Id.
GET /sse: Handshake de flujo persistente SSE legado.
POST /messages?sessionId=...: Endpoint de mensajes de cliente SSE legado.
GET /health o GET /: Endpoint de verificación de salud e información del servidor (200 OK).

4. Ejecución con Docker y GHCR

La imagen del contenedor se publica en GitHub Container Registry (GHCR):

# Multi-user mode (credentials supplied dynamically by connecting clients)
docker run -d -p 3001:3000 \
  -e PLANKA_BASE_URL="http://your-planka-instance:3333" \
  -e MCP_API_KEY="optional-gateway-bearer-token" \
  ghcr.io/navya-tecnologia/planka-v2-mcp:latest

# Or single-user mode (fallback credentials in container)
docker run -d -p 3001:3000 \
  -e PLANKA_BASE_URL="http://your-planka-instance:3333" \
  -e PLANKA_AGENT_EMAIL="bot@yourdomain.com" \
  -e PLANKA_AGENT_PASSWORD="botPassword" \
  ghcr.io/navya-tecnologia/planka-v2-mcp:latest

5. Configuraciones de Integración con Clientes

A. IDE Antigravity

Configura el servidor MCP en ~/.gemini/config/mcp_config.json (o .agent/mcp_config.json en tu espacio de trabajo):

Modo Contenedor Remoto / HTTP SSE (Recomendado):

{
  "mcpServers": {
    "planka-mcp": {
      "serverUrl": "http://127.0.0.1:3001/sse"
    }
  }
}

Modo Stdio Local:

{
  "mcpServers": {
    "planka-mcp": {
      "command": "node",
      "args": ["c:/path/to/kanban-mcp/dist/index.js"],
      "env": {
        "PLANKA_BASE_URL": "http://your-planka-instance:3333",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-password"
      }
    }
  }
}

B. Claude Desktop

Edita tu archivo de configuración de Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json en Windows, ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

Modo Contenedor Remoto / HTTP SSE (mediante puente mcp-remote):

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://127.0.0.1:3001/sse"
      ]
    }
  }
}

Modo Stdio Local:

{
  "mcpServers": {
    "planka-mcp": {
      "command": "npx",
      "args": ["-y", "@navyatec/planka-v2-mcp@latest"],
      "env": {
        "PLANKA_BASE_URL": "http://your-planka-instance:3333",
        "PLANKA_AGENT_EMAIL": "agent@yourdomain.com",
        "PLANKA_AGENT_PASSWORD": "your-password"
      }
    }
  }
}

C. Claude Code (CLI de Terminal)

Puedes adjuntar el servidor global o localmente usando la CLI:

# Add globally for all projects:
claude mcp add -s user planka-mcp http://127.0.0.1:3001/sse

# Or add to current project:
claude mcp add planka-mcp http://127.0.0.1:3001/sse

O configura .mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "planka-mcp": {
      "type": "sse",
      "url": "http://127.0.0.1:3001/sse"
    }
  }
}

D. IDE Cursor

En Cursor Configuración > Funciones > MCP, haz clic en Añadir Nuevo Servidor MCP:

Nombre: planka-mcp
Tipo: sse
URL del Servidor: http://127.0.0.1:3001/sse

O en .cursor/mcp.json:

{
  "mcpServers": {
    "planka-mcp": {
      "url": "http://127.0.0.1:3001/sse"
    }
  }
}

💬 Ejemplos de Prompts para IA

Una vez configurado, puedes dar instrucciones a tu asistente de IA en lenguaje natural:

"Muéstrame un resumen de todos los proyectos y tableros."
"Organiza el tablero Backlog y desglosa la tarjeta principal en tareas."
"Mueve la tarjeta 'Implementar OAuth' a 'En Progreso' y añade un comentario de que el trabajo ha comenzado."
"Crea una Lista de Tareas 'Base de Datos' en la tarjeta 'Migración' y añade 3 elementos de lista de verificación."
"Inicia el cronómetro en la tarjeta 'Refactorizar cliente API'."
"Asigna @sarah.connor a la tarjeta 'Auditoría de Seguridad'."

📖 Wiki y Documentación

Referencia de API: Esquema detallado y acciones para cada herramienta.
Guía para Desarrolladores: Arquitectura, configuración local y pautas de contribución.
Capacidades y Estrategias: Justificación del diseño y patrones de optimización para Cursor.
Guía de Uso: Flujos de trabajo prácticos y recorridos de escenarios.
Guía de Instalación: Configuración paso a paso en varias plataformas.

🏗️ Desarrollo y Pruebas

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run unit tests (offline in-memory suite with 37 tests)
npm test

# Run quality checks (build + test)
npm run qc

# Run integration tests (requires running Planka server)
npm run test:integration

🚀 Lanzamientos Automatizados

Los lanzamientos se automatizan mediante GitHub Actions. Al enviar una etiqueta git semántica (por ejemplo, v1.4.0) se activa:

Suite de pruebas unitarias automatizadas y compilación.
Publicación del paquete NPM (@navyatec/planka-v2-mcp).
Compilación de imagen Docker multi-etapa y publicación en GitHub Container Registry (GHCR).
Creación de Release en GitHub con notas de versión y tarball de producción adjunto.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Desarrollado y mantenido por NAVYA TECNOLOGÍA 2024, S.L. (Proyecto original de Brad Risse)