Meu Runrun.it MCP

Servidor MCP em C# que conecta o Runrun.it ao seu fluxo no Cursor: lê tarefas (com comentários) e ajuda a localizar arquivos em qualquer repositório que você indicar — MVC 5, ASP.NET Core, React, Node, etc.

Este repositório é só o servidor MCP. O código que você analisa fica em outro projeto, em outra pasta.

Índice

Visão geral
Pré-requisitos
Instalação global (sem abrir este projeto) recomendado
Instalação para desenvolvimento
Como usar em outro projeto
Fluxo de trabalho recomendado
Ferramentas disponíveis
Exemplos de prompts no Cursor
Configuração opcional
Solução de problemas
Versionamento e releases
Build e desenvolvimento

Visão geral

┌─────────────┐     stdio      ┌──────────────────┐     HTTPS      ┌─────────────┐
│   Cursor    │ ◄────────────► │ meu-runrunit-mcp │ ◄────────────► │  Runrun.it  │
│  (agente)   │                │  (este repo)     │                │    API      │
└─────────────┘                └────────┬─────────┘                └─────────────┘
                                        │
                                        │ lê arquivos no disco
                                        ▼
                               ┌──────────────────┐
                               │  OUTRO PROJETO   │  ← projectRoot que você informa
                               │  (MVC, React…)   │
                               └──────────────────┘

O parâmetro projectRoot é o caminho absoluto da raiz do repositório alvo (onde está a .sln, package.json, Web.config, etc.). Não use a pasta do MCP.

Pré-requisitos

.NET 8 SDK ou superior (o app targeta net8.0 com roll-forward para runtimes 9/10)
Cursor com MCP habilitado
Conta Runrun.it com App-Key e User-Token (Configurações → Integrações → API)
O outro projeto clonado/local no disco, com caminho que você conhece (ex.: C:\dev\cliente\portal-web)

Instalação global (sem abrir este projeto)

Você não precisa ter a pasta meu-runrunit-mcp aberta no Cursor. O MCP é registrado uma vez no arquivo global do usuário e fica disponível em qualquer workspace (MVC, React, API, etc.).

Como o Cursor enxerga o MCP

| Arquivo | Escopo | |---------|--------| | %USERPROFILE%\.cursor\mcp.json | Global — vale para todos os projetos | | .cursor/mcp.json na pasta do projeto | Só aquele workspace (opcional) |

Use o global para não repetir config em cada cliente.

Passo 1 — Publicar o MCP em uma pasta fixa

No PowerShell, na pasta deste repositório (só na primeira vez ou após atualizar o código):

cd C:\dev\projetos\trabalho\meu-runrunit-mcp
.\scripts\publish-global.ps1

O script verifica os User Secrets antes de publicar:

| Situação | O que o script faz | |----------|-------------------| | Sem App-Key / User-Token | Pede para preencher | | Já configurado | Pergunta: manter secrets [S] ou informar novas [N] |

As credenciais ficam em %APPDATA%\Microsoft\UserSecrets\ — não na pasta da DLL. Republicar não exige digitar de novo, a menos que você escolha [N].

Pular a verificação: .\scripts\publish-global.ps1 -SkipSecretsCheck
Forçar novas credenciais: .\scripts\publish-global.ps1 -ForceNewSecrets

Isso gera os binários em:

%LOCALAPPDATA%\MeuRunrunItMCP\
  MeuRunrunItMCP.dll
  appsettings.json
  ...

Equivalente manual:

dotnet publish MeuRunrunItMCP.csproj -c Release -o "%LOCALAPPDATA%\MeuRunrunItMCP"

Passo 2 — Configurar o Cursor (global)

Edite %USERPROFILE%\.cursor\mcp.json:

{
  "mcpServers": {
    "meu-runrunit": {
      "command": "dotnet",
      "args": [
        "exec",
        "C:\\Users\\SEU_USUARIO\\AppData\\Local\\MeuRunrunItMCP\\MeuRunrunItMCP.dll"
      ]
    }
  }
}

Substitua SEU_USUARIO pelo seu usuário Windows. Exemplo completo com credenciais em variáveis de ambiente: docs/mcp.global.example.json.

Passo 3 — Credenciais Runrun.it (se ainda não configurou no publish)

Opção A — Só credenciais (sem publish)

.\scripts\configure.ps1

