@lpm-registry/mcp-server 0.1.0

package/lib/tools/quality-report.js

@@ -0,0 +1,50 @@
+import { registryGet } from "../api.js"
+import { CACHE_TTL } from "../constants.js"
+import { errorResponse, parseName, textResponse } from "../format.js"
+
+/**
+ * Fetch the quality report for an LPM package.
+ *
+ * @param {{ name: string }} params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function qualityReport({ name }, ctx) {
+	let queryName
+	try {
+		const parsed = parseName(name)
+		queryName = `${parsed.owner}.${parsed.name}`
+	} catch (err) {
+		return errorResponse(err.message)
+	}
+
+	const token = await ctx.getToken()
+	const cacheKey = `quality:${queryName}:auth=${!!token}`
+
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	const baseUrl = ctx.getBaseUrl()
+	const result = await registryGet(
+		`/quality?name=${encodeURIComponent(queryName)}`,
+		token,
+		baseUrl,
+	)
+
+	if (!result.ok) {
+		if (result.status === 404) {
+			return errorResponse(`Package ${queryName} not found.`)
+		}
+		if (result.status === 403) {
+			return errorResponse(
+				"Access denied. Private packages require authentication.",
+			)
+		}
+		return errorResponse(
+			result.data?.error || `Request failed (${result.status})`,
+		)
+	}
+
+	const response = textResponse(JSON.stringify(result.data, null, 2))
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}

package/lib/tools/search-owners.js

@@ -0,0 +1,58 @@
+import { searchGet } from "../api.js"
+import { CACHE_TTL } from "../constants.js"
+import { errorResponse, textResponse } from "../format.js"
+
+/**
+ * Search for users or organizations on the LPM registry.
+ *
+ * @param {{ query: string, limit?: number }} params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function searchOwners({ query, limit }, ctx) {
+	if (!query || query.trim().length < 1) {
+		return errorResponse("Search query is required.")
+	}
+
+	const q = query.trim()
+	const safeLimit = Math.min(Math.max(limit || 5, 1), 10)
+
+	const cacheKey = `search-owners:${q}:${safeLimit}`
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	const token = await ctx.getToken()
+	const baseUrl = ctx.getBaseUrl()
+	const params = new URLSearchParams({ q, limit: String(safeLimit) })
+
+	const result = await searchGet(`/owners?${params.toString()}`, token, baseUrl)
+
+	if (!result.ok) {
+		return errorResponse(
+			result.data?.error || `Search failed (${result.status})`,
+		)
+	}
+
+	const owners = result.data?.owners || []
+
+	if (owners.length === 0) {
+		const response = textResponse(`No users or organizations found for "${q}".`)
+		ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+		return response
+	}
+
+	const lines = [
+		`Found ${owners.length} profile${owners.length === 1 ? "" : "s"}:\n`,
+	]
+
+	for (const owner of owners) {
+		const type = owner.type === "org" ? "org" : "user"
+		const name =
+			owner.name && owner.name !== owner.slug ? ` (${owner.name})` : ""
+		const bio = owner.bio ? ` — ${owner.bio.substring(0, 80)}` : ""
+		lines.push(`- @${owner.slug}${name} [${type}]${bio}`)
+	}
+
+	const response = textResponse(lines.join("\n"))
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}

package/lib/tools/search.js

@@ -0,0 +1,232 @@
+import { searchGet } from "../api.js"
+import { CACHE_TTL, ERROR_MESSAGES } from "../constants.js"
+import { errorResponse, textResponse } from "../format.js"
+
+/**
+ * Unified LPM package search.
+ *
+ * Uses dual-endpoint strategy:
+ * - Semantic path (/packages?mode=semantic): when only query + ecosystem/limit are provided
+ * - 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.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.packageType] - Package type filter
+ * @param {string} [params.sort] - Sort order (newest, popular, name)
+ * @param {boolean} [params.hasTypes] - TypeScript types filter
+ * @param {string} [params.moduleType] - Module type filter (esm, cjs, dual)
+ * @param {string} [params.license] - License filter
+ * @param {string} [params.minNodeVersion] - Min Node version filter
+ * @param {number} [params.limit] - Max results (1-50, default 10)
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function search(params, ctx) {
+	const {
+		query,
+		category,
+		distribution,
+		packageType,
+		sort,
+		hasTypes,
+		moduleType,
+		license,
+		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 ||
+		packageType ||
+		sort ||
+		hasTypes ||
+		moduleType ||
+		license ||
+		minNodeVersion
+
+	// Build deterministic cache key from all params
+	const cacheKey = buildCacheKey(params)
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	let response
+	if (hasStructuredFilters) {
+		response = await exploreSearch(params, token, baseUrl)
+	} else {
+		response = await semanticSearch(params, token, baseUrl)
+	}
+
+	if (response.isError) return response
+
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}
+
+/**
+ * Semantic search path — best quality for natural language queries.
+ * Uses /api/search/packages?mode=semantic
+ */
+async function semanticSearch({ query, ecosystem, limit }, token, baseUrl) {
+	const q = query.trim()
+	const safeLimit = Math.min(Math.max(limit || 10, 1), 20)
+
+	const searchParams = new URLSearchParams({
+		q,
+		mode: "semantic",
+		limit: String(safeLimit),
+	})
+	if (ecosystem) searchParams.set("ecosystem", ecosystem)
+
+	const result = await searchGet(
+		`/packages?${searchParams.toString()}`,
+		token,
+		baseUrl,
+	)
+
+	if (!result.ok) {
+		return errorResponse(
+			result.data?.error || `Search failed (${result.status})`,
+		)
+	}
+
+	const packages = result.data?.packages || []
+	return formatResults(packages, query)
+}
+
+/**
+ * Explore search path — supports all structured filters.
+ * Uses /api/search/packages/explore
+ */
+async function exploreSearch(params, token, baseUrl) {
+	const {
+		query,
+		category,
+		ecosystem,
+		distribution,
+		packageType,
+		sort,
+		hasTypes,
+		moduleType,
+		license,
+		minNodeVersion,
+		limit,
+	} = params
+
+	const safeLimit = Math.min(Math.max(limit || 10, 1), 50)
+
+	const searchParams = new URLSearchParams()
+	if (query?.trim()) searchParams.set("q", query.trim())
+	if (category) searchParams.set("category", category)
+	if (ecosystem) searchParams.set("ecosystem", ecosystem)
+	if (distribution) searchParams.set("distribution", distribution)
+	if (packageType) searchParams.set("packageType", packageType)
+	if (sort) searchParams.set("sort", sort)
+	if (hasTypes) searchParams.set("hasTypes", "true")
+	if (moduleType) searchParams.set("moduleType", moduleType)
+	if (license) searchParams.set("license", license)
+	if (minNodeVersion) searchParams.set("minNodeVersion", minNodeVersion)
+	searchParams.set("limit", String(safeLimit))
+
+	const result = await searchGet(
+		`/packages/explore?${searchParams.toString()}`,
+		token,
+		baseUrl,
+	)
+
+	if (!result.ok) {
+		return errorResponse(
+			result.data?.error || `Search failed (${result.status})`,
+		)
+	}
+
+	const packages = result.data?.packages || []
+	return formatResults(packages, query)
+}
+
+/**
+ * Format search results as readable text for LLM consumption.
+ * Handles both semantic and explore response shapes.
+ */
+function formatResults(packages, query) {
+	if (packages.length === 0) {
+		const label = query?.trim() ? ` for "${query.trim()}"` : ""
+		return textResponse(`No packages found${label}.`)
+	}
+
+	const lines = [
+		`Found ${packages.length} package${packages.length === 1 ? "" : "s"}:\n`,
+	]
+
+	for (const pkg of packages) {
+		const owner = pkg.ownerSlug || pkg.owner
+		const name = `${owner}.${pkg.name}`
+
+		// Type badge (skip default "package")
+		const typeLabel =
+			pkg.packageType && pkg.packageType !== "package"
+				? ` [${pkg.packageType}]`
+				: ""
+
+		// Ecosystem badge (skip default "js")
+		const ecosystemLabel =
+			pkg.ecosystem && pkg.ecosystem !== "js" ? ` {${pkg.ecosystem}}` : ""
+
+		// Distribution mode
+		const distLabel = pkg.distributionMode ? ` (${pkg.distributionMode})` : ""
+
+		const desc = pkg.description ? ` — ${pkg.description}` : ""
+		const downloads = pkg.downloadCount
+			? ` (${Number(pkg.downloadCount).toLocaleString()} downloads)`
+			: ""
+
+		lines.push(
+			`- ${name}${typeLabel}${ecosystemLabel}${distLabel}${desc}${downloads}`,
+		)
+
+		// Second line with extra metadata (from explore path)
+		const meta = []
+		if (pkg.qualityScore != null) meta.push(`Quality: ${pkg.qualityScore}`)
+		if (pkg.category) meta.push(`Category: ${pkg.category}`)
+		if (pkg.tags?.length > 0) meta.push(`Tags: ${pkg.tags.join(", ")}`)
+		if (meta.length > 0) {
+			lines.push(`  ${meta.join(" | ")}`)
+		}
+	}
+
+	return textResponse(lines.join("\n"))
+}
+
+/**
+ * Build a deterministic cache key from all search params.
+ */
+function buildCacheKey(params) {
+	const parts = [
+		"search",
+		params.query?.trim() || "",
+		params.category || "",
+		params.ecosystem || "",
+		params.distribution || "",
+		params.packageType || "",
+		params.sort || "",
+		params.hasTypes ? "types" : "",
+		params.moduleType || "",
+		params.license || "",
+		params.minNodeVersion || "",
+		String(params.limit || 10),
+	]
+	return parts.join(":")
+}

