ado-bridge-mcp

MCP Server para integración con Azure DevOps — pipeline completo: análisis funcional, walkthrough de desarrollo, code review, evidencias QA, release notes wiki y lifecycle management.

Instalación

npm install -g ado-bridge-mcp

Verificá la instalación abriendo una nueva terminal:

ado-bridge-mcp init

Actualizar a la última versión

npm install -g ado-bridge-mcp@latest

Desinstalar

ado-bridge-mcp uninstall
npm uninstall -g ado-bridge-mcp

Configuración en el IDE

El servidor MCP requiere variables de entorno con las credenciales de Azure DevOps. Nunca incluir estas credenciales en archivos commiteados al repositorio.

GitHub Copilot (VS Code)

Agrega a tu configuración de VS Code (.vscode/mcp.json):

{
  "servers": {
    "ado-bridge": {
      "command": "ado-bridge-mcp",
      "env": {
        "ADO_PAT": "tu-personal-access-token",
        "ADO_ORG_URL": "https://dev.azure.com/tu-organizacion",
        "FRESHDESK_URL": "https://tu-dominio.freshdesk.com",
        "FRESHDESK_KEY": "tu-api-key-de-freshdesk"
      }
    }
  }
}

FRESHDESK_URL y FRESHDESK_KEY son opcionales. Solo requeridos si usás el tool ado_publish_release_notes con integración a Freshdesk.

Claude Code

Por proyecto (.mcp.json en la raíz del repo)

{
  "mcpServers": {
    "ado-bridge": {
      "command": "ado-bridge-mcp",
      "env": {
        "ADO_PAT": "tu-personal-access-token",
        "ADO_ORG_URL": "https://dev.azure.com/tu-organizacion",
        "FRESHDESK_URL": "https://tu-dominio.freshdesk.com",
        "FRESHDESK_KEY": "tu-api-key-de-freshdesk"
      }
    }
  }
}

Global (~/.claude.json)

{
  "mcpServers": {
    "ado-bridge": {
      "command": "ado-bridge-mcp",
      "env": {
        "ADO_PAT": "tu-personal-access-token",
        "ADO_ORG_URL": "https://dev.azure.com/tu-organizacion",
        "FRESHDESK_URL": "https://tu-dominio.freshdesk.com",
        "FRESHDESK_KEY": "tu-api-key-de-freshdesk"
      }
    }
  }
}

Windsurf / Antigravity

{
  "mcpServers": {
    "ado-bridge": {
      "command": "ado-bridge-mcp",
      "env": {
        "ADO_PAT": "tu-personal-access-token",
        "ADO_ORG_URL": "https://dev.azure.com/tu-organizacion",
        "FRESHDESK_URL": "https://tu-dominio.freshdesk.com",
        "FRESHDESK_KEY": "tu-api-key-de-freshdesk"
      }
    }
  }
}

Configuración del proyecto

En la raíz del repositorio de tu proyecto, crea un archivo .ado-config.yaml (este archivo sí puede committearse):

# Copiado de .ado-config.yaml.example — ajustar según tu proyecto
project_id: "tu-project-id-aqui"
project_name: "NombreDelProyecto"
wiki_id: "tu-wiki-id-aqui"
wiki_name: "NombreDelProyecto.wiki"
default_area_path: "NombreDelProyecto\\Area\\SubArea"
default_iteration_path: "NombreDelProyecto\\Sprint 1"
assigned_to: "[email protected]"  # Opcional — asigna automáticamente los child tasks al usuario

IDE Setup — Slash Commands

Para invocar los tools de ADO Bridge como slash commands navegables en el panel del agente de tu IDE, ejecuta el siguiente comando en la raíz del proyecto:

ado-bridge-mcp init

Esto genera automáticamente los archivos de definición de comandos para todos los IDEs soportados:

| IDE | Directorio destino | Archivos generados | |-----|--------------------|--------------------| | GitHub Copilot (VS Code) | .vscode/ | 8 archivos .prompt.md | | Claude Code | .claude/commands/ | 8 archivos .md | | Antigravity | .antigravity/commands/ | 8 archivos .md |

