MCP 服务器

pkg-peep

Enables querying NPM package download statistics, metadata, and dependency information through natural language.

README

pkg-peep 👀

A Model Context Protocol (MCP) server for NPM package intelligence. Get download statistics, package metadata, and dependency information for any NPM package.

How It Works

This MCP server exposes NPM registry APIs as tools that Q CLI and Claude can use:

MCP Protocol: Server communicates with AI clients via Model Context Protocol
Tool Registration: NPM API endpoints become callable tools
No Authentication: Uses public NPM APIs (no API key required)
JSON Responses: All package data returned as formatted JSON

pkg-peep MCP Architecture

%%{init: {'flowchart': {'curve': 'basis'}}}%%
graph LR
    A["💻<br/>Q CLI"] -.-> B["🔌<br/>MCP Server"]
    C["💻<br/>Claude Code"] -.-> B
    B <--> D["📦<br/>NPM Registry API"]
    B <--> E["📊<br/>NPM Downloads API"]
    
    style A fill:#6366f1,stroke:#000,stroke-width:3px,color:#fff
    style C fill:#ff9900,stroke:#000,stroke-width:3px,color:#000
    style B fill:#C11C84,stroke:#000,stroke-width:3px,color:#fff
    style D fill:#cb3837,stroke:#000,stroke-width:3px,color:#fff
    style E fill:#10b981,stroke:#000,stroke-width:3px,color:#000

When you ask Q CLI or Claude Code to "get download stats for react", it:

Calls the get_npm_downloads tool
Server makes API request to NPM Downloads API
Returns formatted results to the AI client
The agent presents the data to you in context

Features

📊 Download Statistics - Weekly, monthly, daily, or custom date ranges
📦 Package Metadata - Versions, dependencies, maintainers, license info
🔍 Comprehensive Info - Repository links, keywords, creation dates
⚡ Fast & Reliable - Direct NPM registry API integration
🔑 No API Key Required - Uses public NPM APIs

Tools

`get_npm_downloads`

Get download statistics for any NPM package.

Parameters:

package (required): NPM package name
period (optional): last-day, last-week, last-month
startDate (optional): Custom start date (YYYY-MM-DD)
endDate (optional): Custom end date (YYYY-MM-DD)

Example Response:

{
  "downloads": 50766634,
  "start": "2025-08-27",
  "end": "2025-09-02", 
  "package": "react"
}

`get_npm_package_info`

Get comprehensive package metadata.

Parameters:

package (required): NPM package name

Example Response:

{
  "name": "react",
  "description": "React is a JavaScript library for building user interfaces.",
  "latest": "19.1.1",
  "license": "MIT",
  "homepage": "https://react.dev/",
  "repository": {
    "url": "git+https://github.com/facebook/react.git",
    "type": "git"
  },
  "maintainers": [
    {"name": "fb", "email": "opensource+npm@fb.com"}
  ],
  "dependencies": {...},
  "created": "2011-10-26T17:46:21.942Z"
}

Installation

For Amazon Q CLI

Clone or download this repository
Install dependencies:
```
npm install
```
The MCP server is ready to use with Q CLI's MCP support

For Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "pkg-peep": {
      "command": "node",
      "args": ["/path/to/pkg-peep/index.js"]
    }
  }
}

Using NPX (Recommended)

{
  "mcpServers": {
    "pkg-peep": {
      "command": "npx",
      "args": ["-y", "pkg-peep"]
    }
  }
}

Usage Examples

Get weekly downloads:

Get download stats for "react" package

Custom date range:

Get download stats for "lodash" from 2024-01-01 to 2024-12-31

Package information:

Get package info for "express"

Testing

Run the test suite to verify everything works:

npm test

The tests verify:

✅ Tool registration (both download and package info tools)
✅ Download stats for popular packages
✅ Different time periods (daily, weekly, monthly)
✅ Package metadata retrieval
✅ Custom date ranges
✅ Error handling for non-existent packages

📋 Example Prompts >> - Try these sample queries to test your MCP!

Development

# Install dependencies
npm install

# Run the server
node index.js

# Test with a simple request
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node index.js