mcp-runrunit

MCP Runrun.it

Servidor MCP (Model Context Protocol) para comunicação com a API do Runrun.it. Expõe ferramentas de Tasks e Comments para uso no Cursor ou em outros clientes MCP.

Versão atual: 1.8.1 — ver CHANGELOG.md.

Arquitetura

O projeto adota o padrão Arquitetura Hexagonal (Ports & Adapters): o núcleo da aplicação fica isolado de detalhes de transporte (stdio, HTTP) e do cliente HTTP do Runrun.it. As portas definem contratos de entrada (MCP) e saída (acesso à API); os adaptadores implementam esses contratos (transporte e cliente HTTP).

Mapeamento no projeto

• Núcleo / aplicação: regras e orquestração dos casos de uso (Tasks e Comments). Arquivos: src/application/tasks.ts, src/application/comments.ts; em uma evolução podem depender apenas de uma abstração de "cliente Runrun.it" (porta de saída).
• Porta de entrada (driving): protocolo MCP (ListTools, CallTool). Implementada em src/adapters/driving/app.ts (registro de tools e handler que delega para a aplicação).
• Adaptadores de entrada: como o MCP é acessado — src/index.ts (stdio) e src/server.ts (HTTP). Ambos usam o mesmo createMcpServer().
• Porta de saída (driven): contrato para acessar o Runrun.it (listar/criar tarefas, comentários, etc.). Hoje usada implicitamente; em uma evolução pode ser uma interface TypeScript injetada.
• Adaptador de saída: implementação HTTP da API Runrun.it em src/adapters/driven/api.ts (auth, runrunitFetch, tratamento de erros).

Fluxo

flowchart LR
  subgraph driving [Driving]
    Client[Cursor / Cliente MCP]
    Transport[Adaptadores stdio / HTTP]
    MCP[app.ts - MCP Tools]
  end
  subgraph core [Núcleo]
    App[Application - tasks.ts / comments.ts]
  end
  subgraph driven [Driven]
    Port[Porta Runrun.it]
    Adapter[api.ts - Cliente HTTP]
    API[API Runrun.it]
  end
  Client --> Transport
  Transport --> MCP
  MCP --> App
  App --> Port
  Port --> Adapter
  Adapter --> API

Estrutura de pastas

Pasta / Arquivos	Papel
src/index.ts, src/server.ts	Pontos de entrada (adaptadores de transporte stdio e HTTP)
src/domain/	Domínio (tipos e portas para evolução futura)
src/application/	Núcleo de aplicação: tasks.ts, comments.ts (casos de uso)
src/adapters/driving/	Adaptador de entrada: app.ts (MCP — definição de tools e handler CallTool)
src/adapters/driven/	Adaptador de saída: api.ts (cliente HTTP Runrun.it)

A separação permite trocar o transporte (stdio vs HTTP) sem alterar o núcleo e, no futuro, mockar ou trocar a implementação da API Runrun.it para testes ou outros backends.

Autenticação

A API do Runrun.it exige dois headers em toda requisição:

• App-Key: identifica a conta (obtido em Integração e Apps → API e Webhooks)
• User-Token: token do usuário em nome do qual as ações são executadas

Configure as variáveis de ambiente (ou no JSON de configuração do MCP no Cursor):

• RUNRUNIT_APP_KEY — chave da aplicação
• RUNRUNIT_USER_TOKEN — token do usuário

GitHub (opcional; tools runrunit_share_cursor_agent e runrunit_share_cursor_skill):

• GITHUB_TOKEN — PAT ou token com permissão de escrita em contents e pull_requests no repositório alvo
• GITHUB_REPO_OWNER, GITHUB_REPO_NAME — repositório onde abrir o PR (opcional se project_root for um repo git com origin no GitHub; detectados automaticamente)
• GITHUB_BASE_BRANCH — branch base (opcional; detectada via git symbolic-ref refs/remotes/origin/HEAD, senão main)

Prioridade: variáveis de ambiente > detecção git no project_root > default main.

Exemplo mínimo no MCP host (só credenciais; repositório e branch base vêm do origin do projeto em que o agente trabalha):

{
  "env": {
    "GITHUB_TOKEN": "ghp_...",
    "BITBUCKET_USERNAME": "[e-mail]",
    "BITBUCKET_APP_PASSWORD": "..."
  }
}

Bitbucket (opcional; tools runrunit_share_cursor_agent_bitbucket e runrunit_share_cursor_skill_bitbucket):

