Plugin TypeScript do Nx

Gere um Plugin Nx completo em TypeScript com um servidor integrado do Model Context Protocol (MCP). Este gerador cria uma base para construir geradores personalizados que podem ser usados de forma transparente por assistentes de IA para geração automatizada de código e scaffolding de projetos.

Utilização

Gerar um Plugin Nx

Você pode gerar um Plugin Nx em TypeScript de duas formas:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#nx-plugin
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Opções

Parâmetro	Tipo	Padrão	Descrição
name Obrigatório	string	-	TypeScript project name
directory	string	packages	Parent directory where the library is placed.
subDirectory	string	-	The sub directory the lib is placed in. By default this is the library name.

Saída do Gerador

O gerador criará a seguinte estrutura de projeto:

• Directoryyour-plugin/

  • Directorysrc/

    • index.ts Ponto de entrada vazio para seu plugin
    • Directorymcp-server/

      • index.ts Exporta seu servidor
      • server.ts Configuração principal do servidor MCP
      • stdio.ts Ponto de entrada para servidor MCP com transporte STDIO
      • http.ts Ponto de entrada para servidor MCP com transporte HTTP streamable
      • Directorytools/

        • create-workspace-command.ts Ferramenta para orientação de criação de workspace
        • general-guidance.ts Ferramenta para orientações gerais sobre Nx e plugins
        • list-generators.ts Ferramenta para listar geradores disponíveis
        • generator-guide.ts Ferramenta para informações detalhadas sobre geradores
      • utils.ts Funções utilitárias para o servidor MCP
  • generators.json Configuração de geradores Nx (inicialmente vazio)
  • package.json Configuração do pacote do plugin com binário do servidor MCP
  • tsconfig.json Configuração TypeScript (CommonJS para compatibilidade com Nx)
  • project.json Configuração de projeto Nx com targets de build e package

Trabalhando com Seu Plugin Nx

Adicionando Geradores

Após criar seu projeto de plugin, você pode adicionar geradores usando o ts#nx-generator:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por @aws/nx-plugin - ts#nx-generator
5. Preencha os parâmetros obrigatórios
   • pluginProject: your-plugin
6. Clique em Generate

CLI

pnpm

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

yarn

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

npm

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

bun

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

pnpm

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

yarn

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

npm

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

bun

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

Isso adicionará um novo gerador ao seu plugin.

Dica

Leia o guia ts#nx-generator para detalhes sobre como implementar geradores.

Certifique-se de escrever um README.md detalhado para seu gerador, pois ele é usado pela ferramenta generator-guide do Servidor MCP.

Targets do Projeto

O plugin gerado inclui vários targets importantes:

Target Build

Compila seu código TypeScript e prepara o plugin para 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

Cria um pacote distribuível pronto para publicação no 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

O target package inclui todos os assets necessários:

• Arquivos JavaScript compilados
• Arquivos de declaração TypeScript
• Arquivos de configuração de geradores e executors
• Documentação e arquivos de licença

Integração com Servidor MCP

O plugin configura um servidor MCP usando o gerador ts#mcp-server.

Ferramentas

O plugin inclui um servidor MCP completo que fornece aos assistentes de IA as seguintes ferramentas:

• general-guidance: Obtenha melhores práticas para trabalhar com Nx e seu plugin
• create-workspace-command: Aprenda a criar novos workspaces que podem usar seu plugin
• list-generators: Liste todos os geradores disponíveis em seu plugin
• generator-guide: Obtenha informações detalhadas sobre geradores específicos incluindo schemas e uso

Configurando com Assistantes de IA

Arquivos de Configuração

A maioria dos assistentes de IA que suportam MCP usam uma abordagem de configuração semelhante. Você precisará criar ou atualizar um arquivo de configuração com os detalhes do seu servidor MCP:

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

Cuidado

Se você receber um erro como ENOENT npx ao conectar ao seu servidor, talvez precise especificar o caminho completo para o npx, que pode ser obtido executando which npx no seu terminal.

Recarregamento a Quente

Durante o desenvolvimento do seu servidor MCP, você pode querer configurar a flag --watch para que o assistente de IA sempre veja as versões mais recentes de ferramentas/recursos:

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

Nota

Se você adicionar novas ferramentas ou recursos, pode ser necessário atualizar seu servidor MCP no assistente de IA.

Configuração Específica do Assistente

Consulte a documentação a seguir para configurar o MCP com assistentes de IA específicos:

• Amazon Q Developer
• Cline
• Cursor
• Claude Code
• Roo Code

Dica

Alguns assistentes de IA, como o Amazon Q Developer, permitem especificar uma configuração de servidor MCP no nível de workspace, o que é particularmente útil para definir os servidores MCP relevantes para um projeto específico.

Personalizando o Servidor MCP

Você pode estender o servidor MCP modificando server.ts para adicionar ferramentas ou recursos específicos ao domínio do seu plugin.

Para mais detalhes sobre como escrever Servidores MCP, consulte o guia ts#mcp-server.

Publicando Seu Plugin

Preparando para Publicação

1. Atualize as Informações do Pacote: Edite o package.json do seu plugin com nome, versão, descrição e informações de repositório adequadas.

2. Construa o Pacote:

   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. Teste Localmente: Você pode testar seu plugin localmente instalando-o em outro workspace:

   npm install /caminho/para/seu/workspace/dist/your-plugin/package

Publicando no NPM

Quando seu plugin estiver pronto:

cd dist/your-plugin/package
npm publish

Usando Plugins Publicados

Após a publicação, outros podem instalar e usar seu 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 install your-plugin-name

Em seguida use seus geradores:

VSCode

1. Instale o Nx Console VSCode Plugin se ainda não o fez
2. Abra o console Nx no VSCode
3. Clique em Generate (UI) na seção "Common Nx Commands"
4. Procure por your-plugin-name - your-generator-name
5. Preencha os parâmetros obrigatórios
6. Clique em Generate

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

Você também pode realizar uma execução simulada para ver quais arquivos seriam alterados

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

Configure Assistantes de IA com Seu Plugin Publicado

O servidor MCP do seu plugin publicado pode ser configurado da seguinte forma:

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