TechDebtMCP

Servidor MCP de Deuda Técnica

16 Herramientas · 2 Recursos · 14 Lenguajes · 10 Ecosistemas de Dependencias

Un servidor de Protocolo de Contexto de Modelo (MCP) para analizar deuda técnica en múltiples lenguajes de programación. Diseñado para integrarse con GitHub Copilot, Claude, Cursor y otras herramientas compatibles con MCP.

Características

• Soporte multi-lenguaje: JavaScript, TypeScript, Python, Java, Swift, Kotlin, Objective-C, C++, C, C#, Go, Rust, Ruby, PHP
• Análisis integral: Detecta varios tipos de deuda técnica, incluyendo problemas de calidad de código, vulnerabilidades de seguridad y problemas de mantenibilidad
• Métricas SQALE: Calcula deuda técnica con el sistema de calificación SQALE (escala A-E)
• Análisis SwiftUI: Comprobaciones especializadas para patrones SwiftUI, gestión de estado, fugas de memoria, anidamiento de vistas y problemas de concurrencia
• Reglas personalizadas: Define tus propias comprobaciones basadas en patrones con soporte de regex
• Análisis de dependencias: Analiza manifiestos de paquetes en 10 ecosistemas (npm, pip, Maven/Gradle, Cargo, Go Modules, Composer, Bundler, NuGet, C/C++, Swift)
• Supresión en línea: Suprime falsos positivos con // techdebt-ignore-next-line o comentarios de bloque
• Validación de configuración: Valida archivos de configuración .techdebtrc.json para verificar la corrección del esquema
• Recomendaciones accionables: Proporciona sugerencias priorizadas para abordar la deuda técnica
• Filtrado flexible: Filtra resultados por severidad, categoría o lenguaje
• Endurecido en seguridad (v2.0.2): Prevención de traversal de rutas en todas las entradas de rutas de herramientas y recursos, validación de regex de reglas personalizadas segura contra ReDoS, escape de inyección de regex en comprobaciones SwiftUI, sanitización de rutas absolutas en todos los mensajes de error y escaneo SAST con CodeQL en cada push/PR

Lenguajes Soportados

Instalación

Instalación con un clic

VS Code (vía Terminal):

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

Instalación con un clic

Cursor (vía Terminal):

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

Claude Code (vía Terminal):

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

Claude Desktop — añade a tu claude_desktop_config.json:

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

Plugin de Claude Code — añade el marketplace de este repositorio y luego instala el plugin:

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

El plugin ejecuta npx -y tech-debt-mcp@latest internamente — sin empaquetado de código fuente, siempre sigue la versión publicada en npm. Consulta plugin/README.md para documentación orientada a usuarios del plugin (flujo de instalación, transcripciones de ejemplo, postura de seguridad).

Paquete MCPB de Claude Desktop — instalación con un clic con node_modules incluido (sin npx, sin necesidad de internet en tiempo de ejecución).

Descarga tech-debt-mcp-<version>.mcpb desde la última versión de GitHub y ábrela con Claude para macOS o Windows.

Para compilar el paquete localmente:

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

Añade a tu configuración MCP de Windsurf (~/.codeium/windsurf/mcp_config.json):

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

Vía AI Assistant — abre Settings > Tools > AI Assistant > Model Context Protocol (MCP), haz clic en +, selecciona As JSON y pega:

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

Vía GitHub Copilot for Xcode — abre Settings > pestaña MCP > Edit Config (mcp.json):

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

Configuración Manual

Añade a la configuración de tu cliente MCP:

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

Para desarrollo: npm run dev

Herramientas

Cada herramienta declara una anotación de herramienta — las herramientas Read no tienen efectos secundarios (readOnlyHint: true); las herramientas Write mutan el estado de la sesión del servidor (destructiveHint: true).

Categorías de deuda utilizadas en todo el sistema: dependency · code-quality · architecture · documentation · testing · security · performance · maintainability

Recursos

Dos recursos MCP exponen datos de deuda técnica de solo lectura como JSON. Ambos usan plantillas URI RFC 6570: la sintaxis {+projectPath} es expansión reservada, que permite que la variable contenga los caracteres / de una ruta absoluta del sistema de archivos sin codificación de porcentaje.

Ejemplos concretos — sustituya {+projectPath} con una ruta absoluta. Observe la doble barra: el / final de la plantilla más el / inicial de la ruta producen //, que es sintaxis 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

Pruebas interactivas — la forma más fácil de ejercitar herramientas y recursos es el MCP Inspector:

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

Abra la URL que imprime, cambie a la pestaña Recursos y lea una plantilla URI con la ruta absoluta de su proyecto.

Configuración

Cree un archivo .techdebtrc.json en la raíz de su proyecto:

{
  "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"]
    }
  ]
}

Anulaciones de Lenguaje

Anule reglas, severidad o extensiones de archivo por lenguaje usando languageOverrides. Las claves deben ser identificadores de lenguaje soportado válidos.

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

• rules — umbrales por lenguaje (anulan el rules de nivel superior para archivos coincidentes).
• severity — anulaciones de severidad de reglas por lenguaje.
• extensions — extensiones de archivo adicionales (más allá de los predeterminados) para atribuir a este lenguaje.

Exclusiones de Reglas

