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": "user@example.com",
    "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

1. Abra as configurações do Cursor (MCP).
2. 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.