Coreflows MCP

Core MCP

Ferramentas MCP que transformam tickets do Jira em PRs através do Claude Code. Busca contexto do Jira, GitHub, Notion e Slack, constrói prompts estruturados, lida com git push/PR/CI — tudo de forma autônoma.

🏆 Meio que Viralizou no Product Hunt & Reddit

Configuração (5 minutos)

1. Instalação

git clone https://github.com/adaOctopus/coolplugz-core.git
cd coolplugz-core
npm install

2. Crie seu .env

cp .env.example .env

Abra .env e preencha:

Obrigatório:

Variável	Onde conseguir
GITHUB_TOKEN	github.com/settings/tokens → Gerar token clássico → marque repo + workflow
SHELL_ENV	Seu ambiente de desenvolvimento: wsl2, macos, linux, git-bash ou powershell
REPOS_ROOT	Caminho absoluto onde seus repositórios ficam, ex.: /home/you/projects

Opcional (mas recomendado):

Variável	Onde conseguir
JIRA_API_TOKEN	id.atlassian.com/manage-profile/security/api-tokens
JIRA_EMAIL	O e-mail da sua conta Atlassian
JIRA_BASE_URL	A URL do seu workspace, ex.: https://yourteam.atlassian.net
NOTION_TOKEN	notion.so/my-integrations → Criar integração → copiar token
SLACK_TOKEN	api.slack.com/apps → Criar app → Bot Token com channels:history, search:read
ANTHROPIC_API_KEY	Habilita detecção de repositório com IA a partir do texto do ticket e rascunhos inteligentes de respostas no Slack
WSL_DISTRO	Somente se SHELL_ENV=wsl2 — o nome da sua distribuição (ex.: Ubuntu)

3. Inicie o servidor

npm run dev

Você deve ver:

CoolPlugz Core MCP server listening on :3100

4. Conecte ao Claude Code (uma única vez)

claude mcp add coolplugz --transport http http://localhost:3100/mcp

5. Use

Abra o Claude Code e diga:

Show my dashboard

Start PROJ-142

É isso. O CoolPlugz cuida do resto.

---

O Que Acontece Quando Você Usa

You: "Start PROJ-142"

CoolPlugz:
  ├── Fetches Jira ticket (description, acceptance criteria, comments)
  ├── Checks GitHub for existing branches/PRs
  ├── Pulls linked Notion specs
  ├── Finds relevant Slack mentions
  ├── Figures out which repo (from ticket links or fuzzy matching)
  ├── Builds a CRISPE implementation prompt
  └── Returns loop metadata → Claude Code knows exactly what to do next

Claude Code: writes the code, runs tests

You: (or Claude Code automatically calls push_branch)

CoolPlugz:
  ├── Pushes via token-authenticated HTTPS (no SSH needed)
  ├── Handles fork detection/creation automatically
  └── Returns next action → verify_and_submit

CoolPlugz (verify_and_submit):
  ├── Verifies push landed on GitHub (via API, not trusting output)
  ├── Opens PR with correct title/body
  ├── Polls CI for up to 5 minutes
  ├── If CI passes + no review comments → auto-marks DONE
  ├── If CI fails → fetches failure logs, tells Claude Code to fix
  └── If review comments → fetches them, tells Claude Code to address

Ferramentas Disponíveis

Ferramenta	O que faz
get_dashboard	Mostra todas as suas tarefas com status, PRs e bloqueios
start_task	Busca todo o contexto de um ticket do Jira e retorna o prompt de implementação
push_branch	Envia sua branch para o GitHub — lida com autenticação, forks, tudo
verify_and_submit	Verifica o push, cria o PR, monitora o CI, conclui automaticamente se estiver verde
check_comments	Busca comentários não resolvidos de revisão de PR para tratar
complete_task	Marca uma tarefa como concluída após a verificação
get_task_state	Mostra o estado real a partir do armazenamento + API do GitHub
check_conflicts	Detecta conflitos de merge e dá passos para resolução
add_insight	Adiciona uma instrução personalizada incluída em todos os prompts futuros
morning_report	Gera um relatório de status formatado com tarefas concluídas, PRs, resultados de CI e rascunhos de mensagens do Slack
log_run	Rastreia início/fim de execução — alimenta o morning_report com dados reais de cada execução agendada

Instruções Personalizadas

Diga ao Claude Code para adicionar instruções que o CoolPlugz incluirá em todos os prompts futuros:

"Add an insight: always use pnpm, never npm or yarn"
"Add an insight: this repo uses Tailwind, no inline styles"
"Add an insight for PROJ-142: the auth module uses Passport.js"

