@lpm-registry/mcp-server 0.2.0 → 0.3.0

package/README.md

@@ -12,7 +12,9 @@ lpm mcp setup
 
 This auto-detects Claude Code, Cursor, VS Code, Claude Desktop, and Windsurf, then writes the correct config to each. Authentication is handled via `lpm login` (stored in your OS keychain) — no tokens in config files.
 
-If your CLI is configured to use a custom registry URL (for example local dev), `lpm mcp setup` automatically writes `LPM_REGISTRY_URL` into MCP config so editor-launched MCP processes hit the same registry.
+The generated command is `npx -y @lpm-registry/mcp-server@latest`. The `latest` dist-tag is resolved when the editor starts, so editor restarts pick up the current published MCP server release.
+
+For a custom registry, set `LPM_REGISTRY_URL` in the environment inherited by your editor or add it to the editor's MCP server environment configuration.
 
 ## Manual Setup
 
@@ -72,9 +74,9 @@ If you prefer manual configuration, add to your editor's MCP config:
 
 ## Authentication
 
-The server reads your token from the OS keychain (set by `lpm login`). No token in config files required.
+`LPM_TOKEN` has highest priority. When it is unset, the server reads the OS keychain entry created by `lpm login` for the effective registry URL. Credentials are registry-scoped, so hosted, local, and custom registries do not reuse one another's tokens.
 
-Alternatively, set the `LPM_TOKEN` environment variable for environments without keychain access:
+Set `LPM_TOKEN` explicitly for environments without keychain access:
 
 ```bash
 export LPM_TOKEN=lpm_your_token_here
@@ -92,40 +94,25 @@ For local development, copy `.env.example` to `.env.local` and set your local re
 
 ## Available Tools
 
-| Tool                      | Description                                                     | Auth Required |
-| ------------------------- | --------------------------------------------------------------- | ------------- |
-| `lpm_search`              | Search packages with natural language or structured filters     | Optional      |
-| `lpm_package_info`        | Get package metadata, install method, access model, and readme  | Optional      |
-| `lpm_api_docs`            | Get structured API docs — functions, classes, types, signatures | Optional      |
-| `lpm_llm_context`         | Get LLM-optimized usage guide — quickStart, patterns, gotchas   | Optional      |
-| `lpm_package_context`     | Get complete package context in one call (pre-install evaluation) | Optional    |
-| `lpm_package_skills`      | Get Agent Skills for building with an installed package         | Optional      |
-| `lpm_docs`                | Search or read LPM documentation (setup, CLI, publishing, etc.) | No           |
-| `lpm_browse_source`       | Browse package source code remotely (last resort)               | Yes           |
-| `lpm_add`                 | Add a package by extracting source files into the project       | Yes           |
-| `lpm_install`             | Install a managed dependency (JS → node_modules, Swift → Package.swift) | Yes  |
-| `lpm_audit`               | Security audit — behavioral tags, AI findings, quality scores   | Yes           |
-| `lpm_marketplace_info`    | Marketplace pricing, licensing, and seat management             | Optional      |
-| `lpm_quality_report`      | Get quality score and 28-check breakdown                        | Optional      |
-| `lpm_search_owners`       | Search for users or organizations by name                       | No            |
-| `lpm_packages_by_owner`   | List packages published by a specific user or org               | No            |
-| `lpm_pool_stats`          | Get your Pool revenue earnings for the current month            | Yes           |
-| `lpm_user_info`           | Get authenticated user info, orgs, and usage                    | Yes           |
-
-## AI Workflow
-
-A typical AI agent workflow for finding and adding a package:
-
-1. **Search** — `lpm_search` to find packages matching the need
-2. **Evaluate** — `lpm_package_context` to understand the package before installing (metadata, API docs, usage guide)
-3. **Install** — `lpm_install` for managed dependencies (JS + Swift) or `lpm_add` for source components
-4. **Build** — `lpm_package_skills` for usage patterns, then read local files directly
-
-The `lpm_package_context` response includes `package.installMethod.command` (`lpm add` or `lpm install`) so agents know which tool to use.
-
-> **Tip:** After installing, prefer reading local files over `lpm_browse_source`. Local reads are faster and don't hit the server. Use `lpm_browse_source` only when evaluating a package you can't install (e.g., checking before purchase).
-
-> **Version resolution:** Version-sensitive tools (`lpm_api_docs`, `lpm_llm_context`, `lpm_package_context`, `lpm_package_skills`, `lpm_browse_source`) resolve the version from the local project's package.json dependencies when no explicit version is specified. This ensures you get docs matching the version you actually have installed.
+| Tool                    | Description                                                             | Auth     | Cache |
+| ----------------------- | ----------------------------------------------------------------------- | -------- | ----- |
+| `lpm_search`            | Search packages with natural language or structured filters             | Optional | 5m    |
+| `lpm_package_info`      | Get package metadata, install method, access model, and readme          | Optional | 5m    |
+| `lpm_api_docs`          | Get structured API docs — functions, classes, types, signatures         | Optional | 5m    |
+| `lpm_llm_context`       | Get LLM-optimized usage guide — quickStart, patterns, gotchas           | Optional | 5m    |
+| `lpm_package_context`   | Get complete package context in one call (pre-install evaluation)       | Optional | 5m    |
+| `lpm_package_skills`    | Get Agent Skills for building with an installed package                 | Optional | 5m    |
+| `lpm_docs`              | Search or read LPM documentation (setup, CLI, publishing, etc.)         | No       | 30m   |
+| `lpm_browse_source`     | Browse package source code remotely (last resort)                       | Yes      | 5m    |
+| `lpm_add`               | Add a package by extracting source files into the project               | Yes      | —     |
+| `lpm_install`           | Install a managed dependency (JS → node_modules, Swift → Package.swift) | Yes      | —     |
+| `lpm_audit`             | Security audit — behavioral tags, AI findings, quality scores           | Yes      | —     |
+| `lpm_marketplace_info`  | Marketplace pricing, licensing, and seat management                     | Optional | 5m    |
+| `lpm_quality_report`    | Get quality score and 28-check breakdown                                | Optional | 5m    |
+| `lpm_search_owners`     | Search for users or organizations by name                               | No       | 5m    |
+| `lpm_packages_by_owner` | List packages published by a specific user or org                       | No       | 5m    |
+| `lpm_pool_stats`        | Get your Pool revenue earnings for the current month                    | Yes      | 1h    |
+| `lpm_user_info`         | Get authenticated user info, orgs, and usage                            | Yes      | 5m    |
 
 ### Access Control
 
@@ -133,582 +120,6 @@ The `lpm_package_context` response includes `package.installMethod.command` (`lp
 - **Marketplace packages** require a license purchase. Errors include a link to the package page.
 - **Public metadata** (`lpm_package_info`, `lpm_search`, `lpm_quality_report`) works without auth for public packages.
 
