mcp-azure-setup

CLI genérico para configurar automáticamente el acceso a paquetes privados en Azure Artifacts, con soporte para auto-detección de credenciales mediante Azure CLI.

🚀 Uso Rápido

Con Azure CLI (Recomendado - Auto-detección)

# 1. Inicia sesión en Azure
az login

# 2. Ejecuta el CLI sin credenciales
npx mcp-azure-setup \
  --organization YourOrganization \
  --project your-project \
  --feed "YourFeed@Release" \
  --scope yourscope

✨ El CLI detectará automáticamente:

• Access token de Azure (no necesitas crear un PAT)
• Tu email de usuario
• Organización configurada (opcional)

Sin Azure CLI (Manual)

npx mcp-azure-setup \
  --organization YourOrganization \
  --project your-project \
  --feed "YourFeed@Release" \
  --scope yourscope \
  --pat "tu-personal-access-token" \
  --email [email protected]

📋 ¿Qué hace?

1. ✅ Verifica que tengas Node.js 18 o superior
2. ✅ Auto-detecta credenciales con Azure CLI (si está instalado y configurado)
   • Obtiene access token automáticamente (no necesitas crear PAT)
   • Obtiene tu email de usuario
   • Detecta la organización configurada
3. ✅ Crea o actualiza tu archivo .npmrc global en tu home directory
4. ✅ Configura la autenticación completa con Azure Artifacts:
   • Username (organización)
   • Password codificado en Base64 (PAT o access token)
   • Email
5. ✅ Configura el scope de npm para tus paquetes privados
6. ✅ Configura el registry público de npm como fallback
7. ✅ Opcionalmente deshabilita SSL strict si es necesario
8. ✅Siempre Requeridos

| Parámetro | Alias | Descripción | Ejemplo | |-----------|-------|-------------|---------| | --project | -p | Nombre del proyecto | my-project | | --feed | -f | Nombre del feed de Artifacts | MyFeed@Release | | --scope | -s | Scope de npm (sin @) | mycompany |

Condicionales (auto-detectados con Azure CLI)

| Parámetro | Alias | Auto-detectado | Descripción | Ejemplo | |-----------|-------|----------------|-------------|---------| | --organization | -o | ✅ Sí | Nombre de la organización en Azure DevOps | YourOrganization | | --pat | -t | ✅ Sí (access token) | Personal Access Token de Azure DevOps | abc123... | | --email | -e | ✅ Sí | Email para autenticación | [email protected] |

Opcionales

| Parámetro | Descripción | Valores | Default | |-----------|-------------|---------|---------| | --strict-ssl | Habilita/deshabilita verificación SSL | true, false | true | | --help | Muestra la ayuda | - | - |

🔐 Autenticación con Azure CLI (Recomendado)

Instalación de Azure CLI

# macOS
brew install azure-cli

# Windows
winget install Microsoft.AzureCLI

# Linux (Ubuntu/Debian)
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

O descarga desde: https://aka.ms/install-azure-cli

Configuración

# 1. Iniciar sesión
az login

# 2. (Opcional) Si tienes múltiples suscripciones, selecciona una
az account list --output table
az account set --subscription "Desarrollo"

# 3. Ejecutar el CLI
npx mcp-azure-setup \
  --organization YourOrganization \
  --project your-project \
  --feed "YourFeed@Release" \
  --scope yourscope

Ventajas de usar Azure CLI

✅ No necesitas crear o gestionar PATs manualmente ✅ Token se renueva automáticamente cuando ejecutas az login ✅ Más seguro - no tienes que copiar/pegar tokens ✅ Auto-detecta tu email del usuario logueado ✅ Menos parámetros que especificar

