# azure-devops-mcp-server

Servidor MCP (Model Context Protocol) para Azure DevOps, implementado sobre stdio nativo —
sin SDK de MCP ni dependencias externas más allá de `dotenv`. Expone Azure Boards, Azure
Repos y Azure Pipelines como *tools* invocables por Claude.

## Instalación y arranque

```bash
pnpm install        # instalar dependencias
pnpm start          # iniciar servidor MCP
pnpm dev            # iniciar con recarga automática (node --watch)
```

Variables de entorno requeridas (`.env`, ver `.env.example`):

| Variable            | Descripción                                   |
|---------------------|------------------------------------------------|
| `AZURE_DEVOPS_PAT`  | Personal Access Token de Azure DevOps          |
| `AZURE_DEVOPS_ORG`  | Nombre de la organización (ej. `movii`)        |
| `AZURE_ASSIGNED_TO` | (Opcional) usuario para `query_my_bugs` (default en `src/config.js`) |

## Herramientas (tools) disponibles

### Boards — `src/boards/index.js`

| Tool | Qué hace | Ejemplo básico |
|------|----------|----------------|
| `query_my_bugs` | Lista los bugs activos asignados al usuario configurado en `ASSIGNED_TO`. | `query_my_bugs()` |
| `get_work_item` | Obtiene un work item por ID (título, estado, descripción, repro steps, discussion, etc.). | `get_work_item(id: 12767)` |
| `query_work_items` | Ejecuta una consulta WIQL y devuelve `id/title/state/type` de cada resultado. | `query_work_items(wiql: "SELECT [System.Id] FROM WorkItems WHERE [System.WorkItemType]='Bug' AND [System.State]<>'Closed'")` |
| `update_work_item_state` | Cambia el estado de un work item. | `update_work_item_state(id: 12767, state: "Active")` |
| `create_work_item` | Crea un work item (`User Story`, `Task`, `Bug`, ...) con título, descripción HTML, criterios de aceptación, area/iteration path, tags y — para `Task` — `activity`, `originalEstimate`, `startDate`/`finishDate` y `parentId` (enlaza como hija vía `Hierarchy-Reverse`). | `create_work_item(project: "movii-business-line", type: "Task", title: "Implementar endpoint de saldo", activity: "Development", originalEstimate: 8, startDate: "2026-07-10", finishDate: "2026-07-11", parentId: 4821)` |

### Repos — `src/repos/index.js`

| Tool | Qué hace | Ejemplo básico |
|------|----------|----------------|
| `get_repositories` | Lista los repositorios de un proyecto (id, nombre, rama por defecto). | `get_repositories(project: "internal")` |
| `search_code` | Busca texto en el código vía Azure DevOps Code Search (wildcards, AND/OR/NOT). | `search_code(searchText: "ValidatePSE", repositoryName: "moviired-portal", branch: "development", project: "internal")` |
| `get_file_content` | Lee el contenido de un archivo de un repo en una rama dada. | `get_file_content(repositoryId: "moviired-portal", path: "/app/Http/Controllers/PSEController.php", branch: "development", project: "internal")` |
| `create_branch` | Crea una rama nueva desde otra existente. | `create_branch(repositoryId: "moviired-portal", branchName: "bug/12767", sourceBranch: "development")` |
| `push_commit` | Hace commit de un archivo modificado en una rama existente. | `push_commit(repositoryId: "moviired-portal", branchName: "bug/12767", filePath: "/app/...php", content: "<...>", message: "fix: #12767")` |
| `create_pull_request` | Abre un PR entre dos ramas. | `create_pull_request(repositoryId: "moviired-portal", sourceBranch: "bug/12767", targetBranch: "development", title: "fix: #12767 - ...")` |
| `get_pull_request` | Consulta estado (`active`/`completed`/`abandoned`), merge status y fechas de un PR. | `get_pull_request(repositoryId: "moviired-portal", pullRequestId: 8095)` |

### Pipelines — `src/pipelines/index.js`

| Tool | Qué hace | Ejemplo básico |
|------|----------|----------------|
| `get_pipelines` | Lista los pipelines del proyecto. | `get_pipelines(project: "internal")` |
| `get_pipeline_runs` | Últimas ejecuciones de un pipeline (estado, resultado, fechas). | `get_pipeline_runs(pipelineId: 42, top: 5, project: "internal")` |

### Cierre — `src/services/index.js`

| Tool | Qué hace | Ejemplo básico |
|------|----------|----------------|
| `notify_task_completed` | Hook de cierre: persiste un reporte en `reports/output.json` y finaliza la tarea. | `notify_task_completed(taskId: "12767", summary: "Bug resuelto, PR #8095 mergeado", status: "success")` |

Todos los tools de proyecto (Repos/Pipelines/`create_work_item`) aceptan `project` — si se
omite, usar el nombre exacto del proyecto Azure DevOps (no hay default global, cada llamada
project-scoped lo exige). Los tools de Boards de solo-lectura/escritura de work items
(`get_work_item`, `query_work_items`, `update_work_item_state`) son **org-scoped**: el ID de
work item es único a nivel organización, no requieren `project`.

## Qué agente usar para cada tarea

| Tarea | Agente | Qué hace |
|-------|--------|----------|
| Resolver/investigar un bug por ID | `bug-resolver` | Lee el work item, investiga el código (`search_code` → `get_file_content`), produce un plan de fix estructurado. No toca git. |
| Ejecutar el fix y abrir el PR | `repo-writer` | Recibe el plan de `bug-resolver` y ejecuta rama + commit + PR + notificación de cierre. No analiza bugs. |
| Verificar pipeline y cerrar el bug tras mergear el PR | `pipeline-monitor` | Verifica el resultado del pipeline post-merge; si pasó, cierra el work item y comenta la traza completa (duraciones, tokens). |
| Crear una historia de usuario o tarea nueva, con detalle profesional | `story-writer` | Investiga el código fuente relevante (repo Azure DevOps y/o ruta local), redacta introducción/objetivo/alcance/criterios de aceptación, y crea el work item directamente con `create_work_item`. |
| Desglosar una User Story existente en Tasks | `task-writer` | Lee la historia, investiga el repositorio asociado, propone/completa Tasks con `activity`, `originalEstimate` y fechas, y las crea enlazadas como hijas de la historia. |

Ver `CLAUDE.md` para el flujo paso a paso de cada uno (bugs: diagnóstico → fix/PR →
verificación de pipeline; historias: confirmación de contexto → `story-writer`; desglose de
tareas: confirmación de contexto → `task-writer`).