js-package-manager-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server for comprehensive JavaScript package management across NPM, Yarn, and pnpm. The server provides AI assistants with tools to search, install, analyze, and manage JavaScript dependencies with security and performance analysis capabilities.

Development Commands

Core Commands

• npm run build - Compile TypeScript to JavaScript in dist/
• npm run dev - Run in development mode with hot reload using tsx
• npm test - Run Jest tests
• npm run clean - Remove build artifacts from dist/
• npm start - Run the compiled server from dist/index.js

Testing

• Tests are configured with Jest and ts-jest for TypeScript support
• Test files: **/__tests__/**/*.ts and **/?(*.)+(spec|test).ts
• Coverage reports generated in coverage/ directory

Architecture

Entry Point & Server Structure

• Main entry: src/index.ts - Sets up MCP server with stdio transport and graceful shutdown
• Server configuration: src/server.ts - Unified MCP server with modular tool system
• Package manager detection: src/pm-detect.ts - Auto-detects npm/yarn/pnpm based on lock files
• Caching system: src/cache.ts - Memory cache with TTL for API responses

Tool Organization

The server uses a modular tool architecture where tools are organized by functionality:

• Search Tools: Package registry search and metadata retrieval
• Install Tools: Package installation, updates, and removal
• Security Tools: Vulnerability auditing and security analysis
• Analysis Tools: Bundle size analysis, dependency trees, circular dependency detection
• Management Tools: License checking, cache management, package information

Each tool module exports:

export const tools = [/* tool definitions */];
export const handlers = new Map([/* tool handlers */]);

Key Technical Details

• TypeScript: ES2022 target with ESNext modules and strict mode
• MCP SDK: Uses @modelcontextprotocol/sdk for protocol implementation
• Process Execution: Uses execa for secure package manager command execution
• Validation: Zod schemas for input validation on all tools
• HTTP Client: Custom HTTP client for npm registry and bundle analysis APIs
• Caching: Node-cache with TTL for API responses to reduce external calls
• Package Manager Agnostic: Automatically detects and works with npm, yarn, or pnpm