🔑 Autenticación Manual (sin Azure CLI

| --strict-ssl | Habilita/deshabilita verificación SSL | true, false | true | | --help | Muestra la ayuda | - | - |

🔐 Cómo obtener un Personal Access Token (PAT)

1. Ve a Azure DevOps: https://dev.azure.com/{tu-organizacion}
2. Click en tu perfil (esquina superior derecha) > Personal Access Tokens
3. Click en New Token
4. Configura:
   • Name: "NPM Registry Access" (o el nombre que prefieras)
   • Organization: Selecciona tu organización
   • Expiration: Configura la fecha de expiración
   • Scopes:
     • ✅ Packaging > Read
     • (o "Read & write" si necesitas publicar paquetes)
5. Click en Create
6. ¡IMPORTANTE! Copia el token inmediatamente (solo se muestra una vez)
7. Usa ese token en el parámetro --pat

📄 Formato del archivo .npmrc generado

El CLI genera un archivo .npmrc en tu home directory con este formato:

; begin auth token
//pkgs.dev.azure.com/{ORG}/{PROJECT}/_packaging/{FEED}/npm/registry/:username={ORG}
//pkgs.dev.azure.com/{ORG}/{PROJECT}/_packaging/{FEED}/npm/registry/:_password={BASE64_PAT}
//pkgs.dev.azure.com/{ORG}/{PROJECT}/_packaging/{FEED}/npm/registry/:email={EMAIL}
; end auth token
@{SCOPE}:registry=https://pkgs.dev.azure.com/{ORG}/{PROJECT}/_packaging/{FEED}/npm/registry/
registry=https://registry.npmjs.org/
always-auth=true
strict-ssl=false

Nota: El PAT se codifica automáticamente en Base64 para cumplir con el formato requerido por npm.

💻 Compatibilidad

• ✅ Windows (PowerShell, CMD, Git Bash)
• ✅ macOS (Terminal, iTerm)
• ✅ Linux (bash, zsh, etc.)

El CLI detecta automáticamente el home directory según el sistema operativo.

🔒 Seguridad

• ✅ El PAT se codifica en Base64 automáticamente
• ✅ El archivo .npmrc se crea con permisos de usuario
• ✅ No se almacenan credenciales en otros lugares
• ✅ El CLI es de código abierto y auditable
• ⚠️ No compartas tu archivo .npmrc - contiene credenciales
• ⚠️ No hagas commit del .npmrc - agrégalo a .gitignore

📦 Usando tus paquetes privados

Después de ejecutar el CLI, puedes instalar y usar paquetes privados:

# Instalar un paquete privado
npm install @mycompany/mi-paquete

# Ejecutar un CLI privado
npx @mycompany/mi-cli

# Agregar a package.json
npm install --save @mycompany/mi-libreria

🛠️ Solución de Problemas

Error: "No se pudo validar el acceso"

Posibles causas:

1. No existen paquetes publicados con ese scope
2. El PAT no tiene los permisos correctos
3. Los parámetros de organización/proyecto/feed son incorrectos

Verifica tus parámetros y vuelve a ejecutar el CLI.

Error: "401 Unauthorized"

Tu PAT probablemente expiró o no tiene permisos. Genera un nuevo PAT con permisos de "Packaging (Read)".

Error: "Node.js 18 o superior es requerido"

Actualiza Node.js:

# Con nvm
nvm install 18
nvm use 18

# Con Homebrew (macOS)
brew install node@18

# Descarga manual
# https://nodejs.org

Verificar el archivo .npmrc

# macOS/Linux
cat ~/.npmrc

# Windows (PowerShell)
Get-Content $env:USERPROFILE\.npmrc

# Windows (CMD)
type %USERPROFILE%\.npmrc

🚀 Publicación (para maintainers)

Primera vez

npm login
npm publish --access public

Actualizaciones

npm version patch  # 1.0.0 -> 1.0.1
npm publish --access public

📖 Ayuda

npx mcp-azure-setup --help

📄 Licencia

MIT

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor abre un issue o pull request en el repositorio.

⚠️ Disclaimer

Este es un CLI genérico y no incluye configuraciones específicas de ninguna empresa. Todos los parámetros deben ser proporcionados por el usuario.

Uso

Ejecuta directamente con npx sin necesidad de instalación:

npx optimus-setup

El CLI configurará automáticamente tu archivo .npmrc global para acceder al registry privado de Azure Artifacts.

¿Qué hace?

1. ✅ Verifica que tengas Node.js 18 o superior
2. ✅ Crea o actualiza tu archivo .npmrc global
3. ✅ Configura el scope @empresa-mcp apuntando al registry de Azure Artifacts
4. ✅ Valida que puedas acceder al registry
5. ✅ Muestra instrucciones claras si necesitas autenticarte

Requisitos

• Node.js 18 o superior
• npm 8 o superior
• Acceso a Azure DevOps con permisos al feed de Artifacts

Autenticación

Si el CLI detecta que necesitas autenticarte, te mostrará las instrucciones exactas:

npm login --registry=https://pkgs.dev.azure.com/ORGANIZATION/_packaging/FEED/npm/registry/

Necesitarás:

• Usuario: Tu email de Azure DevOps
• Password: Personal Access Token (PAT) con permisos de "Packaging (Read)"
• Email: Tu email corporativo

Crear un Personal Access Token

1. Ve a Azure DevOps > User Settings > Personal Access Tokens
2. Click en "New Token"
3. Nombre: "NPM Registry Access" (o el que prefieras)
4. Organization: Selecciona tu organización
5. Scopes: Marca "Packaging (Read)" o "Packaging (Read & Write)"
6. Click en "Create"
7. Copia el token generado (solo se muestra una vez)
8. Úsalo como password en el npm login

Configuración manual

El CLI modifica tu archivo ~/.npmrc agregando estas líneas:

@empresa-mcp:registry=https://pkgs.dev.azure.com/ORGANIZATION/_packaging/FEED/npm/registry/
always-auth=true

Desarrollo

Estructura del proyecto

optimus-setup/
├── package.json
├── README.md
├── bin/
│   └── index.js          # Punto de entrada ejecutable
└── src/
    ├── core.js           # Orquestador principal
    ├── npmrc.js          # Gestión del archivo .npmrc
    └── validator.js      # Validación de acceso

Instalación local

git clone <repo-url>
cd optimus-setup
npm install
npm link

Luego puedes ejecutar:

optimus-setup

Testing local con npx

npx .

Publicación

Primera vez

1. Crea una cuenta en npmjs.com si no tienes una

2. Inicia sesión desde la terminal:

npm login

3. Publica el paquete como público:

npm publish --access public

Actualizaciones

1. Actualiza la versión en package.json:

npm version patch  # 1.0.0 -> 1.0.1
npm version minor  # 1.0.0 -> 1.1.0
npm version major  # 1.0.0 -> 2.0.0

2. Publica:

npm publish --access public

Antes de publicar

Verifica que todo esté correcto:

npm pack --dry-run

Esto te mostrará qué archivos se incluirán en el paquete publicado.

Personalización

Para adaptar este CLI a tu organización, edita las siguientes constantes en src/npmrc.js:

const REGISTRY_URL = 'https://pkgs.dev.azure.com/TU_ORG/_packaging/TU_FEED/npm/registry/';
const SCOPE = '@tu-scope';

Compatibilidad

• ✅ macOS
• ✅ Linux
• ✅ Windows

El CLI detecta automáticamente el home directory según el sistema operativo.

Seguridad

• ❌ No almacena credenciales
• ❌ No hardcodea tokens
• ✅ Solo modifica el archivo .npmrc
• ✅ No sobreescribe configuraciones existentes
• ✅ Muestra instrucciones seguras para autenticación

Solución de problemas

Error: "Node.js 18.0.0 o superior es requerido"

Actualiza Node.js:

# Con nvm
nvm install 18
nvm use 18

# Con Homebrew (macOS)
brew install node@18

# Descarga manual
# https://nodejs.org

Error: "401 Unauthorized"

Necesitas autenticarte. Ejecuta:

npm login --registry=https://pkgs.dev.azure.com/ORGANIZATION/_packaging/FEED/npm/registry/

Error: "404 Not Found"

Verifica que:

1. El paquete @empresa-mcp existe en el feed
2. Tienes permisos de lectura en el feed
3. La URL del registry es correcta

El archivo .npmrc no se encuentra

El CLI lo crea automáticamente en tu home directory. Si tienes problemas, verifica los permisos:

ls -la ~/.npmrc

Licencia

MIT

Soporte

Para reportar issues o solicitar features, contacta al equipo de DevOps.