Insights globais se aplicam a todas as tarefas. Insights por tarefa se aplicam a um único ticket. Armazenados em ~/.coolplugz/data.json e persistem entre sessões.

Como o Construtor de Prompts Funciona

Cada start_task constrói um prompt estruturado usando o framework CRISPE:

Seção	O que contém
[C] Capacidade	Papel, repositório, branch, configuração do workspace (WSL2/macOS/Linux), caminhos locais
[R] Insight	Descrição completa do ticket, critérios de aceite, comentários do Jira, especificações do Notion, contexto do Slack, comentários de revisão de PR
[I] Declaração	A instrução específica de implementação
[S] Personalidade	Estilo de código, convenções de commit (feat(PROJ-142): ...), regras de comunicação
[P] Experimento	Permissões de execução autônoma, instruções de engenharia de loop, restrições de segurança
[F] Cerca	Nunca deletar, nunca fazer push para main, nunca commitar segredos
[Q] Qualidade	Segurança de tipos, mudanças cirúrgicas, padrões de segurança
[D] Insights do desenvolvedor	Suas instruções personalizadas (de add_insight)
[E] Contexto de erro	Detalhes de falhas anteriores em novas tentativas

Engenharia de Loop

Cada resposta de ferramenta carrega metadados estruturados em vez de listas de verificação em texto livre:

State: EXECUTING → Goal: DONE
Next: push_branch({ jiraKey: "PROJ-142", branch: "proj-142-impl", repo: "org/repo" })

O Claude Code lê isso e chama a próxima ferramenta automaticamente. A máquina de estados:

IDLE → start_task → EXECUTING → push_branch → PUSHED → verify_and_submit
  → CI passed, no comments → DONE ✅
  → CI failed → fix code → push_branch → verify_and_submit (loop)
  → Review comments → fix → push_branch → verify_and_submit (loop)

Prompt de Piloto Automático

Depois que tudo estiver conectado, cole este prompt no Claude Code para executar seus tickets no piloto automático — percorrendo o Jira, escrevendo código, enviando PRs e postando atualizações no Slack:

You are my autonomous dev agent. Use the coolplugz MCP tools to work through my Jira tickets without asking me anything.

Your loop:
1. Call get_dashboard to see all tasks and their status
2. For any task in QUEUED or EXECUTING state, call start_task with its Jira key
3. Follow the loop metadata exactly — the _meta.loop in each response tells you the next tool to call
4. After writing code and running tests, call push_branch to push
5. Call verify_and_submit — it opens the PR, polls CI, and tells you what to do next
6. If CI fails, read the failure logs, fix the code, and push again
7. If there are review comments, call check_comments, address them, push again
8. When done with a task, move to the next one from the dashboard
9. After completing all tasks, post a summary of what you did

Rules:
- Never ask me for confirmation — just do it
- Never push to main — always use feature branches
- Never commit secrets or .env files
- If you get stuck after 3 retries, mark it blocked and move on
- Commit messages follow: feat(TICKET-KEY): description

Agende (roda mesmo com o laptop fechado)

Cole isto no Claude Code para configurar um agendamento diário que executa seus tickets automaticamente:

Set up a scheduled task using /schedule that runs every weekday:

- 6:00 AM: Morning run
  1. Call log_run with action "start" and trigger "morning" — save the run_id
  2. Call get_dashboard to see all tasks
  3. For every QUEUED ticket, call start_task with its Jira key
  4. Follow the loop metadata for each: code → push_branch → verify_and_submit
  5. If CI fails, fix and retry up to 3 times
  6. When all tasks are processed, call log_run with action "finish", the run_id, and all task_results
  7. Call morning_report with mode "latest" and slack_channels ["standup", "engineering"]
  8. Show me the full report output

- 12:00 PM: Midday check
  1. Call log_run with action "start" and trigger "midday"
  2. Call get_dashboard — for any task stuck in EXECUTING or CI_FAILED, retry it
  3. For tasks with review comments, call check_comments, address them, push again
  4. Call log_run with action "finish" with results
  5. Call morning_report with mode "latest"

- 5:00 PM: End of day
  1. Call log_run with action "start" and trigger "evening"
  2. Call get_dashboard and process any remaining tasks
  3. Call log_run with action "finish" with results
  4. Call morning_report with mode "today" and slack_channels ["standup", "engineering", "product"]
  5. Show me the full report — I want to see what got done today

Rules for all runs:
- Use the coolplugz MCP tools
- Never ask for confirmation — just do it
- Never push to main — always feature branches
- Never commit secrets or .env files
- If stuck after 3 retries, mark blocked and move on
- Commit messages: feat(TICKET-KEY): description
- Always call log_run start/finish so morning_report has real data

