Agency Skills — Backend API

Plataforma de gestión de agencias de agentes con sistema multi-agente, recursos personalizados (skills, rules, agentes, workflows) y protocolo MCP (Model Context Protocol) para integración con herramientas CLI.

Stack

Runtime: Node.js + TypeScript
Framework: NestJS 11 (Arquitectura Hexagonal + CQRS)
Base de datos: PostgreSQL (TypeORM 0.3)
Cache/Sesiones: Redis (ioredis)
Auth: Google OAuth 2.0 + JWT (access + refresh tokens)
API Docs: Swagger UI (/api)
MCP: @modelcontextprotocol/sdk (stdio + SSE)

Quick Start

# Instalar dependencias
pnpm install

# Configurar variables de entorno
cp .env.example .env
# Editar .env con tus credenciales (DB, JWT secrets, Google OAuth)

# Docker (PostgreSQL + Redis)
pnpm run docker:up

# Ejecutar migraciones
pnpm run db:migrate

# Desarrollo
pnpm run start:dev

El servidor arranca en http://localhost:8004.

Estructura

src/
├── core/                           # Domain + Ports (Clean Architecture)
│   ├── agents/                     # 17 agentes especializados
│   ├── domain/                     # Interfaces, entidades, tokens
│   ├── infrastructure/             # DB, adapters, MCP controller
│   ├── presentation/               # Controllers REST (health, rules, mcp, agents, sessions)
│   └── skills/                     # Sistema de skills Hermes
├── modules/
│   ├── auth/                       # Google OAuth + JWT (access/refresh)
│   ├── agencies/                   # CRUD de agencias
│   ├── agency-resources/           # Skills, rules, agents, workflows por agencia
│   ├── users/                      # Usuarios (lookup por IP)
│   ├── sessions/                   # Sesiones MCP
│   ├── issues/                     # Gestión de issues
│   ├── projects/                   # Detección de proyectos
│   ├── contexts/                   # Contextos de proyecto
│   ├── plans/                      # Planes de trabajo
│   ├── memory/                     # Sistema de memoria
│   └── agency-agents/              # Catálogo de agentes
├── agents/                         # Implementaciones de agentes
├── rules/                          # Reglas de código (archivos .rule.ts)
├── shared/                         # Middleware, utils, constantes
├── mcp-server.ts                   # Servidor MCP stdio
├── mcp-http-server.ts              # Servidor MCP HTTP
└── main.ts                         # Bootstrap NestJS

Variables de entorno

# Server
PORT=8004
CORS_ORIGIN=http://localhost:4200

# Database
DB_URL=postgres://user:password@localhost:5432/agent_skills?sslmode=disable
DB_SYNCHRONIZE=false

# Redis
REDIS_URL=redis://localhost:6379/0

# JWT
JWT_ACCESS_SECRET=your-secret-here
JWT_REFRESH_SECRET=your-other-secret-here
JWT_ACCESS_EXPIRES_IN=15m
JWT_REFRESH_EXPIRES_IN=7d

# Google OAuth
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

Ver .env.example para todas las variables disponibles (Exa AI, Context7, ChromaDB, etc.).

Scripts

# Desarrollo
pnpm run start:dev              # Hot-reload
pnpm run start:debug            # Debug mode

# Producción
pnpm run build                  # Build completo
pnpm run start:prod             # Ejecutar dist/main

# Base de datos
pnpm run db:migrate             # Ejecutar migraciones pendientes
pnpm run db:migrate:revert      # Revertir última migración
pnpm run db:generate            # Generar migración desde cambios en entidades

# MCP
pnpm run start:mcp              # MCP stdio server
pnpm run start:mcp-http         # MCP HTTP server
pnpm run build:mcp              # Build MCP stdio
pnpm run build:mcp-http         # Build MCP HTTP

# Tests
pnpm run test                   # Unit tests
pnpm run test:e2e               # E2E tests
pnpm run test:cov               # Coverage

# Docker
pnpm run docker:up              # Levantar servicios
pnpm run docker:down            # Parar servicios
pnpm run docker:logs            # Ver logs

# Lint
pnpm run lint                   # ESLint + auto-fix
pnpm run typecheck              # Type-check sin emitir

