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](https://github.com/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 ```bash git clone <este-repositorio> cd npm-mcp-server npm install npm run build ``` ## 🔧 Uso ### Como servidor MCP standalone ```bash npm start ``` ### Integración con clientes MCP Agrega la siguiente configuración a tu cliente MCP: ```json { "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): ```json { "mcpServers": { "npm": { "command": "node", "args": ["/ruta/completa/a/npm-mcp-server/main.js"] } } } ``` ## 📖 Ejemplos de Uso ### Buscar paquetes ```typescript // Buscar paquetes relacionados con React { "name": "npm_search", "arguments": { "query": "react", "limit": 5 } } ``` ### Instalar dependencias ```typescript // Instalar React y React DOM { "name": "npm_install", "arguments": { "packages": ["react", "react-dom"], "directory": "/path/to/project" } } ``` ### Instalar dependencias de desarrollo ```typescript // Instalar TypeScript como dependencia de desarrollo { "name": "npm_install", "arguments": { "packages": ["typescript", "@types/node"], "dev": true } } ``` ### Ejecutar scripts ```typescript // Ejecutar el script "build" { "name": "npm_run_script", "arguments": { "script": "build" } } ``` ### Auditar seguridad ```typescript // 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 ```bash 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: ```bash npm install ``` ### Error de permisos Si tienes problemas con permisos globales: ```bash 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](LICENSE) para más detalles. **Autor:** [Kpangaa](https://github.com/Kpangaa) ## 🤝 Soporte Si encuentras algún problema o tienes sugerencias: 1. Revisa los [issues existentes](https://github.com/Kpangaa/npm-mcp-server/issues) 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