Veja o relatório a qualquer momento

Você também pode chamar o relatório manualmente no Claude Code:

Call morning_report with mode "today" and slack_channels ["standup", "engineering"]

Modos:

• latest — mostra os resultados da execução mais recente (padrão)
• today — mostra todas as tarefas atualizadas hoje
• full — mostra tudo no armazenamento

Referência de Variáveis de Ambiente

Obrigatórias

Variável	O que faz	Como conseguir
GITHUB_TOKEN	Envia branches, abre PRs, lê o estado do repositório, monitora o CI	github.com/settings/tokens → Gerar token clássico → marque os escopos repo + workflow
SHELL_ENV	Diz ao CoolPlugz como executar comandos de shell no seu ambiente	Um de: wsl2, macos, linux, git-bash, powershell
REPOS_ROOT	Onde seus repositórios estão clonados localmente	Caminho absoluto, ex.: /home/you/projects ou C:\Users\you\repos

Jira (habilita contexto de tickets)

Variável	O que faz	Como conseguir
JIRA_API_TOKEN	Busca descrição do ticket, critérios de aceite, comentários	id.atlassian.com/manage-profile/security/api-tokens → Criar token de API
JIRA_EMAIL	Autentica com o Jira (auth básica = email:token)	O e-mail da sua conta Atlassian
JIRA_BASE_URL	A URL da sua instância do Jira	ex.: https://yourteam.atlassian.net

GitHub (já coberto pelo GITHUB_TOKEN acima)

O GITHUB_TOKEN cuida de tudo: ler repositórios, enviar branches, abrir PRs, monitorar status do CI, buscar comentários de revisão, detectar forks.

Escopos necessários: repo (acesso total ao repositório) + workflow (disparar/ler CI)

Notion (habilita busca de especificações)

Variável	O que faz	Como conseguir
NOTION_TOKEN	Puxa documentos vinculados do Notion para o prompt CRISPE como contexto de referência	notion.so/my-integrations → Criar integração → Copiar "Internal Integration Secret" → Compartilhar páginas alvo com a integração

Slack (habilita rastreamento de menções + rascunhos de respostas)

Variável	O que faz	Como conseguir
SLACK_TOKEN	Rastreia menções aos seus tickets no Slack, gera rascunhos de respostas com IA	api.slack.com/apps → Criar Novo App → OAuth & Permissões → Adicionar escopos: channels:history, search:read → Instalar no workspace → Copiar Bot User OAuth Token (xoxb-...)

Recursos de IA (opcional)

Variável	O que faz	Como conseguir
ANTHROPIC_API_KEY	Habilita detecção inteligente de repositório a partir do texto do ticket + respostas do Slack redigidas por IA	console.anthropic.com → API Keys → Criar Chave

Workspace (opcional)

Variável	O que faz	Quando necessário
WSL_DISTRO	Nome da sua distribuição WSL2 para tradução de caminhos	Somente se SHELL_ENV=wsl2 (ex.: Ubuntu)
PORT	Porta do servidor MCP	Padrão: 3100 — altere se a porta estiver ocupada

Armazenamento de Dados

Todos os dados ficam em ~/.coolplugz/data.json — tarefas, snapshots de contexto, mapeamentos de repositórios, insights, histórico de prompts. Nenhum banco de dados necessário. Exclua o arquivo para começar do zero.

Arquitetura

src/
├── index.ts              # MCP server (Express + StreamableHTTP)
├── config.ts             # Reads tokens from .env
├── store.ts              # JSON file store (~/.coolplugz/data.json)
├── lib/
│   ├── loopState.ts      # State machine
│   └── response.ts       # mcpText() and mcpLoop() builders
├── context/
│   ├── jira.ts           # Jira fetcher (Basic auth)
│   ├── github.ts         # GitHub state (branches, PRs, CI)
│   ├── notion.ts         # Notion doc fetcher
│   ├── slack.ts          # Slack mentions + AI draft replies
│   ├── repoResolver.ts   # Auto-detect repo from ticket content
│   └── assemble.ts       # CRISPE prompt builder
├── orchestrator/
│   └── githubApi.ts      # GitHub API helpers
└── tools/
    ├── orchestrator.ts   # start_task, verify_and_submit, etc.
    ├── pushBranch.ts     # Token-authenticated push + fork handling
    ├── getDashboard.ts   # Text dashboard
    └── addInsight.ts     # Custom instruction management

Licença

MIT