package/lib/tools/user-info.js

@@ -0,0 +1,38 @@
+import { registryGet } from "../api.js"
+import { CACHE_TTL, ERROR_MESSAGES } from "../constants.js"
+import { errorResponse, textResponse } from "../format.js"
+
+/**
+ * Fetch info about the authenticated LPM user.
+ * Requires authentication.
+ *
+ * @param {object} _params
+ * @param {{ cache: import('../cache.js').MemoryCache, getToken: () => Promise<string|null>, getBaseUrl: () => string }} ctx
+ */
+export async function userInfo(_params, ctx) {
+	const token = await ctx.getToken()
+	if (!token) {
+		return errorResponse(ERROR_MESSAGES.noToken)
+	}
+
+	const cacheKey = "user-info"
+
+	const cached = ctx.cache.get(cacheKey)
+	if (cached) return cached
+
+	const baseUrl = ctx.getBaseUrl()
+	const result = await registryGet("/-/whoami", token, baseUrl)
+
+	if (!result.ok) {
+		if (result.status === 401) {
+			return errorResponse(ERROR_MESSAGES.unauthorized)
+		}
+		return errorResponse(
+			result.data?.error || `Request failed (${result.status})`,
+		)
+	}
+
+	const response = textResponse(JSON.stringify(result.data, null, 2))
+	ctx.cache.set(cacheKey, response, CACHE_TTL.SHORT)
+	return response
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+	"name": "@lpm-registry/mcp-server",
+	"version": "0.1.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)",
+	"homepage": "https://lpm.dev",
+	"license": "ISC",
+	"keywords": [
+		"lpm",
+		"mcp",
+		"model-context-protocol",
+		"package-registry",
+		"ai-tools"
+	],
+	"type": "module",
+	"main": "lib/server.js",
+	"bin": {
+		"lpm-mcp-server": "./bin/mcp-server.js"
+	},
+	"exports": {
+		".": "./lib/server.js"
+	},
+	"files": [
+		"bin",
+		"lib",
+		"!lib/__tests__",
+		"README.md"
+	],
+	"scripts": {
+		"prepare": "husky",
+		"start": "node bin/mcp-server.js",
+		"test": "vitest run",
+		"test:watch": "vitest",
+		"lint": "biome check .",
+		"lint:fix": "biome check --write ."
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.12.0",
+		"zod": "^3.24.0"
+	},
+	"optionalDependencies": {
+		"keytar": "^7.9.0"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.10",
+		"husky": "^9.1.7",
+		"vitest": "^3.0.0"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	}
+}