@slorenzot/mcp-azure

Servidor MCP (Model Context Protocol) para Azure DevOps. Permite interactuar con Work Items, repositorios Git, Pull Requests, sprints, áreas, comentarios y adjuntos desde cualquier cliente MCP compatible.

Instalación

npm install -g @slorenzot/mcp-azure

O usar directamente con npx:

npx @slorenzot/mcp-azure

Configuración

Variables de Entorno

El servidor se configura automáticamente usando las siguientes variables de entorno:

Configuración con .mcp.json

El servidor también puede leer credenciales desde un archivo .mcp.json, buscándolo en este orden:

1. Directorio actual

2. Directorio padre

3. Directorio del script

4. Home del usuario

Ejemplo:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@slorenzot/mcp-azure"],
      "env": {
        "AZURE_DEVOPS_ORG": "https://dev.azure.com/tu-organizacion",
        "AZURE_DEVOPS_PAT": "tu-pat-aqui",
        "AZURE_DEVOPS_PROJECT": "tu-proyecto"
      }
    }
  }
}

Configuración en Claude Desktop

Agrega la siguiente configuración en tu archivo claude_desktop_config.json:

{
  "mcpServers": {
    "azure-devops": {
      "command": "npx",
      "args": ["-y", "@slorenzot/mcp-azure"],
      "env": {
        "AZURE_DEVOPS_ORG": "https://dev.azure.com/tu-organizacion",
        "AZURE_DEVOPS_PAT": "tu-pat-aqui",
        "AZURE_DEVOPS_PROJECT": "tu-proyecto"
      }
    }
  }
}

Configuración en OpenCode

OpenCode utiliza el mismo MCP, pero la configuración se puede hacer de dos formas:

Opción 1: Configuración inicial con variables de entorno

1. Configura las variables de entorno en tu sistema o en tu configuración de OpenCode:

   export AZURE_DEVOPS_ORG="https://dev.azure.com/tu-organizacion"
   export AZURE_DEVOPS_PAT="tu-pat-aqui"
   export AZURE_DEVOPS_PROJECT="tu-proyecto"

2. O agrega el servidor MCP en tu configuración de OpenCode:

   {
     "mcpServers": {
       "azure-devops": {
         "command": "npx",
         "args": ["-y", "@slorenzot/mcp-azure"],
         "env": {
           "AZURE_DEVOPS_ORG": "https://dev.azure.com/tu-organizacion",
           "AZURE_DEVOPS_PAT": "tu-pat-aqui",
           "AZURE_DEVOPS_PROJECT": "tu-proyecto"
         }
       }
     }
   }

Opción 2: Configuración dinámica con ado_configure

OpenCode permite configurar la conexión directamente durante la sesión usando el comando ado_configure:

{
  "organization": "https://dev.azure.com/tu-organizacion",
  "project": "tu-proyecto",
  "pat": "tu-pat-aqui"
}

Esta opción es útil para cambiar entre diferentes organizaciones o proyectos sin modificar el archivo de configuración.

Nota: Cuando usas ado_configure, la conexión persiste durante la sesión actual de OpenCode.

Obtener un Personal Access Token (PAT)

1. Ve a tu organización de Azure DevOps

2. Haz clic en tu avatar (esquina superior derecha)

3. Selecciona Personal Access Tokens

4. Crea un nuevo token con los siguientes permisos:

   • Work Items: Read & Write

   • Code: Read & Write (para operaciones de repositorios y Pull Requests)

   • Project and Team: Read (opcional)

Herramientas Disponibles

Autenticación

Work Items

Consultas

Estructura del Proyecto

Repositorios Git

Pull Requests

Pull Request Reviews

Pull Request Comments

Pull Request Info

Búsqueda de Identidades

Comentarios y Discusiones

Adjuntos

Ejemplos de Uso

Crear una User Story

{
  "title": "Implementar login con OAuth",
  "type": "User Story",
  "description": "Como usuario quiero poder iniciar sesión con mi cuenta de Google",
  "areaPath": "MiProyecto\\Backend",
  "iterationPath": "MiProyecto\\Sprint 5",
  "fields": {
    "Custom.OKR": "Seguridad",
    "Custom.Prioridad": "Alta"
  }
}

Consulta WIQL Personalizada

{
  "wiql": "SELECT [System.Id], [System.Title] FROM WorkItems WHERE [System.State] = 'Active' AND [System.AssignedTo] = @Me ORDER BY [System.CreatedDate] DESC",
  "getDetails": true
}

