feat(mcp): MCP server for AI clients, consuming the REST API

New app apps/mcp (NestJS + @nestjs-mcp/server 2): Streamable HTTP at POST /mcp, stateless. - 24 tools: projects (mine, public, details with settings, board, stats, analytics, activity), tickets (my work, search, details with comments and history, create, update, move, assign, release, comment, link), releases (list, upcoming, details with progress and burnup, create, publish) and users (whoami, search). Admin operations stay in the web. - No credentials of its own: each call's Authorization header (a Pireon token) is forwarded to the API; without it only public projects are read. - Typed REST client generated from apps/api/openapi.json (openapi-fetch + openapi-typescript via `nx run mcp:openapi-types`); API refusals become readable tool errors; parameters validated with zod. - Tests: the real MCP against a simulated API (token forwarding, errors, validation, writes). - Docker target `mcp` (Node 24) and an optional compose service under the `mcp` profile; zod declared as a root dependency. - Docs: chapter 9 «Servidor MCP», references in 01/06/07 and the index; Word/PDF regenerated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-07 18:59:38 +02:00
parent 71dc2d6f2d
commit 9236cb73c6
36 changed files with 6054 additions and 38 deletions
--- a/docs/09-mcp.md
+++ b/docs/09-mcp.md
@@ -0,0 +1,132 @@
+# 9. Servidor MCP
+
+`apps/mcp` es un servidor [MCP](https://modelcontextprotocol.io) (Model Context Protocol) para que asistentes de IA
+(Claude Code, Claude Desktop, Cursor…) trabajen con TaskStream: consultar tableros y tickets, crear y mover tickets,
+comentar, gestionar releases o leer las estadísticas. Está hecho con NestJS y
+[`@nestjs-mcp/server`](https://www.npmjs.com/package/@nestjs-mcp/server) 2.x, y consume la **API REST** como cualquier
+otra app: con tipos generados desde `apps/api/openapi.json`.
+
+```mermaid
+flowchart LR
+  C["Cliente MCP<br/>(Claude…)"] -- "POST /mcp<br/>Authorization: Bearer token" --> M["apps/mcp<br/>(NestJS)"]
+  M -- "REST /api/…<br/>mismo token" --> A["apps/api"]
+  A -- "valida el token" --> P["Pireon"]
+```
+
+## 9.1 Cómo funciona
+
+- **Un endpoint**: `POST /mcp`, transporte _Streamable HTTP_. Sin estado (la versión 2026-07-28 del protocolo retiró
+  las sesiones): cualquier instancia atiende cualquier llamada.
+- **Sin credenciales propias**: cada llamada lleva su `Authorization: Bearer <token de Pireon>`, y el MCP la reenvía
+  tal cual a la API. Cada persona ve y puede cambiar exactamente lo que la API le permite (su rol en cada proyecto);
+  **sin token**, solo se leen los proyectos públicos.
+- **Errores legibles**: si la API rechaza algo (permiso, regla de negocio, transición no permitida…), la herramienta
+  responde con un error que el modelo puede leer y corregir («Cannot move WEB-16 from Backlog to Hecho. Allowed: Por
+  hacer, En curso, Cancelado»), en vez de cortar la llamada.
+- **Validación**: los parámetros de cada herramienta se validan con zod antes de llamar a la API.
+- **Respuestas compactas**: los listados devuelven lo que el modelo necesita (clave, título, estado, persona…); el
+  detalle completo, con `get_issue` o `get_project`.
+
+## 9.2 Herramientas
+
+| Ámbito    | Herramienta             | Qué hace                                                                                    |
+| --------- | ----------------------- | ------------------------------------------------------------------------------------------- |
+| Usuario   | `whoami`                | El usuario del token                                                                        |
+|           | `search_users`          | Buscar personas de Pireon (para asignar)                                                    |
+| Proyectos | `list_my_projects`      | Mis proyectos                                                                               |
+|           | `list_public_projects`  | Proyectos públicos                                                                          |
+|           | `get_project`           | Equipo y configuración: ids de estados, tipos y áreas que aceptan las demás herramientas    |
+|           | `get_board`             | Tablero por columnas (filtros por persona, release, área)                                   |
+|           | `get_project_stats`     | Cifras de seguimiento                                                                       |
+|           | `get_project_analytics` | Estadísticas de los últimos días (creados/resueltos, flujo, tiempos, throughput, QA)        |
+|           | `get_project_activity`  | Actividad reciente                                                                          |
+| Tickets   | `my_issues`             | Mi trabajo en todos los proyectos (o de cualquiera, por categoría: p. ej. lo que espera QA) |
+|           | `search_issues`         | Buscar por texto y filtros                                                                  |
+|           | `get_issue`             | Detalle, transiciones permitidas, enlaces, comentarios e historial                          |
+|           | `create_issue`          | Crear un ticket                                                                             |
+|           | `update_issue`          | Cambiar título, descripción, tipo, área, prioridad, etiquetas…                              |
+|           | `change_issue_status`   | Mover de estado (con motivo cuando el estado lo pide)                                       |
+|           | `assign_issue`          | Asignar o desasignar                                                                        |
+|           | `set_issue_release`     | Meter en una release o sacar                                                                |
+|           | `add_comment`           | Comentar                                                                                    |
+|           | `link_issues`           | Relacionar tickets (`DEPENDS_ON`, `BLOCKS`, `TESTS`…)                                       |
+| Releases  | `list_releases`         | Releases de un proyecto                                                                     |
+|           | `upcoming_releases`     | Próximas releases de mis proyectos                                                          |
+|           | `get_release`           | Progreso, tickets y burnup                                                                  |
+|           | `create_release`        | Planificar una release                                                                      |
+|           | `publish_release`       | Publicar (con `force` si quedan tickets sin terminar)                                       |
+
+Las de lectura van marcadas como `readOnlyHint`, para que el cliente no pida confirmación al usarlas. Lo que es de
+administración (miembros, configuración, visibilidad, borrar proyectos) no se expone: se hace desde la web.
+
+## 9.3 Conectar un cliente
+
+Hace falta un token de Pireon. Con email y contraseña (si la API tiene configurado el cliente `password`):
+
+```sh
+curl -s https://api.taskstream.pireon.dev/api/auth/token \
+  -H 'content-type: application/json' \
+  -d '{"grant_type":"password","username":"tu@email.com","password":"…"}'
+# → { "access_token": "…", "refresh_token": "…", "expires_in": … }
+```
+
+Claude Code:
+
+```sh
+claude mcp add --transport http taskstream https://mcp.taskstream.pireon.dev/mcp \
+  --header "Authorization: Bearer $TASKSTREAM_TOKEN"
+# en local: http://localhost:3010/mcp
+```
+
+Otros clientes (JSON de configuración):
+
+```json
+{
+  "mcpServers": {
+    "taskstream": {
+      "type": "http",
+      "url": "https://mcp.taskstream.pireon.dev/mcp",
+      "headers": { "Authorization": "Bearer <token de Pireon>" }
+    }
+  }
+}
+```
+
+El token caduca como cualquier sesión de Pireon: cuando la herramienta responda «Error 401», hay que pedir otro (o
+renovarlo con `grant_type: refresh_token`). El MCP todavía no implementa el flujo de autorización OAuth del propio
+protocolo MCP, así que el cliente no lo obtiene solo.
+
+## 9.4 Desarrollo
+
+```sh
+npx nx serve api                     # la API en :3000
+npx nx serve mcp                     # el MCP en http://localhost:3010/mcp (TASKSTREAM_API_URL=http://localhost:3000)
+npx @modelcontextprotocol/inspector  # probar las herramientas en el navegador
+npx nx test mcp                      # MCP real contra una API simulada: token reenviado, errores, validación
+npx nx run mcp:openapi-types         # regenerar los tipos tras cambiar la API (apps/api/openapi.json)
+```
+
+| Variable             | Por defecto             | Qué es                                                                                     |
+| -------------------- | ----------------------- | ------------------------------------------------------------------------------------------ |
+| `MCP_PORT`           | `3010`                  | Puerto del MCP (no `PORT`: Nx carga el `.env` del workspace, donde `PORT` es el de la API) |
+| `TASKSTREAM_API_URL` | `http://localhost:3000` | Origen de la API (sus rutas ya llevan `/api`)                                              |
+| `MCP_LOG_LEVEL`      | `log`                   | `error`, `warn`, `log`, `debug` o `verbose`                                                |
+
+Añadir una herramienta: un método con `@Tool({ name, description, paramsSchema: z.object(…), annotations })` en el
+resolver de su ámbito (`apps/mcp/src/app/tools`), que llame a la API con `this.api.as(ctx)` (cliente tipado con el
+token de quien llama) y devuelva `toolResult(…)`.
+
+La imagen solo instala lo que lista `apps/mcp/package.json`: si el MCP empieza a usar un paquete nuevo en tiempo de
+ejecución, hay que añadirlo ahí (igual que en la API).
+
+## 9.5 Despliegue
+
+El servicio `mcp` de `docker-compose.yml` va en el perfil `mcp`, así que no arranca salvo que se pida:
+
+```sh
+docker compose --profile mcp up -d --build   # local: http://localhost:3010/mcp
+```
+
+En Dokploy: `COMPOSE_PROFILES=mcp` en las variables del proyecto y un dominio (p. ej. `mcp.taskstream.pireon.dev`) →
+servicio `mcp`, puerto 3010. Habla con la API por la red interna (`http://task-stream-api:3000`). La imagen usa Node 24,
+que es lo que pide `@nestjs-mcp/server` 2.