planka-v2-mcp

Um servidor especializado do Model Context Protocol (MCP) que permite que LLMs (como Claude no Cursor) interajam com quadros kanban do Planka v2.x.

GitHub

Documentação

📋 Servidor MCP Kanban Planka (v2.x)

Um servidor Model Context Protocol (MCP) pronto para produção que permite que assistentes de codificação com IA e agentes autônomos (como Claude, Cursor e Antigravity) interajam perfeitamente com quadros kanban Planka v2.x.

Suporta tanto CLI Local (Stdio) quanto Servidor HTTP Remoto com Server-Sent Events (SSE) com Isolamento Multi-Tenant por Usuário.

✨ Principais Recursos

🌐 Arquitetura de Transporte Duplo: Execute localmente via stdio (para aplicativos de desktop como Cursor e Claude Desktop) ou como um serviço HTTP de alta performance via sse (para web, agentes em nuvem e microsserviços centralizados).
👥 Credenciais Multi-Tenant por Chamada: No modo HTTP SSE, cada usuário pode enviar suas próprias credenciais do Planka ao se conectar. Ações, cartões, comentários e conclusões de tarefas são atribuídos a cada usuário respectivo no Planka.
📂 Hierarquia de Listas de Tarefas (Planka v2.x): Suporte nativo para Listas de Tarefas como contêineres pai dentro de cartões.
⚡ Fluxos de Trabalho Automatizados de Cartões: workflow_action integrado em mcp_kanban_card_manager permitindo transições de estado em uma única chamada (start_working, mark_completed, move_to_testing, move_to_done) com comentários automáticos e resolução de tarefas.
⏱️ Controle de Tempo (Cronômetro): Inicie, pare, reinicie e consulte cronômetros de cartões diretamente registrados no Planka.
👤 Resolução Inteligente de Membros: Atribua usuários por email ou username sem precisar consultar o ID interno do usuário antecipadamente.
🗂️ Ferramentas de Gerenciamento Consolidadas: As ferramentas são agrupadas em gerenciadores lógicos para respeitar os limites de ferramentas de LLMs (limite de 40 ferramentas do Cursor) enquanto expõem funcionalidade completa da API.
🐳 Pronto para Docker e GHCR: Imagem multi-estágio conteinerizada publicada automaticamente no GitHub Container Registry (ghcr.io).
🛡️ Segurança Empresarial: Proteção contra path traversal, proteções SSRF, sanitização de IDs, renovação transparente de tokens em 401 e segurança opcional de gateway com token Bearer (MCP_API_KEY).

🛠️ Visão Geral das Ferramentas MCP

Todas as operações são agrupadas em 8 Ferramentas de Gerenciamento Consolidadas:

Nome da Ferramenta	Ações Principais	Descrição
`mcp_kanban_project_board_manager`	`get_projects`, `create_project`, `get_boards`, `create_board`, `get_board_summary`, `get_project_summary`	Gerencie projetos e quadros com estatísticas agregadas.
`mcp_kanban_card_manager`	`get_all`, `create`, `update`, `move`, `duplicate`, `delete`, `workflow_action`	Gerencie cartões e automatize progressões de status de fluxo de trabalho.
`mcp_kanban_stopwatch`	`start`, `stop`, `get`, `reset`	Acompanhe e registre tempo de trabalho em cartões.
`mcp_kanban_task_list_manager`	`get_all`, `create`, `get_one`, `update`, `delete`	Gerencie contêineres de Listas de Tarefas do Planka v2.0 dentro de cartões.
`mcp_kanban_task_manager`	`get_all`, `create`, `batch_create`, `update`, `complete_task`, `delete`	Gerencie checklists e tarefas dentro de listas de tarefas.
`mcp_kanban_comment_manager`	`get_all`, `create`, `update`, `delete`	Publique comentários de auditoria e discussões em cartões.
`mcp_kanban_label_manager`	`get_all`, `create`, `update`, `delete`, `add_to_card`, `remove_from_card`	Gerencie taxonomias de etiquetas dos quadros com 10+ cores padrão do Planka.
`mcp_kanban_card_membership_manager`	`get_all`, `create`, `delete`, `get_users`	Atribua e remova membros com resolução automática por e-mail/nome de usuário.

🚀 Começando

1. Pré-requisitos

Uma instância Planka v2.x em execução acessível pela rede.
Uma conta de usuário ou conta de bot de serviço no Planka.

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

