TechDebtMCP

Tech Debt MCP Server

16 Ferramentas · 2 Recursos · 14 Linguagens · 10 Ecossistemas de Dependências

Um servidor Model Context Protocol (MCP) para analisar dívida técnica em múltiplas linguagens de programação. Projetado para integrar-se com GitHub Copilot, Claude, Cursor e outras ferramentas compatíveis com MCP.

Recursos

• Suporte a múltiplas linguagens: JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby, PHP
• Análise abrangente: Detecta vários tipos de dívida técnica, incluindo problemas de qualidade de código, vulnerabilidades de segurança e problemas de manutenibilidade
• Métricas SQALE: Calcule dívida técnica com o sistema de classificação SQALE (escala A-E)
• Análise SwiftUI: Verificações especializadas para padrões SwiftUI, gerenciamento de estado, vazamentos de memória, aninhamento de views e problemas de concorrência
• Regras personalizadas: Defina suas próprias verificações baseadas em padrões com suporte a regex
• Análise de dependências: Analise manifestos de pacotes em 10 ecossistemas (npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, Swift)
• Supressão inline: Suprima falsos positivos com // techdebt-ignore-next-line ou comentários em bloco
• Validação de configuração: Valide arquivos de configuração .techdebtrc.json quanto à correção do esquema
• Recomendações acionáveis: Fornece sugestões priorizadas para abordar a dívida técnica
• Filtragem flexível: Filtre resultados por severidade, categoria ou linguagem
• Segurança reforçada (v2.0.2): Prevenção de traversal de caminho em todas as entradas de caminho de ferramentas e recursos, validação de regex de regras personalizadas segura contra ReDoS, escape de injeção de regex em verificações SwiftUI, sanitização de caminhos absolutos em todas as mensagens de erro e varredura SAST CodeQL em cada push/PR

Linguagens Suportadas

Instalação

Instalação com um clique

VS Code (via Terminal):

code --add-mcp '{"name":"tech-debt-mcp","command":"npx","args":["-y","tech-debt-mcp@latest"]}'

Instalação com um clique

Cursor (via Terminal):

cursor --add-mcp '{"name":"tech-debt-mcp","command":"npx -y tech-debt-mcp@latest"}'

Claude Code (via Terminal):

claude mcp add tech-debt-mcp -- npx -y tech-debt-mcp@latest

Claude Desktop — adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Plugin Claude Code — adicione o marketplace deste repositório e instale o plugin:

/plugin marketplace add PierreJanineh/TechDebtMCP
/plugin install tech-debt-mcp@techdebtmcp

O plugin executa npx -y tech-debt-mcp@latest internamente — sem empacotamento de código-fonte, sempre rastreia a versão npm publicada. Consulte plugin/README.md para documentação voltada ao usuário do plugin (fluxo de instalação, transcrições de exemplo, postura de segurança).

Pacote MCPB Claude Desktop — instalação com um clique com node_modules incluído (sem npx, sem necessidade de internet em tempo de execução).

Baixe tech-debt-mcp-<version>.mcpb da última versão do GitHub e abra-o com Claude para macOS ou Windows.

Para compilar o pacote localmente:

npm install --include=dev --ignore-scripts
npm run mcpb:pack
# -> mcpb/tech-debt-mcp-<version>.mcpb

Adicione à sua configuração MCP do Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Via AI Assistant — abra Configurações > Ferramentas > AI Assistant > Model Context Protocol (MCP), clique em +, selecione Como JSON e cole:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Via GitHub Copilot for Xcode — abra Configurações > aba MCP > Editar Configuração (mcp.json):

