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",
        "ADO_ASSIGNED_TO": "[email protected]",
        "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. También se soportan aliases de compatibilidad: FRESHDESK_DOMAIN (equivalente de URL) y FRESHDESK_API_KEY (equivalente de KEY).

ADO_ASSIGNED_TO es opcional — es el email/UPN con el que se asigna (System.AssignedTo) cada task que crea el servidor (análisis, walkthrough, QA evidence, code review). Si no se configura, las tasks se crean sin asignar. También se puede configurar como campo assigned_to en .ado-config.yaml; la env var tiene precedencia.

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",
        "ADO_ASSIGNED_TO": "[email protected]",
        "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",
        "ADO_ASSIGNED_TO": "[email protected]",
        "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",
        "ADO_ASSIGNED_TO": "[email protected]",
        "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_calculate_session_hours | Calcula completedHours a partir de tokens consumidos (tokens / 500 × factor de complejidad, mínimo 0.5h) — ayuda a modelos con dificultades aritméticas | | 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.

📎 Adjuntos de entregables

Los 4 tools de publicación (ado_push_analysis, ado_push_walkthrough, ado_push_qa_evidence, ado_push_code_review) aceptan un parámetro attachmentRefs: una lista de rutas relativas a archivos entregables del proyecto — scripts de base de datos, archivos de configuración, migraciones, colecciones de Postman, capturas, o cualquier otro artefacto relevante para la tarea.

{
  "workItemId": 1234,
  "title": "Walkthrough — Migración de esquema",
  "summary": "...",
  "attachmentRefs": ["db/migrations/2026_08_add_index.sql", "config/feature-flags.json"]
}

Cómo funciona:

1. Validación pre-flight, antes de mostrar el preview: cada archivo debe existir, quedar dentro de la raíz del proyecto (sin ../ ni rutas absolutas), pesar 60 MB o menos (límite de Azure DevOps) y no repetirse en la lista.
2. Preview con detalle: el draft que se muestra para confirmación incluye el nombre y el tamaño de cada adjunto, para que se revise antes de publicar.
3. Subida post-publicación: al confirmar, los archivos se suben como adjuntos nativos de ADO, vinculados exactamente a la subtarea que corresponde (análisis, walkthrough, QA evidence o code review — nunca a la tarea de estimación).
4. Tolerante a fallos parciales: si la subida de un adjunto falla (permisos, red), la publicación del reporte no se interrumpe — la respuesta indica qué adjunto no se pudo subir para reintentarlo manualmente.

🔄 Actualización de tareas ya publicadas

Al volver a ejecutar ado_push_analysis, ado_push_walkthrough, ado_push_qa_evidence o ado_push_code_review sobre un work item que ya tiene ese artefacto publicado, el contenido existente ya no se pisa. En su lugar:

1. El contenido nuevo se agrega como comentario nativo de ADO en la task existente — el título, la descripción y el estado originales quedan intactos, y queda un historial completo de cada actualización directamente en el work item.
2. Se crea automáticamente una task adicional — "Actualización WorkItem {id} - {responsable} (...)" — en estado Closed, exclusivamente para registrar las horas dedicadas a esa actualización puntual (parámetro updateCompletedHours). Así el esfuerzo de re-trabajo queda trazado por separado del esfuerzo original, sin mezclarse en la misma métrica.
3. Nunca reporta éxito falso: si por algún motivo el comentario no se pudo publicar (permisos, conectividad), la respuesta lo señala explícitamente con un warning — la task de horas se intenta crear igual, para no perder el registro del esfuerzo.

Esto conserva el historial completo de cada work item: cada vuelta de análisis, walkthrough, QA o code review queda documentada como un comentario propio, en lugar de perderse en un sobreescritura silenciosa.

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. Si assigned_to está configurado en .ado-config.yaml, los WIs se crean asignados automáticamente. Sin assigned_to, se crean igualmente sin asignar con aviso en la respuesta.

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: soporta attachmentRefs — ver la sección "Adjuntos de entregables" más arriba

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.

Avance automático de estado del padre

Además de estampar tokens y tag, cada ado_push_* avanza el estado del User Story/Issue padre para reflejar el progreso del ciclo:

• ado_push_analysis, ado_push_walkthrough, ado_push_code_review → avanzan el padre a "In Progress"
• ado_push_qa_evidence (cierre del ciclo) → avanza el padre a "Done"

Solo actúa sobre padres User Story/Issue (nunca Epic, Feature o Task) y nunca sobrescribe un estado ya terminal (Closed, Done, Removed) ni repite una transición si el padre ya está en el estado destino. Es non-blocking: si falla, se reporta como warning en la respuesta sin interrumpir la publicación.

Overflow automático a adjunto

Si ADO rechaza la creación o actualización de una child task por exceso de longitud en un campo de texto (error TF400508), el servidor activa automáticamente un flujo de fallback:

1. Guarda el contenido completo en un archivo .md en .ado-context/ (nombre: overflow-{wiId}-{tool}-{timestamp}.md)
2. Reintenta la operación con un texto placeholder que referencia el adjunto
3. Adjunta el .md al work item creado via addAttachment
4. Incluye overflowWarnings en la respuesta con el nombre del archivo adjuntado

No hay configuración necesaria — el fallback es transparente para el agente.

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_ASSIGNED_TO | Email/UPN con el que se asigna (System.AssignedTo) cada task creada — tiene precedencia sobre el campo assigned_to de .ado-config.yaml. Sin ninguno de los dos, las tasks se crean sin asignar | ⚙️ Opcional | | 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 | | TELEMETRY_REDIS_URL | Connection string de Redis para la telemetría de cumplimiento del modelo operativo (Épica 23, ej: redis://localhost:6379) | ⚙️ Opcional | | TELEMETRY_DEPLOYMENT_CUTOFF_DATE | Fecha ISO desde la que se miden KPIs de cumplimiento — sin retroactividad (FR155) | ⚙️ Opcional | | PORTAL_CACHE_TTL_SECONDS | TTL (segundos) del cache en memoria del endpoint /api/kpis. Default: 60 | ⚙️ Opcional | | PORTAL_HTTP_PORT | Puerto del servidor HTTP de KPIs del Telemetry Worker. Default: 4000 | ⚙️ Opcional |

Aliases compatibles:

• FRESHDESK_DOMAIN (equivalente a FRESHDESK_URL; se normaliza a https://...)
• FRESHDESK_API_KEY (equivalente a FRESHDESK_KEY)
• REDIS_URL (equivalente a TELEMETRY_REDIS_URL)

Diagnóstico operativo:

• ado_health expone freshdeskReadiness con estado seguro (sin secretos) para validar si Freshdesk está listo en el entorno del proceso MCP.

Telemetría de cumplimiento del modelo operativo (Épica 23)

El middleware interceptor persiste breadcrumbs de cumplimiento (CP2–CP7) en un Redis Stream (telemetry:breadcrumbs). Si Redis no responde, la llamada real a ADO nunca se bloquea (fail-open) — el breadcrumb se reintenta localmente (ver .ado-context/pending-breadcrumbs/).

Requisito de infraestructura: la instancia de Redis usada para TELEMETRY_REDIS_URL debe correr con persistencia RDB o AOF habilitada. Sin persistencia, un reinicio del contenedor/servidor de Redis perdería breadcrumbs ya confirmados. Ver info redis.md (entorno local de desarrollo, no versionado) para un ejemplo de arranque con --appendonly yes.

Portal Web de KPIs (Épica 24)

El proceso ado-bridge-telemetry-worker (bin, src/telemetry-worker.ts) expone GET /api/kpis — un endpoint HTTP de solo lectura que sirve el documento calculado por kpi-export.ts (Épica 23) al portal de visualización externo (fuera de este repositorio, ver KPI Portal/).

• Control de acceso: solo por perímetro de red (VPN/intranet) — sin token de aplicación. El portal se despliega en una intranet corporativa, no expuesto a internet público (decisión del owner, 2026-07-29).
• Filtros por query param: GET /api/kpis?range=semana|mes|trimestre&project=<nombre>. range default: mes.
• Cache en memoria por combinación range+project, con TTL configurable (PORTAL_CACHE_TTL_SECONDS).
• Ver docs/deployment-portal-kpis.md para el despliegue productivo (HTTPS, checklist de operación).

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: 1516 tests en 82 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