No modo local, o servidor MCP se conecta via entrada/saída padrão (stdio).

Configuração com `npx` (Recomendado)

Adicione a definição do servidor ao arquivo de configuração do seu cliente (ex.: claude_desktop_config.json ou Configurações do 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"
      }
    }
  }
}

Configuração Local da Fonte

{
  "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)

Execute o servidor como um daemon HTTP centralizado para atender agentes remotos, plataformas em nuvem ou múltiplos desenvolvedores simultâneos.

Iniciando o 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

👥 Credenciais Multi-Tenant por Chamada

Ao executar no modo SSE, você não precisa armazenar credenciais de usuários no .env do servidor. Em vez disso, cada cliente envia suas próprias credenciais durante o handshake da conexão SSE.

Opção A: Via Cabeçalhos 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

(Suporta também Authorization: Basic <base64(email:password)> padrão).

Opção B: Via Parâmetros de Consulta na URL (GET /sse) (Ideal para clientes de navegador e EventSource padrão)

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

Endpoints e Protocolos

O servidor suporta nativamente tanto o moderno Transporte HTTP Streamable quanto o Transporte SSE Legado:

POST /sse, POST /mcp, POST /: Handshake HTTP Streamable e chamadas JSON-RPC com gerenciamento de sessão via cabeçalho Mcp-Session-Id.
GET /sse: Handshake de stream persistente SSE legado.
POST /messages?sessionId=...: Endpoint de mensagens do cliente SSE legado.
GET /health ou GET /: Endpoint de healthcheck e informações do servidor (200 OK).

4. Executando com Docker e GHCR

A imagem do contêiner é publicada no 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. Configurações de Integração com Clientes

A. IDE Antigravity

Configure o servidor MCP em ~/.gemini/config/mcp_config.json (ou .agent/mcp_config.json no seu workspace):

Modo Contêiner Remoto / HTTP SSE (Recomendado):

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

Modo Local Stdio:

{
  "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

Edite o arquivo de configuração do Claude Desktop (%APPDATA%\Claude\claude_desktop_config.json no Windows, ~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

Modo Contêiner Remoto / HTTP SSE (via bridge mcp-remote):

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

Modo Local Stdio:

{
  "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)

Você pode anexar o servidor globalmente ou localmente usando a 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

Ou configure .mcp.json na raiz do seu projeto:

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

D. IDE Cursor

No Cursor, vá em Settings > Features > MCP, clique em Add New MCP Server:

Nome: planka-mcp
Tipo: sse
URL do Servidor: http://127.0.0.1:3001/sse

Ou em .cursor/mcp.json:

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

💬 Exemplos de Prompts para IA

Após a configuração, você pode comandar seu assistente de IA em linguagem natural:

"Mostre-me um resumo de todos os projetos e quadros."
"Organize o quadro Backlog e divida o cartão principal em tarefas."
"Mova o cartão 'Implementar OAuth' para 'Em Andamento' e adicione um comentário de que o trabalho começou."
"Crie uma Lista de Tarefas 'Banco de Dados' no cartão 'Migração' e adicione 3 itens de checklist."
"Inicie o cronômetro no cartão 'Refatorar cliente de API'."
"Atribua @sarah.connor ao cartão 'Auditoria de Segurança'."

📖 Wiki e Documentação

Referência da API: Esquema detalhado e ações para cada ferramenta.
Guia do Desenvolvedor: Arquitetura, configuração local e diretrizes de contribuição.
Capacidades e Estratégias: Fundamentação do design e padrões de otimização para Cursor.
Guia de Uso: Fluxos de trabalho práticos e exemplos de cenários.
Guia de Instalação: Configuração passo a passo em várias plataformas.

🏗️ Desenvolvimento e Testes

# 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

🚀 Lançamentos Automatizados

Os lançamentos são automatizados usando GitHub Actions. Enviar uma tag semântica de git (ex.: v1.4.0) aciona:

Suíte automatizada de testes unitários e compilação.
Publicação do pacote NPM (@navyatec/planka-v2-mcp).
Build da imagem Docker multi-estágio e push para o GitHub Container Registry (GHCR).
Criação de Release no GitHub com notas de versão e tarball de produção anexado.

📄 Licença

Este projeto está licenciado sob a Licença MIT.

Desenvolvido e mantido por NAVYA TECNOLOGÍA 2024, S.L. (Projeto original por Brad Risse)