Agregar Comentario con Markdown

{
  "id": 12345,
  "comment": "## Análisis completado\n\n- Revisado el código\n- Identificados 3 issues\n\n**Próximo paso:** Corregir validaciones"
}

Agregar Comentario con Mención

Las menciones requieren el ID de identidad (UUID) del usuario. Hay dos formas de obtenerlo:

1. Buscar usuario con ado_search_users:

{
  "searchTerm": "Juan Pérez"
}

2. Obtener ID desde un Work Item — los campos System.AssignedTo, System.CreatedBy o System.ChangedBy contienen el id de identidad.

Luego, agregar el comentario con la mención:

{
  "id": 12345,
  "comment": "@Juan Pérez ¿podrías revisar este cambio?",
  "mentions": [
    {
      "name": "Juan Pérez",
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    }
  ]
}

Nota: El texto del comentario debe incluir @DisplayName o @{DisplayName} en la posición donde quieras la mención. El MCP reemplaza automáticamente con el HTML de mención de Azure DevOps.

Subir y Adjuntar Archivo

{
  "workItemId": 12345,
  "filePath": "/ruta/al/archivo.pdf",
  "comment": "Documento de especificaciones",
  "name": "Especificaciones Funcionales v2.0"
}

Vincular Adjunto Existente

{
  "workItemId": 12345,
  "attachmentUrl": "https://dev.azure.com/org/proj/_apis/wit/attachments/abc123",
  "comment": "Diseño de arquitectura",
  "name": "Arquitectura del Sistema"
}

Eliminar Adjunto de un Work Item

{
  "workItemId": 12345,
  "attachmentUrl": "https://dev.azure.com/org/proj/_apis/wit/attachments/abc123",
  "comment": "Adjunto agregado por error"
}

Eliminar una User Story

{
  "id": 12345,
  "confirm": true,
  "destroy": false,
  "expectedType": "User Story"
}

ado_delete_work_item exige confirm: true. Si envías destroy: true, la eliminación es permanente.

Listar Repositorios

{
  "includeHidden": false,
  "top": 50
}

Listar Pull Requests Activos

{
  "status": "Active",
  "top": 20
}

Crear un Pull Request

{
  "repositoryId": "mi-repo",
  "sourceRefName": "refs/heads/feature-login",
  "targetRefName": "refs/heads/main",
  "title": "Implementar login con OAuth",
  "description": "Esta PR agrega soporte para login con Google OAuth",
  "reviewerIds": ["12345678-1234-1234-1234-1234567890ab"],
  "isDraft": false
}

Aprobar un Pull Request

{
  "pullRequestId": 12345,
  "repositoryId": "mi-repo"
}

Completar (Merge) un Pull Request

{
  "pullRequestId": 12345,
  "repositoryId": "mi-repo",
  "mergeStrategy": "Squash",
  "deleteSourceBranch": true,
  "mergeCommitMessage": "Merge de feature-login"
}

Crear Comentario en Código

{
  "pullRequestId": 12345,
  "repositoryId": "mi-repo",
  "content": "Por favor extraer esto en una función separada",
  "filePath": "/src/components/Login.tsx",
  "startLine": 45,
  "endLine": 52
}

Prompts Disponibles

El servidor incluye prompts predefinidos para facilitar tareas comunes:

Recursos

Desarrollo

Requisitos

• Node.js 18+

• npm o yarn

Instalación local

git clone https://github.com/slorenzot/mcp-azure.git
cd mcp-azure
npm install
npm run build

Scripts disponibles

npm run build    # Compila TypeScript
npm run start    # Inicia el servidor
npm run dev      # Modo desarrollo con watch
npm run release:check          # Valida build y paquete NPM
npm run release:version:patch  # Sube versión patch y sincroniza lockfile
npm run release:version:minor  # Sube versión minor y sincroniza lockfile
npm run release:version:major  # Sube versión major y sincroniza lockfile
npm run release:publish        # Publica en NPM

Flujo de Release

Para futuras funcionalidades, el flujo recomendado quedó documentado en RELEASE_WORKFLOW.md.

Licencia

MIT

Autor

Soulberto Lorenzo - @slorenzot

Versión

2.7.3 - 37 herramientas disponibles para Azure DevOps (Work Items, Repositorios Git, Pull Requests, sprints, áreas, comentarios con menciones, adjuntos y búsqueda de identidades)