• BITBUCKET_USERNAME, BITBUCKET_APP_PASSWORD — credenciais (obrigatórias no host MCP)
• BITBUCKET_WORKSPACE, BITBUCKET_REPO_SLUG — repositório alvo (opcional se project_root tiver origin no Bitbucket)
• BITBUCKET_BASE_BRANCH — branch base (opcional; mesma detecção git que GitHub)

Estas variáveis existem só no anfitrião do processo MCP (ficheiro de config do Cursor, CI, segredos da org). Não passe token nem credenciais como argumento de tool nem partilhe em chat ou repositório.

Sentry (opcional; monitoramento de erros do MCP):

• SENTRY_DSN — DSN do projeto Sentry
• SENTRY_ENVIRONMENT — ambiente (development, staging, production)
• SENTRY_RELEASE — versão/release (ex.: mcp-runrunit@1.8.1+abc1234)
• SENTRY_ENABLED — liga/desliga o envio de eventos
• SENTRY_ERROR_SAMPLE_RATE — taxa de amostragem de erros (0.0 a 1.0; default 1.0)

Recomendação: manter sendDefaultPii desabilitado (já aplicado no código) e configurar segredos apenas no ambiente do host MCP/CI. Guia operacional de validação/rollout: docs/SENTRY-ROLLOUT.md.

Instalação e utilização local

cd mcp-runrunit
npm install
npm run build

Uso no Cursor

• Abra as configurações do Cursor (MCP).
• Adicione o servidor no arquivo de configuração de MCP (por exemplo em .cursor/mcp.json ou nas configurações do Cursor).

Exemplo de configuração (ajuste o caminho para o seu projeto):

{
  "mcpServers": {
    "runrunit": {
      "command": "node",
      // Use o caminho absoluto para `dist/index.js` no seu ambiente.
      "args": ["caminho-do-repositório-local/mcp-runrunit/dist/index.js"],
      "env": {
        "RUNRUNIT_APP_KEY": "sua_app_key",
        "RUNRUNIT_USER_TOKEN": "seu_user_token"
      }
    }
  }
}

// ou

"runrunit-mcp": {
      "url": "http://localhost:3000/mcp",
      "env": {
        // Nesse modo é importante criar o arquivo .env na raiz do mcp ./plugin-sentinel-mcp/mcp-runrunit
      }
    },

Uso via npm (para outras pessoas)

Depois de publicado no npm, qualquer pessoa pode usar com npx sem clonar o repositório:

{
  "mcpServers": {
    "runrunit": {
      "command": "npx",
      "args": ["-y", "mcp-runrunit"],
      "env": {
        "RUNRUNIT_APP_KEY": "<RUNRUNIT_APP_KEY>",
        "RUNRUNIT_USER_TOKEN": "<RUNRUNIT_USER_TOKEN>",
        "BOT_DISCORD_TOKEN_PUBLIC_ID": "<BOT_DISCORD_TOKEN_PUBLIC_ID>",
        "BOT_RUNRUNIT_REPORT_PRIVATE_KEY": "<BOT_RUNRUNIT_REPORT_PRIVATE_KEY>",
        "DISCORD_GUILD_ID": "<DISCORD_GUILD_ID>",
        "DISCORD_CHANNEL_ID": "<DISCORD_CHANNEL_ID>"
      }
    }
  }
}

Cursor Skills e agentes (evidências, PR, comentários na task, agents)

O pacote inclui skills (cursor-skills/) e agentes (cursor-agents/) organizados em subpastas por plataforma, tecnologia ou utilidade. O índice machine-readable está em cursor-catalog.json (ids estáveis, paths no repo, tags platform / technology / utility).

Para descobrir o que instalar, use runrunit_list_cursor_catalog (filtros opcionais, ex. platform: ["runrunit"]). Para copiar para o Cursor local, use runrunit_install_cursor_skills ou runrunit_install_cursor_agents com dry_run: true primeiro. Parâmetros opcionais: skill_names / agent_names, categories (intersecta com nomes quando ambos existem), target (global ou project + project_root), source_dir.

O destino no Cursor permanece plano: ~/.cursor/skills/{id}/ e ~/.cursor/agents/{basename}.md — os ids públicos (ex. comentar-task-runrunit) não mudam.

Alternativa manual — skills: copie (ou crie link) das pastas em node_modules/mcp-runrunit/cursor-skills/ para um destes diretórios:

• Global: ~/.cursor/skills/ (ex.: ~/.cursor/skills/registrar-evidencias, etc.)
• Por projeto: .cursor/skills/ ou .agents/skills/ na raiz do projeto

