@pkgseer/cli 0.1.0-alpha.3 → 0.1.1

package/LICENSE

@@ -20,3 +20,4 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+

package/README.md

@@ -2,67 +2,47 @@
 
 CLI and MCP server for [PkgSeer](https://pkgseer.dev) — package intelligence for developers and AI assistants.
 
-Query package metadata, security vulnerabilities, dependencies, and quality metrics across npm and PyPI registries.
+Get insights about packages across npm, PyPI, and Hex registries: metadata, security vulnerabilities, dependencies, and quality metrics. Works standalone or as an MCP server for AI assistants like Claude and Cursor.
 
 ## Installation
 
-```bash
-# Run directly with npx (no install needed)
-npx @pkgseer/cli
+The easiest way to get started is using npx — no installation required:
 
-# Or install globally
-npm install -g @pkgseer/cli
+```bash
+npx @pkgseer/cli --help
 ```
 
-## Quick Start
+For frequent use, install globally:
 
 ```bash
-# Authenticate (optional, for higher rate limits)
-pkgseer login
-
-# Start MCP server for AI assistants
-pkgseer mcp
+npm install -g @pkgseer/cli
 ```
 
-## CLI Commands
+## Getting Started
 
-```bash
-pkgseer --help           # Show all commands
-pkgseer --version        # Show version
+### 1. Authenticate (Recommended)
 
-pkgseer login            # Authenticate with PkgSeer
-pkgseer logout           # Clear stored credentials
-pkgseer auth status      # Check authentication status
+While you can use PkgSeer without authentication, logging in gives you higher rate limits and access to all features:
 
-pkgseer mcp              # Start MCP server
+```bash
+pkgseer login
 ```
 
-## MCP Server
-
-The MCP (Model Context Protocol) server exposes package intelligence tools to AI assistants like Claude, Cursor, and others.
-
-### Available Tools
+This opens your browser to authenticate with your PkgSeer account. Your credentials are stored securely in `~/.pkgseer/`.
 
-| Tool | Description |
-|------|-------------|
-| `package_summary` | Package metadata, versions, security advisories, quickstart info |
-| `package_vulnerabilities` | Security vulnerabilities affecting a package |
-| `package_dependencies` | Direct and transitive dependency tree |
-| `package_quality` | Quality metrics and scores |
-| `compare_packages` | Side-by-side comparison of multiple packages |
+To check your authentication status:
 
-All tools support both `npm` and `pypi` registries.
+```bash
+pkgseer auth status
+```
 
-### Configuration
+### 2. Use with AI Assistants
 
-| Environment Variable | Default | Description |
-|---------------------|---------|-------------|
-| `PKGSEER_API_URL` | `https://pkgseer.dev/api/graphql` | API endpoint |
-| `PKGSEER_API_TOKEN` | — | Authentication token (from `pkgseer login`) |
+The main use case for this CLI is as an MCP (Model Context Protocol) server that gives AI assistants access to package intelligence.
 
-### Cursor Integration
+#### Cursor IDE
 
-Add to `.cursor/mcp.json`:
+Add this to your `.cursor/mcp.json` file:
 
 ```json
 {
@@ -75,9 +55,12 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-### Claude Desktop Integration
+#### Claude Desktop
+
+Add this to your Claude Desktop configuration file:
 
-Add to Claude Desktop config:
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -90,17 +73,56 @@ Add to Claude Desktop config:
 }
 ```
 
-## Authentication
+Once configured, your AI assistant can use tools to answer questions like:
 
-Authentication is optional but recommended for higher rate limits.
+- "What security vulnerabilities does lodash have?"
+- "Compare react vs preact vs solid-js"
+- "What are the dependencies of express?"
+
+#### Prompt for AI Assistants
+
+To help your AI assistant use PkgSeer proactively, add this to your project rules (`.cursor/rules`, `AGENTS.md`, or similar):
+
+```markdown
+When working with dependencies:
+
+- Use PkgSeer MCP tools to check for security vulnerabilities before adding new packages
+- Compare package alternatives with compare_packages when multiple options exist
+- Review package quality metrics to ensure dependencies are well-maintained
+```
+
+## Available Tools
+
+When running as an MCP server, the following tools are available to AI assistants:
+
+| Tool                      | What it does                                                                        |
+| ------------------------- | ----------------------------------------------------------------------------------- |
+| `package_summary`         | Get package metadata, latest versions, security advisories, and quickstart examples |
+| `package_vulnerabilities` | Find known security vulnerabilities affecting a package                             |
+| `package_dependencies`    | Explore the dependency tree (direct and transitive)                                 |
+| `package_quality`         | View quality metrics and maintenance scores                                         |
+| `compare_packages`        | Compare multiple packages side-by-side                                              |
+
+All tools work with **npm**, **PyPI**, and **Hex** registries.
+
+## CLI Commands
 
 ```bash
-# Opens browser for OAuth login
-pkgseer login
+pkgseer --help           # Show all available commands
+pkgseer --version        # Show version number
 
-# Credentials stored in ~/.pkgseer/
+pkgseer login            # Authenticate with your PkgSeer account
+pkgseer logout           # Sign out and clear stored credentials
+pkgseer auth status      # Check if you're logged in and token validity
+
+pkgseer mcp              # Start the MCP server (for AI assistant integration)
 ```
 
+## Need Help?
+
+- Visit [pkgseer.dev](https://pkgseer.dev) for documentation
+- Report issues on [GitHub](https://github.com/pkgseer/pkgseer-cli/issues)
+
 ## License
 
 MIT © [Juha Litola](https://github.com/pkgseer)