-## Tool Details
-
-### lpm_search
-
-Search LPM packages using natural language or structured filters. Uses hybrid semantic search for natural language queries, and the explore API when structured filters are active.
-
-**Parameters:**
-
-- `query` (string, optional) — Natural language search query (required unless `category` is provided)
-- `category` (string, optional) — Package category filter (e.g., `ui-components`, `tools`)
-- `ecosystem` (enum, optional) — Filter by ecosystem: `js`, `swift`, or `xcframework`
-- `distribution` (enum, optional) — Filter by distribution mode: `marketplace`, `pool`, or `private`
-- `packageType` (enum, optional) — Filter by type: `package`, `source`, `mcp-server`, `vscode-extension`, `cursor-rules`, `github-action`, `xcframework`, `other`
-- `sort` (enum, optional) — Sort order: `newest`, `popular`, or `name`
-- `hasTypes` (boolean, optional) — Filter to packages with TypeScript type definitions
-- `moduleType` (enum, optional) — Filter by module type: `esm`, `cjs`, or `dual`
-- `license` (enum, optional) — Filter by license: `MIT`, `Apache-2.0`, `ISC`, `GPL-3.0`, `BSD-3-Clause`, `Unlicense`
-- `minNodeVersion` (enum, optional) — Filter to packages supporting Node.js `18`, `20`, or `22`+
-- `limit` (number, optional) — Max results, 1-50 (default: 10)
-
-At least one of `query` or `category` is required.
-
-**Example response:**
-
-```
-Found 2 packages:
-
-- alice.ui-kit [source] (pool) — React UI components (5,000 downloads)
-  Quality: 88 | Category: ui-components | Tags: react, components
-- bob.form-builder (marketplace) — Form builder library (1,200 downloads)
-```
-
-### lpm_package_info
-
-Get metadata for an LPM package including versions, description, downloads, install method, access status, and readme.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/alice.ui-kit",
-  "description": "A modern UI component kit for React",
-  "ecosystem": "js",
-  "latestVersion": "2.1.0",
-  "totalVersions": 12,
-  "versions": ["2.1.0", "2.0.0", "1.9.0"],
-  "downloads": 5400,
-  "createdAt": "2024-01-15T10:30:00Z",
-  "updatedAt": "2025-11-20T14:00:00Z",
-  "dependencies": ["react", "react-dom"],
-  "readme": "# UI Kit\n\nA modern component library...",
-  "distributionMode": "pool",
-  "hasAccess": true,
-  "installMethod": {
-    "command": "lpm add",
-    "description": "Extracts source files into your project for customization."
-  },
-  "accessInfo": {
-    "model": "pool",
-    "summary": "Included with Pool subscription ($12/mo)",
-    "actionRequired": false
-  }
-}
-```
-
-### lpm_api_docs
-
-Get structured API documentation for an LPM package. Returns functions, classes, interfaces, type aliases, enums, and variables with full signatures, parameter types, return types, and descriptions. Use this to understand how to use a package before installing it.
-
-API docs are auto-generated during publish from TypeScript definitions, AI analysis, or JSDoc annotations.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-- `version` (string, optional) — Specific version to get docs for (defaults to latest)
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/alice.ui-kit",
-  "version": "2.1.0",
-  "available": true,
-  "docsStatus": "extracted",
-  "apiDocs": {
-    "version": 1,
-    "strategy": "typescript",
-    "entryPoint": "dist/index.d.ts",
-    "modules": [
-      {
-        "path": "index",
-        "functions": [
-          {
-            "name": "createTheme",
-            "description": "Create a custom theme configuration",
-            "signatures": [
-              {
-                "params": [
-                  { "name": "options", "type": "ThemeOptions", "optional": true }
-                ],
-                "returnType": "Theme",
-                "typeParams": []
-              }
-            ]
-          }
-        ],
-        "interfaces": [
-          {
-            "name": "ThemeOptions",
-            "description": "Configuration for theme creation",
-            "properties": [
-              { "name": "colors", "type": "ColorPalette", "optional": true },
-              { "name": "spacing", "type": "SpacingScale", "optional": true }
-            ]
-          }
-        ],
-        "classes": [],
-        "typeAliases": [],
-        "enums": [],
-        "variables": []
-      }
-    ],
-    "stats": {
-      "functionCount": 5,
-      "classCount": 2,
-      "interfaceCount": 8,
-      "totalExports": 18
-    }
-  }
-}
-```
-
-**When docs aren't available:**
-
-```json
-{
-  "name": "@lpm.dev/bob.utils",
-  "version": "1.0.0",
-  "available": false,
-  "docsStatus": "pending",
-  "message": "API docs are being generated. Try again in a few minutes."
-}
-```
-
-### lpm_llm_context
-
-Get an LLM-optimized usage guide for an LPM package. Returns a concise cheat sheet with purpose, quickStart code, key exports with signatures, common usage patterns, gotchas, and guidance on when to use the package. Use this to quickly understand how to write correct code with a package.
-
-LLM context is auto-generated during publish using AI analysis of the package's API docs, source code, and readme.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-- `version` (string, optional) — Specific version to get context for (defaults to latest)
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/alice.ui-kit",
-  "version": "2.1.0",
-  "available": true,
-  "llmContextStatus": "extracted",
-  "llmContext": {
-    "version": 1,
-    "purpose": "React UI component library with theme support and accessibility built-in",
-    "quickStart": "import { Button, Input } from '@lpm.dev/alice.ui-kit'\n\n<Button variant=\"primary\">Click me</Button>",
-    "keyExports": [
-      {
-        "name": "Button",
-        "kind": "component",
-        "signature": "(props: ButtonProps) => JSX.Element",
-        "description": "Primary button component with variants and loading state"
-      },
-      {
-        "name": "createTheme",
-        "kind": "function",
-        "signature": "(options?: ThemeOptions) => Theme",
-        "description": "Create a custom theme configuration"
-      }
-    ],
-    "commonPatterns": [
-      {
-        "title": "Basic button with loading state",
-        "code": "<Button isLoading={isPending} onClick={handleSubmit}>Save</Button>",
-        "description": "Use isLoading prop to show spinner during async operations"
-      }
-    ],
-    "gotchas": [
-      "Requires React 18+ as peer dependency",
-      "Theme must be wrapped in ThemeProvider at app root"
-    ],
-    "whenToUse": "Building React apps that need consistent, accessible UI components with theme support",
-    "whenNotToUse": "Server-rendered pages without React, or when you need only a single component"
-  }
-}
-```
-
-**When context isn't available:**
-
-```json
-{
-  "name": "@lpm.dev/bob.utils",
-  "version": "1.0.0",
-  "available": false,
-  "llmContextStatus": "pending",
-  "message": "LLM context is being generated. Try again in a few minutes."
-}
-```
-
-### lpm_package_context
-
-Get complete context for an LPM package in a single call. Combines condensed package metadata, structured API documentation, LLM-optimized usage guide, and Agent Skills. This is the recommended tool when you need to understand a package before using it.
-
-Internally makes 4 parallel API calls. If API docs or LLM context aren't available yet (still being generated), they are omitted from the response. Only fails if the package itself is not found or inaccessible.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-- `version` (string, optional) — Specific version to get context for (defaults to latest)
-
-**Example response (all available):**
-
-```json
-{
-  "package": {
-    "name": "@lpm.dev/alice.ui-kit",
-    "description": "A modern UI component kit for React",
-    "ecosystem": "js",
-    "latestVersion": "2.1.0",
-    "license": "MIT",
-    "dependencies": ["react", "react-dom"],
-    "peerDependencies": [],
-    "installMethod": {
-      "command": "lpm add",
-      "description": "Extracts source files into your project for customization"
-    },
-    "distributionMode": "pool",
-    "readme": "# UI Kit\n\nA modern component library for building..."
-  },
-  "apiDocs": {
-    "version": 1,
-    "strategy": "typescript",
-    "modules": [
-      {
-        "path": "index",
-        "functions": [{ "name": "createTheme", "description": "Create a custom theme" }]
-      }
-    ]
-  },
-  "llmContext": {
-    "version": 1,
-    "purpose": "React UI component library with theme support",
-    "quickStart": "import { Button } from '@lpm.dev/alice.ui-kit'",
-    "keyExports": [{ "name": "Button", "kind": "component" }],
-    "commonPatterns": [],
-    "gotchas": ["Requires React 18+"],
-    "whenToUse": "Building React apps with consistent UI"
-  }
-}
-```
-
-When API docs, LLM context, or skills aren't available, those keys are simply omitted. Only the `package` key is always present. The readme is truncated to ~500 characters — use `lpm_package_info` for the full readme.
-
-### lpm_package_skills
-
-Fetch Agent Skills for an LPM package. Returns approved skills with their name, description, applicable file globs, and content. Skills are markdown files that provide workflow-specific instructions for AI coding assistants.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-- `version` (string, optional) — Specific version to get skills for (defaults to latest)
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/alice.ui-kit",
-  "version": "2.1.0",
-  "skills": [
-    {
-      "name": "theming",
-      "description": "How to create and apply custom themes",
-      "globs": ["**/*.theme.*", "**/*.styles.*"],
-      "content": "# Theming\n\nWhen creating a custom theme..."
-    }
-  ]
-}
-```
-
-### lpm_browse_source
-
-Browse source code of an LPM package you have access to. Call without `path` to get the file tree, then request specific files or directories.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` or `@lpm.dev/owner.package-name` format
-- `version` (string, optional) — Specific version to browse (defaults to latest)
-- `path` (string, optional) — File or directory path (e.g., `src/index.js` or `src`). Omit for tree only.
-
-**Example response (tree only):**
-
-```json
-{
-  "package": "alice.ui-kit",
-  "version": "2.0.0",
-  "ecosystem": "js",
-  "tree": ["src/index.js", "src/button.jsx", "src/input.jsx", "package.json"]
-}
-```
-
-**Example response (with path):**
-
-```json
-{
-  "package": "alice.ui-kit",
-  "version": "2.0.0",
-  "ecosystem": "js",
-  "tree": ["src/index.js", "src/button.jsx", "src/input.jsx", "package.json"],
-  "files": [
-    { "path": "src/button.jsx", "content": "export function Button() { ... }" }
-  ]
-}
-```
-
-### lpm_add
-
-Add an LPM package to the project by extracting source files for customization. Use for UI components, blocks, templates, and MCP servers. Requires LPM CLI installed locally.
-
-**Parameters:**
-
-- `name` (string, required) — Package name
-- `version` (string, optional) — Specific version (defaults to latest)
-- `path` (string, optional) — Target directory (e.g., `src/components/ui`)
-- `alias` (string, optional) — Import alias prefix (e.g., `@/components/ui`)
-- `target` (string, optional) — Swift SPM target name
-- `force` (boolean, optional) — Overwrite existing files
-- `installDeps` (boolean, optional) — Auto-install npm deps (default: true)
-- `config` (object, optional) — Config schema params (e.g., `{ "styling": "panda" }`)
-
-**Example response:**
-
-```json
-{
-  "success": true,
-  "package": { "name": "@lpm.dev/alice.ui-kit", "version": "2.0.0" },
-  "installPath": "src/components/ui",
-  "files": [
-    { "dest": "src/components/ui/button.jsx", "action": "created" },
-    { "dest": "src/components/ui/input.jsx", "action": "created" }
-  ],
-  "dependencies": { "npm": ["react"], "lpm": [] }
-}
-```
-
-### lpm_install
-
-Install an LPM package as a managed dependency. JS packages go to node_modules, Swift packages edit Package.swift via SE-0292. Requires LPM CLI installed locally.
-
-**Parameters:**
-
-- `name` (string, required) — Package name
-- `version` (string, optional) — Specific version (defaults to latest)
-
-**Example response:**
-
-```json
-{
-  "success": true,
-  "packages": [{ "name": "@lpm.dev/bob.validate" }],
-  "npmOutput": "added 1 package in 1s"
-}
-```
-
-### lpm_audit
-
-Run a security audit on the project's LPM dependencies. Returns behavioral tags (eval, childProcess, shell), AI security findings, quality scores, and lifecycle scripts.
-
-**Parameters:**
-
-- `path` (string, optional) — Project directory to audit (defaults to current directory)
-
-**Example response:**
-
-```json
-{
-  "success": true,
-  "totalPackages": 3,
-  "packagesWithIssues": 1,
-  "packages": [
-    {
-      "name": "@lpm.dev/alice.ui-kit",
-      "version": "2.0.0",
-      "qualityScore": 85,
-      "issues": []
-    },
-    {
-      "name": "@lpm.dev/bob.exec-tool",
-      "version": "1.0.0",
-      "qualityScore": 45,
-      "issues": ["uses child_process", "[moderate] Executes shell commands with user input"]
-    }
-  ]
-}
-```
-
-### lpm_marketplace_info
-
-Get marketplace information for an LPM package — pricing, licensing, seat management, and purchase status.
-
-**Parameters:**
-
-- `name` (string, required) — Package name
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/acme.pro-suite",
-  "isMarketplace": true,
-  "distributionMode": "marketplace",
-  "pricing": { "monthlyPriceCents": 2900, "yearlyPriceCents": 29000 },
-  "licenseType": "per-seat",
-  "accessInfo": { "hasLicense": true, "seatsUsed": 3, "seatsTotal": 5 }
-}
-```
-
-### lpm_docs
-
-Search or read LPM documentation. Use when the user asks how to use LPM itself.
-
-**Parameters:**
-
-- `page` (string, optional) — Doc page slug (e.g., `cli/commands`, `packages/swift-registry`)
-- `query` (string, optional) — Search query (e.g., `npmrc`, `CI deployment`)
-
-Without parameters: returns the full docs index.
-
-### lpm_quality_report
-
-Get the quality score and detailed check breakdown for an LPM package. Covers 28 checks across documentation, code quality, testing, and maintenance health.
-
-**Parameters:**
-
-- `name` (string, required) — Package name in `owner.package-name` format
-
-**Example response:**
-
-```json
-{
-  "name": "@lpm.dev/alice.ui-kit",
-  "score": 85,
-  "maxScore": 100,
-  "tier": "good",
-  "categories": [
-    { "name": "documentation", "score": 22, "maxScore": 25 },
-    { "name": "code", "score": 28, "maxScore": 30 }
-  ],
-  "checks": [
-    { "id": "has-readme", "passed": true, "points": 10, "maxPoints": 10 }
-  ]
-}
-```
-
-### lpm_search_owners
-
-Search for users or organizations on the LPM registry by name or username.
-
-**Parameters:**
-
-- `query` (string, required) — Name or username to search for
-- `limit` (number, optional) — Max results, 1-10 (default: 5)
-
-**Example response:**
-
-```
-Found 2 profiles:
-
-- @alice (Alice Smith) [user] — Full-stack developer
-- @acme (Acme Corp) [org] — Open source tools for developers
-```
-
-### lpm_packages_by_owner
-
-List packages published by a specific user or organization. Shows only public (pool/marketplace) packages.
-
-**Parameters:**
-
-- `owner` (string, required) — Username or organization slug
-- `limit` (number, optional) — Max results, 1-50 (default: 10)
-
-**Example response:**
-
-```
-Found 2 packages by alice:
-
-- alice.ui-kit [pool] — A modern UI component kit for React (5,400 downloads)
-- alice.form-validator [marketplace] — Form validation utilities (1,200 downloads)
-```
-
-### lpm_pool_stats
-
-Get your Pool revenue sharing earnings estimate for the current month. Shows per-package breakdown with installs, weighted downloads, share percentage, and estimated earnings.
-
-**Parameters:** None
-
-**Example response:**
-
-```json
-{
-  "billingPeriod": "2026-02",
-  "totalWeightedDownloads": 5000,
-  "estimatedEarningsCents": 2450,
-  "packages": [
-    {
-      "name": "@lpm.dev/alice.my-utils",
-      "installCount": 120,
-      "weightedDownloads": 3200,
-      "sharePercentage": 1.85,
-      "estimatedEarningsCents": 1800
-    }
-  ]
-}
-```
-
-### lpm_user_info
-
-Get information about the authenticated LPM user including organizations, plan tier, pool access, and usage limits.
-
-**Parameters:** None
-
-**Example response:**
-
-```json
-{
-  "username": "alice@example.com",
-  "profile_username": "alice",
-  "organizations": [{ "slug": "acme", "name": "Acme Corp", "role": "owner" }],
-  "available_scopes": ["@alice", "@acme"],
-  "plan_tier": "pro",
-  "has_pool_access": true,
-  "usage": { "storage_bytes": 50000000, "private_packages": 2 },
-  "limits": { "privatePackages": 10, "storageBytes": 524288000 }
-}
-```
-
-## Caching
-
-Responses are cached in memory to reduce API calls:
-
-| Tool                      | Cache TTL |
-| ------------------------- | --------- |
-| `lpm_search`              | 5 minutes |
-| `lpm_package_info`        | 5 minutes |
-| `lpm_api_docs`            | 5 minutes |
-| `lpm_llm_context`         | 5 minutes |
-| `lpm_package_context`     | 5 minutes |
-| `lpm_package_skills`      | 5 minutes |
-| `lpm_browse_source`       | 5 minutes |
-| `lpm_marketplace_info`    | 5 minutes |
-| `lpm_docs`                | 30 minutes |
-| `lpm_quality_report`      | 5 minutes |
-| `lpm_search_owners`       | 5 minutes |
-| `lpm_packages_by_owner`   | 5 minutes |
-| `lpm_pool_stats`          | 1 hour    |
-| `lpm_user_info`           | 5 minutes |
-| `lpm_audit`               | No cache  |
-| `lpm_add`                 | No cache  |
-| `lpm_install`             | No cache  |
-
-Cache is in-memory only and resets when the server restarts.
-
 ## Troubleshooting
 
 **"No LPM token found"**