{
  "servers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Configuração Manual

Adicione à configuração do seu cliente MCP:

{
  "mcpServers": {
    "tech-debt-mcp": {
      "command": "npx",
      "args": ["-y", "tech-debt-mcp@latest"]
    }
  }
}

Para desenvolvimento: npm run dev

Ferramentas

Cada ferramenta declara uma anotação de ferramenta — ferramentas Read são sem efeitos colaterais (readOnlyHint: true); ferramentas Write alteram o estado da sessão do servidor (destructiveHint: true).

Categorias de dívida usadas em todo o sistema: dependency · code-quality · architecture · documentation · testing · security · performance · maintainability

Recursos

Dois recursos MCP expõem dados somente leitura de dívida técnica como JSON. Ambos usam modelos de URI RFC 6570: a sintaxe {+projectPath} é expansão reservada, que permite que a variável contenha os caracteres / de um caminho absoluto do sistema de arquivos sem codificação percentual.

Exemplos concretos — substitua {+projectPath} por um caminho absoluto. Observe a barra dupla: o / final do modelo mais o / inicial do caminho produzem //, que é sintaxe de URI válida.

debt://summary//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp
debt://issues//Users/you/projects/myapp?severity=high&limit=50
debt://issues//Users/you/projects/myapp?category=security

Testando interativamente — a maneira mais fácil de exercitar ferramentas e recursos é o MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Abra a URL que ele exibe, mude para a aba Resources e leia um URI de modelo com o caminho absoluto do seu projeto.

Configuração

Crie um arquivo .techdebtrc.json na raiz do seu projeto:

{
  "include": ["src/**", "lib/**"],
  "ignore": ["vendor/**", "generated/**"],
  "rules": {
    "maxFileLines": 500,
    "maxFunctionLines": 50,
    "maxComplexity": 10,
    "maxNestingDepth": 4
  },
  "severity": {
    "todo-comment": "low",
    "console-log": "medium"
  },
  "ruleExclusions": {
    "debugger": ["**/src/analyzers/**"],
    "ts-ignore": ["**/src/analyzers/**"]
  },
  "customPatterns": [
    {
      "id": "no-console-log",
      "pattern": "console\\.log",
      "severity": "low",
      "category": "code-quality",
      "message": "Remove console.log() statements",
      "suggestion": "Use proper logging library instead",
      "languages": ["javascript", "typescript"]
    }
  ]
}

Substituições por Idioma

Substitua regras, severidade ou extensões de arquivo por idioma usando languageOverrides. As chaves devem ser identificadores válidos de idioma suportado.

{
  "languageOverrides": {
    "typescript": {
      "rules": {
        "maxFileLines": 800,
        "maxFunctionLines": 80
      },
      "severity": {
        "todo-comment": "high"
      }
    },
    "python": {
      "extensions": [".pyx"],
      "rules": {
        "maxComplexity": 15
      }
    }
  }
}

• rules — limites por idioma (substituem o rules de nível superior para arquivos correspondentes).
• severity — substituições de severidade de regras por idioma.
• extensions — extensões de arquivo adicionais (além dos padrões) para atribuir a este idioma.

Exclusões de Regras

Use ruleExclusions para suprimir regras específicas para arquivos que correspondem a padrões glob. Os padrões usam barras normais (/) em todas as plataformas. Use padrões com prefixo **/ (por exemplo, **/src/analyzers/**) para correspondência confiável independentemente do formato do caminho.

Supressão Inline

Suprima problemas específicos diretamente no código-fonte. Os prefixos de comentário // e # são suportados em todos os idiomas.

Linha única — suprime a próxima linha:

// techdebt-ignore-next-line debugger
debugger; // only the 'debugger' rule is suppressed

# techdebt-ignore-next-line print-statement
print("debug output")  # will not be reported

Bloco — suprime todas as linhas entre o início e o fim:

// techdebt-ignore-start ts-ignore
issues.push(...this.checkPattern(filePath, content, /@ts-ignore/g, { ... }));
// techdebt-ignore-end ts-ignore

Sem um nome de regra, todas as regras são suprimidas. Blocos podem ser aninhados. Comentários de supressão devem aparecer em sua própria linha.

Exemplos de Regras Personalizadas

Nota de escopo: customPatterns definidas em .techdebtrc.json são aplicadas apenas por analyze_project, que carrega a configuração do projeto antes da varredura. analyze_file invoca o analisador de idioma diretamente sem carregar .techdebtrc.json, portanto, padrões definidos na configuração não são aplicados nesse caminho. Use add_custom_rule em tempo de execução (ou chame execute_custom_rules diretamente) para executar padrões personalizados em um único arquivo.

Defina padrões em .techdebtrc.json sob customPatterns, ou registre-os em tempo de execução por meio da ferramenta MCP add_custom_rule:

{
  "customPatterns": [
    {
      "id": "no-magic-numbers",
      "pattern": "=\\s*\\d{3,}",
      "severity": "medium",
      "category": "maintainability",
      "message": "Magic number detected",
      "suggestion": "Extract to named constant"
    },
    {
      "id": "forbidden-library",
      "pattern": "import.*moment.*from",
      "severity": "medium",
      "category": "dependency",
      "message": "moment.js is deprecated",
      "suggestion": "Use native Date or date-fns instead",
      "languages": ["javascript", "typescript"]
    }
  ]
}

Métricas SQALE

O Tech Debt MCP usa a metodologia SQALE para quantificar a dívida técnica:

Mapeamento esforço-tempo: trivial (≤5m) · pequeno (5-30m) · médio (30m-2h) · grande (2-4h) · extra grande (4h+)

Análise SwiftUI

14 verificações especializadas para aplicativos SwiftUI cobrindo gerenciamento de estado (@State excessivo, uso incorreto de @ObservedObject, segurança de valores de ambiente), memória e ciclo de vida (ciclos de retenção do Combine, limpeza de timers, cancelamento de tarefas, ciclos de retenção em closures), desempenho (modificadores .id() ausentes, cálculos caros no body, aninhamento profundo, uso incorreto de GeometryReader) e boas práticas (apagamento de tipo AnyView, NavigationLink obsoleto, segurança da thread principal).

// Excessive @State - should use ViewModel
struct UserView: View {
  @State private var firstName = ""
  @State private var lastName = ""
  @State private var email = ""
  @State private var phone = ""
  @State private var address = ""
  @State private var city = ""  // 6+ @State variables!
}

// @ObservedObject with initialization
struct ContentView: View {
  @ObservedObject var viewModel = UserViewModel()  // Should be @StateObject!
}

// Missing Timer cleanup
struct TimerView: View {
  var body: some View {
    Text("Hello")
      .onAppear {
        Timer.scheduledTimer(...)  // Missing .onDisappear cleanup!
      }
  }
}

// Retain cycle in Combine
publisher
  .sink { value in
    self.updateUI(value)  // Missing [weak self]!
  }

Exemplo de Saída

# Tech Debt Analysis Report

## Health Score: 72/100

### Issues by Severity
| Severity | Count |
|----------|-------|
| Critical | 2 |
| High | 15 |
| Medium | 45 |
| Low | 120 |

## Top Recommendations

1. **Address Critical Issues Immediately**
   Fix 2 critical security issues.

2. **Clean Up TODO/FIXME Comments**
   Found 45 TODO comments - consider creating tracked issues.

Qualidade de Código

O Tech Debt MCP pratica o que prega — construído com vibe coding assistido por IA, mantém uma classificação A ao se escanear regularmente. Refatorações internas (por exemplo, redução de aninhamento em customRulesEngine.validatePattern por meio de helper extraído — #146) são impulsionadas por descobertas do auto-scan.

Resultados do Auto-Scan (v2.0.2, abril de 2026)

• Classificação SQALE: A (Excelente)
• Pontuação de Dívida: 5/100 (Meta: ≤5/100)
• Total de Problemas: 13 (0 crítico, 0 alto, 6 médio, 7 baixo)
• Tempo de Remediação: 14 horas
• Pontuação de Saúde: 95/100

Reduzido de 118 problemas / 42.4 de saúde na linha de base v2.0.1 após o endurecimento de segurança v2.0.2, configuração ruleExclusions, refatorações de aninhamento (#113, #118, #131, #146) e extração do handler de regras personalizadas (#145). Dívida restante: 5 pontos críticos de aninhamento (4 em módulos server/core + 1 em eslint.config.mjs), 7 usos de type assertion em fronteiras de sistema e 1 asserção não nula. Consulte TECH_DEBT_SCAN.md para detalhes por problema.

Desenvolvimento

npm install --include=dev --ignore-scripts  # Install dependencies (incl. devDependencies)
npm run typecheck  # Type-check without emitting output
npm run lint       # Lint source files
npm run build      # Compile TypeScript
npm run dev        # Run with ts-node
npm run watch      # Watch mode
npm test           # Run tests

Documentação

• ARCHITECTURE.md - Arquitetura do sistema e padrões de design
• ROADMAP.md - Fases de desenvolvimento e melhorias futuras
• CONTRIBUTING.md - Diretrizes de contribuição
• CHANGELOG.md - Histórico de versões e alterações
• RELEASE.md - Processo de release e guia de versionamento
• TECH_DEBT_SCAN.md - Resultados do auto-scan com comparação antes/depois
• CODE_OF_CONDUCT.md - Padrões da comunidade
• PRIVACY.md - Política de privacidade (também hospedada em https://pierrejanineh.github.io/TechDebtMCP/privacy)
• plugin/README.md - Documentação voltada ao usuário do plugin (instalação, transcrições de exemplo, postura de segurança)

Privacidade

O Tech Debt MCP é executado inteiramente na sua máquina. Uma vez instalado, ele lê os arquivos que você passa, retorna problemas ao seu cliente MCP pelo transporte local stdio e não faz mais nada — o próprio servidor não faz chamadas de rede de saída, não tem telemetria, não tem analytics e não usa serviços de terceiros. A instalação via npm/npx contata o registro npm como comportamento padrão de gerenciador de pacotes; o pacote MCPB é enviado pré-instalado e não precisa de mais acesso à rede. Consulte PRIVACY.md ou a política hospedada em https://pierrejanineh.github.io/TechDebtMCP/privacy para detalhes.

Contribuindo

Contribuições são bem-vindas! Consulte CONTRIBUTING.md para diretrizes e CODE_OF_CONDUCT.md para nossos padrões da comunidade.

Releases

• Mais recente:
• Releases: GitHub Releases
• Roadmap: Consulte ROADMAP.md para recursos planejados
• Segurança: escapeRegExp() (src/utils/regexUtils.ts) deve ser usado ao interpolar strings capturadas em new RegExp() — consulte o problema #128; a saída do handler usa basename() / getRelativePath() para evitar vazamento de caminhos absolutos do sistema de arquivos em mensagens intencionais, e strings err.message brutas de operações do sistema de arquivos são sanitizadas antes de serem retornadas aos clientes — consulte o problema #129

Licença

MIT