Mesma lógica do publish-global: detecta secrets existentes e pergunta manter ou criar novas.

Opção B — Setup completo (credenciais + publish)

.\scripts\setup.ps1

Opção C — Variáveis no mcp.json (funciona sem User Secrets)

"env": {
  "RunrunIt__AppKey": "sua-app-key",
  "RunrunIt__UserToken": "seu-user-token"
}

Passo 4 — Usar em qualquer outro projeto

Abra no Cursor apenas o projeto do cliente (ex.: C:\dev\acme\portal-web).
No chat, chame as tools com projectRoot apontando para esse projeto.
O MCP sobe em segundo plano via mcp.json global — não precisa do workspace do MCP.

Atualizar o MCP após mudanças no código

cd C:\dev\projetos\trabalho\meu-runrunit-mcp
.\scripts\publish-global.ps1

Na republicação, pressione S para manter as credenciais já salvas (padrão).

Reinicie o Cursor (ou desligue/ligue o servidor MCP nas configurações).

Comparação das formas de instalação

| Modo | Comando no mcp.json | Precisa repo aberto? | Velocidade | |------|------------------------|----------------------|------------| | Publicado (recomendado) | dotnet exec ...\MeuRunrunItMCP.dll | Não | Mais rápido | | dotnet run --project | Caminho absoluto do .csproj | Não (só pasta no disco) | Compila ao iniciar | | Workspace local | .cursor/mcp.json no projeto | Só se usar config local | — |

Instalação para desenvolvimento

Use esta seção se você está alterando o código do MCP. Para só usar em outros projetos, prefira Instalação global.

1. Clone ou mantenha este repositório

Exemplo:

C:\dev\projetos\trabalho\meu-runrunit-mcp

2. Credenciais Runrun.it (User Secrets)

No terminal, na pasta do MCP:

cd C:\dev\projetos\trabalho\meu-runrunit-mcp
.\scripts\configure.ps1

3. Registre o MCP no Cursor (modo desenvolvimento)

Em %USERPROFILE%\.cursor\mcp.json, apontando para o .csproj (caminho absoluto):

{
  "mcpServers": {
    "meu-runrunit": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\dev\\projetos\\trabalho\\meu-runrunit-mcp\\MeuRunrunItMCP.csproj"
      ]
    }
  }
}

Para uso diário em outros projetos, prefira a instalação global publicada.

4. Reinicie o Cursor

Feche e abra o Cursor (ou recarregue a janela) para o servidor MCP subir.

5. Confirme que as tools aparecem

No chat, o agente deve listar ferramentas como:

analyze_task_against_code
get_task_context
search
read_file
validate_project_root

Como usar em outro projeto

Você não copia o MCP para dentro do outro projeto. Você aponta o MCP para a pasta dele em cada uso.

O que é `projectRoot`

| Correto | Incorreto | |---------|-----------| | C:\dev\cliente-a\portal-mvc5 (raiz do app) | C:\dev\projetos\trabalho\meu-runrunit-mcp | | Pasta que contém Controllers/, src/, .sln, etc. | Pasta bin\ ou node_modules\ |

Use sempre caminho absoluto no Windows (C:\...).

Prioridade do caminho

projectRoot na chamada da tool (recomendado para vários clientes/repos)
CodeAnalysis:ProjectRoot na config (atalho se você usa sempre o mesmo repo)
Se faltar os dois → erro pedindo o caminho

Abrir o “outro projeto” no Cursor

Duas formas comuns:

A) Workspace só do projeto alvo
Abra a pasta do cliente no Cursor e, no chat, informe o mesmo caminho em projectRoot.

B) Workspace com MCP + projeto
Abra uma pasta pai ou multi-root; no prompt, passe o projectRoot absoluto do repo que quer analisar.

O MCP lê o disco diretamente — não depende de qual pasta está aberta no editor, desde que o caminho exista e seja legível.

Passo a passo rápido

Pegue o ID da tarefa no Runrun.it (número na URL, ex.: .../tasks/12345 → 12345).
Defina o caminho absoluto do repositório alvo.
No Cursor, peça algo como:

Use analyze_task_against_code com taskId 12345 e projectRoot C:\dev\cliente-a\portal-mvc5.
Depois diga quais arquivos devo alterar e por quê.

Se precisar de detalhe, peça read_file com o mesmo projectRoot e o caminho relativo retornado na busca.

