npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

ado-bridge-mcp

v3.1.0

Published

MCP Server for Azure DevOps integration — pull/push work items, analysis, walkthroughs, QA evidence, code reviews, release notes wiki and 7pace Timetracker worklogs

Readme

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.

Es un único proceso sobre stdio, arrancado por el IDE: no hay servidor persistente, ni puerto HTTP, ni daemon que administrar.

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

Novedades de la v3.1.0

Release del 2026-10-15:

  • Los worklogs de 7pace vuelven a cargarse. Fallaban en todas las publicaciones con 7pace API error: 400, y las horas quedaban sólo en Completed Work. Ahora cada worklog lleva la actividad Development, sin configurar nada.
  • 7pace es obligatorio y se configura con dos variables. SEVENPACE_API_URL y SEVENPACE_API_TOKEN (personal) en el env del mcp.json, y nada más: el flag sevenpace_enabled del .ado-config.yaml ya no existe. Si falta alguna, las horas se cargan igual en Completed Work y se avisa.
  • Nuevo ado_log_hours para cargar horas a mano en cualquier task (gestión, reuniones, soporte): escribe el worklog en 7pace y suma a Completed Work, o no escribe nada. Rechaza la carga si se superpone con otra tuya del mismo día.
  • Los problemas de 7pace se ven antes de publicar: en el preview de generate_draft y en ado_health (token vencido, actividad inexistente, token de otra persona).

Novedades de la v3.0.1

Release de corrección del 2026-10-14:

  • Republicar ya no frena con "no se puede actualizar una task ya creada" (error 409). Seguía pasando si un duplicado se había pasado a Removed, y los análisis publicados con versiones viejas (título "Análisis Funcional", con tilde) se duplicaban en vez de recibir la actualización. El mensaje del 409, cuando hay duplicados reales, ahora explica cómo actualizar igual.
  • ado_pull_analysis trae las actualizaciones del análisis. Republicar agrega el contenido nuevo como comentario, y el tool sólo leía el original. Ahora el archivo incluye esos comentarios en "Actualizaciones posteriores": la más reciente es la versión vigente.

Si estás en 2.0.x, actualizar también corrige el 409 que aparecía a la tercera publicación sobre el mismo work item.

Novedades de la v3.0.0

Release mayor del 2026-09-21. Recoge la revisión general del 2026-09-15 y deja el paquete acotado a un único MCP server sobre stdio.

Cambio breaking (uno solo): el bin ado-bridge-telemetry-worker ya no se publica. Si algún script o servicio lo invocaba, ese comando deja de existir al actualizar. Para el uso normal desde el IDE, actualizar es transparente.

Un cambio de comportamiento que conviene revisar: la telemetría ya no tiene destino por defecto. Se eliminaron el alias REDIS_URL y el fallback a redis://localhost:6379 — REDIS_URL es la variable más común que existe, y en un repo con su propio Redis ADO Bridge terminaba escribiendo breadcrumbs, con el UPN del desarrollador adentro, en una instancia que nadie había designado para eso. Si tenías telemetría andando sin TELEMETRY_REDIS_URL declarada, ahora queda inactiva hasta que la declares.

Lo demás, resumido:

  • Seguridad: el chequeo de versión dejó de pasar por GitHub y de mandar GITHUB_TOKEN; el ticket de Freshdesk se extrae sólo del prefijo del título (un work item renombrado podía publicar una nota pública en el ticket de otro cliente); ado_clean_context ya no borra los breadcrumbs pendientes; .env y .vscode/mcp.json dejaron de ser adjuntables. axios y sharp actualizados por CVEs; npm audit --omit=dev en 0.
  • Correcciones de fondo: ado_publish_release_notes valida assigned_to antes de publicar (y conserva el draft para reintentar); ado_push_qa_evidence ya no cierra la User Story padre cuando QA rechazó o cuando la evidencia no llegó a ADO; las llamadas a ADO ahora sí tienen timeout y reintentos; getWorkItems pagina (un padre con más de 200 hijos rompía todos los tools).
  • Documentación: se documentó la integración con 7pace Timetracker y los tools ado_query_breadcrumbs / ado_reconstruct_breadcrumbs, que no tenían una sola mención.

Cómo actualizar

npm install -g ado-bridge-mcp@latest
ado-bridge-mcp update