Use ruleExclusions para suprimir reglas específicas para archivos que coincidan con patrones glob. Los patrones usan barras diagonales (/) en todas las plataformas. Use patrones con prefijo **/ (por ejemplo, **/src/analyzers/**) para una coincidencia confiable independientemente del formato de ruta.

Supresión en Línea

Suprima problemas específicos directamente en el código fuente. Ambos prefijos de comentario // y # son soportados en todos los lenguajes.

Una línea — suprime la siguiente línea:

// 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

Bloque — suprime todas las líneas entre inicio y fin:

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

Sin un nombre de regla, se suprimen todas las reglas. Los bloques pueden anidarse. Los comentarios de supresión deben aparecer en su propia línea.

Ejemplo de Reglas Personalizadas

Nota de alcance: customPatterns definidas en .techdebtrc.json se aplican solo mediante analyze_project, que carga la configuración del proyecto antes de escanear. analyze_file invoca el analizador de lenguaje directamente sin cargar .techdebtrc.json, por lo que los patrones definidos en la configuración no se aplican en esa ruta. Use add_custom_rule en tiempo de ejecución (o llame a execute_custom_rules directamente) para ejecutar patrones personalizados contra un solo archivo.

Defina patrones en .techdebtrc.json bajo customPatterns, o regístrelos en tiempo de ejecución mediante la herramienta 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

Tech Debt MCP usa la metodología SQALE para cuantificar la deuda técnica:

Mapeo esfuerzo-tiempo: trivial (≤5m) · pequeño (5-30m) · mediano (30m-2h) · grande (2-4h) · muy grande (4h+)

Análisis SwiftUI

14 verificaciones especializadas para aplicaciones SwiftUI que cubren gestión de estado (@State excesivo, mal uso de @ObservedObject, seguridad de valores de entorno), memoria y ciclo de vida (ciclos de retención en Combine, limpieza de temporizadores, cancelación de tareas, ciclos de retención en cierres), rendimiento (modificadores .id() faltantes, cálculos costosos en el cuerpo, anidamiento profundo, mal uso de GeometryReader) y mejores prácticas (borrado de tipo AnyView, NavigationLink obsoleto, seguridad del hilo 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]!
  }

Ejemplo de Salida

# 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.

Calidad del Código

Tech Debt MCP practica lo que predica — construido con codificación asistida por IA, mantiene una calificación A al escanearse regularmente. Refactorizaciones internas (por ejemplo, reducción de anidamiento en customRulesEngine.validatePattern mediante helper extraído — #146) son impulsadas por hallazgos de autoescaneo.

Resultados de Autoescaneo (v2.0.2, abril 2026)

• Calificación SQALE: A (Excelente)
• Puntuación de Deuda: 5/100 (Objetivo: ≤5/100)
• Problemas Totales: 13 (0 críticos, 0 altos, 6 medios, 7 bajos)
• Tiempo de Remediación: 14 horas
• Puntuación de Salud: 95/100

Bajó de 118 problemas / 42.4 de salud en la línea base v2.0.1 después del endurecimiento de seguridad v2.0.2, configuración ruleExclusions, refactorizaciones de anidamiento (#113, #118, #131, #146) y extracción del manejador de reglas personalizadas (#145). Deuda restante: 5 puntos de anidamiento (4 en módulos de servidor/núcleo + 1 en eslint.config.mjs), 7 usos de aserción de tipo en límites del sistema y 1 aserción no nula. Consulte TECH_DEBT_SCAN.md para detalles por problema.

Desarrollo

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

Documentación

• ARCHITECTURE.md - Arquitectura del sistema y patrones de diseño
• ROADMAP.md - Fases de desarrollo y mejoras futuras
• CONTRIBUTING.md - Guías de contribución
• CHANGELOG.md - Historial de versiones y cambios
• RELEASE.md - Proceso de publicación y guía de versionado
• TECH_DEBT_SCAN.md - Resultados de autoescaneo con comparación antes/después
• CODE_OF_CONDUCT.md - Estándares comunitarios
• PRIVACY.md - Política de privacidad (también alojada en https://pierrejanineh.github.io/TechDebtMCP/privacy)
• plugin/README.md - Documentación orientada al usuario del plugin (instalación, transcripciones de ejemplo, postura de seguridad)

Privacidad

Tech Debt MCP se ejecuta completamente en su máquina. Una vez instalado, lee los archivos que usted le pasa, devuelve problemas a su cliente MCP a través del transporte stdio local y no hace nada más — el servidor en sí no realiza llamadas de red salientes, no tiene telemetría, no tiene análisis y no usa servicios de terceros. La instalación mediante npm/npx sí contacta el registro npm como comportamiento estándar del gestor de paquetes; el paquete MCPB se envía preinstalado y no necesita acceso de red adicional. Consulte PRIVACY.md o la política alojada en https://pierrejanineh.github.io/TechDebtMCP/privacy para detalles.

Contribuciones

¡Las contribuciones son bienvenidas! Consulte CONTRIBUTING.md para las guías y CODE_OF_CONDUCT.md para nuestros estándares comunitarios.

Publicaciones

• Última:
• Publicaciones: GitHub Releases
• Hoja de ruta: Consulte ROADMAP.md para características planificadas
• Seguridad: escapeRegExp() (src/utils/regexUtils.ts) debe usarse al interpolar cadenas capturadas en new RegExp() — consulte el problema #128; la salida del manejador usa basename() / getRelativePath() para prevenir la fuga de rutas absolutas del sistema de archivos en mensajes intencionales, y las cadenas err.message crudas de operaciones del sistema de archivos se sanitizan antes de devolverse a los clientes — consulte el problema #129

Licencia

MIT