Alternativa manual — agentes: copie os .md de node_modules/mcp-runrunit/cursor-agents/ para ~/.cursor/agents/ (ou .cursor/agents/ no projeto).

Ferramentas (Tools)

Tasks

Ferramenta	Descrição
runrunit_list_tasks	Lista tarefas com filtros opcionais (ids, responsible_id, assignee_id, filter_id, board_stage_id, project_id, etc.)
runrunit_list_task_filters	Lista filtros de tarefas (para obter filter_id de "Minhas partes abertas")
runrunit_list_board_stages	Lista stages do board (Task, Ongoing, Manager Validation) — use com runrunit_move_task_stage ao mover por nome
runrunit_move_task_stage	Move uma tarefa para uma etapa/coluna do board (task_id + board_stage_id ou board_stage_name). Para etapas que exigem "Link da branch", preencher antes com runrunit_update_task
runrunit_get_task	Retorna uma tarefa pelo ID
runrunit_list_subtasks	Lista subtarefas de uma tarefa
runrunit_create_task	Cria tarefa (obrigatório: title, type_id; opcional: project_id, assignments, desired_date, etc.)
runrunit_update_task	Atualiza tarefa (id + objeto com campos a atualizar, ex.: title, desired_date, link_da_branch). Para mover entre colunas use runrunit_move_task_stage
runrunit_delete_task	Remove uma tarefa
runrunit_create_workflow	Cria workflow para uma tarefa (permite iniciar tracking)
runrunit_assignment_play	Inicia tracking (play) em um assignment de tarefa

Comments

Ferramenta	Descrição
runrunit_list_task_comments	Lista comentários de uma tarefa
runrunit_get_comment	Retorna um comentário pelo ID
runrunit_create_comment	Cria comentário em tarefa (task_id, text)
runrunit_create_external_comment	Cria comentário na sessão externa/guest (compartilhada com clientes; channel_name: guest)
runrunit_update_comment	Edita o texto de um comentário
runrunit_delete_comment	Remove um comentário
runrunit_comment_reaction	Adiciona reação (emoji) a um comentário

Discord

Ferramenta	Descrição
runrunit_discord_send_message	Envia mensagem em um canal do Discord (channel_id, content; opcional task_id, project_id). Requer BOT_RUNRUNIT_REPORT.
runrunit_discord_create_channel	Cria um canal de texto no servidor (guild). Parâmetros: name (slug, ex.: client-1); opcional guild_id, parent_id, topic. Usa DISCORD_GUILD_ID se guild_id não for passado.
runrunit_discord_list_channels	Lista canais do servidor Discord. guild_id opcional (usa DISCORD_GUILD_ID ou resolve por DISCORD_CHANNEL_ID).
runrunit_discord_get_or_create_channel	Obtém ou cria um canal por cliente Runrun.it (1 canal por cliente). client_id ou client_name (ex.: "Client 1" → slug client-1). Retorna channel_id e channel_name; use antes de enviar mensagens.

Cursor (skills e agentes do pacote)

Ferramenta	Descrição
runrunit_list_cursor_catalog	Lista skills e agentes de cursor-catalog.json com categorias e descrição. Filtros: kind, platform, technology, utility.
runrunit_install_cursor_skills	Só instalação local: copia skills para ~/.cursor/skills ou projeto. Filtros: skill_names, categories. Não usar para partilhar no GitHub — use runrunit_share_cursor_skill.
runrunit_install_cursor_agents	Só instalação local: copia agentes para ~/.cursor/agents (basename preservado). Filtros: agent_names, categories. PR no repo: runrunit_share_cursor_agent.
runrunit_share_cursor_agent	Partilha com o time (PR GitHub): abre PR com o ficheiro no path do catálogo (cursor-agents/{path}). Requer GITHUB_TOKEN no servidor MCP; owner, repo e branch base detectados do git em project_root (env sobrescreve).
runrunit_share_cursor_skill	Partilha com o time (PR GitHub): abre PR com a pasta completa no path do catálogo (cursor-skills/{path}/). Resposta inclui file_count e paths. Mesma detecção git que runrunit_share_cursor_agent.
runrunit_share_cursor_agent_bitbucket	Partilha com o time (PR Bitbucket): abre PR com um agente em cursor-agents/{path}. Requer credenciais Bitbucket no host MCP; workspace, repo e branch base detectados do git em project_root.
runrunit_share_cursor_skill_bitbucket	Partilha com o time (PR Bitbucket): abre PR com a pasta completa da skill. Mesma detecção git e credenciais que runrunit_share_cursor_agent_bitbucket.