Los artefactos generados (.ado-context/) y la configuración (.ado-config.yaml) se preservan intactos.

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 publicada en el registry npm — el mismo del que instala ado-bridge-mcp update. Si la hay, notifica por stderr:

⚠️  ADO Bridge v3.1.0 disponible (instalado: v3.0.0)
    Ejecutá: ado-bridge-mcp update

El chequeo no envía credenciales. Con ADO_BRIDGE_REGISTRY_URL se lo puede apuntar a un feed propio (ej. Azure Artifacts); contra un feed privado que exija autenticación simplemente no avisa, igual que ante cualquier otro fallo.

Tools disponibles

| Tool | Descripción | |------|-------------| | ado_health | Verifica que el servidor MCP está activo, y el estado de Freshdesk y 7pace (token válido, a nombre de quién, actividad Development presente) | | 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_log_hours | Carga horas a mano en cualquier task, en los dos lados a la vez: worklog en 7pace y suma a Completed Work. Rechaza la carga si se superpone con otro worklog tuyo de ese día | | 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/ | | ado_query_breadcrumbs | Consulta los breadcrumbs de telemetría ya registrados para un work item (solo lectura) | | ado_reconstruct_breadcrumbs | Reconstruye breadcrumbs faltantes de un work item a partir de sus child tasks ya publicadas, con flujo draft/preview/confirm |

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.

⏱️ Integración 7pace Timetracker

7pace es obligatorio en la empresa. Cada hora que ADO Bridge registra en una child task se carga además como worklog diario en el calendario de 7pace del desarrollador.

Es una doble escritura deliberada, no un reemplazo. ADO Bridge escribe Microsoft.VSTS.Scheduling.CompletedWork en el patch de cierre de la task y crea el worklog en 7pace. ADO Bridge es la fuente de verdad de Completed Work: se verificó empíricamente que 7pace no puebla ese campo aunque la Work Item Automation esté encendida, y en binit-srl ese "sumarizador" además está apagado a propósito. Si 7pace falla, se pierde la entrada del calendario — nunca las horas.

Todo worklog se carga con la actividad Development. Está fija en código: todo lo que carga ADO Bridge es trabajo de desarrollo, y el tenant rechaza un worklog sin actividad (400 ActivityTypeRequired). No hay que configurar nada. ado_health avisa si esa actividad deja de existir en el tenant.

Configuración

