# NPM Registry MCP

> NPM Registry connects your AI agent directly to NPM, the world's largest software package repository. Use this server to search for libraries by keyword or author, check full metadata on any package, or verify specific version details—all without leaving your IDE or chat window.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** npm, javascript, node-js, package-manager, software-registry

## Description

Your AI agent connects you straight to NPM, giving it direct access to the world's biggest software package repository. This server lets you search for libraries, check deep metadata, or verify specific versions—all without having to leave your IDE or chat window and jump through hoops.

**Finding Packages by Search Criteria**
You can run `search_packages` to locate any library using full-text search across the entire repository. You'll need this tool when you know what kind of package you want but don't have a specific name. This function lets you filter results based on multiple qualifiers, like pinning down an author or specifying required keywords that must appear in the description. It also lets you narrow the scope by stability status—you can search only for packages marked as stable releases, skipping all the pre-alpha garbage.

**Inspecting Full Package Details**
The `get_package` tool retrieves the complete metadata dump for any NPM package name you throw at it. This isn't just a quick glance; it provides every piece of information attached to that library entry—the full description, the author list, and all associated build details. If you need to know everything about a package before committing to using it, calling `get_package` is your move.

**Verifying Specific Versions**
When you use `get_package_version`, you're drilling down past the general info to look at exact release cycles. You can pull specific details for any version number of a library, say `v1.2.3`. It also lets you check the current 'latest' release without having to guess what the primary entry point is. This function ensures that you're working with the precise build data you expect.

**Monitoring Registry Status**
If you need to know how healthy the NPM registry instance itself is, run `get_registry_meta`. This tool pulls system-level metrics and status information about the entire database—stuff like its current document count or overall storage size. You use this when you're auditing the environment or just want a quick health check on the source data.

***

**How It Works:**