package/lib/auth.js

@@ -1,36 +1,90 @@
+import { createHash } from "node:crypto"
+import { isIP } from "node:net"
 import {
 	DEFAULT_REGISTRY_URL,
-	KEYTAR_ACCOUNT_NAME,
+	KEYTAR_ACCOUNT_PREFIX,
 	KEYTAR_SERVICE_NAME,
 } from "./constants.js"
 
+const KEYCHAIN_READ_ERROR =
+	"Unable to read LPM credentials from the OS keychain. Set LPM_TOKEN or run `lpm login` and retry."
+
 /**
  * Resolve the LPM auth token.
  * Priority: LPM_TOKEN env var → OS keychain (via keytar) → null
  *
+ * @param {() => Promise<unknown>} [loadKeytar]
  * @returns {Promise<string | null>}
  */
-export async function getToken() {
-	// 1. Environment variable (recommended for MCP configs)
+export async function getToken(loadKeytar = () => import("keytar")) {
 	if (process.env.LPM_TOKEN) {
 		return process.env.LPM_TOKEN
 	}
 
-	// 2. OS keychain (reads from same store as `lpm login`)
+	let keytarModule
 	try {
-		const keytar = await import("keytar")
-		const token = await keytar.default.getPassword(
-			KEYTAR_SERVICE_NAME,
-			KEYTAR_ACCOUNT_NAME,
-		)
-		if (token) return token
+		keytarModule = await loadKeytar()
+	} catch (error) {
+		if (
+			error &&
+			typeof error === "object" &&
+			"code" in error &&
+			(error.code === "ERR_MODULE_NOT_FOUND" ||
+				error.code === "MODULE_NOT_FOUND")
+		) {
+			return null
+		}
+		throw new Error(KEYCHAIN_READ_ERROR)
+	}
+
+	try {
+		const keytar = keytarModule.default ?? keytarModule
+		for (const account of keychainAccountsToTry(getBaseUrl())) {
+			const token = await keytar.getPassword(KEYTAR_SERVICE_NAME, account)
+			if (token) return token
+		}
 	} catch {
-		// keytar not available — this is expected in many environments
+		throw new Error(KEYCHAIN_READ_ERROR)
 	}
 
 	return null
 }
 
+/**
+ * The accounts that may hold the login for `registryUrl`, whichever way it
+ * ends: the one LPM CLI uses now, then the one CLI releases before 0.86 used
+ * for a login made with the registry spelled with a trailing slash.
+ *
+ * @param {string} registryUrl
+ * @returns {string[]}
+ */
+function keychainAccountsToTry(registryUrl) {
+	const canonical = registryUrl.replace(/\/+$/, "")
+	return [accountForKey(canonical), accountForKey(`${canonical}/`)]
+}
+
+/**
+ * Apply the LPM CLI's default registry transport contract: HTTPS, or HTTP
+ * only for loopback. The MCP server has no `--insecure` remote-HTTP escape hatch.
+ *
+ * @param {string | undefined} raw
+ * @returns {string}
+ */
+export function resolveRegistryUrl(raw = process.env.LPM_REGISTRY_URL) {
+	if (!raw) return DEFAULT_REGISTRY_URL
+
+	let parsed
+	try {
+		parsed = new URL(raw)
+	} catch {
+		return DEFAULT_REGISTRY_URL
+	}
+
+	if (parsed.protocol === "https:") return raw
+	if (parsed.protocol === "http:" && isLoopbackHost(parsed.hostname)) return raw
+	return DEFAULT_REGISTRY_URL
+}
+
 /**
  * Resolve the LPM registry base URL.
  * Priority: LPM_REGISTRY_URL env var → default
@@ -38,5 +92,43 @@ export async function getToken() {
  * @returns {string}
  */
 export function getBaseUrl() {
-	return process.env.LPM_REGISTRY_URL || DEFAULT_REGISTRY_URL
+	return resolveRegistryUrl()
+}
+
+/**
+ * Derive the keychain account used by LPM CLI for one effective registry URL.
+ * LPM CLI keys logins by the registry without trailing slashes, so both
+ * spellings name one account.
+ *
+ * @param {string} [registryUrl]
+ * @returns {string}
+ */
+export function getKeychainAccount(registryUrl = getBaseUrl()) {
+	return accountForKey(registryUrl.replace(/\/+$/, ""))
+}
+
+/** @param {string} key */
+function accountForKey(key) {
+	const digest = createHash("sha256").update(key, "utf8").digest("hex")
+	return `${KEYTAR_ACCOUNT_PREFIX}:${digest.slice(0, 16)}`
+}
+
+function isLoopbackHost(host) {
+	const unbracketed =
+		host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host
+	if (unbracketed.toLowerCase() === "localhost") return true
+
+	const version = isIP(unbracketed)
+	if (version === 4) return unbracketed.split(".", 1)[0] === "127"
+	if (version !== 6) return false
+
+	const normalized = new URL(`http://[${unbracketed}]/`).hostname
+		.slice(1, -1)
+		.toLowerCase()
+	if (normalized === "::1") return true
+
+	const mapped = normalized.match(/^::ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/)
+	if (!mapped) return false
+	const high = Number.parseInt(mapped[1], 16)
+	return high >> 8 === 127
 }

package/lib/cli.js

@@ -1,41 +1,83 @@
-import { execFile, execSync } from "node:child_process"
+import { execFile } from "node:child_process"
+import { accessSync, constants, realpathSync, statSync } from "node:fs"
+import { createRequire } from "node:module"
+import path from "node:path"
 
 const CLI_TIMEOUT_MS = 60_000
 
-/**
- * Resolve the path to the `lpm` CLI binary.
- *
- * Resolution order:
- * 1. LPM_CLI_PATH env var (explicit override)
- * 2. `which lpm` (global install)
- * 3. null (caller should handle fallback)
- *
- * @returns {string|null}
- */
-export function resolveCli() {
-	// 1. Explicit override
+/** Resolve an explicit CLI path or a global installation outside the caller's project. */
+export function resolveCli(platform = process.platform) {
 	const envPath = process.env.LPM_CLI_PATH
-	if (envPath) return envPath
+	if (envPath) {
+		const syntax = platform === "win32" ? path.win32 : path.posix
+		const qualified =
+			syntax.isAbsolute(envPath) &&
+			(platform !== "win32" || syntax.parse(envPath).root.length > 1)
+		return qualified ? envPath : null
+	}
+
+	const workspace = realpathSync(process.cwd())
+	for (const directory of (process.env.PATH || "").split(path.delimiter)) {
+		if (!path.isAbsolute(directory)) continue
+		const executable = globalExecutable(
+			path.join(directory, platform === "win32" ? "lpm.exe" : "lpm"),
+			workspace,
+			platform,
+		)
+		if (executable) return executable
+		if (platform !== "win32") continue
+
+		// npm exposes a .cmd shim. Resolve its native dependency without a shell.
+		try {
+			const wrapper = path.join(
+				directory,
+				"node_modules",
+				"@lpm-registry",
+				"cli",
+				"package.json",
+			)
+			if (!globalExecutable(wrapper, workspace, platform)) continue
+			const require = createRequire(wrapper)
+			const nativePackage = require.resolve(
+				"@lpm-registry/cli-win32-x64/package.json",
+			)
+			const native = globalExecutable(
+				path.join(path.dirname(nativePackage), "lpm.exe"),
+				workspace,
+				platform,
+			)
+			if (native) return native
+		} catch {
+			// Continue to the next PATH directory if optional native dependencies are absent.
+		}
+	}
+	return null
+}
 
-	// 2. Global install
+function globalExecutable(candidate, workspace, platform) {
 	try {
-		const result = execSync("which lpm", {
-			encoding: "utf-8",
-			timeout: 5_000,
-		}).trim()
-		if (result) return result
+		const resolved = realpathSync(candidate)
+		const relative = path.relative(workspace, resolved)
+		if (
+			relative === "" ||
+			(!relative.startsWith(`..${path.sep}`) &&
+				relative !== ".." &&
+				!path.isAbsolute(relative))
+		)
+			return null
+		if (!statSync(resolved).isFile()) return null
+		accessSync(resolved, platform === "win32" ? constants.F_OK : constants.X_OK)
+		return resolved
 	} catch {
-		// not found
+		return null
 	}
-
-	return null
 }
 
 /**
  * Run an LPM CLI command and return parsed JSON output.
  *
  * @param {string[]} args - CLI arguments (e.g., ['add', '@lpm.dev/owner.pkg', '--json'])
- * @param {{ timeout?: number }} options
+ * @param {{ timeout?: number, cwd?: string }} options
  * @returns {Promise<{ success: boolean, data: object|null, error: string|null }>}
  */
 export async function runCli(args, options = {}) {
@@ -58,6 +100,7 @@ export async function runCli(args, options = {}) {
 			args,
 			{
 				timeout,
+				cwd: options.cwd,
 				maxBuffer: 10 * 1024 * 1024,
 				env: { ...process.env },
 			},
@@ -74,13 +117,23 @@ export async function runCli(args, options = {}) {
 				// Try to parse JSON from stdout
 				try {
 					const data = JSON.parse(stdout)
+					if (!data || typeof data !== "object" || Array.isArray(data)) {
+						throw new Error("CLI returned an invalid result")
+					}
+					const success = !err && data.success !== false
+					const reason =
+						typeof data.error === "string" ? data.error : data.error?.message
 					resolve({
-						success: data.success !== false,
+						success,
 						data,
-						error:
-							data.success === false
-								? data.errors?.[0] || "Command failed"
-								: null,
+						error: success
+							? null
+							: reason ||
+								data.errors?.[0] ||
+								(err?.killed
+									? `CLI command timed out after ${timeout / 1000}s`
+									: err?.message) ||
+								"Command failed",
 					})
 				} catch {
 					// CLI produced output but not valid JSON

package/lib/constants.js

@@ -3,7 +3,7 @@
 export const DEFAULT_REGISTRY_URL = "https://lpm.dev"
 
 export const KEYTAR_SERVICE_NAME = "lpm-cli"
-export const KEYTAR_ACCOUNT_NAME = "auth-token"
+export const KEYTAR_ACCOUNT_PREFIX = "auth-token"
 
 export const REQUEST_TIMEOUT_MS = 30_000
 export const MAX_RETRIES = 2
@@ -31,5 +31,5 @@ export const ERROR_MESSAGES = {
 	timeout: "Request timed out. Try again later.",
 	invalidName:
 		"Invalid package name format. Expected: owner.package-name or @lpm.dev/owner.package-name",
-	searchNoParams: 'At least one of "query" or "category" is required.',
+	searchNoParams: "A search query or structured filter is required.",
 }

package/lib/format.js

@@ -65,3 +65,11 @@ export function parseName(input) {
 
 	return { owner, name }
 }
+
+/** Preserve CLI reports and mark failed process results as MCP tool errors. */
+export function cliResponse(result) {
+	if (!result.data) return errorResponse(result.error || "Command failed")
+	const response = jsonResponse(result.data)
+	if (!result.success) response.isError = true
+	return response
+}

package/lib/server.js

@@ -1,3 +1,4 @@
+import { createRequire } from "node:module"
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 import { z } from "zod"
 import { getBaseUrl, getToken } from "./auth.js"
@@ -20,6 +21,8 @@ import { search } from "./tools/search.js"
 import { searchOwners } from "./tools/search-owners.js"
 import { userInfo } from "./tools/user-info.js"
 
+const { version } = createRequire(import.meta.url)("../package.json")
+
 /**
  * Create and configure the MCP server with all LPM tools.
  * @returns {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer}
@@ -27,7 +30,7 @@ import { userInfo } from "./tools/user-info.js"
 export function createServer() {
 	const server = new McpServer({
 		name: "lpm-registry",
-		version: "0.2.0",
+		version,
 	})
 
 	const cache = new MemoryCache()
@@ -48,7 +51,7 @@ export function createServer() {
 
 	server.tool(
 		"lpm_quality_report",
-		"Get the quality score and detailed check breakdown for an LPM package (27 checks across documentation, code, testing, health)",
+		"Get the quality score and detailed, ecosystem-specific check breakdown for a package on the LPM.dev Registry across documentation, code quality, testing, and health.",
 		{
 			name: z.string().describe("Package name in owner.package-name format"),
 		},
@@ -173,7 +176,7 @@ export function createServer() {
 
 	server.tool(
 		"lpm_audit",
-		"Run a security audit on the project's LPM dependencies. Returns behavioral tags (eval, childProcess, shell, dynamicRequire), AI security findings, quality scores, and lifecycle scripts. Requires LPM CLI installed and authentication.",
+		"Run a security audit on the project's LPM dependencies. Returns behavioral tags (eval, childProcess, shell, dynamicRequire), AI security findings, quality scores, and lifecycle scripts. Requires LPM CLI installed; registry access follows CLI authentication and policy.",
 		{
 			path: z
 				.string()
@@ -308,7 +311,7 @@ If you must use this tool: fetch directory paths (e.g., "src") to get multiple f
 					'Filter by package ecosystem (e.g., "swift" for iOS/macOS packages)',
 				),
 			distribution: z
-				.enum(["marketplace", "pool", "private"])
+				.enum(["free", "marketplace", "pool", "private"])
 				.optional()
 				.describe("Filter by distribution mode"),
 			packageType: z

package/lib/tools/add.js

@@ -1,17 +1,22 @@
 import { runCli } from "../cli.js"
-import { errorResponse, parseName, textResponse } from "../format.js"
+import { cliResponse, errorResponse, parseName } from "../format.js"
 
 /**
  * Add an LPM package to the user's project via the CLI.
  * Extracts source files into the project for customization.
  *
  * @param {{ name: string, version?: string, path?: string, alias?: string, target?: string, force?: boolean, installDeps?: boolean, config?: Record<string, string> }} params
- * @param {{ getToken: () => Promise<string|null> }} ctx
  */
-export async function add(
-	{ name, version, path, alias, target, force, installDeps, config },
-	ctx,
-) {
+export async function add({
+	name,
+	version,
+	path,
+	alias,
+	target,
+	force,
+	installDeps,
+	config,
+}) {
 	let owner, pkgName
 	try {
 		const parsed = parseName(name)
@@ -21,13 +26,6 @@ export async function add(
 		return errorResponse(err.message)
 	}
 
-	const token = await ctx.getToken()
-	if (!token) {
-		return errorResponse(
-			"Authentication required. Set LPM_TOKEN environment variable or run `lpm login`.",
-		)
-	}
-
 	// Build package reference with optional config params as URL query string
 	let pkgRef = `@lpm.dev/${owner}.${pkgName}`
 	if (version) pkgRef += `@${version}`
@@ -49,31 +47,5 @@ export async function add(
 
 	const result = await runCli(args)
 
-	if (!result.success) {
-		return errorResponse(result.error || "Failed to add package.")
-	}
-
-	// Format the result for the AI
-	const data = result.data
-	const summary = {
-		success: true,
-		package: data.package,
-		installPath: data.installPath,
-		alias: data.alias || null,
-		files: (data.files || []).map(f => ({
-			dest: f.dest,
-			action: f.action,
-		})),
-		dependencies: data.dependencies || { npm: [], lpm: [] },
-	}
-
-	if (data.config && Object.keys(data.config).length > 0) {
-		summary.config = data.config
-	}
-
-	if (data.warnings?.length > 0) {
-		summary.warnings = data.warnings
-	}
-
-	return textResponse(JSON.stringify(summary, null, 2))
+	return cliResponse(result)
 }

package/lib/tools/audit.js

@@ -1,21 +1,13 @@
 import { runCli } from "../cli.js"
-import { errorResponse, textResponse } from "../format.js"
+import { cliResponse } from "../format.js"
 
 /**
  * Run a security audit on the project's LPM dependencies.
  * Returns behavioral tags, AI security findings, quality scores, and lifecycle scripts.
  *
  * @param {{ path?: string }} params
- * @param {{ getToken: () => Promise<string|null> }} ctx
  */
-export async function audit({ path }, ctx) {
-	const token = await ctx.getToken()
-	if (!token) {
-		return errorResponse(
-			"Authentication required. Set LPM_TOKEN environment variable or run `lpm login`.",
-		)
-	}
-
+export async function audit({ path }) {
 	const args = ["audit", "--json"]
 
 	const result = await runCli(args, {
@@ -23,28 +15,5 @@ export async function audit({ path }, ctx) {
 		...(path && { cwd: path }),
 	})
 
-	if (!result.success) {
-		return errorResponse(result.error || "Failed to run audit.")
-	}
-
-	const data = result.data
-
-	// Format for AI consumption
-	const summary = {
-		success: true,
-		totalPackages: data.totalPackages || 0,
-		packagesWithIssues: data.packagesWithIssues || 0,
-		packages: (data.packages || []).map(pkg => ({
-			name: pkg.name,
-			version: pkg.version,
-			qualityScore: pkg.qualityScore,
-			issues: pkg.issues || [],
-		})),
-	}
-
-	if (data.summary) {
-		summary.summary = data.summary
-	}
-
-	return textResponse(JSON.stringify(summary, null, 2))
+	return cliResponse(result)
 }

package/lib/tools/install.js

@@ -1,14 +1,13 @@
 import { runCli } from "../cli.js"
-import { errorResponse, parseName, textResponse } from "../format.js"
+import { cliResponse, errorResponse, parseName } from "../format.js"
 
 /**
  * Install an LPM package as a dependency via the CLI.
  * Installs to node_modules like npm install.
  *
  * @param {{ name: string, version?: string }} params
- * @param {{ getToken: () => Promise<string|null> }} ctx
  */
-export async function install({ name, version }, ctx) {
+export async function install({ name, version }) {
 	let owner, pkgName
 	try {
 		const parsed = parseName(name)
@@ -18,13 +17,6 @@ export async function install({ name, version }, ctx) {
 		return errorResponse(err.message)
 	}
 
-	const token = await ctx.getToken()
-	if (!token) {
-		return errorResponse(
-			"Authentication required. Set LPM_TOKEN environment variable or run `lpm login`.",
-		)
-	}
-
 	let pkgRef = `@lpm.dev/${owner}.${pkgName}`
 	if (version) pkgRef += `@${version}`
 
@@ -32,20 +24,5 @@ export async function install({ name, version }, ctx) {
 
 	const result = await runCli(args)
 
-	if (!result.success) {
-		return errorResponse(result.error || "Failed to install package.")
-	}
-
-	const data = result.data
-	const summary = {
-		success: true,
-		packages: data.packages || [{ name: pkgRef }],
-		npmOutput: data.npmOutput || "",
-	}
-
-	if (data.warnings?.length > 0) {
-		summary.warnings = data.warnings
-	}
-
-	return textResponse(JSON.stringify(summary, null, 2))
+	return cliResponse(result)
 }

package/lib/tools/search.js

@@ -10,10 +10,10 @@ import { errorResponse, textResponse } from "../format.js"
  * - Explore path (/packages/explore): when any structured filter is active
  *
  * @param {object} params
- * @param {string} [params.query] - Search text (required unless category provided)
+ * @param {string} [params.query] - Search text (optional with a structured filter)
  * @param {string} [params.category] - Category slug filter
  * @param {string} [params.ecosystem] - Ecosystem filter (js, swift, xcframework)
- * @param {string} [params.distribution] - Distribution mode filter (marketplace, pool, private)
+ * @param {string} [params.distribution] - Distribution mode filter (free, marketplace, pool, private)
  * @param {string} [params.packageType] - Package type filter
  * @param {string} [params.sort] - Sort order (newest, popular, name)
  * @param {boolean} [params.hasTypes] - TypeScript types filter
@@ -36,18 +36,6 @@ export async function search(params, ctx) {
 		minNodeVersion,
 	} = params
 
-	// Validation: at least query or category required
-	if (!query?.trim() && !category) {
-		return errorResponse(ERROR_MESSAGES.searchNoParams)
-	}
-	if (query && query.trim().length < 2) {
-		return errorResponse("Search query must be at least 2 characters.")
-	}
-
-	const token = await ctx.getToken()
-	const baseUrl = ctx.getBaseUrl()
-
-	// Determine which path to use
 	const hasStructuredFilters =
 		category ||
 		distribution ||
@@ -56,7 +44,18 @@ export async function search(params, ctx) {
 		hasTypes ||
 		moduleType ||
 		license ||
-		minNodeVersion
+		minNodeVersion ||
+		(!query?.trim() && params.ecosystem)
+
+	if (!query?.trim() && !hasStructuredFilters) {
+		return errorResponse(ERROR_MESSAGES.searchNoParams)
+	}
+	if (query && query.trim().length < 2) {
+		return errorResponse("Search query must be at least 2 characters.")
+	}
+
+	const token = await ctx.getToken()
+	const baseUrl = ctx.getBaseUrl()
 
 	// Build deterministic cache key from all params
 	const cacheKey = buildCacheKey(params)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@lpm-registry/mcp-server",
-	"version": "0.2.0",
+	"version": "0.3.0",
 	"description": "MCP server for the LPM package registry — exposes package info, quality reports, name checks, pool stats, and marketplace search as AI tools",
 	"author": "LPM <hello@lpm.dev> (https://lpm.dev)",
 	"repository": {