TypeScript Nx Plugin

Genera un Nx Plugin completo en TypeScript con un servidor Model Context Protocol (MCP) integrado. Este generador crea una base para construir generadores personalizados que pueden ser utilizados sin problemas por asistentes de IA para la generación automatizada de código y el andamiaje de proyectos.

Uso

Generar un Nx Plugin

Puedes generar un TypeScript Nx Plugin de dos maneras:

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin

npm

npx nx g @aws/nx-plugin:ts#nx-plugin

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-plugin --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-plugin --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-plugin --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-plugin --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-plugin
5. Complete los parámetros requeridos
6. Haga clic en Generate

Opciones

Parámetro	Tipo	Predeterminado	Descripción
name Requerido	string	-	Nombre del proyecto TypeScript
directory	string	packages	Directorio padre donde se coloca la biblioteca.
subDirectory	string	-	El subdirectorio donde se coloca la biblioteca. Por defecto es el nombre de la biblioteca.
preferInstallDependencies	boolean	true	Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesaria para que los generadores subsecuentes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del Generador

El generador creará la siguiente estructura de proyecto:

• Directorioyour-plugin/

  • Directoriosrc/

    • index.ts Empty entry point for your plugin
    • Directoriomcp-server/

      • index.ts Exports your server
      • server.ts Main MCP server configuration
      • stdio.ts Entry point for your MCP server with STDIO transport
      • http.ts Entry point for your MCP server with Streamable HTTP transport
      • Directoriotools/

        • create-workspace-command.ts Tool for workspace creation guidance
        • general-guidance.ts Tool for general Nx and plugin guidance
        • list-generators.ts Tool to list available generators
        • generator-guide.ts Tool for detailed generator information
      • utils.ts Utility functions for the MCP server
  • generators.json Nx generator configuration (initially empty)
  • package.json Plugin package configuration
  • tsconfig.json TypeScript configuration (CommonJS for Nx compatibility)
  • project.json Nx project configuration with build and package targets

Trabajar con tu Nx Plugin

Agregar Generadores

Una vez que tengas tu proyecto de plugin, puedes agregar generadores usando el generador ts#nx-generator:

CLI

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

npm

npx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

yarn

yarn nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

npm

npx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

bun

bunx nx g @aws/nx-plugin:ts#nx-generator --project=your-plugin --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - ts#nx-generator
5. Complete los parámetros requeridos
   • project: your-plugin
6. Haga clic en Generate

Esto agregará un nuevo generador a tu plugin.

Documentación del Generador

Lee la guía de ts#nx-generator para obtener detalles sobre cómo implementar generadores.

Asegúrate de escribir un README.md detallado para tu generador, ya que esto es utilizado por la herramienta generator-guide del servidor MCP.

Targets del Proyecto

El plugin generado incluye varios targets importantes:

Target Build

Compila tu código TypeScript y prepara el plugin para su uso:

pnpm

pnpm nx build your-plugin

yarn

yarn nx build your-plugin

npm

npx nx build your-plugin

bun

bunx nx build your-plugin

Target Package

Crea un paquete distribuible listo para publicar en NPM:

pnpm

pnpm nx package your-plugin

yarn

yarn nx package your-plugin

npm

npx nx package your-plugin

bun

bunx nx package your-plugin

El target package incluye todos los activos necesarios:

• Archivos JavaScript compilados
• Archivos de declaración TypeScript
• Archivos de configuración de generadores y ejecutores
• Archivos de documentación y licencia

Integración del Servidor MCP

El plugin configura un servidor MCP usando el generador ts#mcp-server.

Herramientas

El plugin incluye un servidor MCP completo que proporciona a los asistentes de IA las siguientes herramientas:

• general-guidance: Obtén mejores prácticas para trabajar con Nx y tu plugin
• create-workspace-command: Aprende cómo crear nuevos workspaces que puedan usar tu plugin
• list-generators: Lista todos los generadores disponibles en tu plugin
• generator-guide: Obtén información detallada sobre generadores específicos, incluyendo esquemas y uso