La única configuración son dos variables en el bloque env del mcp.json. No hay nada que poner en .ado-config.yaml:

  1. SEVENPACE_API_URL — origen del servicio (ej. https://tu-org.timehub.7pace.com). Si se pega la URL del endpoint OData (.../api/odata/v3.2), se recorta sola. Exige HTTPS
  2. SEVENPACE_API_TOKEN — token personal, uno por desarrollador (nunca commitear). Las horas quedan a nombre del dueño del token

Si falta alguna, la publicación no se frena: las horas se cargan en Completed Work y la respuesta trae un warning que dice qué falta. El preview de generate_draft y ado_health lo avisan antes. Un sevenpace_enabled que haya quedado en un .ado-config.yaml viejo se ignora.

Qué hace en cada publicación

| | | |---|---| | Cuándo | En el cierre de toda task que crea un ado_push_*, incluidas las tasks de "Actualización WorkItem" del flujo commented | | Fecha del worklog | El día local de la máquina que ejecuta el tool | | Comentario del worklog | El título de la task | | No duplicación | Antes de crear un worklog se buscan los existentes del mismo work item y día; una entrada equivalente dentro de una ventana de 120 s no se vuelve a crear | | Reparto de horas | En el caso commented de la Épica ADO-29 (análisis y estimación en la misma corrida), cada mitad genera su propio worklog contra su propia task | | Aviso previo | El preview de generate_draft ya chequea 7pace (credenciales, token válido, actividad, dueño del token vs. ADO_ASSIGNED_TO) y muestra los problemas en sevenPaceWarnings, antes de crear ninguna task. No bloquea el draft | | Ante fallo | La publicación nunca se interrumpe: el warning dice explícitamente que las horas sí quedaron en Completed Work y que lo único ausente es la entrada del calendario |

Prerequisito organizacional: el Service Account de 7pace necesita permisos sobre la API de Azure DevOps para poder asociar un worklog a un work item. Sin eso, todo worklog falla y la integración queda permanentemente en modo warning.

Carga manual de horas: ado_log_hours

Para cargar horas que no salen de publicar un artefacto (gestión, reuniones, soporte), en cualquier task y de cualquier proyecto:

{ "taskId": 153211, "hours": 4, "startTime": "09:00" }

date (YYYY-MM-DD) y comment son opcionales; la fecha por defecto es hoy. Usa las mismas dos variables de 7pace. Las horas quedan a nombre del dueño del token, así que cada persona carga con el suyo.

| | | |---|---| | Dos lados o ninguno | Crea el worklog en 7pace y suma las horas a Completed Work. Si Completed Work no se puede escribir, borra el worklog. Sólo si ese borrado también falla, el error dice qué quedó de un solo lado y cómo arreglarlo | | No duplicación | Antes de escribir, rechaza la carga si el horario se superpone con otro worklog tuyo de ese día, en esa task o en otra. Los tramos pegados (09–13 y 13–15) no se superponen. Si 7pace no responde, no se carga nada | | Concurrencia | La suma a Completed Work usa control de versión (test /rev): si alguien edita la task en el medio, relee y suma sobre el valor nuevo | | Validaciones | Fecha real y no futura; el tramo no puede pasar la medianoche |

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 Closed — 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: testEnvironment, testingSummary, successfulScenarios[] (nombre, pasos, resultado observado), defectsFound[] (título, severidad critical|high|medium|low, descripción, pasos de reproducción), coverageNotes y recommendation (approve / conditional-approve / reject)
  • 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 Closed.

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_REGISTRY_URL | Registry npm que consulta el chequeo diario de versión. Por defecto, el registry público de npm. Apuntalo a tu propio feed (ej. Azure Artifacts) si publicás ahí. El chequeo no manda credenciales: contra un feed privado simplemente no avisa | ⚙️ 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 | | SEVENPACE_API_URL | Origen del servicio de 7pace — esquema + host, sin path de API (ej. https://tu-org.timehub.7pace.com). Exige HTTPS. 7pace es obligatorio en la empresa: sin esta variable las horas van sólo a Completed Work, con un warning | ✅ Requerido | | SEVENPACE_API_TOKEN | Token personal de 7pace, uno por desarrollador (nunca commitear). Sin él las horas van sólo a Completed Work, con un warning | ✅ Requerido | | TELEMETRY_REDIS_URL | Connection string de Redis donde se persisten los breadcrumbs de cumplimiento (ej: redis://localhost:6379). Sin esta variable la telemetría queda inactiva: no hay destino por defecto | ⚙️ Opcional | | TELEMETRY_DEPLOYMENT_CUTOFF_DATE | Fecha ISO (YYYY-MM-DD o ISO-8601 completa) desde la que se registran breadcrumbs. Toda operación anterior a esa fecha no genera breadcrumb — evita contaminar la métrica con actividad previa al despliegue. Sin la variable, se registra todo | ⚙️ Opcional |

Aliases compatibles:

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

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

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

ADO Bridge solo produce los breadcrumbs: los escribe en el stream y expone ado_query_breadcrumbs para consultarlos. Analizarlos o graficarlos no es parte de este paquete.

Tools de telemetría:

  • ado_query_breadcrumbs — solo lectura. Recibe workItemId y devuelve los breadcrumbs ya registrados para ese work item, en el mismo esquema en el que se persistieron. No escribe nada.
  • ado_reconstruct_breadcrumbs — repara huecos. Recibe workItemId, deriva de las child tasks ya publicadas los breadcrumbs que deberían existir y no están (por ejemplo, work items trabajados antes de habilitar la telemetría, o durante una caída de Redis que agotó la cola local), y los propone. Usa el mismo flujo draft/preview/confirm que los ado_push_*: generate_draft muestra qué se escribiría, publish_draft lo persiste en Redis, cancel_draft lo descarta. Nunca escribe sin confirmación.

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. Arrancar el contenedor con --appendonly yes.

Desarrollo

git clone https://binit-srl.visualstudio.com/BinitAIFactory/_git/ADO-BRIDGE
cd ADO-BRIDGE/ado-bridge-mcp
npm install
npm run build
npm test

Test suite

  • Framework: Vitest
  • Tests: 2115 en 100 archivos al cierre de la v3.1.0 (npm test para el conteo actual)
  • 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