To get started, just subscribe to this server on Vinkius. Your agent handles the rest. If your organization requires it, you can feed your NPM Read-Only Token into the setup (it's only required if you run into rate limits). After that, all you do is tell your AI client exactly what data point you need—like 'What are the keywords for a stable package written by Google?' or 'Give me the full metadata for React.' Your agent routes that request through the correct tool and sends you the clean data. You'll get accurate results instantly, no manual API calls needed.

## Tools

### get_package
Retrieves the full metadata details for a given NPM package name.

### get_package_version
Gets specific metadata for a defined version or the most recent release of an NPM package.

### get_registry_meta
Provides metrics and status information about the overall NPM registry instance itself.

### search_packages
Searches the entire package repository using qualifiers (like author or keywords) to find relevant libraries.

## Prompt Examples

**Prompt:** 
```
Search for packages related to 'react' with high popularity.
```

**Response:** 
```
I've searched the registry for 'react' with a focus on popularity. Top results include 'react' (the core library), 'react-dom', and 'react-router'. Would you like to see the specific metadata for any of these?
```

**Prompt:** 
```
Get the metadata for the latest version of the 'lodash' package.
```

**Response:** 
```
Fetching the latest version of 'lodash'... The current version is 4.17.21. It has 0 dependencies and is widely used for JavaScript utility functions. I can provide the full list of exported methods if needed.
```

**Prompt:** 
```
What is the current document count in the NPM registry?
```

**Response:** 
```
Checking registry metadata... The NPM registry currently contains over 3.5 million documents with a total database size of approximately 2.4TB. The instance name is 'registry'.
```

## Capabilities

### Find Packages by Search Criteria
Run `search_packages` to locate libraries using full-text search, filtering results by author, keywords, or stability status.

### Inspect Full Package Details
Call `get_package` to retrieve the complete metadata for any NPM package name.

### Verify Specific Versions
Use `get_package_version` to pull exact details or check the current 'latest' release of a library.

### Monitor Registry Status
Run `get_registry_meta` to get system-level information about the NPM registry instance, like its document count and size.

## Use Cases

### Troubleshooting a failed build due to dependency drift
A DevOps engineer notices a build failing because of an outdated library. Instead of manually checking the npm docs, they ask their agent: 'What's the latest stable version for `axios`?' The agent runs `get_package_version`, immediately returning the current release number and confirming if it changed since the last successful build.

### Starting a new feature that requires an obscure library
A developer needs a niche charting utility. They ask their agent to 'Search for high-quality React chart libraries.' The agent runs `search_packages`, filtering results by both 'React' and 'charting,' providing a curated list of options with direct links to the metadata.

### Security review before deploying code
A security researcher needs to validate that a third-party utility package hasn't been abandoned. They run `get_package` on the library name and inspect the full metadata, checking for last updated dates or maintenance score warnings.

### Verifying project scope during initial setup
A junior engineer is setting up a new microservice and needs to know the official package names. They ask their agent to 'What are the core packages for Node.js web servers?' The agent runs `search_packages` with broad qualifiers, giving them a clear starting list.

## Benefits

- Stop context switching. Instead of leaving your IDE to check npmjs.com, you ask your agent to run `get_package` and get the full metadata right in your chat.
- Verify dependencies instantly. Use `search_packages` to find packages based on keywords or authors, narrowing down options much faster than a manual search.
- Audit versions safely. Need to know if version 4.17.21 exists for 'lodash'? Run `get_package_version` and get an immediate answer without guessing.
- Keep track of the system. Use `get_registry_meta` when you need to check the total document count or database size—useful for monitoring internal tooling limits.
- Focus on code, not CLI commands. Your agent handles running complex API calls like `search_packages`, letting you just focus on the next block of code.

## How It Works

The bottom line is: you get structured, up-to-date package data returned to your chat or IDE context immediately.

1. First, subscribe to the NPM Registry server on Vinkius.
2. Next, give your AI client an NPM Read-Only Token (this prevents hitting rate limits).
3. Finally, ask your agent for package data. It runs the necessary tool—like `search_packages` or `get_package`—and returns the raw metadata.

## Frequently Asked Questions

**How do I use search_packages to find a library by author?**
You include an author qualifier in your prompt. For example: 'Search for packages with the author:microsoft.' The agent runs `search_packages` and filters out irrelevant results immediately.

**Which tool should I use to check a package's current version?**
Use `get_package_version`. This is designed specifically for version tracking. It gives you the latest or a specific version number, which is usually all you need.

**Does get_package give me enough info to start coding?**
It provides the full metadata. You'll see dependencies and package descriptions, but remember it gives data; you still have to write the code yourself.

**What does get_registry_meta tell me about NPM?**
This tool reports on the registry instance itself. It shows metrics like the total document count and database size, which is useful for operational monitoring.

**When running `search_packages`, how do I handle rate limiting or ensure reliability?**
You must provide your NPM Read-Only Token when calling `search_packages`. While the service works for public queries, attaching a token drastically reduces your risk of hitting API rate limits. This ensures consistent results across repeated searches.

**Does `get_package` retrieve a package’s full dependency graph?**
The primary metadata returned by `get_package` includes key dependencies, but it doesn't provide a complete, nested dependency graph. If you need the full list of required packages, check the project's documentation or use alternative build tools.

**For complex searches using `search_packages`, what is the correct syntax for combining criteria?**
You combine qualifiers by separating them with commas. For example, to find a package written by 'userA' that also uses 'crypto', you structure your query as: author:userA, keywords:crypto.

**If I use `get_package_version` and the specified version doesn't exist, what error do I receive?**
The tool returns a specific package not found status. Instead of failing entirely, your AI client receives an explicit error code indicating that the requested version could not be located in the registry.

**Can I check the latest version of a package and its dependencies?**
Yes! Use the `get_package_version` tool with the version set to 'latest'. It will return the full metadata including dependencies, scripts, and engine requirements for that specific release.

**How do I search for packages by a specific author or keyword?**
You can use the `search_packages` tool. It supports qualifiers in the text field like 'author:name' or 'keywords:word', and allows you to weight results by quality, popularity, or maintenance.

**Is it possible to get a faster, smaller response for package metadata?**
Yes, when using the `get_package` tool, you can set the `abbreviated` parameter to true. This requests a 'packument' with less data, which is ideal for quick version checks or faster response times.