Kpangaa/npm-mcp-server

NPM MCP Server

Un servidor MCP (Model Context Protocol) completo para interactuar con npm y sus servicios. Este servidor permite a los modelos de lenguaje usar npm de forma segura y estructurada.

Desarrollado por: Kpangaa

🚀 Características

🛠️ Herramientas Disponibles

• npm_search: Buscar paquetes en el registro de npm
• npm_info: Obtener información detallada de un paquete
• npm_install: Instalar paquetes (con soporte para dependencias de desarrollo y globales)
• npm_uninstall: Desinstalar paquetes
• npm_list: Listar paquetes instalados
• npm_outdated: Verificar paquetes desactualizados
• npm_update: Actualizar paquetes a sus últimas versiones
• npm_run_script: Ejecutar scripts definidos en package.json
• npm_init: Inicializar un nuevo proyecto npm
• npm_audit: Auditar vulnerabilidades de seguridad
• npm_audit_fix: Arreglar vulnerabilidades automáticamente

📚 Recursos Disponibles

• npm://package.json: Acceso al contenido del archivo package.json
• npm://scripts: Lista de scripts disponibles en package.json

🧠 Prompts Disponibles

• npm_project_analysis: Análisis completo del estado del proyecto npm

📦 Instalación

git clone <este-repositorio>
cd npm-mcp-server
npm install
npm run build

🔧 Uso

Como servidor MCP standalone

npm start

Integración con clientes MCP

Agrega la siguiente configuración a tu cliente MCP:

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/ruta/a/npm-mcp-server/main.js"],
      "env": {}
    }
  }
}

Para Claude Desktop

Agrega esto a tu archivo de configuración de Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "npm": {
      "command": "node",
      "args": ["/ruta/completa/a/npm-mcp-server/main.js"]
    }
  }
}

📖 Ejemplos de Uso

Buscar paquetes

// Buscar paquetes relacionados con React
{
  "name": "npm_search",
  "arguments": {
    "query": "react",
    "limit": 5
  }
}

Instalar dependencias

// Instalar React y React DOM
{
  "name": "npm_install",
  "arguments": {
    "packages": ["react", "react-dom"],
    "directory": "/path/to/project"
  }
}

Instalar dependencias de desarrollo

// Instalar TypeScript como dependencia de desarrollo
{
  "name": "npm_install",
  "arguments": {
    "packages": ["typescript", "@types/node"],
    "dev": true
  }
}

Ejecutar scripts

// Ejecutar el script "build"
{
  "name": "npm_run_script",
  "arguments": {
    "script": "build"
  }
}

Auditar seguridad

// Verificar vulnerabilidades
{
  "name": "npm_audit",
  "arguments": {
    "directory": "/path/to/project"
  }
}

🛡️ Seguridad

• Todas las operaciones tienen timeout de 30 segundos
• Validación de entrada usando esquemas Zod
• Manejo seguro de errores
• Soporte para directorios específicos para evitar operaciones no deseadas

🗂️ Estructura del Proyecto

npm-mcp-server/
├── main.ts              # Código principal del servidor
├── main.js              # Código compilado
├── package.json         # Configuración del proyecto
├── tsconfig.json        # Configuración de TypeScript
├── README.md           # Este archivo
└── dist/               # Archivos compilados

🔧 Desarrollo

Requisitos

• Node.js 18+
• npm 9+
• TypeScript 5+

Scripts Disponibles

npm run build       # Compilar TypeScript
npm run dev         # Ejecutar en modo desarrollo con watch
npm start          # Ejecutar el servidor compilado

Contribuir

1. Fork el repositorio
2. Crea una rama para tu feature (git checkout -b feature/amazing-feature)
3. Commit tus cambios (git commit -m 'Add amazing feature')
4. Push a la rama (git push origin feature/amazing-feature)
5. Abre un Pull Request

📝 API Reference

Herramientas (Tools)

npm_search

Busca paquetes en el registro de npm.

Parámetros:

• query (string): Término de búsqueda
• limit (number, opcional): Límite de resultados (default: 10)

npm_info

Obtiene información detallada de un paquete.

Parámetros:

• name (string): Nombre del paquete
• version (string, opcional): Versión específica

npm_install

Instala paquetes usando npm.

Parámetros:

• packages (string[]): Lista de paquetes a instalar
• directory (string, opcional): Directorio del proyecto
• dev (boolean, opcional): Instalar como dependencia de desarrollo
• global (boolean, opcional): Instalación global

npm_list

Lista los paquetes instalados.

Parámetros:

• directory (string, opcional): Directorio del proyecto

npm_run_script

Ejecuta un script definido en package.json.

Parámetros:

• script (string): Nombre del script
• directory (string, opcional): Directorio del proyecto

Recursos (Resources)

npm://package.json

Proporciona acceso al contenido del archivo package.json del proyecto.

npm://scripts

Lista todos los scripts disponibles en package.json.

Prompts

npm_project_analysis

Genera un análisis completo del estado actual del proyecto npm.

Argumentos:

• directory (string, opcional): Directorio del proyecto a analizar

🐛 Resolución de Problemas

Error: "No se encuentra el módulo"

Asegúrate de que todas las dependencias estén instaladas:

npm install

Error de permisos

Si tienes problemas con permisos globales:

sudo npm install -g <paquete>

Timeout en comandos

Los comandos tienen un timeout de 30 segundos. Para proyectos grandes, considera usar el directorio específico.

📄 Licencia

MIT License - ver el archivo para más detalles.

Autor: Kpangaa

🤝 Soporte

Si encuentras algún problema o tienes sugerencias:

1. Revisa los issues existentes
2. Crea un nuevo issue si es necesario
3. Proporciona información detallada sobre el problema

🔄 Changelog

v1.0.0

• ✨ Implementación inicial del servidor MCP
• 🛠️ 11 herramientas completas para npm
• 📚 2 recursos para acceso a metadatos
• 🧠 1 prompt para análisis de proyectos
• 🛡️ Validación completa con Zod
• ⚡ Soporte para TypeScript