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
Maintainers
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-mcpVerificá la instalación abriendo una nueva terminal:
ado-bridge-mcp initActualizar a la última versión
npm install -g ado-bridge-mcp@latestDesinstalar
ado-bridge-mcp uninstall
npm uninstall -g ado-bridge-mcpNovedades 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_URLySEVENPACE_API_TOKEN(personal) en elenvdelmcp.json, y nada más: el flagsevenpace_enableddel.ado-config.yamlya no existe. Si falta alguna, las horas se cargan igual en Completed Work y se avisa. - Nuevo
ado_log_hourspara 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_drafty enado_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_analysistrae 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_contextya no borra los breadcrumbs pendientes;.envy.vscode/mcp.jsondejaron de ser adjuntables.axiosysharpactualizados por CVEs;npm audit --omit=deven 0. - Correcciones de fondo:
ado_publish_release_notesvalidaassigned_toantes de publicar (y conserva el draft para reintentar);ado_push_qa_evidenceya 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;getWorkItemspagina (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 updateLos 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_URLyFRESHDESK_KEYson opcionales. Solo requeridos si usás el toolado_publish_release_notescon integración a Freshdesk. También se soportan aliases de compatibilidad:FRESHDESK_DOMAIN(equivalente de URL) yFRESHDESK_API_KEY(equivalente de KEY).
ADO_ASSIGNED_TOes 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 campoassigned_toen.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 usuarioIDE 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 initEsto 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 --overwriteInstala 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 uninstallElimina 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 updateEl 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_*yado_publish_release_notesusan 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:
- 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. - 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.
- 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).
- 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:
- 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.
- 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ámetroupdateCompletedHours). Así el esfuerzo de re-trabajo queda trazado por separado del esfuerzo original, sin mezclarse en la misma métrica. - 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:
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 HTTPSSEVENPACE_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áginaPipeline: 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 }]engenerate_draftpara 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
qaWorkItemIdscuando 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. Siassigned_toestá configurado en.ado-config.yaml, los WIs se crean asignados automáticamente. Sinassigned_to, se crean igualmente sin asignar con aviso en la respuesta.
Estimación BINIT
El tool ado_push_analysis genera 2 child tasks independientes:
- "Analisis Funcional" — Descripción funcional del WI (estado Closed)
- "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, severidadcritical|high|medium|low, descripción, pasos de reproducción),coverageNotesyrecommendation(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:
- Guarda el contenido completo en un archivo
.mden.ado-context/(nombre:overflow-{wiId}-{tool}-{timestamp}.md) - Reintenta la operación con un texto placeholder que referencia el adjunto
- Adjunta el
.mdal work item creado viaaddAttachment - Incluye
overflowWarningsen 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 aFRESHDESK_URL; se normaliza ahttps://...)FRESHDESK_API_KEY(equivalente aFRESHDESK_KEY)
Diagnóstico operativo:
ado_healthexponefreshdeskReadinesscon 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. RecibeworkItemIdy 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. RecibeworkItemId, 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 losado_push_*:generate_draftmuestra qué se escribiría,publish_draftlo persiste en Redis,cancel_draftlo 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 testTest suite
- Framework: Vitest
- Tests: 2115 en 100 archivos al cierre de la v3.1.0 (
npm testpara 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