# Agentes CLI
pnpm run agent:setup-gemini     # Configurar Gemini MCP
pnpm run mcp:update-claude      # Actualizar config Claude Code

Endpoints principales

Método	Ruta	Descripción
`GET`	`/health`	Health check
`GET`	`/api`	Swagger UI
`GET`	`/mcp/sse`	MCP SSE endpoint
`POST`	`/mcp/message`	MCP message endpoint

Auth

Método	Ruta	Descripción
`GET`	`/api/auth/login/google`	Login con Google
`GET`	`/api/auth/refresh`	Renovar access token
`POST`	`/api/auth/logout`	Cerrar sesión

Agencies

Método	Ruta	Descripción
`POST`	`/v1/agency`	Crear agencia
`GET`	`/v1/agency/by-user/:userId`	Obtener agencia del usuario
`GET`	`/v1/agency/:id`	Obtener agencia por ID
`PATCH`	`/v1/agency/:id`	Actualizar agencia
`DELETE`	`/v1/agency/:id`	Eliminar agencia

Agency Resources

Método	Ruta	Descripción
`POST`	`/v1/agency/:agencyId/skills`	Crear skill
`GET`	`/v1/agency/:agencyId/skills`	Listar skills
`GET`	`/v1/agency/:agencyId/skills/:id`	Obtener skill
`PUT`	`/v1/agency/:agencyId/skills/:id`	Actualizar skill
`DELETE`	`/v1/agency/:agencyId/skills/:id`	Eliminar skill
		(ídem para `/rules`, `/agents`, `/workflows`)

Agency Members

Método	Ruta	Descripción
`GET`	`/v1/agency/:id/members`	Listar miembros
`POST`	`/v1/agency/:id/members`	Agregar miembro
`DELETE`	`/v1/agency/:id/members/:userId`	Remover miembro

Users

Método	Ruta	Descripción
`GET`	`/v1/users/search?q=`	Buscar usuarios por email/nombre
`GET`	`/v1/users/:id`	Obtener usuario por ID

Agentes (17)

Agente	Responsabilidad
RouterAgent	Orquestador principal, detecta intención y delega
SearchAgent	Búsqueda BM25 de reglas
IdentityAgent	Identidad MCP y prefijos
RulesAgent	Listado y gestión de reglas
CodeAgent	Generación de código
ArchitectureAgent	Validación arquitectónica
AnalysisAgent	Análisis de código
MetricsAgent	Métricas y tracking
PMAgent	Gestión de proyecto
IssueWorkflowAgent	Workflow de issues
GitHubAgent	Integración GitHub
FrontendArchitectureAgent	Arquitectura frontend
WebSearchAgent	Búsqueda web (Exa AI)
Context7Agent	Documentación de librerías
ContextAgent	Contexto de proyecto
ProjectHistoryAgent	Historial de proyecto
GraphifyAgent	Visualización de código
ObsidianAgent	Integración Obsidian

MCP (Model Context Protocol)

El servidor MCP expone herramientas a través de dos transportes:

stdio (pnpm run start:mcp): para integración con CLI locales (Claude Code, Gemini, OpenCode)
SSE (/mcp/sse + /mcp/message): para integración web y remota

Herramientas MCP

Tool	Descripción
`session_init_auto`	Inicializa sesión MCP con contexto del proyecto
`list_agency_skills`	Lista skills de la agencia activa
`get_skill_detail`	Detalle de un skill específico
`invoke_skill`	Ejecuta un skill

Arquitectura

Hexagonal (Ports & Adapters): lógica de negocio aislada de infraestructura
CQRS: comandos y queries separados con @nestjs/cqrs
Repository Pattern: interfaces en domain, implementaciones en infrastructure
JWT dual: access tokens (15min) en localStorage, refresh tokens (7d) en httpOnly cookie
IP-based auth: para conexiones SSE/MCP donde no hay cookie disponible

Documentación adicional

doc/ARCHITECTURE.md — Arquitectura completa del sistema
doc/MCP-CONFIG.md — Configuración MCP por herramienta
doc/IMPLEMENTATION_STATUS.md — Estado de implementación

Agent Skills API