NPM Context Agent MCP

# npm-context-agent-mcp A Model Context Protocol (MCP) server that provides comprehensive contextual information about npm packages, including README files, versions, dependencies, download statistics, and more. <a href="https://glama.ai/mcp/servers/@JuanSebastianGB/npm-context-agent-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@JuanSebastianGB/npm-context-agent-mcp/badge" alt="NPM Context Agent MCP server" /> </a> ## 🚀 Features ### Core Capabilities - **📦 Package Metadata** - Get detailed information about any npm package - **📖 README Files** - Automatically fetches README from GitHub repositories with smart branch fallback - **🔍 Package Search** - Search npm registry by keyword with customizable result limits - **📋 Version History** - Get all available versions of a package with dist tags - **🔗 Dependencies Info** - View dependencies, devDependencies, and peerDependencies - **📊 Download Statistics** - Track package download trends (last day, week, or month) - **ℹ️ Comprehensive Info** - Get full package metadata including keywords, license, maintainers - **🔀 Package Comparison** - Compare two packages side-by-side - **📦 Bundle Size** - Get package bundle size information from bundlephobia - **⭐ Quality Metrics** - Get quality scores from npms.io ### MCP Resources Resources provide application-driven data access: - **package://{packageName}** - Package metadata as JSON resource - **package://{packageName}/readme** - README content as markdown resource - **package://{packageName}/dependencies** - Dependencies as JSON resource - **package://{packageName}/versions** - Version history as JSON resource ### MCP Prompts Ready-to-use prompt templates: - **analyze-package** - Comprehensive package analysis prompt - **compare-packages** - Compare two packages prompt - **find-alternatives** - Find alternative packages prompt ### Transport Support - **stdio Transport** - Traditional stdio-based communication (default) - **HTTP Transport** - HTTP-based communication for remote access - **Dual Mode** - Support both transports simultaneously ### Technical Features - **🛡️ Type-safe validation** - Uses Zod for runtime schema validation - **🏷️ Scoped package support** - Handles scoped packages like `@types/node` - **🎯 Version support** - Fetch specific package versions for all operations - **⚡ Smart branch fallback** - Automatically tries main → master → default branches - **🔄 Error handling** - Graceful error handling with detailed error messages - **📤 Structured output** - All tools return structured JSON for programmatic access - **🎨 Modern MCP SDK** - Uses latest MCP SDK v1.20.2 with resources and prompts - **🌐 HTTP & stdio** - Choose your transport mode based on your needs ## 📋 Requirements - Node.js 18+ (works with Node.js 20+ recommended) - pnpm 10.19.0+ ## 🛠️ Installation ### From npm (when published) ```bash npm install -g npm-context-agent-mcp ``` ### From source ```bash git clone <repository-url> cd npm-context-agent-mcp pnpm install pnpm build ``` ## 🎯 Usage ### As an MCP Server This server implements the Model Context Protocol and can be used with MCP-compatible clients. #### Stdio Transport (Default) Add to your MCP configuration: ```json { "mcpServers": { "npm-context-agent": { "command": "node", "args": ["path/to/npm-context-agent-mcp/build/index.js"] } } } ``` #### HTTP Transport To use HTTP transport, set the environment variable before starting: ```bash export TRANSPORT_MODE=http export PORT=3000 # optional, defaults to 3000 node build/index.js ``` Then connect to `http://localhost:3000/mcp` from your MCP client. #### Dual Mode To run both stdio and HTTP transports simultaneously: ```bash export TRANSPORT_MODE=both node build/index.js ``` **Environment Variables:** - `TRANSPORT_MODE` - Transport mode: `stdio` (default), `http`, or `both` - `PORT` - HTTP server port (default: 3000, only used for http/both modes) ### Quick Start Examples **Tools:** Get README for a package: ```json { "packageName": "react" } ``` Search for packages: ```json { "query": "state management", "limit": 5 } ``` Get all versions: ```json { "packageName": "svelte" } ``` Get dependencies: ```json { "packageName": "@types/node", "version": "24.0.0" } ``` Check download stats: ```json { "packageName": "lodash", "period": "last-week" } ``` Compare packages: ```json { "packageName1": "express", "packageName2": "fastify" } ``` Get bundle size: ```json { "packageName": "lodash", "version": "4.17.21" } ``` Get quality metrics: ```json { "packageName": "react" } ``` **Resources:** Read package metadata: ``` package://react ``` Read package README: ``` package://react/readme ``` Read package dependencies: ``` package://react/dependencies ``` Read version history: ``` package://react/versions ``` **Prompts:** Analyze a package: ```json { "packageName": "express" } ``` Compare two packages: ```json { "packageName1": "vue", "packageName2": "react" } ``` Find alternatives: ```json { "packageName": "lodash", "useCase": "utility functions" } ``` ### Available Tools | Tool | Description | Parameters | | -------------------------- | --------------------------------- | ------------------------------ | | `get_readme_data` | Get package README from GitHub | `packageName`, `version?` | | `search_packages` | Search npm packages by keyword | `query`, `limit?` | | `get_package_versions` | Get all versions of a package | `packageName` | | `get_package_dependencies` | Get package dependencies | `packageName`, `version?` | | `get_download_stats` | Get download statistics | `packageName`, `period?` | | `get_package_info` | Get comprehensive package info | `packageName`, `version?` | | `compare_packages` | Compare two packages side-by-side | `packageName1`, `packageName2` | | `get_package_size` | Get bundle size information | `packageName`, `version?` | | `get_package_quality` | Get quality metrics from npms.io | `packageName` | #### `get_readme_data` Retrieves package information and README content from npm packages. **Parameters:** - `packageName` (string, required): The name of the npm package - `version` (string, optional): Specific version to fetch (defaults to latest) **Example:** ```json { "packageName": "zustand", "version": "5.0.0" } ``` **Response:** Returns package name, version, description, repository URL, and README content. --- #### `search_packages` Search npm registry for packages by keyword. **Parameters:** - `query` (string, required): Search keyword - `limit` (number, optional): Maximum number of results (default: 20) **Example:** ```json { "query": "state management", "limit": 10 } ``` **Response:** Returns matching packages with names, versions, descriptions, authors, and links. --- #### `get_package_versions` Get all available versions of a package. **Parameters:** - `packageName` (string, required): The name of the npm package **Example:** ```json { "packageName": "react" } ``` **Response:** Returns list of all versions, dist tags, and latest version. --- #### `get_package_dependencies` Get dependencies and devDependencies for a package. **Parameters:** - `packageName` (string, required): The name of the npm package - `version` (string, optional): Specific version to fetch (defaults to latest) **Example:** ```json { "packageName": "@types/node", "version": "24.0.0" } ``` **Response:** Returns dependencies, devDependencies, and peerDependencies for the specified version. --- #### `get_download_stats` Get download statistics from npm. **Parameters:** - `packageName` (string, required): The name of the npm package - `period` (string, optional): Time period - "last-day", "last-week", or "last-month" (default: "last-month") **Example:** ```json { "packageName": "lodash", "period": "last-week" } ``` **Response:** Returns download counts and date range for the specified period. --- #### `get_package_info` Get comprehensive package metadata. **Parameters:** - `packageName` (string, required): The name of the npm package - `version` (string, optional): Specific version to fetch (defaults to all versions) **Example:** ```json { "packageName": "express", "version": "4.18.0" } ``` **Response:** Returns comprehensive package information including keywords, license, maintainers, and repository details. --- #### `compare_packages` Compare two packages side-by-side with detailed metrics. **Parameters:** - `packageName1` (string, required): First package to compare - `packageName2` (string, required): Second package to compare **Example:** ```json { "packageName1": "express", "packageName2": "fastify" } ``` **Response:** Returns side-by-side comparison including versions, descriptions, download statistics, maintainers, and keywords. --- #### `get_package_size` Get bundle size information for a package from bundlephobia. **Parameters:** - `packageName` (string, required): The name of the npm package - `version` (string, optional): Specific version to check (defaults to latest) **Example:** ```json { "packageName": "lodash", "version": "4.17.21" } ``` **Response:** Returns minified size, gzipped size, and dependency count. --- #### `get_package_quality` Get quality metrics from npms.io for a package. **Parameters:** - `packageName` (string, required): The name of the npm package **Example:** ```json { "packageName": "react" } ``` **Response:** Returns quality score, popularity score, and maintenance score. --- ### Available Resources | Resource | Description | MIME Type | | -------------------------------------- | ----------------------- | ------------------ | | `package://{packageName}` | Package metadata | `application/json` | | `package://{packageName}/readme` | Package README content | `text/markdown` | | `package://{packageName}/dependencies` | Package dependencies | `application/json` | | `package://{packageName}/versions` | Package version history | `application/json` | ### Available Prompts | Prompt | Description | Arguments | | ------------------- | --------------------------------- | ------------------------------ | | `analyze-package` | Comprehensive package analysis | `packageName` | | `compare-packages` | Compare two packages | `packageName1`, `packageName2` | | `find-alternatives` | Find alternative packages | `packageName`, `useCase?` | --- ## 🏗️ Development ### Project Structure ``` npm-context-agent-mcp/ ├── src/ │ └── index.ts # Main MCP server implementation ├── build/ # Compiled JavaScript output ├── package.json ├── tsconfig.json └── README.md ``` ### Scripts - `pnpm build` - Compile TypeScript to JavaScript - `pnpm inspect` - Run MCP inspector for testing ### Building ```bash pnpm build ``` The build process compiles TypeScript and makes the output executable. ### Testing with MCP Inspector ```bash pnpm inspect ``` This runs the MCP inspector which allows you to test the server interactively. ## 🏛️ Architecture ### MCP Server Implementation The server uses the `@modelcontextprotocol/sdk` v1.20.2 to create a standardized MCP server that: 1. Fetches package metadata from various npm APIs 2. Validates all responses using Zod schemas 3. For README fetching: Extracts the GitHub repository URL and fetches README with branch fallback 4. Returns formatted, structured data with both text and JSON output 5. Supports Resources for application-driven data access 6. Supports Prompts for reusable analysis templates 7. Provides multiple transport options (stdio, HTTP, or both) ### API Endpoints Used - **npm Registry API**: `https://registry.npmjs.org/` - Package metadata, versions, dependencies - **npm Search API**: `https://registry.npmjs.org/-/v1/search` - Package search functionality - **npm Downloads API**: `https://api.npmjs.org/downloads/point/` - Download statistics - **GitHub Raw Content**: `https://raw.githubusercontent.com/` - README file fetching - **Bundlephobia API**: `https://bundlephobia.com/api/size` - Bundle size information - **npms.io API**: `https://api.npms.io/v2/package/` - Quality metrics ### Data Flow ``` Client Request → MCP Server → Multiple APIs (npm, bundlephobia, npms.io, GitHub) ↓ Validation (Zod) ↓ Structured Response (Text + JSON) ``` ### Error Handling The server implements comprehensive error handling: - HTTP errors from all APIs (npm registry, bundlephobia, npms.io, GitHub) - Invalid response structures - GitHub README fetch failures with branch fallback - Network errors and timeouts - Scoped package handling - Missing package or version errors All errors are returned with descriptive messages and proper error flags in both text and structured formats. ### README Fetching with Branch Fallback The server intelligently fetches README files by trying multiple branches in order: 1. Try `main` branch 2. Try `master` branch 3. Try default branch (no branch specification) This ensures maximum compatibility across different repository configurations. ## 🔒 Type Safety The project uses Zod for runtime validation across all tools: ```typescript const NpmRegistryResponseSchema = z.object({ name: z.string(), version: z.string(), description: z.string().optional(), repository: z.object({ type: z.string(), url: z.string(), }), }); ``` This ensures type safety and prevents runtime errors from unexpected API responses across all API endpoints. ## 📦 Dependencies - `@modelcontextprotocol/sdk` - MCP SDK for server implementation - `zod` - Runtime type validation - `express` - HTTP server for HTTP transport mode ## 📦 Supported Package Types This server can query any npm package. Here are examples: - **Regular packages**: `lodash`, `express`, `react` - **Scoped packages**: `@types/node`, `@babel/core`, `@angular/core` - **Specific versions**: All tools support optional version parameters ## 📝 Version History ### Version 2.0.0 (Current) **Major Update** - MCP SDK modernization and new features **New Features:** - ✅ MCP Resources support (4 resources) - ✅ MCP Prompts support (3 prompts) - ✅ HTTP transport mode - ✅ Dual transport mode (stdio + HTTP) - ✅ Package comparison tool - ✅ Bundle size tool (bundlephobia integration) - ✅ Quality metrics (npms.io integration) - ✅ Structured output for all tools - ✅ Modern SDK v1.20.2 with registerTool/Resource/Prompt APIs **Improvements:** - ✅ All tools migrated to `registerTool()` API - ✅ All tools return structured content - ✅ Better error handling and type safety - ✅ Enhanced documentation **Note:** - Removed security checking tool due to unavailable public API for vulnerability data ### Version 1.0.0 **Initial Release** - Complete npm context agent MCP server **Features:** - ✅ README fetching with branch fallback - ✅ Package search functionality - ✅ Version history retrieval - ✅ Dependencies analysis - ✅ Download statistics - ✅ Comprehensive package info - ✅ Scoped package support - ✅ Version-specific queries - ✅ Zod schema validation - ✅ Comprehensive error handling ## 🤝 Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## 📄 License MIT License Copyright (c) 2025 Juan Sebastian Gonzalez See [LICENSE.md](LICENSE.md) for full license text. ## 🙏 Acknowledgments - Built with [Model Context Protocol](https://modelcontextprotocol.io/) - Powered by the npm registry API - README content sourced from GitHub - Quality metrics provided by [npms.io](https://npms.io/) - Bundle size data from [Bundlephobia](https://bundlephobia.com/)