Files

Josep Piguillem 9236cb73c6 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

6.3 KiB

Raw Blame History

1. Visión general

Qué resuelve

Necesidad	Cómo se resuelve
🐛 Bugs	Tickets de tipo `BUG` con prioridad, área y etiquetas
🌍 Públicos	Un proyecto público se puede leer sin iniciar sesión (web, GraphQL y REST): tablero, tickets, comentarios, releases, actividad y estadísticas; «Explorar» los lista
🗑️ Borrar	El propietario borra un proyecto confirmando su clave; tickets, comentarios, releases y enlaces desde otros proyectos se borran en cascada (sagas) y la clave queda libre
🧩 Configuración	Cada proyecto tiene sus estados (con categoría, color y motivo obligatorio), transiciones, tipos de ticket y áreas; lo usado se archiva, no se borra
🎨 Cambios de UI	Tipo `UI_CHANGE` con enlace al frame de Figma (validado contra `figma.com`)
⚙️ Features	Tipo `FEATURE` siguiendo el workflow completo
🧪 QA	Por defecto, `READY_FOR_QA → IN_QA → DONE / QA_FAILED`; fallar QA exige un motivo
🚀 Releases	Versiones a las que se asignan tickets; no se publican con tickets sin terminar (salvo forzando)
👥 Asignaciones	Solo a miembros del proyecto; panel de carga por persona
💬 Comentarios	Decisiones y explicaciones dentro del ticket; el autor edita, el admin modera
🔗 Relaciones	`BLOCKS`, `DEPENDS_ON`, `TESTS`, `DUPLICATES`, `RELATES_TO`, también entre proyectos (FE ↔ BE ↔ QA)
🏠 Inicio	«Mi trabajo»: mis tickets en todos los proyectos, por categoría (QA fallidos primero), lo que espera QA, próximas releases e «Ir a…» por clave
📊 Seguimiento	Panel con contadores, flujo por estado, el equipo con sus tickets abiertos (enlaza a su tablero), feed de actividad e historial por ticket
📈 Estadísticas	Creados vs. resueltos, flujo acumulado, burnup de releases, tiempos de ciclo y entrega, tasa de fallo en QA y resueltos por persona
⚡ Tiempo real	Tablero, comentarios, actividad, releases y membresías se actualizan solos (GraphQL subscriptions)

Los usuarios no se gestionan aquí: vienen del servidor de identidad Pireon (Swagger). TaskStream gestiona proyectos, membresías y roles por proyecto (OWNER, ADMIN, MEMBER, VIEWER).

Stack

Pieza	Tecnología
Monorepo	Nx 23
API	NestJS 11, `@nestjs/cqrs`, GraphQL (Apollo Server 5, code-first) con subscriptions `graphql-ws`
Escritura	PostgreSQL 17: event store + tablas de lookup (TypeORM)
Escritura → lectura	Redis 7: Redis Stream (eventos) y pub/sub (tiempo real); también caché de sesiones
Lectura	MongoDB 8: vistas desnormalizadas (Mongoose)
Identidad	Pireon (OAuth2 / Laravel Passport)
Cliente	Angular 22 (standalone, zoneless, Signal Forms), NgRx Signals (plugin de eventos), Apollo Angular, `@pi/ui`
Tests	Jest (API), Vitest (web), e2e de la API contra Docker
Despliegue	Docker: imagen Node de la API y nginx para la web

Estructura del monorepo

apps/
  api/          composición de la API (NestJS): config, GraphQL, conexiones, e2e
  web/          composición del cliente (Angular): rutas, providers, estilos, nginx
  mcp/          servidor MCP para asistentes de IA (NestJS), consume la API REST
libs/
  api/{shared,identity,tracker}/{domain,application,infrastructure,presenters}
  web/{shared,identity,tracker}/{domain,application,infrastructure,presenters}   (+ web/shared/ui)
docs/           esta documentación
codegen.ts      tipos GraphQL del cliente generados desde apps/api/schema.gql
Dockerfile      tres destinos: api, web y mcp
docker-compose.yml

API y web comparten la misma estructura: contexto (shared, identity, tracker) × capa (domain, application, infrastructure, presenters). Los imports siguen el mismo patrón: @task-stream/api/tracker/domain, @task-stream/web/tracker/application…

Contextos

shared: piezas comunes. En la API, event store, Redis, VersionedAggregateRoot, errores de dominio. En la web, el cliente GraphQL y la integración de @pi/ui.
identity: quién es el usuario (Pireon), sesiones, inicio de sesión y autorización global.
tracker: el producto (proyectos, tickets, comentarios, releases, actividad).

6.3 KiB Raw Blame History Unescape Escape