packagelens-mcp

Advanced and Local Usage

This document collects the deeper, more technical details for contributors and folks running PackageLens MCP locally.

How to Test (local)

Basic smoke test (CLI, no MCP)

• Search: pnpm demo:search -- react debounce hook
• README: pnpm demo:readme -- react
• Info: pnpm demo:info -- react
• Downloads: pnpm demo:downloads -- react week
• Snippet: pnpm demo:snippet -- react

You should see JSON/text output with package lists, README content, weekly downloads, and an extracted snippet.

Demo CLI (no MCP)

A tiny CLI is included to try functionality directly during development.

Search

npx -y packagelens-mcp@latest --help
# Or try a standalone search via the built-in demo commands in this
# repo (dev only)
pnpm demo:search -- react debounce hook

# Version pinning guidance
# - Latest (moving): use @latest
# - Major pin: packagelens-mcp@0 (gets newest 0.x)
# - Minor pin: packagelens-mcp@0.1 (newest 0.1.x)
# - Exact: packagelens-mcp@0.1.3
# Tip: check the current version with
# `npm view packagelens-mcp version`.

Fetch README

pnpm demo:readme -- react
pnpm demo:readme -- lodash 4.17.21

Enriched info (downloads + GitHub)

pnpm demo:info -- react

Downloads

pnpm demo:downloads -- react week

Usage snippet

pnpm demo:snippet -- react

Tool Schemas

PackageLens MCP provides 8 tools with automatic ecosystem detection. All tools use smart detection to automatically determine the package ecosystem from context. When ecosystem cannot be determined, tools ask for user clarification.

Smart Search

smart_search

• input: { query: string, packageName?: string, size?: number (1-250) }
• output: { searchedEcosystems: string[], results: Array<{ ecosystem, name, version, description?, downloads?, repository?, homepage?, stars?, forks?, license? }> }
• auto-detection: Uses context keywords (Python, Rust, JavaScript) and package name patterns
• if no context: asks user to specify language/ecosystem
• example: { query: "Find Python HTTP clients", size: 10 }
• example: { query: "http clients" } → asks for clarification

Package Information

smart_package_info

• input: { packageName: string, context?: string, includeReadme?: boolean }
• output: { ecosystem, name, version?, repository?, homepage?, github?: { fullName, url, stars?, forks?, license? }, downloads?: number, readme?: string }
• auto-detects ecosystem from package name and context
• example: { packageName: "react" } → detects npm
• example: { packageName: "django", context: "Python web framework" } → detects pypi

smart_get_readme

• input: { packageName: string, context?: string, version?: string, truncateAt?: number }
• output: two contents
  • json content: { ecosystem, name, version?, repository?, homepage? }
  • text content: README markdown (possibly truncated)
• auto-detects ecosystem from package name and context
• example: { packageName: "django" } → detects pypi

smart_get_usage_snippet

• input: { packageName: string, context?: string, version?: string }
• output: { ecosystem, name, version?, snippet?: { language?, code, heading? } }
• auto-detects ecosystem from package name and context
• example: { packageName: "axios" } → detects npm

Version & Dependency Analysis

smart_get_versions

• input: { packageName: string, context?: string, limit?: number, since?: string }
• output: { ecosystem, name, versions: Array<{ version: string, date: string, tags?: string[] }> }
• since formats: ISO date ("2024-01-01T00:00:00.000Z") or relative ("6 months", "1 year", "30 days")
• auto-detects ecosystem from package name and context
• example: { packageName: "tokio", limit: 10, since: "6 months" } → detects crates

smart_get_dependencies

• input: { packageName: string, context?: string, version?: string }
• output: { ecosystem, name, version, dependencies: Array<{ name: string, version: string }>, devDependencies?: Array<{ name: string, version: string }> }
• auto-detects ecosystem from package name and context
• example: { packageName: "express" } → detects npm

Download Statistics

smart_get_downloads

• input: { packageName: string, context?: string, period?: 'day'|'week'|'month' }
• output: { ecosystem, name, period, downloads?: number }
• auto-detects ecosystem from package name and context
• note: Availability varies by ecosystem (PyPI has no official API)
• example: { packageName: "react", period: "week" } → detects npm

Comparison

compare_packages

• input: { items: Array<{ ecosystem: string, name: string }> (1-10 items) }
• output: Array<{ ecosystem, name, version?, description?, downloads?, stars?, forks?, license?, repository?, homepage?, error?: string }>
• fetches all packages in parallel; errors returned per-package in error field
• example: { items: [{ ecosystem: "npm", name: "react" }, { ecosystem: "pypi", name: "django" }] }

Example MCP Messages (stdio)

Initialize

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "clientInfo": { "name": "demo", "version": "0.0.0" },
    "capabilities": {}
  }
}

List tools

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Call smart_search

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "smart_search",
    "arguments": { "query": "Find JavaScript debounce hooks", "size": 10 }
  }
}

Call smart_get_readme

{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "smart_get_readme",
    "arguments": { "packageName": "react" }
  }
}

Call smart_package_info

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "smart_package_info",
    "arguments": { "packageName": "react", "includeReadme": false }
  }
}

Call smart_get_versions

{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "smart_get_versions",
    "arguments": {
      "packageName": "react",
      "limit": 10,
      "since": "6 months"
    }
  }
}

Call smart_get_dependencies

{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "smart_get_dependencies",
    "arguments": { "packageName": "express" }
  }
}

Call smart_get_downloads

{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "smart_get_downloads",
    "arguments": { "packageName": "react", "period": "week" }
  }
}

Call compare_packages

{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "compare_packages",
    "arguments": {
      "items": [
        { "ecosystem": "npm", "name": "react" },
        { "ecosystem": "npm", "name": "vue" },
        { "ecosystem": "npm", "name": "svelte" }
      ]
    }
  }
}

Troubleshooting

• ESM import errors: ensure Node 18.17+ and that you ran pnpm build (or use pnpm dev).
• GitHub details missing: likely hitting unauthenticated rate limits; set GITHUB_TOKEN.
• Network or rate limit errors: retry, reduce requests, or increase cache TTL.
• MCP client cannot find the server: confirm absolute path to dist/index.js and correct permissions.

Development

• Format/lint/typecheck: pnpm lint
• Tests: pnpm test (100% coverage enforced via pnpm coverage)
• Pre-commit hooks: Husky + lint-staged run typecheck, ESLint and related tests on staged files

Security notes

• Inputs are validated by JSON Schema at the tool boundary; additional checks are in handlers.
• In-memory caching with TTL reduces request volume; adjust CACHE_TTL_MS/CACHE_MAX via env.
• GitHub API usage is optional; set GITHUB_TOKEN to raise rate limits.
• Only communicates with trusted package registries (npm, PyPI, RubyGems, Crates.io, Packagist, Hex) and GitHub API, no arbitrary URL fetching.

Roadmap

• Add more filters (types, TS typings, keywords) for search.
• Support sorting by downloads/stars client-side.
• Add persistent cache or Etags for READMEs.
• Tests for search mapping and snippet extraction.

This site is open source. Improve this page.