Configurar con Asistentes de IA

Archivos de Configuración

La mayoría de los asistentes de IA que soportan MCP utilizan un enfoque de configuración similar. Necesitarás crear o actualizar un archivo de configuración con los detalles de tu servidor MCP:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Resolución de Rutas

Si recibes un error como ENOENT npx al conectarte a tu servidor, es posible que necesites especificar la ruta completa a npx, la cual puedes obtener ejecutando which npx en tu terminal.

Recarga en Caliente

Mientras desarrollas tu servidor MCP, es posible que desees configurar la bandera --watch para que el asistente de IA siempre vea las últimas versiones de herramientas/recursos:

{
  "mcpServers": {
    "your-mcp-server": {
      "command": "npx",
      "args": ["tsx", "--watch", "/path/to/your-mcp-server/stdio.ts"]
    }
  }
}

Actualización de Herramientas

Si agregas nuevas herramientas o recursos, es posible que necesites actualizar tu servidor MCP en el asistente de IA.

Configuración Específica del Asistente

Por favor, consulta la siguiente documentación para configurar MCP con Asistentes de IA específicos:

• Kiro
• Kiro CLI
• Claude Code
• Cursor
• Codex
• Cline
• Roo Code

Configuración del Espacio de Trabajo

Algunos Asistentes de IA, como Kiro, te permiten especificar la configuración del servidor MCP a nivel de espacio de trabajo, lo cual es particularmente útil para definir los servidores MCP relevantes para un proyecto en particular.

Personalizar el Servidor MCP

Puedes extender el servidor MCP modificando server.ts para agregar herramientas o recursos adicionales específicos del dominio de tu plugin.

Para más detalles sobre cómo escribir servidores MCP, consulta la guía de ts#mcp-server.

Publicar tu Plugin

Preparar para la Publicación

1. Actualizar Información del Paquete: Edita el package.json de tu plugin con el nombre, versión, descripción e información del repositorio adecuados.

2. Construir el Paquete:

   pnpm

   pnpm nx package your-plugin

   yarn

   yarn nx package your-plugin

   npm

   npx nx package your-plugin

   bun

   bunx nx package your-plugin

3. Probar Localmente: Puedes probar tu plugin localmente instalándolo en otro workspace:

   npm install /path/to/your/workspace/dist/your-plugin/package

Publicar en NPM

Una vez que tu plugin esté listo:

cd dist/your-plugin/package
npm publish

Usar Plugins Publicados

Después de publicar, otros pueden instalar y usar tu plugin:

pnpm

pnpm add -w your-plugin-name

yarn

yarn add your-plugin-name

npm

npm install --legacy-peer-deps your-plugin-name

bun

bun add your-plugin-name

Luego usar tus generadores:

CLI

pnpm

pnpm nx g your-plugin-name:your-generator-name

yarn

yarn nx g your-plugin-name:your-generator-name

npm

npx nx g your-plugin-name:your-generator-name

bun

bunx nx g your-plugin-name:your-generator-name

También puede realizar una ejecución en seco para ver qué archivos se cambiarían

pnpm

pnpm nx g your-plugin-name:your-generator-name --dry-run

yarn

yarn nx g your-plugin-name:your-generator-name --dry-run

npm

npx nx g your-plugin-name:your-generator-name --dry-run

bun

bunx nx g your-plugin-name:your-generator-name --dry-run

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque your-plugin-name - your-generator-name
5. Complete los parámetros requeridos
6. Haga clic en Generate

Configurar Asistentes de IA con tu Plugin Publicado

El servidor MCP de tu plugin publicado se puede configurar de la siguiente manera:

{
  "mcpServers": {
    "aws-nx-mcp": {
      "command": "npx",
      "args": ["-y", "-p", "your-plugin-name", "your-plugin-name-mcp-server"]
    }
  }
}