Los archivos generados nunca sobrescriben archivos existentes — si ya existen, se omiten y se informa en la salida.

Nota: Para actualizar el toolkit a la última versión y sincronizar todos los archivos generados automáticamente, ejecutá ado-bridge-mcp update.

Lifecycle Management

Actualización

npm install -g ado-bridge-mcp@latest
ado-bridge-mcp init --overwrite

Instala la última versión disponible en npm y luego ejecuta init en modo overwrite para sincronizar todos los archivos generados (IDE commands, skills, templates). Los artefactos generados (.ado-context/) y la configuración (.ado-config.yaml) se preservan intactos.

Desinstalación

ado-bridge-mcp uninstall

Elimina todos los archivos instalados por ADO Bridge (IDE commands, skills, AI exclusion files), revierte los bloques en .gitignore y .github/copilot-instructions.md, y elimina el manifest. Los artefactos generados (.ado-context/) y .ado-config.yaml se preservan con nota informativa.

Notificación de versión nueva

Al iniciar el IDE, el servidor verifica silenciosamente (una vez por día, no-bloqueante) si hay una versión más nueva disponible en npm. Si la hay, notifica por stderr:

⚠️  ADO Bridge v1.5.0 disponible (instalado: v1.4.0)
    Ejecutá: ado-bridge-mcp update

Tools disponibles

| Tool | Descripción | |------|-------------| | ado_health | Verifica que el servidor MCP está activo | | ado_setup | Configura el proyecto resolviendo IDs automáticamente y generando archivos de configuración | | ado_pull_requirement | Descarga un work item de ADO como contexto de análisis | | ado_push_analysis | Publica análisis funcional + estimación BINIT como 2 tasks hijos independientes en ADO | | ado_pull_analysis | Descarga el análisis funcional de un task hijo | | ado_push_walkthrough | Publica un walkthrough de desarrollo en ADO | | ado_push_qa_evidence | Sube evidencias de QA (imágenes/video) y publica reporte | | ado_push_code_review | Publica un reporte de Code Review como task hijo en estado Done con horas reales | | ado_publish_release_notes | Genera release notes wiki desde múltiples work items con preview, sub-páginas, publicación en ADO Wiki y notificación a Freshdesk | | ado_clean_context | Limpia los archivos temporales de .ado-context/ |

Nota: Todos los tools ado_push_* y ado_publish_release_notes usan un flujo obligatorio de draft/preview/confirm — ninguno escribe en ADO sin confirmación explícita del usuario.

Release Notes Wiki

El tool ado_publish_release_notes genera documentación wiki con estructura de 2 niveles:

/Release Notes/
  └── v1.0.0/                              ← Página índice (resumen de cambios)
        ├── 144231-Correccion-de-texto...   ← Sub-página con análisis + reporte de implementación + QA
        ├── 144500-Implementacion-API-PDI   ← Sub-página
        └── 144800-Ajuste-permisos...       ← Sub-página

Pipeline: preview_scope → generate_draft → publish_draft

• Página índice: Lista todos los work items con título y descripción
• Sub-páginas: Incluyen análisis funcional, reporte de implementación y evidencia QA
• Reporte de Implementación unificado: Pasá implementationOverrides: [{ workItemId, report }] en generate_draft para usar un texto sintetizado (walkthrough + code review fusionados) por WI. Sin override, usa el walkthrough extraído como fallback
• Las secciones internas (hallazgos, dependencias, estimación BINIT) se excluyen automáticamente de la wiki. La task "Estimación" también se excluye antes del matching de artefactos
• Soporte para cross-WI QA lookup via qaWorkItemIds cuando la evidencia QA está en otro work item
• Integración opcional con Freshdesk: publica un comentario público en cada ticket vinculado y actualiza el estado a "En UAT"
• Deduplicación automática: si múltiples work items referencian el mismo ticket Freshdesk, se envía una sola notificación
• Management Tracking automático: al publicar exitosamente, crea una User Story "Management | Generación de Release [version]" con una child task "Generación RN y Actualización Freshdesk", ambas en estado Closed, para registrar el esfuerzo del proceso. Requiere assigned_to en .ado-config.yaml