Fluxo de trabalho recomendado

Cenário: nova tarefa em um projeto MVC 5

1. validate_project_root  → confirma que o caminho existe
2. analyze_task_against_code → tarefa + comentários + lista de arquivos
3. read_file               → trechos dos arquivos mais relevantes
4. (você / agente)         → plano de implementação e código

Cenário: só ler a tarefa (sem código)

get_task_context com taskId 12345

Cenário: outro repositório no mesmo dia

Troque apenas o projectRoot; credenciais Runrun.it são as mesmas:

analyze_task_against_code taskId 200 projectRoot C:\dev\cliente-b\api-node

Ferramentas disponíveis

| Ferramenta | Quando usar | Parâmetros principais | |------------|-------------|------------------------| | analyze_task_against_code | Fluxo completo (tarefa + busca no código) | taskId, projectRoot, extraQuery?, maxResults? | | get_task_context | Só título, descrição e comentários | taskId | | search | Busca manual por termos | projectRoot, query?, taskContext?, maxResults? | | read_file | Ler trecho de um arquivo | projectRoot, relativePath, startLine?, endLine? | | validate_project_root | Testar caminho antes de analisar | projectRoot? |

Tipos de arquivo considerados na busca (entre outros): .cs, .cshtml, .js, .ts, .tsx, .vue, .py, .java, .go, .json, .xml, .config, .sql, .md.

Pastas ignoradas: bin, obj, node_modules, .git, dist, packages, etc.

Exemplos de prompts no Cursor

Substitua TASK_ID, caminhos e nomes pelos seus valores reais.

ASP.NET MVC 5 (Full Framework)

Valide projectRoot C:\dev\acme\MeuPortalMvc5.
Em seguida use analyze_task_against_code na tarefa TASK_ID com esse projectRoot.
Liste controllers e views impactados e um plano de alteração.

ASP.NET Core

analyze_task_against_code taskId TASK_ID projectRoot C:\dev\acme\MinhaApiCore

Frontend React / Node

analyze_task_against_code taskId TASK_ID projectRoot C:\dev\acme\frontend
extraQuery "checkout pagamento"

Ler arquivo específico após a análise

Use read_file com projectRoot C:\dev\acme\MeuPortalMvc5,
relativePath Areas/Vendas/Controllers/PedidoController.cs e startLine 1 endLine 120.

Vários projetos na mesma sessão

Primeiro analise a tarefa 100 no projeto C:\dev\projeto-a.
Depois analise a tarefa 200 no projeto C:\dev\projeto-b.
Use analyze_task_against_code em cada um com o projectRoot correto.

Configuração opcional

Arquivo appsettings.json (valores vazios por padrão):

{
  "RunrunIt": {
    "BaseUrl": "https://runrun.it/api/v1.0",
    "AppKey": "",
    "UserToken": ""
  },
  "CodeAnalysis": {
    "ProjectRoot": "",
    "MaxSearchResults": 25,
    "MaxFileReadLines": 200,
    "MaxTerms": 30
  }
}

Repositório padrão (opcional)

Se você trabalha sempre no mesmo repo e não quer repetir o caminho:

dotnet user-secrets set "CodeAnalysis:ProjectRoot" "C:\dev\meu-repo-padrao"

No chat pode omitir projectRoot — o MCP usa esse padrão. Para outro projeto, passe projectRoot na chamada (ele tem prioridade).

Variáveis de ambiente (alternativa)

No mcp.json, se preferir não usar User Secrets:

{
  "mcpServers": {
    "meu-runrunit": {
      "command": "dotnet",
      "args": ["run", "--project", "C:\\...\\MeuRunrunItMCP.csproj"],
      "env": {
        "RunrunIt__AppKey": "sua-key",
        "RunrunIt__UserToken": "seu-token",
        "CodeAnalysis__ProjectRoot": "C:\\dev\\repo-opcional"
      }
    }
  }
}

Solução de problemas

