NPM MCP Server
A Model Context Protocol server that enables language models to interact with npm services securely, providing tools for package management, project initialization, script execution, and security auditing.
README Documentation
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
- Fork el repositorio
- Crea una rama para tu feature (
git checkout -b feature/amazing-feature
) - Commit tus cambios (
git commit -m 'Add amazing feature'
) - Push a la rama (
git push origin feature/amazing-feature
) - 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úsquedalimit
(number, opcional): Límite de resultados (default: 10)
npm_info
Obtiene información detallada de un paquete.
Parámetros:
name
(string): Nombre del paqueteversion
(string, opcional): Versión específica
npm_install
Instala paquetes usando npm.
Parámetros:
packages
(string[]): Lista de paquetes a instalardirectory
(string, opcional): Directorio del proyectodev
(boolean, opcional): Instalar como dependencia de desarrolloglobal
(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 scriptdirectory
(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 LICENSE para más detalles.
Autor: Kpangaa
🤝 Soporte
Si encuentras algún problema o tienes sugerencias:
- Revisa los issues existentes
- Crea un nuevo issue si es necesario
- 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