Estimación BINIT

El tool ado_push_analysis genera 2 child tasks independientes:

1. "Analisis Funcional" — Descripción funcional del WI (estado Closed)
2. "Estimacion" — Estimación completa aplicando la fórmula BINIT (estado Closed)

Fórmula: Y = X × Σ × Factor de Complejidad

Al publicar, registra automáticamente CompletedWork (horas reales) en cada subtarea.

Code Review

El tool ado_push_code_review publica un reporte de revisión de código con:

• Tabla de archivos revisados: path, hallazgos y severidad (critical/high/medium/low/info) con iconos visuales
• Estado de aprobación: approved / approved-with-observations / changes-required / rejected
• Secciones condicionales: issues críticos, sugerencias, seguridad, performance, cobertura de tests
• CompletedWork automático: horas reales auto-reportadas por el agente
• IA Fields inline: modelo y tokens consumidos estampados directamente en la child task del artefacto (Custom.AIModelo / Custom.AITokens)
• Adjuntos de entregables (attachmentRefs): pasá rutas relativas a archivos entregables del WI (scripts de BD, configs, migraciones). El preview muestra nombre y tamaño; al confirmar, los archivos se suben como adjuntos a la subtarea. Fallos parciales no bloquean la publicación

El reporte se crea como child task en estado Done — listo para consulta inmediata en el sprint board.

QA Evidence

El tool ado_push_qa_evidence gestiona la evidencia de testing de un WI:

• Compresión automática de video: si se pasa un archivo de video, lo comprime con ffmpeg antes de subirlo para optimizar el tamaño del adjunto
• Subida de adjuntos: sube imágenes y videos como attachments a la child task de QA en ADO
• Reporte estructurado: genera un reporte con los casos de prueba ejecutados, resultado (pass/fail), observaciones y porcentaje de cobertura
• CompletedWork automático: horas reales del proceso de QA registradas en la subtarea
• IA Fields inline: modelo y tokens del agente estampados en Custom.AIModelo / Custom.AITokens
• Rollback automático: si la subida de adjuntos falla, los archivos ya subidos se eliminan antes de reportar el error

El reporte se publica como child task en estado Done.

IA Tracking

Cada invocación de un tool ado_push_* estampa automáticamente el modelo y los tokens del agente IA directamente en la child task del artefacto publicado, usando los campos custom Custom.AIModelo y Custom.AITokens. Adicionalmente, se propaga el tag [MMYYYY] al User Story o Issue padre si aún no lo tiene.

Archivos temporales

El servidor crea archivos temporales en .ado-context/ en el directorio raíz del workspace. Esta carpeta está en .gitignore y puede limpiarse con ado_clean_context.

Variables de entorno requeridas

| Variable | Descripción | Requerida | |----------|-------------|----------| | ADO_PAT | Personal Access Token de Azure DevOps | ✅ Siempre | | ADO_ORG_URL | URL base de la organización (ej: https://dev.azure.com/myorg) | ✅ Siempre | | ADO_BRIDGE_GH_TOKEN | PAT de GitHub (o GITHUB_TOKEN). Usado por el chequeo automático de versiones para evitar rate-limits en la API pública de GitHub. Si no se configura, el chequeo sigue funcionando en condiciones normales de red. | ⚙️ Opcional | | FRESHDESK_URL | URL base de tu instancia Freshdesk (ej: https://tu-dominio.freshdesk.com) | ⚙️ Opcional | | FRESHDESK_KEY | API Key de Freshdesk (nunca commitear) | ⚙️ Opcional |

Desarrollo

git clone https://github.com/sstefanetti_binitar/ADO-BRIDGE-MCP.git
cd ado-bridge-mcp
npm install
npm run build
npm test

Test suite

• Framework: Vitest
• Tests: 1290 tests en 75 archivos (0 fallos)
• Unit tests: test/unit/
• Integration tests: test/integration/
• QA E2E tests: test/qa/

npm test              # run completo
npm run test:watch    # modo watch
npm run test:coverage # con cobertura