Skills

Skills em cursor-skills/:

Skill	Descrição
code-reviewer	Revisão de código alinhada aos padrões da agência. Use ao revisar PRs, sugerir melhorias ou validar implementações.
registrar-evidencias	Captura screenshots em múltiplos viewports (mobile, tablet, desktop) a partir de URLs "antes" e "depois". Usar para evidências visuais, comparar antes/depois, documentar mudanças de UI ou preparar imagens para PRs e relatórios.
comentar-task-runrunit	Orquestra evidências e comentário na tarefa do Runrun.it: captura antes/depois, opcionalmente abre PR e cria comentário na task com resumo, passo a passo de teste e referências; grava link_da_branch e link_da_branch_relatorio (custom_12) na task se houver PR.
create-pr-github	Cria um pull request bem estruturado, com descrição, rótulos, revisores e evidências visuais. Inclui preparar branch, descrição, checklist e output obrigatório (link da PR, branch, ambiente de destino).
install-cursor-team-skills	Orienta runrunit_install_cursor_skills (cópia local) e distingue de runrunit_share_cursor_skill (PR no GitHub quando pedirem compartilhar com o time).
react-best-practices	Checklist e regras de performance para React e Next.js (Vercel). Use ao editar TSX/JSX, revisar componentes ou otimizar bundle e render. Inclui ficheiros detalhados em rules/ e o documento compilado AGENTS.md.

Agents

Agente	Nome exibido	Descrição	Quando usar
context-bridge	Doc-Brief (Implementation Brief)	Filtro de documentação técnica: extrai lógica de implementação, assinaturas e dependências em Implementation Briefs de alta densidade; remove marketing e redundância.	Quando precisar transformar documentação longa em um resumo técnico pronto para implementação (Quick Start, Core Logic, API Reference, Gotchas).
kieran-typescript-reviewer	kieran-typescript-reviewer	Revisa código TypeScript com barra de qualidade alta em type safety, padrões modernos e manutenibilidade.	Após implementar features, modificar código ou criar novos componentes TypeScript; para garantir convenções e boas práticas.
mentor	Mentor mode	Ajuda a mentorar o engenheiro com orientação e suporte, sem editar código.	Quando quiser desafiar premissas, fazer perguntas socráticas e guiar a solução sem dar a resposta pronta.
prd	Create PRD Chat Mode	Gera um PRD (Product Requirements Document) em Markdown com user stories, critérios de aceite, considerações técnicas e métricas; opcionalmente cria issues no GitHub.	Para documentar requisitos de produto de forma estruturada e, se desejado, gerar issues a partir das user stories.
toph	Toph	Especialista em acessibilidade web (WCAG 2.1/2.2), UX inclusiva e testes de a11y.	Para revisar acessibilidade, teclado, foco, ARIA, formulários, mídia, testes com leitores de tela e ferramentas (axe, pa11y, Lighthouse).
security-auditor	security-auditor	Revisor focado em segurança: vulnerabilidades e boas práticas (OWASP, supply chain).	Para checar injeção (SQL, XSS, comandos), autenticação/autorização, dados sensíveis, criptografia, dependências e validação de entrada.
shopify-expert	Shopify Expert	Desenvolvimento Shopify: temas Liquid, apps e APIs.	Tarefas de tema, app ou integração Shopify.

Contexto para o agente (uso assertivo das tools)

Para que o Cursor/IA use as tools de forma assertiva e inteligente, consulte:

• docs/CONTEXTO-AGENTE.md — quando usar cada tool, parâmetros (tipos, formatos), fluxos recomendados, erros comuns e glossário Runrun.it.
• docs/Atlassian-Jira-com-Runrun.it.md — como usar Atlassian (Jira) junto com o MCP Runrun.it (dois MCPs no Cursor, vínculo task ↔ issue, automação via Zapier).

No workspace do plugin existe também a regra Runrun.it MCP em .cursor/rules/runrunit-mcp.mdc, que resume essas orientações para o agente.

Documentação da API

Os endpoints seguem a documentação oficial do Runrun.it. No repositório do plugin, a pasta docs/ contém os markdowns de referência (por exemplo docs/Tasks.md e docs/Comments.md). Use docs/Indíce.md para localizar os demais endpoints. Para configurar o fluxo de trabalho (Task, Ongoing, Manager Validation), consulte docs/Workflow-Config-Exemplo.md.

Base URL da API

• https://runrun.it/api/v1.0/

Respostas são JSON; datas em ISO 8601. Limite de 100 requisições por minuto.