| Problema | Causa provável | O que fazer | |----------|----------------|-------------| | Credenciais Runrun.it ausentes | App-Key / User-Token não configurados | .\scripts\configure.ps1 ou env no mcp.json | | Informe projectRoot... | Caminho não passado e config vazia | Informe projectRoot absoluto no prompt | | ProjectRoot não encontrado | Caminho errado ou pasta não existe | Confira o disco; use validate_project_root | | não parece um repositório de código | Pasta vazia ou só documentação | Aponte para a raiz da solution/app | | Nenhum arquivo na busca | Termos da tarefa muito genéricos | Use extraQuery com nomes de tela, controller, módulo | | Tools não aparecem no Cursor | MCP não carregou | Verifique mcp.json, dotnet build, reinicie o Cursor | | Erro ao compilar o MCP | SDK incompatível | Instale .NET 8 SDK ou superior | | Erro ao iniciar o MCP publicado | Runtime ausente | Instale .NET 8 Runtime (8, 9 ou 10 com roll-forward) |

Compatibilidade .NET

O projeto compila para net8.0 com RollForward: Major no .csproj. Isso significa:

Build: .NET 8 SDK ou superior.
Execução (publish global): qualquer máquina com .NET 8, 9 ou 10 runtime instalado.
Não é necessário ter exatamente a mesma versão do SDK usada no desenvolvimento.

Após alterar a versão do framework, rode .\scripts\publish-global.ps1 de novo e reinicie o Cursor.

Versionamento e releases

Este repositório usa Conventional Commits, Semantic Versioning e Semantic Release (via Node.js apenas para tooling de git/release — o app continua em .NET).

Pré-requisito

Node.js 20+ (para Commitizen, Commitlint e Husky localmente)

Na primeira vez, na pasta do repositório:

npm install

O script prepare configura o Husky e valida mensagens de commit no hook commit-msg.

Commits no dia a dia

| Ferramenta | Uso | |------------|-----| | Commitizen | npm run commit — assistente interativo (feat, fix, chore, etc.) | | Commitlint | Valida automaticamente no git commit (hook Husky) | | Conventional Commits | Formato: tipo(escopo opcional): descrição |

Exemplos válidos:

feat: adicionar busca por tag na API Runrun.it
fix(tools): corrigir projectRoot com barras invertidas
chore: atualizar dependências MCP

Commits que não seguem o padrão são rejeitados localmente antes de subir.

Releases automáticas (Semantic Release)

Ao fazer push na branch main, o workflow .github/workflows/release.yml:

Analisa commits desde a última tag (feat → minor, fix → patch, BREAKING CHANGE → major).
Gera/atualiza CHANGELOG.md (Conventional Changelog).
Atualiza <Version> em MeuRunrunItMCP.csproj e package.json.
Cria tag Git e GitHub Release com notas.

O commit de release usa [skip ci] para não disparar outro release em loop.

Importante: commits antigos fora do padrão convencional não entram no cálculo da próxima versão. A partir da adoção deste fluxo, use sempre npm run commit ou mensagens no formato conventional.

Referência rápida de tipos

| Tipo | Versão (SemVer) | Exemplo | |------|-----------------|---------| | feat | minor | nova tool MCP | | fix | patch | correção de bug | | perf | patch | melhoria de performance | | BREAKING CHANGE no corpo ou ! após tipo | major | remoção de parâmetro |

Documentação: Conventional Commits, Semantic Versioning.

Build e desenvolvimento

cd C:\dev\projetos\trabalho\meu-runrunit-mcp
dotnet build MeuRunrunItMCP.slnx

Executar localmente (teste):

dotnet run --project MeuRunrunItMCP.csproj

API Runrun.it

GET /tasks/{id} — detalhe da tarefa (título, projeto, quadro, etc.)
GET /descriptions?subject_type=Task&subject_id={id} — corpo da descrição (HTML)
GET /tasks/{id}/comments — comentários da tarefa (apenas de usuários; automáticos do Runrun.it são filtrados)

Documentação oficial: https://runrun.it/api/documentation

Resumo

| Pergunta | Resposta | |----------|----------| | Preciso abrir o projeto do MCP no Cursor? | Não. Use mcp.json global + publish. | | Preciso instalar o MCP dentro do outro projeto? | Não. Só projectRoot no prompt. | | Como indico o outro projeto? | Parâmetro projectRoot com caminho absoluto. | | Posso usar em vários projetos? | Sim. Mude o projectRoot a cada tarefa/cliente. | | O MCP analisa só MVC 5? | Não. Qualquer repo com arquivos-fonte suportados. | | Onde ficam as credenciais Runrun.it? | User Secrets ou env no mcp.json global. |